@reefclaw/openclaw-plugin 0.1.0

package/live/listen-key-manager.js

@@ -0,0 +1,169 @@
+// ListenKeyManager — owns the Binance Futures user-data listenKey lifecycle.
+//
+// Flow:
+//   1. `start()` — POST /fapi/v1/listenKey → emit 'keyMinted' with the listenKey.
+//   2. Schedule PUT /fapi/v1/listenKey every `refreshIntervalMs` (default 25 min).
+//      Binance expires idle keys at 60 min; 25 min gives a 2x safety margin.
+//   3. On failed keep-alive, re-mint (POST) a fresh key and emit 'keyRotated'.
+//      Binance returns the SAME listenKey for repeat POSTs from the same API
+//      key, so "re-mint" is effectively a probe that the key is still valid.
+//      If the probe succeeds, we accept its answer; if it fails, we emit
+//      'keyKeepAliveFailed' and stop — the parent UserDataStream schedules
+//      a reconnect that re-enters `start()`.
+//   4. `stop()` — clear timer + DELETE /fapi/v1/listenKey (best-effort).
+//
+// Why this is a separate component:
+//   - Testable in isolation with fake timers + a mock API.
+//   - UserDataStream can stay focused on frame parsing + reconnect logic.
+//   - Graduated alert thresholds live here (3 failed refreshes = WARN,
+//     10 = ERROR) rather than being spread through the WS state machine.
+import { EventEmitter } from 'node:events';
+import { logger, formatError } from '../logger.js';
+const TAG = 'listen-key-manager';
+const REAL_TIMER_DEPS = {
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (h) => clearTimeout(h),
+    now: () => Date.now(),
+};
+/** Lightweight typed emitter — EventEmitter with a phantom type. */
+export class ListenKeyManager extends EventEmitter {
+    api;
+    refreshIntervalMs;
+    maxConsecutiveFailures;
+    timers;
+    currentKey = null;
+    keyMintedAt = null;
+    refreshTimer = null;
+    consecutiveFailures = 0;
+    running = false;
+    constructor(api, options = {}) {
+        super();
+        this.api = api;
+        this.refreshIntervalMs = options.refreshIntervalMs ?? 25 * 60_000;
+        this.maxConsecutiveFailures = options.maxConsecutiveFailures ?? 3;
+        this.timers = {
+            setTimeout: options.timers?.setTimeout ?? REAL_TIMER_DEPS.setTimeout,
+            clearTimeout: options.timers?.clearTimeout ?? REAL_TIMER_DEPS.clearTimeout,
+            now: options.timers?.now ?? REAL_TIMER_DEPS.now,
+        };
+    }
+    /** Mint a listenKey and start the refresh loop. Returns the minted key.
+     *  Throws if the first POST fails — caller decides how to back off. */
+    async start() {
+        if (this.running) {
+            throw new Error('ListenKeyManager already started');
+        }
+        const key = await this.api.createListenKey();
+        this.currentKey = key;
+        this.keyMintedAt = this.timers.now();
+        this.consecutiveFailures = 0;
+        this.running = true;
+        this.emit('keyMinted', key);
+        this.scheduleRefresh();
+        logger.info(TAG, `listenKey minted (hash=${hashKey(key)}), refresh every ${this.refreshIntervalMs / 1000}s`);
+        return key;
+    }
+    /** Stop the refresh loop and best-effort close the key. Idempotent.
+     *  For GRACEFUL shutdown only — a reconnect-driven teardown must use
+     *  `stopKeepAlive()` instead (see below). */
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        if (this.refreshTimer) {
+            this.timers.clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+        if (this.currentKey) {
+            try {
+                await this.api.closeListenKey();
+            }
+            catch (err) {
+                // Not worth retrying on shutdown — Binance expires idle keys anyway.
+                logger.warn(TAG, `closeListenKey failed on stop (non-fatal): ${formatError(err)}`);
+            }
+            this.currentKey = null;
+            this.keyMintedAt = null;
+        }
+    }
+    /** Stop the refresh loop WITHOUT the DELETE — for reconnect-driven closes.
+     *  Binance returns the SAME active listenKey on a re-POST and merely
+     *  extends its validity (doc-verified 2026-07-02: "Doing a POST on an
+     *  account with an active listenKey will return the currently active
+     *  listenKey and extend its validity for 60 minutes"), so an in-flight
+     *  DELETE racing the reconnect's POST can land AFTER it and invalidate the
+     *  key the fresh socket just authenticated with — a silent dead stream.
+     *  Skipping the DELETE is safe: an unused key expires on its own after
+     *  60 min of no keep-alive. Synchronous + idempotent. */
+    stopKeepAlive() {
+        if (!this.running)
+            return;
+        this.running = false;
+        if (this.refreshTimer) {
+            this.timers.clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+        this.currentKey = null;
+        this.keyMintedAt = null;
+    }
+    /** Current listenKey, or null if stopped. */
+    getKey() {
+        return this.currentKey;
+    }
+    /** Age in ms since the key was last minted. Null if stopped. Useful for
+     *  observability dashboards — a key far beyond refreshIntervalMs but still
+     *  alive means Binance is tolerating us past the nominal window. */
+    getKeyAge() {
+        if (this.keyMintedAt == null)
+            return null;
+        return this.timers.now() - this.keyMintedAt;
+    }
+    /** Number of consecutive failed keep-alive probes. Exposed for diagnostics. */
+    getConsecutiveFailures() {
+        return this.consecutiveFailures;
+    }
+    // ---- Internal ----
+    scheduleRefresh() {
+        if (!this.running)
+            return;
+        this.refreshTimer = this.timers.setTimeout(() => {
+            this.refreshTimer = null;
+            void this.refresh();
+        }, this.refreshIntervalMs);
+    }
+    async refresh() {
+        if (!this.running)
+            return;
+        try {
+            await this.api.keepAliveListenKey();
+            this.consecutiveFailures = 0;
+            this.emit('keyRefreshed');
+            logger.info(TAG, `listenKey refreshed (age=${Math.round((this.getKeyAge() ?? 0) / 1000)}s)`);
+            this.scheduleRefresh();
+        }
+        catch (err) {
+            this.consecutiveFailures += 1;
+            const reason = formatError(err);
+            if (this.consecutiveFailures >= this.maxConsecutiveFailures) {
+                // Stream is dead. Don't reschedule — parent will restart us.
+                logger.error(TAG, `listenKey keep-alive failed ${this.consecutiveFailures} times (last: ${reason}) — giving up`);
+                this.running = false;
+                if (this.refreshTimer) {
+                    this.timers.clearTimeout(this.refreshTimer);
+                    this.refreshTimer = null;
+                }
+                this.emit('keyKeepAliveFailed', reason);
+                return;
+            }
+            // Transient — log and retry on the normal cadence. We deliberately do
+            // NOT shrink the interval on failure; the keep-alive window is 60 min
+            // so we can afford up to 2 more tries before the key expires.
+            logger.warn(TAG, `listenKey keep-alive failed (${this.consecutiveFailures}/${this.maxConsecutiveFailures}): ${reason}`);
+            this.scheduleRefresh();
+        }
+    }
+}
+/** First 8 chars of a listenKey for log correlation without leaking the key. */
+function hashKey(key) {
+    return key.length > 8 ? key.slice(0, 8) : '(short)';
+}

package/live/live-adapter.d.ts

@@ -0,0 +1,264 @@
+import { EventEmitter } from 'node:events';
+import type { IExchangeAdapter, AdapterReadiness, OrderOptions } from '../exchange-adapter.js';
+import { BinancePrivateApi } from '../ccxt/binance-private.js';
+import type { CcxtOrder, CcxtBalance, CcxtPosition, TradingMode, ExchangeConfig } from '../types.js';
+import type { PositionMetadata, CloseReason } from '../simulator/types.js';
+import { ExchangeInfoCache } from './exchange-info-cache.js';
+import { BinanceRateLimiter } from './rate-limiter.js';
+import { IntentJournal } from './intent-journal.js';
+import { OrderPoller } from './order-poller.js';
+import { SlippageTracker } from './slippage-tracker.js';
+import { PositionReconciler } from './reconciler.js';
+import { LiveBalanceEnricher } from './live-balance-enricher.js';
+import { DepositTracker } from './deposit-tracker.js';
+import { BracketLedger } from './bracket-ledger.js';
+import { BracketManager } from './bracket-manager.js';
+import { type BracketMode } from '../config/brackets-config.js';
+import { type UserDataStreamMode, type UserDataStreamTunables } from '../config/user-data-stream-config.js';
+import { UserDataStreamController } from './user-data-stream-controller.js';
+import type { AutoCaptureContext } from '../ingest/position-auto-capture.js';
+import type { TradeStoreClient } from '../ingest/trade-store-client.js';
+/** Optional audit-trail wiring (TRADE_AUDIT_TRAIL_PLAN Phase 1).  Caller
+ *  passes this only when userDataStream.dbWrite='on' AND the WEBAPP_INGEST_TOKEN
+ *  + REEFCLAW_USER_ID env vars are present.  Forwarded into the controller
+ *  which spins up a WsIngest alongside the existing read path. */
+export interface TradeIngestWiring {
+    client: TradeStoreClient;
+    userId: string;
+    exchange?: string;
+}
+/**
+ * Backfill `balance.free[cur] = total[cur]` for currencies where Binance's CCXT
+ * response left the per-currency `free` and `used` at zero despite a non-zero
+ * total. Only safe when `used` is zero — otherwise the exchange really is
+ * reserving margin and we must not inflate availability.
+ */
+export declare function repairFreeFromTotal(balance: CcxtBalance): void;
+export declare class LiveAdapter extends EventEmitter implements IExchangeAdapter {
+    readonly mode: TradingMode;
+    readonly isLive = true;
+    private api;
+    private sizeCapMultiplier;
+    private maxPositionUSDT;
+    private exchangeInfo;
+    private isHedgeMode;
+    private getOpenOrdersUnavailableUntil;
+    private static readonly OPEN_ORDERS_RL_COOLDOWN_MS;
+    private rateLimiter;
+    private intentJournal;
+    private orderPoller;
+    private slippageTracker;
+    private reconciler;
+    private enricher;
+    private depositTracker;
+    private readonly bracketMode;
+    private bracketLedger;
+    private bracketManager;
+    private bracketReconciler;
+    private readonly userDataStreamMode;
+    private userDataStream;
+    private readonly wsAlgoStatusByCid;
+    private static readonly WS_ALGO_STATUS_CAP;
+    private static readonly WS_LIVE_LEG_MAX_AGE_MS;
+    private _sessionStartNav;
+    private lastIncomeRefreshMs;
+    private incomeAnchorUtcDay;
+    private liveMetadata;
+    private _readiness;
+    get readiness(): AdapterReadiness;
+    /** Session-start NAV, captured once at initialization. Used for drawdown calculation. */
+    getSessionStartNav(): number | null;
+    constructor(config: ExchangeConfig, mode: 'MICRO_LIVE' | 'LIVE', microLiveConfig?: {
+        sizeCapPercent?: number;
+        maxPositionUSDT?: number;
+    }, bracketMode?: BracketMode, userDataStreamMode?: UserDataStreamMode, userDataStreamTunables?: UserDataStreamTunables, 
+    /** TRADE_AUDIT_TRAIL_PLAN Phase 1 — optional audit-trail wiring.  Wired
+     *  through to UserDataStreamController.  Absent today on every existing
+     *  call site (default off); operator-driven once activation is approved. */
+    tradeIngest?: TradeIngestWiring, 
+    /** Position-decision auto-capture wiring. When provided alongside
+     *  tradeIngest, ws-ingest also routes every TRADE event through
+     *  `onWsFillObserved` to capture limit-order entries + scale-ins
+     *  (PR1 deferral resolution, 2026-05-03). Optional for back-compat. */
+    autoCapture?: AutoCaptureContext);
+    /** Get the underlying BinancePrivateApi (for advanced queries like fetchTicker). */
+    getApi(): BinancePrivateApi;
+    /** Get the exchange info cache (for symbol rules). */
+    getExchangeInfo(): ExchangeInfoCache;
+    /** Whether the account is in hedge mode. */
+    getIsHedgeMode(): boolean;
+    /** Get safety modules for external access (dashboard, tools, etc.). */
+    getRateLimiter(): BinanceRateLimiter;
+    getIntentJournal(): IntentJournal;
+    getOrderPoller(): OrderPoller;
+    getSlippageTracker(): SlippageTracker;
+    getReconciler(): PositionReconciler;
+    getEnricher(): LiveBalanceEnricher;
+    getDepositTracker(): DepositTracker;
+    /** Active user-data-stream mode. `'off'` when the feature flag is disabled. */
+    getUserDataStreamMode(): UserDataStreamMode;
+    /** User-data stream controller, or null if mode='off'. Used by dashboards
+     *  and diagnostic tools to read the live-state store + health. */
+    getUserDataStream(): UserDataStreamController | null;
+    /**
+     * Post-registration async initialization.
+     * Must complete before create_order is allowed (readiness gate).
+     * Emergency controls (cancel, close) work regardless of readiness.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Acknowledge existing positions on startup.
+     * Transitions DEGRADED → READY. Exchange info + position mode are already loaded
+     * (they're loaded before the position check in initialize()).
+     */
+    acknowledgePositions(): Promise<void>;
+    /**
+     * Tear down background loops so the adapter can be replaced at runtime
+     * (e.g. when the operator changes credentials or trading mode from the
+     * dashboard). Must be called before discarding the LiveAdapter reference
+     * or the poller + reconciler timers will keep firing against stale state.
+     *
+     * Idempotent — safe to call multiple times.
+     */
+    shutdown(): void;
+    createOrder(symbol: string, side: 'buy' | 'sell', type: 'market' | 'limit', amount: number, price?: number, metadata?: PositionMetadata, options?: OrderOptions): Promise<CcxtOrder>;
+    /**
+     * Attach brackets in the background. Auto-flattens on failure per locked
+     * decision #2. Never throws — errors are surfaced via emitted events and
+     * the subsequent flatten.
+     */
+    private attachBracketsAsync;
+    /**
+     * AUTHORITATIVE bracket-lifecycle handler — Binance's ALGO_UPDATE push.
+     *
+     * Why this exists (2026-05-15 RCA, doc-verified): pre-fix the plugin
+     * learned bracket state by REST-polling `audit_bracket_protection` /
+     * `fetchOpenOrders` and *guessing* — under a 429 storm that produced the
+     * audit→re-attach→cancel spiral that flushed live positions. Binance
+     * already PUSHES authoritative conditional-order lifecycle. Doc-exact
+     * status semantics (developers.binance.com → Event Algo Order Update):
+     *
+     *   EXPIRED   = SYSTEM cancel. The canonical trigger is "GTE_GTC
+     *               conditional + position closed → Binance auto-cancels the
+     *               surviving sibling". So EXPIRED on our bracket cid ⇒ the
+     *               position just closed by a non-close_position path (bracket
+     *               fill, manual, opposite-side). EXPECTED — not a fault.
+     *   TRIGGERED / FINISHED = the bracket fired (SL/TP hit) → position closed.
+     *   CANCELED  = MANUAL cancel (an explicit cancelOrder from us). Post the
+     *               bracket-reconciler fix we should NOT be doing this while a
+     *               position is open; if we see it, it's the canary that some
+     *               *other* path still strips protection — WARN loudly.
+     *
+     * For EXPIRED/TRIGGERED/FINISHED we (a) mark the ledger terminal so the
+     * attach-brackets re-attach loop STOPS chasing a bracket Binance already
+     * removed, and (b) emit the SAME `drift_detected` shape the position
+     * reconciler emits, so the existing, tested close-bypass cleanup
+     * (`onReconcilerObservedClose` in index.ts) runs immediately instead of
+     * up to 60 s later — which is what clears the stale state-store entry and
+     * stops the NEXT entry on the symbol being mis-classified as a scale-in
+     * (the bug that left fresh positions naked). No auto-flatten here: that
+     * stays deferred until this signal has soaked.
+     */
+    private onAlgoUpdate;
+    /** Expose the bracket manager for agent-facing tools (modify_stop, etc.).
+     *  Returns null when bracket mode is 'off'. */
+    getBracketManager(): BracketManager | null;
+    /** Expose the bracket ledger for reconciliation + admin queries. */
+    getBracketLedger(): BracketLedger | null;
+    /** Is the user-data WS store currently trusted (seeded + fresh + no gap)?
+     *  The Tier-1 gate for resolveBracketLegLiveness — when false the WS
+     *  per-cid signal is NOT consulted (a stale/gapped stream that missed a
+     *  CANCELED would otherwise yield a false 'live' on a naked leg — the exact
+     *  flaw the layered design exists to prevent). Null stream (mode=off) ⇒
+     *  never trusted ⇒ always the REST authority. */
+    isUserDataStoreTrusted(): boolean;
+    /** Authoritative per-bracket-leg liveness — the Phase 2 disambiguator that
+     *  replaces inferring presence/absence from a broad openOrders snapshot
+     *  (the SOL/INJ spiral root: a *successful* empty /fapi/v1/openAlgoOrders
+     *  is NOT proof a leg is gone).
+     *
+     *  Precedence (the agreed layering):
+     *   1. WS fast-path — ONLY behind isUserDataStoreTrusted(): the real
+     *      per-cid ALGO_UPDATE status (incl. CANCELED, which the ledger does
+     *      NOT record). Zero weight, sub-second. No record for the cid ⇒ no
+     *      WS opinion ⇒ fall through (never infer from absence).
+     *   2. REST authority — queryAlgoOrderStatus(cid): a DIRECT weight-1
+     *      question about that exact order id. Used when WS is untrusted or
+     *      silent on the cid.
+     *   3. 'unknown' — both unavailable. The d59e51b safe floor: callers MUST
+     *      refuse destructive action and retry; NEVER treat 'unknown' as
+     *      'terminal'/'stale'.
+     *
+     *  'live'     = leg is on the exchange (do NOT reattach/clobber).
+     *  'terminal' = positively confirmed gone (CANCELED/EXPIRED/REJECTED) or
+     *               fired (TRIGGERED/FINISHED) — only this licenses repair.
+     *  'unknown'  = could not get an answer — safe-wait. */
+    resolveBracketLegLiveness(cid: string): Promise<'live' | 'terminal' | 'unknown'>;
+    /** Symbol-scoped generalization of the trusted-WS fast-path — the
+     *  authoritative action-layer guard for the 2026-05-16 INJ bracket spiral.
+     *
+     *  `resolveBracketLegLiveness(cid)` answers about ONE cid. The spiral is:
+     *  a prior `attach_brackets` reattach placed a FRESH bracket that is live
+     *  on the exchange under a NEW cid, while the ledger row still holds the
+     *  PREVIOUS, genuinely-terminal cids. Classifying only the ledger's cids
+     *  yields a false 'stale' → clear+reattach cancels the live fresh bracket
+     *  → naked → audit unprotected → attach → spiral (prod: INJ/USDT cancelled
+     *  every ~15-40s for hours). This asks the question the ledger cids can't:
+     *  "is ANY rc-* bracket leg for this symbol live RIGHT NOW, under any cid?"
+     *
+     *  Trust model (identical to resolveBracketLegLiveness Tier-1): the WS map
+     *  is consulted ONLY when `isUserDataStoreTrusted()` (seeded + fresh +
+     *  no-gap — the property that guarantees no missed CANCELED, so a record
+     *  reading 'live' really is live). When the store is NOT trusted this
+     *  returns `{ trusted:false, liveCids:[] }` and the caller must NOT infer
+     *  "no live leg" from it — it falls back to the per-leg REST authority and,
+     *  failing that, refuses the destructive action (the d59e51b safe floor).
+     *  A record older than WS_LIVE_LEG_MAX_AGE_MS is ignored (caller falls back
+     *  too) so a stale 'live' can never suppress a genuine repair forever. */
+    findTrustedLiveBracketCidsForSymbol(symbol: string): {
+        trusted: boolean;
+        liveCids: string[];
+    };
+    /** Cancel every bracket-tagged (SL or TP) open order for a symbol. Used by
+     *  the `attach_brackets` recovery tool to clear stale bracket orders before
+     *  re-attaching a fresh pair. Does not touch non-bracket orders. Returns
+     *  the number successfully cancelled. Errors are logged + swallowed —
+     *  "already gone" is treated as success by the underlying cancel path. */
+    cancelSymbolBracketOrders(symbol: string): Promise<number>;
+    cancelOrder(orderId: string, symbol?: string): Promise<CcxtOrder>;
+    cancelAllOrders(symbol?: string): Promise<CcxtOrder[]>;
+    closePosition(symbol: string, closeReason?: CloseReason): Promise<CcxtOrder>;
+    /** Re-arm protection on a position whose closePosition flow cancelled the
+     *  brackets and then failed every market-close attempt. Reuses the normal
+     *  attach machinery: re-register the ledger row (terminal row → fresh
+     *  pending_entry with the SAME stop/target levels) and run the standard
+     *  3-retry attach. Never throws — this runs on the already-failing close
+     *  path; on any failure it emits the reconciler's `position_unprotected`
+     *  drift shape (re-emitted upstream as `bracket_drift`) plus a loud log so
+     *  the operator knows re-protection is required. */
+    private reattachBracketsAfterFailedClose;
+    getBalance(): Promise<CcxtBalance>;
+    /** Re-anchor the realized-today seed + sessionStartNav from /fapi/v1/income.
+     *  Throttled to {@link INCOME_REFRESH_MIN_INTERVAL_MS}; UTC date rollover
+     *  forces an immediate refresh. Best-effort — failures are logged and
+     *  swallowed so a transient income-endpoint blip never blocks a balance
+     *  read. Called from getBalance() with the fresh quote wallet so we don't
+     *  fetch balance twice.
+     */
+    private refreshIncomeAnchor;
+    getPositions(symbol?: string): Promise<CcxtPosition[]>;
+    getPositionsOrNull(symbol?: string): Promise<CcxtPosition[] | null>;
+    /** Merge agent-supplied entry metadata + ratchet MFE state into the raw
+     *  CCXT position list. Side effect: drops metadata for symbols no longer
+     *  in the open-positions snapshot (only when called without a symbol filter
+     *  — symbol-scoped calls skip cleanup so we don't lose context for other
+     *  open positions). */
+    private decoratePositionsWithMetadata;
+    getOpenOrders(symbol?: string): Promise<CcxtOrder[]>;
+    fetchOrder(orderId: string, symbol?: string): Promise<CcxtOrder | null>;
+    getLastPrice(symbol: string): Promise<number | null>;
+    /** Sync rate limiter from exchange response headers after every private API call. */
+    private syncRateLimits;
+    private loadExchangeInfo;
+    private detectPositionMode;
+}