@reefclaw/connect 0.1.0

package/assets/plugin/config/user-data-stream-config.js

@@ -0,0 +1,224 @@
+// Feature flag reader for the Binance user-data WebSocket stream.
+//
+// Ordering of sources (first hit wins):
+//   1. Remote override from intelligence (set via admin dashboard OTA) — stored
+//      in memory on the plugin after push; not persisted to plugin-config.json.
+//      Wired in Phase 2; for Phase 1 this is always undefined.
+//   2. Local plugin-config.json `userDataStream.mode` field.
+//   3. Default: 'off' (legacy REST polling remains authoritative).
+//
+// Rollout stages:
+//   off     — WS not started. REST polling authoritative.
+//   shadow  — DEPRECATED 2026-05-06. WS runs alongside REST; diffs logged every
+//             60s; REST authoritative. Was the soak stage during the original
+//             rollout; retained as a runtime mode for backward compatibility
+//             with existing plugin-config files but no longer reachable as a
+//             forward transition target. New deployments go off → observe.
+//   observe — WS authoritative for reads; REST drops to 30-60s truth-check.
+//   enforce — Full cutover. Skill-side pollers disabled; REST at 60s only.
+//
+// Transitions must progress forward only (no skipping). Deploy script enforces.
+// Reverse transitions to any earlier stage (including 'shadow' and 'off') are
+// always permitted as a safety-net rollback.
+import { readPluginConfig } from './plugin-config-io.js';
+const VALID = new Set(['off', 'shadow', 'observe', 'enforce']);
+/** Allowed forward transitions. Reverse transitions are always permitted so
+ *  the operator can fall back to REST if WS misbehaves.
+ *
+ *  'shadow' is deprecated as a forward target (2026-05-06): nothing transitions
+ *  TO shadow anymore. Configs that already have 'shadow' continue to work; the
+ *  shadow → observe escape path is preserved so an operator stuck on a
+ *  shadow-configured plugin can still ladder up. */
+const FORWARD_TRANSITIONS = {
+    off: new Set(['observe']),
+    shadow: new Set(['observe']),
+    observe: new Set(['enforce']),
+    enforce: new Set(),
+};
+export const DEFAULT_TUNABLES = {
+    listenKeyRefreshMs: 25 * 60_000, // 25 min
+    reconnectBaseMs: 1_000, // 1 s
+    reconnectCapMs: 60_000, // 60 s
+    // Ping-aware watchdog (refactored 2026-04-25). The watchdog now compares
+    // against `lastFrameAt` — any incoming WS frame including server pings —
+    // not `lastEventAt` (message frames only). Binance documents server pings
+    // every 3 min on the user-data stream:
+    //   "The websocket server will send a ping frame every 3 minutes."
+    //   "If the websocket server does not receive a pong frame back from the
+    //    connection within a 10 minute period, the connection will be disconnected."
+    //   https://developers.binance.com/docs/derivatives/usds-margined-futures/websocket-market-streams
+    // 6 min comfortably exceeds the 180 s ping interval and stays well under
+    // Binance's own 10-min no-pong cutoff. The previous 90 s active threshold
+    // false-fired ~200×/day on idle accounts; the active REST probe (60 s
+    // fetchMyTrades per open-position symbol) is the correct mechanism for
+    // catching missed fills, and remains in place.
+    staleEventWatchdogMs: 6 * 60_000, // 6 min
+    // 60 s. NOT a "cheap" call: the algo refresh is an UNSCOPED fetchOpenOrders
+    // = 80 weight (40 regular + 40 algo, doc-verified developers.binance.com
+    // 2026-05-15). At 15 s that was 4/min × 80 = ~320 weight/min — measured on
+    // prod (binance-ban-gate weight-window summary) as the dominant idle
+    // consumer after the audit-scope fix, pinning the pacer ceiling and
+    // starving the agent's heartbeat reads. ALGO_UPDATE (5a16f05) is now the
+    // AUTHORITATIVE bracket-lifecycle push (terminal events arrive immediately,
+    // not on this poll) and the 60 s bracket-reconciler unscoped sweep
+    // cross-checks, so this periodic full-algo-view refresh only needs to keep
+    // the dashboard's open-orders panel eventually-consistent — 60 s is
+    // operationally invisible. Still clamped 5 s–5 min + plugin-config
+    // overridable for per-VPS tuning.
+    algoRefreshMs: 60_000,
+    // @deprecated — kept for backward compatibility with existing plugin-config
+    // files. Runtime no longer consults this value (see UserDataStreamController
+    // .buildStreamOptions). 90 s default retained so an old config file doesn't
+    // drift silently on field validation.
+    activeStaleEventWatchdogMs: 90_000,
+    // Active probe (added 2026-04-25). 60 s tick polls fetchMyTrades for every
+    // open-position symbol; if any trade timestamp exceeds lastEventAt, the WS
+    // missed a fill and we force-reconnect. Belt + suspenders alongside the
+    // adaptive watchdog. ~5 weight per open position per probe; with 5 positions
+    // = 25 weight/min, well under the 2400/min budget.
+    activeProbeIntervalMs: 60_000,
+};
+/** Read user-data-stream mode from a config object. Invalid values fall back to 'off'. */
+export function getUserDataStreamMode(config, remoteOverride) {
+    if (remoteOverride && VALID.has(remoteOverride))
+        return remoteOverride;
+    const raw = config?.userDataStream?.mode;
+    if (typeof raw === 'string' && VALID.has(raw)) {
+        return raw;
+    }
+    return 'off';
+}
+/** Convenience: load from disk and return the effective mode. */
+export function loadUserDataStreamMode() {
+    try {
+        return getUserDataStreamMode(readPluginConfig());
+    }
+    catch {
+        // Matches loadBracketMode policy: don't gate trading on a corrupt flag read.
+        return 'off';
+    }
+}
+/** Is the WS stream enabled at all (anything other than 'off')? */
+export function userDataStreamEnabled(mode) {
+    return mode !== 'off';
+}
+/** Read the dbWrite flag.  Orthogonal to `mode`: `mode` controls the read
+ *  path (WS vs REST authoritative for getPositions etc.); `dbWrite` controls
+ *  whether WS-observed fills are POSTed to the webapp's audit-trail store.
+ *  Both must be enabled together for WS rows to land in `trades`. */
+export function getUserDataStreamDbWrite(config) {
+    const raw = config?.userDataStream?.dbWrite;
+    return raw === 'on' ? 'on' : 'off';
+}
+export function loadUserDataStreamDbWrite() {
+    try {
+        return getUserDataStreamDbWrite(readPluginConfig());
+    }
+    catch {
+        return 'off';
+    }
+}
+/** Webapp ingest base URL (POST target).  Defaults to production reefclaw.com. */
+export function getUserDataStreamIngestBaseUrl(config) {
+    const raw = config?.userDataStream?.ingestBaseUrl;
+    if (typeof raw === 'string' && /^https?:\/\//.test(raw))
+        return raw;
+    return 'https://www.reefclaw.com';
+}
+/** Resolve the webapp-ingest credential (the per-user `rc_*` token).
+ *
+ *  Prefers `connectionToken` in plugin-config.json — the same `rc_*` token
+ *  already stored there for the intel-service client, so there's one fewer
+ *  place to update on rotation than the legacy `WEBAPP_INGEST_TOKEN` systemd
+ *  env var. Falls back to that env var so existing deployments that haven't
+ *  moved the token into plugin-config.json keep working unchanged.
+ *
+ *  Both ingest paths (position-decisions journal + WS audit-trail) use this. */
+export function resolveIngestToken(config) {
+    const fromConfig = config?.connectionToken;
+    if (typeof fromConfig === 'string' && fromConfig.trim())
+        return fromConfig.trim();
+    return process.env.WEBAPP_INGEST_TOKEN ?? '';
+}
+/** Is the WS authoritative for reads (observe or enforce)? In shadow it's
+ *  only observed — REST remains the source of truth for getPositions etc. */
+export function userDataStreamAuthoritative(mode) {
+    return mode === 'observe' || mode === 'enforce';
+}
+/** Should REST polling cadence be reduced? True in observe/enforce where
+ *  WS is carrying the hot-path signal and REST is only a truth-check. */
+export function restPollingReduced(mode) {
+    return mode === 'observe' || mode === 'enforce';
+}
+/** Read tunables, falling back to DEFAULT_TUNABLES for any missing field.
+ *  Clamps are defense-in-depth against a truncated or nonsensical config. */
+export function getUserDataStreamTunables(config) {
+    const u = config?.userDataStream;
+    const clamp = (v, fallback, min, max) => {
+        if (typeof v !== 'number' || !Number.isFinite(v) || v < min || v > max)
+            return fallback;
+        return v;
+    };
+    return {
+        // listenKey expires at 60 min; refresh must be below that with margin.
+        listenKeyRefreshMs: clamp(u?.listenKeyRefreshMs, DEFAULT_TUNABLES.listenKeyRefreshMs, 60_000, 55 * 60_000),
+        reconnectBaseMs: clamp(u?.reconnectBaseMs, DEFAULT_TUNABLES.reconnectBaseMs, 100, 10_000),
+        reconnectCapMs: clamp(u?.reconnectCapMs, DEFAULT_TUNABLES.reconnectCapMs, 5_000, 300_000),
+        // Lower bound 4 min — any tighter and Binance's documented 3-min ping
+        // interval can fail to update lastFrameAt (jitter, network blips) and
+        // trigger false reconnects. Upper bound 60 min — beyond that we no longer
+        // catch a dead socket before Binance's own 10-min idle timeout would.
+        staleEventWatchdogMs: clamp(u?.staleEventWatchdogMs, DEFAULT_TUNABLES.staleEventWatchdogMs, 4 * 60_000, 60 * 60_000),
+        // 0 = disabled. Otherwise clamp to a reasonable range: 5s minimum (so we
+        // don't hammer REST), 5 min maximum (beyond that the drift window gets
+        // long enough to forcedResync the whole store anyway).
+        algoRefreshMs: clampOrZero(u?.algoRefreshMs, DEFAULT_TUNABLES.algoRefreshMs, 5_000, 5 * 60_000),
+        // @deprecated — read for backward compat with existing plugin-config files
+        // but the runtime no longer wires this into the watchdog. Clamp range left
+        // intact so a bad value in an old config doesn't cause a validation failure
+        // when re-saving the file.
+        activeStaleEventWatchdogMs: clamp(u?.activeStaleEventWatchdogMs, DEFAULT_TUNABLES.activeStaleEventWatchdogMs, 30_000, 5 * 60_000),
+        // 0 = disabled. 10s minimum to keep weight pressure sensible; 10 min
+        // maximum because a probe that runs less often than the stale watchdog
+        // adds no value.
+        activeProbeIntervalMs: clampOrZero(u?.activeProbeIntervalMs, DEFAULT_TUNABLES.activeProbeIntervalMs, 10_000, 10 * 60_000),
+    };
+}
+function clampOrZero(v, fallback, min, max) {
+    if (v === 0)
+        return 0;
+    if (typeof v !== 'number' || !Number.isFinite(v) || v < min || v > max)
+        return fallback;
+    return v;
+}
+export function loadUserDataStreamTunables() {
+    try {
+        return getUserDataStreamTunables(readPluginConfig());
+    }
+    catch {
+        return { ...DEFAULT_TUNABLES };
+    }
+}
+export function checkTransition(from, to) {
+    if (!VALID.has(from))
+        return { allowed: false, reason: `invalid source mode: ${from}` };
+    if (!VALID.has(to))
+        return { allowed: false, reason: `invalid target mode: ${to}` };
+    if (from === to)
+        return { allowed: true };
+    const stageOrder = ['off', 'shadow', 'observe', 'enforce'];
+    const fromIdx = stageOrder.indexOf(from);
+    const toIdx = stageOrder.indexOf(to);
+    // Reverse transitions always allowed (rollback).
+    if (toIdx < fromIdx)
+        return { allowed: true };
+    // Forward transition — must go through next stage only.
+    const allowed = FORWARD_TRANSITIONS[from];
+    if (!allowed.has(to)) {
+        return {
+            allowed: false,
+            reason: `forward transition ${from} → ${to} skips stages (next allowed: ${[...allowed].join(', ') || '(none)'})`,
+        };
+    }
+    return { allowed: true };
+}

package/assets/plugin/exchange-adapter.d.ts

@@ -0,0 +1,49 @@
+import type { CcxtOrder, CcxtBalance, CcxtPosition, TradingMode } from './types.js';
+import type { PositionMetadata, CloseReason } from './simulator/types.js';
+/** Adapter readiness state machine: INIT_PENDING → READY | DEGRADED | BLOCKED */
+export type AdapterReadiness = 'INIT_PENDING' | 'READY' | 'DEGRADED' | 'BLOCKED';
+/** Options for order submission. */
+export interface OrderOptions {
+    clientOrderId?: string;
+    reduceOnly?: boolean;
+    positionSide?: 'LONG' | 'SHORT' | 'BOTH';
+    emergency?: boolean;
+}
+/**
+ * Common exchange adapter interface.
+ * Implemented by PaperAdapter (wrapping ExchangeSimulator) and LiveAdapter (wrapping BinancePrivateApi).
+ *
+ * Trade tools call adapter methods instead of directly referencing the simulator.
+ * Emergency controls (cancel, close) have NO readiness gate — they ALWAYS work.
+ * Only create_order is blocked when readiness !== 'READY'.
+ */
+export interface IExchangeAdapter {
+    createOrder(symbol: string, side: 'buy' | 'sell', type: 'market' | 'limit', amount: number, price?: number, metadata?: PositionMetadata, options?: OrderOptions): Promise<CcxtOrder>;
+    cancelOrder(orderId: string, symbol?: string): Promise<CcxtOrder>;
+    cancelAllOrders(symbol?: string): Promise<CcxtOrder[]>;
+    /** Close a position at market.
+     *  @param closeReason Tags the resulting Trade record with who initiated the close.
+     *    Paper mode persists it on the closing Trade.metadata.closeReason so the agent
+     *    can see on its next heartbeat that e.g. a stop_watcher auto-closed the trade.
+     *    Live mode currently ignores this (metadata not tracked in live path). */
+    closePosition(symbol: string, closeReason?: CloseReason): Promise<CcxtOrder>;
+    getBalance(): Promise<CcxtBalance>;
+    getPositions(symbol?: string): Promise<CcxtPosition[]>;
+    /**
+     * Like getPositions(), but returns `null` (not `[]`) when the underlying
+     * exchange fetch FAILED (429 / weight-paced / transient) — i.e. position
+     * state is UNKNOWN, not "flat". Decision/destructive paths (flatten, audit,
+     * portfolio snapshot, attach_brackets, reconciler) MUST use this and treat
+     * `null` as "do not act on a phantom-empty account". getPositions() keeps
+     * the `?? []` display contract for the 20+ KPI/display callers
+     * (KPI-must-equal-Binance invariant). Paper adapters never fail a fetch, so
+     * this is equivalent to getPositions() there.
+     */
+    getPositionsOrNull(symbol?: string): Promise<CcxtPosition[] | null>;
+    getOpenOrders(symbol?: string): Promise<CcxtOrder[]>;
+    fetchOrder(orderId: string, symbol?: string): Promise<CcxtOrder | null>;
+    getLastPrice(symbol: string): Promise<number | null>;
+    readonly readiness: AdapterReadiness;
+    readonly mode: TradingMode;
+    readonly isLive: boolean;
+}

package/assets/plugin/exchange-adapter.js

@@ -0,0 +1,4 @@
+// Exchange adapter interface — common abstraction over ExchangeSimulator (paper) and BinancePrivateApi (live).
+// Both PaperAdapter and LiveAdapter implement this interface.
+// All methods return Promise for uniform call sites — paper adapter wraps sync results in Promise.resolve().
+export {};

package/assets/plugin/index.d.ts

@@ -0,0 +1,30 @@
+interface PluginApi {
+    registerTool: (tool: any, opts?: {
+        names?: string[];
+        optional?: boolean;
+    }) => void;
+    config?: any;
+    [key: string]: any;
+}
+declare const paperTradingPlugin: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: {
+        type: "object";
+        properties: {
+            startingBalance: {
+                type: "number";
+                default: number;
+                description: string;
+            };
+            symbol: {
+                type: "string";
+                default: string;
+                description: string;
+            };
+        };
+    };
+    register(api: PluginApi): void;
+};
+export default paperTradingPlugin;