@reefclaw/connect 0.1.10 → 0.1.12

package/assets/plugin/live/slippage-tracker.js

@@ -1,78 +0,0 @@
-// Slippage tracker — records expected vs actual fill price for every live order.
-// Computes slippage in basis points and tracks statistics per symbol.
-import { logger } from '../logger.js';
-const TAG = 'slippage';
-export class SlippageTracker {
-    records = [];
-    maxRecords;
-    constructor(maxRecords = 1000) {
-        this.maxRecords = maxRecords;
-    }
-    /** Record a fill with slippage measurement. */
-    recordFill(params) {
-        // Slippage: positive means worse execution for the order side
-        // For buy: actual > expected = positive slippage (paid more)
-        // For sell: actual < expected = positive slippage (received less)
-        let slippageBps;
-        if (params.side === 'buy') {
-            slippageBps = ((params.actualPrice - params.expectedPrice) / params.expectedPrice) * 10_000;
-        }
-        else {
-            slippageBps = ((params.expectedPrice - params.actualPrice) / params.expectedPrice) * 10_000;
-        }
-        const record = {
-            ...params,
-            slippageBps,
-            timestamp: Date.now(),
-        };
-        this.records.push(record);
-        // Circular buffer
-        if (this.records.length > this.maxRecords) {
-            this.records.shift();
-        }
-        logger.info(TAG, `${params.symbol} ${params.side}: expected=${params.expectedPrice}, actual=${params.actualPrice}, slippage=${slippageBps.toFixed(2)}bps`);
-        return record;
-    }
-    /** Get average slippage in bps for a symbol. */
-    getAverageSlippage(symbol) {
-        const relevant = symbol
-            ? this.records.filter(r => r.symbol === symbol)
-            : this.records;
-        if (relevant.length === 0)
-            return 0;
-        return relevant.reduce((s, r) => s + r.slippageBps, 0) / relevant.length;
-    }
-    /** Get slippage stats summary. */
-    getStats(symbol) {
-        const relevant = symbol
-            ? this.records.filter(r => r.symbol === symbol)
-            : this.records;
-        if (relevant.length === 0) {
-            return { count: 0, avgBps: 0, maxBps: 0, minBps: 0, p95Bps: 0, totalCost: 0 };
-        }
-        const bps = relevant.map(r => r.slippageBps).sort((a, b) => a - b);
-        const p95Idx = Math.floor(bps.length * 0.95);
-        return {
-            count: relevant.length,
-            avgBps: bps.reduce((s, v) => s + v, 0) / bps.length,
-            maxBps: bps[bps.length - 1],
-            minBps: bps[0],
-            p95Bps: bps[p95Idx],
-            totalCost: relevant.reduce((s, r) => {
-                // Cost of slippage = (actualPrice - expectedPrice) * amount
-                const diff = r.side === 'buy'
-                    ? (r.actualPrice - r.expectedPrice)
-                    : (r.expectedPrice - r.actualPrice);
-                return s + diff * r.amount;
-            }, 0),
-        };
-    }
-    /** Get recent records (last N). */
-    getRecent(count = 10) {
-        return this.records.slice(-count);
-    }
-    /** Get all records for a symbol. */
-    getRecordsForSymbol(symbol) {
-        return this.records.filter(r => r.symbol === symbol);
-    }
-}

package/assets/plugin/live/stop-watcher.d.ts

@@ -1,60 +0,0 @@
-import { EventEmitter } from 'node:events';
-import type { IExchangeAdapter } from '../exchange-adapter.js';
-import type { CcxtPosition } from '../types.js';
-import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
-export declare const DEFAULT_INTERVAL_MS = 10000;
-export interface StopTriggeredEvent {
-    symbol: string;
-    side: 'long' | 'short';
-    stopPrice: number;
-    markPrice: number;
-    quantity: number;
-}
-export type Wave9StopCloseOutcome = {
-    status: 'flat';
-    detail: string;
-    candidateId: string;
-    symbol: string;
-} | {
-    status: 'protected' | 'manual_intervention';
-    detail: string;
-    candidateId: string;
-    symbol: string;
-    stopPrice: number;
-    residualQuantity?: number;
-    stopClientOrderId?: string;
-};
-/** Optional durable Wave 9 lifecycle. Generic watcher behavior is unchanged
- *  when this is absent or the current position has no owned candidate. */
-export interface Wave9StopCloseLifecycle {
-    resolveCandidateId(position: CcxtPosition): Promise<string | undefined> | string | undefined;
-    settleAfterClose(candidateId: string, symbol: string): Promise<Wave9StopCloseOutcome>;
-}
-/** Decide whether a position has crossed its stop.
- *  Exported for direct unit-testing without spinning up a watcher loop. */
-export declare function isStopBreached(position: CcxtPosition): boolean;
-export declare class PositionWatcher extends EventEmitter {
-    private interval;
-    private intervalMs;
-    private adapter;
-    private readonly operationLock?;
-    private wave9CloseLifecycle?;
-    /** Symbols currently awaiting a close RPC — second trigger in the same tick
-     *  is suppressed so the watcher cannot double-close. Cleared after the close
-     *  call resolves (success or failure). */
-    private closePending;
-    /** Symbols we've already logged a breach for this session, to avoid spamming
-     *  the log every tick while the close is in flight. */
-    private notifiedBreach;
-    constructor(adapter: IExchangeAdapter, intervalMs?: number, operationLock?: TradingOperationLock);
-    /** Configure this after the durable execution ledger is ready. Runtime
-     *  lifecycle hooks reapply it to every watcher after reconnect. */
-    setWave9CloseLifecycle(lifecycle?: Wave9StopCloseLifecycle): void;
-    start(): void;
-    stop(): void;
-    /** Run one check cycle. Exposed for tests (skip setInterval). */
-    tick(): Promise<void>;
-    private fireClose;
-    /** For tests. */
-    isRunning(): boolean;
-}

package/assets/plugin/live/stop-watcher.js

@@ -1,215 +0,0 @@
-// Stop watcher — polls open positions and auto-closes any that have crossed
-// their metadata stopPrice, independent of the LLM agent.
-//
-// Policy vs enforcement split:
-//   - The LLM owns POLICY: it sets stopPrice at entry and may update it at
-//     any time (move to breakeven, trail, widen, or remove entirely by
-//     clearing it). The watcher just reads whatever stopPrice currently is.
-//   - The watcher owns ENFORCEMENT: if mark crosses stopPrice, it fires a
-//     market close immediately rather than waiting for the agent's next
-//     15-min heartbeat. This closes the exit-latency gap the LLM-centric
-//     model would otherwise leave open.
-//
-// Scope:
-//   - Works in paper mode (PaperAdapter.getPositions returns CcxtPosition with
-//     stopPrice populated from position metadata).
-//   - In live mode LiveAdapter does NOT track per-position metadata, so
-//     getPositions returns positions without stopPrice and the watcher
-//     naturally skips them. Wiring live-mode metadata is a separate change
-//     for when live trading turns on.
-import { EventEmitter } from 'node:events';
-import { logger, formatError } from '../logger.js';
-const TAG = 'stop-watcher';
-// 2026-05-15 EFFICIENCY_QUICK_WINS Change 1: 3s → 10s. The watcher was
-// designed when it was the ONLY stop-enforcement mechanism; with exchange-
-// native brackets (live in enforce mode) it is now belt-and-suspenders, so
-// 10s latency to catch a watcher-triggered close is fine — Binance fires the
-// bracket stop in ms regardless. Saves ~70 weight/min (100→30). Operator can
-// revert with zero deploy via plugin-config.json `stopWatcher.intervalMs`.
-// See docs/EFFICIENCY_QUICK_WINS_PLAN.md + the Binance ban-gate context.
-export const DEFAULT_INTERVAL_MS = 10_000;
-/** Decide whether a position has crossed its stop.
- *  Exported for direct unit-testing without spinning up a watcher loop. */
-export function isStopBreached(position) {
-    const stop = position.stopPrice;
-    if (stop === undefined || stop === null || !Number.isFinite(stop) || stop <= 0) {
-        return false;
-    }
-    const mark = position.markPrice;
-    if (!Number.isFinite(mark) || mark <= 0) {
-        return false;
-    }
-    return position.side === 'long' ? mark <= stop : mark >= stop;
-}
-export class PositionWatcher extends EventEmitter {
-    interval = null;
-    intervalMs;
-    adapter;
-    operationLock;
-    wave9CloseLifecycle;
-    /** Symbols currently awaiting a close RPC — second trigger in the same tick
-     *  is suppressed so the watcher cannot double-close. Cleared after the close
-     *  call resolves (success or failure). */
-    closePending = new Set();
-    /** Symbols we've already logged a breach for this session, to avoid spamming
-     *  the log every tick while the close is in flight. */
-    notifiedBreach = new Set();
-    constructor(adapter, intervalMs = DEFAULT_INTERVAL_MS, operationLock) {
-        super();
-        this.adapter = adapter;
-        this.intervalMs = intervalMs;
-        this.operationLock = operationLock;
-    }
-    /** Configure this after the durable execution ledger is ready. Runtime
-     *  lifecycle hooks reapply it to every watcher after reconnect. */
-    setWave9CloseLifecycle(lifecycle) {
-        this.wave9CloseLifecycle = lifecycle;
-    }
-    start() {
-        if (this.interval) {
-            logger.warn(TAG, 'Already running');
-            return;
-        }
-        logger.info(TAG, `Starting stop watcher (interval: ${this.intervalMs}ms)`);
-        this.interval = setInterval(() => {
-            void this.tick();
-        }, this.intervalMs);
-    }
-    stop() {
-        if (this.interval) {
-            clearInterval(this.interval);
-            this.interval = null;
-        }
-        this.closePending.clear();
-        this.notifiedBreach.clear();
-        logger.info(TAG, 'Stopped');
-    }
-    /** Run one check cycle. Exposed for tests (skip setInterval). */
-    async tick() {
-        let positions;
-        try {
-            positions = await this.adapter.getPositionsOrNull();
-        }
-        catch (err) {
-            logger.warn(TAG, `getPositions failed: ${formatError(err)}`);
-            return;
-        }
-        if (positions === null) {
-            // Fetch failed (429 / weight-paced / transient) — position state is
-            // UNKNOWN, not "flat". Skip this tick WITHOUT touching notifiedBreach /
-            // closePending: a null-collapse to [] would wipe the in-flight close
-            // guard (openSymbols below would be empty, clearing every closePending
-            // entry) and let the NEXT tick fire a SECOND close on a position whose
-            // close is already in flight. State repairs on the next successful tick.
-            logger.warn(TAG, 'getPositions unavailable (null) — skipping tick, preserving in-flight close guards');
-            return;
-        }
-        // Clear notification flags for any symbol no longer holding a position,
-        // so a re-entered position later gets a fresh log line on re-breach.
-        const openSymbols = new Set(positions.map(p => p.symbol));
-        for (const sym of this.notifiedBreach) {
-            if (!openSymbols.has(sym))
-                this.notifiedBreach.delete(sym);
-        }
-        for (const sym of this.closePending) {
-            if (!openSymbols.has(sym))
-                this.closePending.delete(sym);
-        }
-        for (const position of positions) {
-            if (!isStopBreached(position))
-                continue;
-            if (this.closePending.has(position.symbol))
-                continue;
-            if (!this.notifiedBreach.has(position.symbol)) {
-                logger.warn(TAG, `STOP BREACHED: ${position.symbol} ${position.side} mark=${position.markPrice} stop=${position.stopPrice} — auto-closing`);
-                this.notifiedBreach.add(position.symbol);
-            }
-            this.closePending.add(position.symbol);
-            // Fire-and-forget per symbol so one slow close doesn't stall the tick.
-            void this.fireClose(position);
-        }
-    }
-    async fireClose(position) {
-        const event = {
-            symbol: position.symbol,
-            side: position.side,
-            stopPrice: position.stopPrice ?? 0,
-            markPrice: position.markPrice,
-            quantity: position.contracts,
-        };
-        this.emit('stop_triggered', event);
-        const close = async () => {
-            let trustedPosition = position;
-            // Re-read after acquiring the shared trading boundary. A Wave 9
-            // reversal or another stop may have flattened the symbol while this
-            // watcher was queued.
-            if (this.operationLock) {
-                const current = await this.adapter.getPositionsOrNull(position.symbol);
-                if (current === null) {
-                    throw new Error('position recheck unavailable while holding trading operation lock');
-                }
-                const latest = current.find((candidate) => candidate.symbol === position.symbol);
-                if (!latest || !isStopBreached(latest)) {
-                    logger.info(TAG, `${position.symbol} no longer stop-triggered after locked recheck — skipping`);
-                    return 'skipped';
-                }
-                trustedPosition = latest;
-            }
-            let candidateId;
-            let ownershipError;
-            if (this.wave9CloseLifecycle) {
-                try {
-                    candidateId = await this.wave9CloseLifecycle.resolveCandidateId(trustedPosition);
-                }
-                catch (error) {
-                    ownershipError = formatError(error);
-                }
-            }
-            if (ownershipError) {
-                throw new Error(`Wave 9 ownership resolution failed before stop close submission: ${ownershipError}; ` +
-                    'IMMEDIATE MANUAL INTERVENTION REQUIRED');
-            }
-            await this.adapter.closePosition(trustedPosition.symbol, 'stop_watcher');
-            if (!candidateId || !this.wave9CloseLifecycle)
-                return 'closed';
-            const outcome = await this.wave9CloseLifecycle.settleAfterClose(candidateId, trustedPosition.symbol);
-            if (outcome.status === 'flat')
-                return 'closed';
-            if (outcome.status === 'protected') {
-                logger.warn(TAG, `Stop close left a Wave 9 residual on ${trustedPosition.symbol}; ` +
-                    `${outcome.detail}. The exact frozen stop is proven and the watcher will retry.`);
-                this.emit('stop_residual_protected', { ...event, ...outcome });
-                return 'residual_protected';
-            }
-            throw new Error(outcome.detail);
-        };
-        try {
-            const result = this.operationLock
-                ? await this.operationLock.withSymbolLock(position.symbol, `stop_watcher:${position.symbol}`, close)
-                : await close();
-            if (result !== 'closed')
-                return;
-            logger.info(TAG, `Auto-closed ${position.symbol} (reason=stop_watcher)`);
-            this.emit('stop_closed', event);
-        }
-        catch (err) {
-            const msg = formatError(err);
-            // "No open position" means the LLM or another path already closed it —
-            // that's a successful no-op, not a failure.
-            if (msg.includes('No open position')) {
-                logger.info(TAG, `${position.symbol} already closed by another path — skipping`);
-            }
-            else {
-                logger.error(TAG, `Auto-close failed for ${position.symbol}: ${msg}`);
-            }
-            this.emit('stop_failed', { ...event, error: msg });
-        }
-        finally {
-            this.closePending.delete(position.symbol);
-        }
-    }
-    /** For tests. */
-    isRunning() {
-        return this.interval !== null;
-    }
-}

package/assets/plugin/live/user-data-active-probe.d.ts

@@ -1,54 +0,0 @@
-import type { BinancePrivateApi } from '../ccxt/binance-private.js';
-import type { UserDataStream } from './user-data-stream.js';
-import type { LiveStateStore } from './live-state-store.js';
-export interface UserDataActiveProbeOptions {
-    api: BinancePrivateApi;
-    stream: UserDataStream;
-    store: LiveStateStore;
-    /** How often to run the probe. Default 60_000 (60s). Pass 0 to disable. */
-    intervalMs?: number;
-    /** Subtracted from `lastEventAt` when computing `since` so we don't miss
-     *  trades whose timestamp landed in the same millisecond as our last
-     *  frame. Default 1_000 (1 s). */
-    safetyBufferMs?: number;
-    /** For unit tests — injected timers + clock. */
-    timers?: {
-        setInterval?: (fn: () => void, ms: number) => ReturnType<typeof setInterval>;
-        clearInterval?: (h: ReturnType<typeof setInterval>) => void;
-    };
-    /** For unit tests — injected clock used only for log timestamps. */
-    now?: () => number;
-}
-export interface UserDataActiveProbeHealth {
-    probesRun: number;
-    reconnectsTriggered: number;
-    errorCount: number;
-    lastReconnectReason: string | null;
-    lastReconnectAt: number | null;
-}
-export declare class UserDataActiveProbe {
-    private readonly api;
-    private readonly stream;
-    private readonly store;
-    private readonly intervalMs;
-    private readonly safetyBufferMs;
-    private readonly setIntervalFn;
-    private readonly clearIntervalFn;
-    private readonly now;
-    private timer;
-    private running;
-    private inFlight;
-    private probesRun;
-    private reconnectsTriggered;
-    private errorCount;
-    private lastReconnectReason;
-    private lastReconnectAt;
-    constructor(opts: UserDataActiveProbeOptions);
-    start(): void;
-    stop(): void;
-    getHealth(): UserDataActiveProbeHealth;
-    /** Testing hook — runs one probe pass synchronously (well, async, but
-     *  awaitable). Production uses the interval-driven path; tests can drive
-     *  this directly without touching fake timers. */
-    runProbe(): Promise<void>;
-}

package/assets/plugin/live/user-data-active-probe.js

@@ -1,180 +0,0 @@
-// UserDataActiveProbe — proactive REST probe that catches "WS silently
-// stopped delivering" before the staleness watchdog does.
-//
-// WHY THIS EXISTS
-// ---------------
-// On 2026-04-25 we observed the prod user-data stream go silent for 15
-// minutes at a stretch while a real bracket-stop fill happened on Binance.
-// The socket stayed "open" at the OS level (no FIN, no error), the listenKey
-// keep-alive succeeded, but no frames arrived. The 15-min staleness watchdog
-// caught it eventually, but in that window the local store still showed an
-// already-closed position as live. Either alone — adaptive watchdog OR active
-// probe — narrows the window; together they close it.
-//
-// WHAT IT DOES
-// ------------
-// Every `intervalMs` (default 60s):
-//   1. If the stream isn't connected, skip — reconnect logic owns recovery.
-//   2. Read symbols from `store.getPositions()` — only positions where a
-//      missed fill matters (a closed position is a non-event).
-//   3. For each symbol, call `api.fetchMyTrades(symbol, since=lastEventAt - 1s)`.
-//   4. If any returned trade has `timestamp > lastEventAt`, the WS missed
-//      a fill: log the trade id + symbol and call `stream.requestReconnect`.
-//   5. Stop after the first detection — reconnect will trigger snapshot +
-//      gap-fill, and another probe pass on the next tick covers anything new.
-//
-// WHAT IT DOES NOT DO
-// -------------------
-// - Does NOT ingest the trade itself. Reconnect → resyncRequired → gap-filler
-//   handles ingest with `source='rest_reconcile'`. Single-responsibility.
-// - Does NOT touch LiveStateStore. Reconnect snapshot reseeds it.
-// - Does NOT run on flat accounts. With no open positions there's nothing to
-//   protect — the watchdog's looser idle threshold is appropriate.
-//
-// COST
-// ----
-// `fetchMyTrades` is weight 5 per symbol per call on Binance Futures. With
-// ~5 open positions on a typical account, that's 25 weight/min — well below
-// the 2400/min budget.
-import { logger, formatError } from '../logger.js';
-const TAG = 'user-data-active-probe';
-/** CCXT unified symbol → API form. The reconciler stores `BTC/USDT` (no suffix);
- *  CCXT's fetchMyTrades takes either form, but we re-attach the settle suffix
- *  to be explicit. */
-function toApiSymbol(s) {
-    if (!s)
-        return s;
-    if (s.includes(':'))
-        return s;
-    const parts = s.split('/');
-    return parts.length === 2 ? `${s}:${parts[1]}` : s;
-}
-export class UserDataActiveProbe {
-    api;
-    stream;
-    store;
-    intervalMs;
-    safetyBufferMs;
-    setIntervalFn;
-    clearIntervalFn;
-    now;
-    timer = null;
-    running = false;
-    inFlight = false;
-    probesRun = 0;
-    reconnectsTriggered = 0;
-    errorCount = 0;
-    lastReconnectReason = null;
-    lastReconnectAt = null;
-    constructor(opts) {
-        this.api = opts.api;
-        this.stream = opts.stream;
-        this.store = opts.store;
-        this.intervalMs = opts.intervalMs ?? 60_000;
-        this.safetyBufferMs = opts.safetyBufferMs ?? 1_000;
-        this.setIntervalFn = opts.timers?.setInterval ?? ((fn, ms) => setInterval(fn, ms));
-        this.clearIntervalFn = opts.timers?.clearInterval ?? ((h) => clearInterval(h));
-        this.now = opts.now ?? (() => Date.now());
-    }
-    start() {
-        if (this.running)
-            return;
-        if (this.intervalMs <= 0) {
-            logger.info(TAG, 'disabled (intervalMs=0)');
-            return;
-        }
-        this.running = true;
-        this.timer = this.setIntervalFn(() => {
-            void this.runProbe().catch((err) => {
-                this.errorCount++;
-                logger.warn(TAG, `probe pass threw: ${formatError(err)} — continuing`);
-            });
-        }, this.intervalMs);
-        logger.info(TAG, `started (intervalMs=${this.intervalMs}, safetyBufferMs=${this.safetyBufferMs})`);
-    }
-    stop() {
-        if (!this.running)
-            return;
-        if (this.timer) {
-            this.clearIntervalFn(this.timer);
-            this.timer = null;
-        }
-        this.running = false;
-        logger.info(TAG, 'stopped');
-    }
-    getHealth() {
-        return {
-            probesRun: this.probesRun,
-            reconnectsTriggered: this.reconnectsTriggered,
-            errorCount: this.errorCount,
-            lastReconnectReason: this.lastReconnectReason,
-            lastReconnectAt: this.lastReconnectAt,
-        };
-    }
-    /** Testing hook — runs one probe pass synchronously (well, async, but
-     *  awaitable). Production uses the interval-driven path; tests can drive
-     *  this directly without touching fake timers. */
-    async runProbe() {
-        if (!this.running && this.timer === null) {
-            // Allow direct invocation in tests even when start() wasn't called.
-        }
-        if (this.inFlight)
-            return;
-        this.inFlight = true;
-        this.probesRun++;
-        try {
-            if (!this.stream.isConnected())
-                return;
-            const health = this.stream.getHealth();
-            const lastEventAt = health.lastEventAt;
-            if (lastEventAt == null)
-                return; // Never received an event; nothing to compare against.
-            const positions = this.store.getPositions().filter((p) => p && p.contracts > 0);
-            if (positions.length === 0)
-                return;
-            const symbols = Array.from(new Set(positions.map((p) => p.symbol).filter(Boolean)));
-            const since = lastEventAt - this.safetyBufferMs;
-            for (const symbol of symbols) {
-                let trades;
-                try {
-                    trades = await this.api.fetchMyTrades(toApiSymbol(symbol), since, 50);
-                }
-                catch (err) {
-                    this.errorCount++;
-                    logger.warn(TAG, `fetchMyTrades(${symbol}) threw: ${formatError(err)}`);
-                    continue;
-                }
-                if (!Array.isArray(trades) || trades.length === 0)
-                    continue;
-                let newest = null;
-                for (const t of trades) {
-                    if (!t || typeof t !== 'object')
-                        continue;
-                    const rec = t;
-                    const ts = typeof rec.timestamp === 'number' ? rec.timestamp : 0;
-                    if (ts <= lastEventAt)
-                        continue;
-                    const id = typeof rec.id === 'string' ? rec.id : String(rec.id ?? '?');
-                    if (!newest || ts > newest.timestamp) {
-                        newest = { id, timestamp: ts };
-                    }
-                }
-                if (newest) {
-                    const lagMs = this.now() - newest.timestamp;
-                    const reason = `active_probe_silent_stream`;
-                    logger.error(TAG, `silent-stream detected: ${symbol} trade id=${newest.id} t=${new Date(newest.timestamp).toISOString()} ` +
-                        `> lastEventAt=${new Date(lastEventAt).toISOString()} (lagMs=${lagMs}) — forcing reconnect`);
-                    this.reconnectsTriggered++;
-                    this.lastReconnectReason = `${reason}:${symbol}`;
-                    this.lastReconnectAt = this.now();
-                    this.stream.requestReconnect(reason);
-                    // One reconnect per pass — don't fire repeatedly across symbols.
-                    return;
-                }
-            }
-        }
-        finally {
-            this.inFlight = false;
-        }
-    }
-}