@reefclaw/connect 0.1.10 → 0.1.12

package/assets/plugin/ingest/readiness-reporter.js

@@ -1,163 +0,0 @@
-// Agent-readiness reporter — runs connect-phase health checks ON the trader's
-// host and POSTs a self-describing report to the webapp, so a silently-broken
-// agent (geo-blocked by Binance, clock-skewed, no tools) surfaces a plain-English
-// dashboard alert instead of a false green. Advisory only: it NEVER blocks
-// trading or the safety floor. See docs/AGENT_READINESS_GATE_PLAN.md (Phase 1).
-//
-// No token → no-op (nothing to authenticate; matches the config poller). A
-// module-level singleton guard mirrors `pluginInitialised` in index.ts — OpenClaw
-// calls register() multiple times per process and we must never spawn a second
-// timer. The interval is unref()'d so it never holds the process open.
-import { makeReadinessCheck, deriveOverallReadiness, } from '@reefclaw/shared';
-import { logger, formatError } from '../logger.js';
-const TAG = 'readiness';
-const DEFAULT_INTERVAL_MS = 300_000; // 5 min — geo/clock state changes rarely.
-const MIN_INTERVAL_MS = 60_000;
-/** Best-effort display fact; kept in sync with the register() banner in index.ts. */
-const PLUGIN_VERSION = '3.8.0';
-function resolveIntervalMs(explicit) {
-    if (explicit && explicit > 0)
-        return Math.max(MIN_INTERVAL_MS, explicit);
-    const raw = Number(process.env.RC_READINESS_INTERVAL_MS);
-    if (!Number.isFinite(raw) || raw <= 0)
-        return DEFAULT_INTERVAL_MS;
-    return Math.max(MIN_INTERVAL_MS, raw);
-}
-/** Run every connect-phase check once and assemble the report. Exported for
- *  unit tests.
- *
- *  `bootWarmup` marks the FIRST cycle, which fires during gateway boot while
- *  the event loop is congested (WS start, snapshot, seed all racing). That
- *  delay between the probe's server-time response and the local `Date.now()`
- *  read inflates the apparent clock drift — observed −4112ms at boot
- *  self-correcting to −108ms on the next 5-min cycle. During warm-up a
- *  warn/fail drift is reported 'unknown' (not amber/red) so the readiness
- *  banner doesn't cry-wolf for ~5 min after every restart; a genuinely
- *  skewed clock still surfaces on cycle 2. */
-export async function collectReadiness(opts, bootWarmup = false) {
-    const now = Date.now();
-    const checks = [];
-    // The venue decides which reachability check this report carries; the copy
-    // for both ids lives in shared/src/readiness.ts. Clock drift comes from the
-    // same probe on both venues (Binance fapi serverTime / Hyperliquid
-    // exchangeStatus.time — live-verified 2026-07-11).
-    const reachId = opts.venue === 'hyperliquid' ? 'hyperliquid_reachable' : 'binance_reachable';
-    // plugin_loaded — trivially true (this code runs inside the loaded plugin),
-    // but a positive row is what proves the report path is alive at all.
-    checks.push(makeReadinessCheck('plugin_loaded', 'pass', { checkedAt: now }));
-    // tools_registered
-    checks.push(makeReadinessCheck('tools_registered', opts.toolCount > 0 ? 'pass' : 'fail', {
-        detail: `${opts.toolCount} tools`,
-        checkedAt: now,
-    }));
-    // venue reachability (+ clock drift from the same probe response)
-    const probe = await opts.publicApi.probeReachability();
-    if (probe.outcome === 'reachable') {
-        checks.push(makeReadinessCheck(reachId, 'pass', { checkedAt: now }));
-        const drift = probe.driftMs;
-        if (drift == null) {
-            checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
-        }
-        else {
-            const abs = Math.abs(drift);
-            const rawStatus = abs <= 1000 ? 'pass' : abs <= 5000 ? 'warn' : 'fail';
-            // Boot warm-up: a non-pass reading on the first cycle is untrustworthy
-            // (event-loop congestion inflates the measured drift) — report 'unknown'
-            // and let the next cycle confirm, rather than flash the banner amber/red.
-            const status = bootWarmup && rawStatus !== 'pass' ? 'unknown' : rawStatus;
-            checks.push(makeReadinessCheck('clock_in_sync', status, {
-                detail: bootWarmup && rawStatus !== 'pass'
-                    ? `drift ${Math.round(drift)}ms (boot warm-up — rechecking)`
-                    : `drift ${Math.round(drift)}ms`,
-                checkedAt: now,
-            }));
-        }
-    }
-    else if (probe.outcome === 'geo_blocked') {
-        checks.push(makeReadinessCheck(reachId, 'fail', {
-            detail: opts.venue === 'binance' ? 'HTTP 451' : 'blocked (HTTP 451/403)',
-            checkedAt: now,
-        }));
-        checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
-    }
-    else if (probe.outcome === 'unreachable') {
-        // Network/DNS/timeout — could be transient, so warn (amber) rather than
-        // asserting a definitive failure. A persistent problem stays amber across
-        // re-checks; only the geo-block is a hard red.
-        checks.push(makeReadinessCheck(reachId, 'warn', { detail: 'unreachable', checkedAt: now }));
-        checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
-    }
-    else {
-        // 'unknown' — the ban/weight gate paused the probe; don't assert anything.
-        checks.push(makeReadinessCheck(reachId, 'unknown', { checkedAt: now }));
-        checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
-    }
-    return {
-        schemaVersion: 1,
-        generatedAt: now,
-        overall: deriveOverallReadiness(checks),
-        checks,
-        agent: { pluginVersion: PLUGIN_VERSION, toolCount: opts.toolCount, venue: opts.venue },
-    };
-}
-async function postReadiness(apiBaseUrl, token, report, fetchImpl, timeoutMs) {
-    const url = `${apiBaseUrl.replace(/\/+$/, '')}/api/internal/agent-readiness`;
-    const ac = new AbortController();
-    const tid = setTimeout(() => ac.abort(), timeoutMs);
-    try {
-        const res = await fetchImpl(url, {
-            method: 'POST',
-            headers: {
-                'content-type': 'application/json',
-                authorization: `Bearer ${token}`,
-            },
-            body: JSON.stringify(report),
-            signal: ac.signal,
-        });
-        if (res.status < 200 || res.status >= 300) {
-            logger.warn(TAG, `POST ${url} → ${res.status}`);
-        }
-    }
-    catch (err) {
-        logger.warn(TAG, `readiness POST failed: ${formatError(err)}`);
-    }
-    finally {
-        clearTimeout(tid);
-    }
-}
-let reporterStarted = false;
-/** Test-only — reset the singleton guard between unit tests. */
-export function __resetReadinessReporterForTests() {
-    reporterStarted = false;
-}
-/** Fire the readiness report once at boot then on an unref'd interval. */
-export function startReadinessReporter(opts) {
-    if (reporterStarted)
-        return;
-    if (!opts.token || !opts.token.trim()) {
-        logger.info(TAG, 'no connection token — readiness reporting disabled');
-        return;
-    }
-    reporterStarted = true;
-    const fetchImpl = opts.fetchImpl ?? fetch;
-    const intervalMs = resolveIntervalMs(opts.intervalMs);
-    const timeoutMs = opts.requestTimeoutMs ?? 10_000;
-    const cycle = async (bootWarmup) => {
-        try {
-            const report = await collectReadiness({ venue: opts.venue, publicApi: opts.publicApi, toolCount: opts.toolCount }, bootWarmup);
-            await postReadiness(opts.apiBaseUrl, opts.token, report, fetchImpl, timeoutMs);
-            if (report.overall === 'fail') {
-                const failing = report.checks.filter((c) => c.status === 'fail').map((c) => c.id).join(', ');
-                logger.warn(TAG, `readiness FAIL: ${failing}`);
-            }
-        }
-        catch (err) {
-            logger.warn(TAG, `readiness cycle failed: ${formatError(err)}`);
-        }
-    };
-    // First fire is the boot cycle (warm-up); the interval cycles are steady-state.
-    void cycle(true);
-    const timer = setInterval(() => void cycle(false), intervalMs);
-    timer.unref();
-    logger.info(TAG, `readiness reporter started (interval ${Math.round(intervalMs / 1000)}s)`);
-}

package/assets/plugin/ingest/reconcile-db-vs-exchange.d.ts

@@ -1,13 +0,0 @@
-import type { PositionDecisionsClient } from './position-decisions-client.js';
-export interface DbVsExchangeContext {
-    decisionsClient?: PositionDecisionsClient;
-    userId?: string;
-}
-/**
- * Close webapp `positions` rows that are status='open' but absent from the
- * (trusted) exchange snapshot. Returns the number of synthetic closes posted.
- *
- * @param exchangeSymbols symbols from a TRUSTED snapshot (getPositionsOrNull()
- *        !== null). Pass only when the fetch genuinely succeeded.
- */
-export declare function reconcileDbOpenVsExchange(ctx: DbVsExchangeContext, exchangeSymbols: Iterable<string>, nowMs?: number): Promise<number>;

package/assets/plugin/ingest/reconcile-db-vs-exchange.js

@@ -1,114 +0,0 @@
-// DB-authoritative orphan close (Increment 0 of the durable orphan-position fix).
-//
-// The problem the existing backstops can't solve: a position closed on the
-// exchange (bracket SL/TP fill or manual close) while the gateway was DOWN, or
-// whose state-store entry was already wiped, leaves webapp `positions.status`
-// stuck 'open' forever. reconcileStateStoreOnStartup can't help — it iterates
-// only LOCAL state-store entries (a wiped entry is invisible) and passes
-// lastContracts:0 (which trips the fillSize>0 guard, so it never posts a close).
-//
-// This pass is DB-authoritative: it asks the webapp for the open set (keyed by
-// the DB row id, not local state), diffs against the EXCHANGE TRUTH snapshot,
-// and posts a synthetic close for any open DB row whose symbol is absent from
-// the exchange. Keying off the DB row id means a missing webappPositionId /
-// wiped state-store / untracked contracts can't defeat it for the common
-// one-row-per-symbol case.
-//
-// Known limitations (all fail SAFE — only false-negatives, never a wrong close):
-//   - Diff is symbol-membership only. If a symbol has BOTH a genuine orphan and
-//     a freshly re-opened live position (two open rows, same symbol, different
-//     positionOpenAt), the symbol is on the exchange so NEITHER is closed — the
-//     orphan persists until the next boot when that symbol is flat. A later
-//     increment can make this count-aware (close the M−N oldest-by-openedAt when
-//     the DB has M open rows but the exchange has N<M for the symbol).
-//   - First-writer-wins on position_closes UNIQUE(position_id): if a real
-//     close_position's journal POST is still retrying at boot, a synthetic close
-//     can land first and the accurate PnL becomes a no-op. Synthetic rows are
-//     tagged (metadata.synthetic) so a later increment could upgrade them.
-//   - closeAt is stamped at boot, not the real (earlier) exchange close time, so
-//     time-in-position analytics on these rows are approximate. Tagged synthetic.
-//
-// Safety (mandatory): the caller MUST pass a TRUSTED exchange snapshot
-// (getPositionsOrNull() !== null). A failed REST fetch collapses to [] in
-// getPositions(), which would make EVERY open row look orphaned — never run
-// this pass off an untrusted/empty-on-error snapshot.
-//
-// Idempotency: position_closes is UNIQUE(position_id) with onConflictDoNothing,
-// and the parent status flip is idempotent — a real close_position (exact PnL)
-// that lands first always wins the UNIQUE. closeReason='reconciler_observed_flat'
-// + metadata.synthetic=true tags these for KPI exclusion.
-import { logger } from '../logger.js';
-const TAG = 'reconcile-db-vs-exchange';
-/** Canonicalise a symbol to its settle-suffix-free form (BTC/USDT:USDT → BTC/USDT). */
-function canonical(symbol) {
-    return symbol.split(':')[0];
-}
-/**
- * Close webapp `positions` rows that are status='open' but absent from the
- * (trusted) exchange snapshot. Returns the number of synthetic closes posted.
- *
- * @param exchangeSymbols symbols from a TRUSTED snapshot (getPositionsOrNull()
- *        !== null). Pass only when the fetch genuinely succeeded.
- */
-export async function reconcileDbOpenVsExchange(ctx, exchangeSymbols, nowMs = Date.now()) {
-    if (!ctx.decisionsClient || !ctx.userId)
-        return 0;
-    const resp = await ctx.decisionsClient.getOpenPositions(ctx.userId);
-    if (!resp) {
-        // null = fetch failed (network / terminal). NEVER treat as "no open rows"
-        // (null≠empty) — skip; the next boot / periodic sweep retries.
-        logger.warn(TAG, 'DB open-positions fetch returned null — skipping reconcile (will retry)');
-        return 0;
-    }
-    if (resp.positions.length === 0)
-        return 0;
-    const exchangeSet = new Set();
-    for (const s of exchangeSymbols)
-        exchangeSet.add(canonical(s));
-    const orphans = resp.positions.filter((p) => !exchangeSet.has(canonical(p.symbol)));
-    if (orphans.length === 0) {
-        logger.info(TAG, `DB reconcile: all ${resp.positions.length} open row(s) present on exchange`);
-        return 0;
-    }
-    logger.warn(TAG, `DB reconcile: ${orphans.length} open DB row(s) absent from exchange — closing: ${orphans.map((o) => o.symbol).join(', ')}`);
-    let posted = 0;
-    for (const o of orphans) {
-        if (!(o.remainingSize > 0) || !(o.entryPrice > 0)) {
-            logger.warn(TAG, `${o.symbol}: bad size/price from DB (size=${o.remainingSize}, entry=${o.entryPrice}) — skipping close`);
-            continue;
-        }
-        const close = {
-            positionId: o.id,
-            closeAt: nowMs,
-            closeReason: 'reconciler_observed_flat',
-            closeAssessment: {
-                source: 'db_exchange_sweep_boot',
-                synthetic: true,
-                note: 'Position open in DB but absent from the exchange snapshot. It was ' +
-                    'closed on-exchange via a path that bypassed close_position (bracket ' +
-                    'SL/TP fill or manual close). Synthetic close; PnL/R/MFE recomputed ' +
-                    'server-side from the entry + last review.',
-                openedAtMs: o.openedAt,
-            },
-            // Synthetic-but-neutral context. Tagged so KPI aggregation can exclude it.
-            scorecardVerdict: 'unknown',
-            confluenceScore: 0,
-            regime: 'UNKNOWN',
-            regimeConfidence: 0,
-            // The true exit price wasn't captured; use the entry so the server-side
-            // recompute yields ~0 realized PnL (honest "unknown") rather than a
-            // fabricated number. R/MFE/give-back come from the last review row.
-            fillPrice: o.entryPrice,
-            fillSize: o.remainingSize,
-            realizedPnl: 0,
-            realizedR: 0,
-            mfeRAtClose: 0,
-            giveBackPctAtClose: 0,
-            metadata: { synthetic: true, source: 'boot_reconcile' },
-        };
-        ctx.decisionsClient.postClose(ctx.userId, close);
-        posted++;
-        logger.info(TAG, `synthetic close posted ${o.symbol} (positionId=${o.id.slice(0, 8)}…, size=${o.remainingSize})`);
-    }
-    return posted;
-}

package/assets/plugin/ingest/reconciler-cleanup.d.ts

@@ -1,37 +0,0 @@
-import type { PositionDecisionsClient } from './position-decisions-client.js';
-import type { PositionStateStore } from '../live/position-state-store.js';
-export interface ReconcilerCleanupContext {
-    decisionsClient?: PositionDecisionsClient;
-    stateStore?: PositionStateStore;
-    userId?: string;
-    /** Last-price fetcher. Plugin-side passes a closure over
-     *  `adapter.getLastPrice`. Tests inject a mock. Returning `null` skips
-     *  the webapp close post (state-store still cleaned). */
-    lastPriceFn?: (symbol: string) => Promise<number | null>;
-}
-export interface CloseObservedArgs {
-    /** Symbol observed flat. Either canonical (`BTC/USDT`) or settle-suffix
-     *  (`BTC/USDT:USDT`) form — state-store normalises internally. */
-    symbol: string;
-    /** Last contracts seen by reconciler before exchange showed flat. Used as
-     *  fillSize on the synthetic close payload. */
-    lastContracts: number;
-    /** Epoch ms — when reconciler observed the close. Defaults to Date.now(). */
-    observedAtMs?: number;
-}
-export declare function onReconcilerObservedClose(ctx: ReconcilerCleanupContext, args: CloseObservedArgs): Promise<void>;
-/** Startup-time reconciliation between state-store and exchange truth.
- *
- *  Why this exists: the in-memory reconciler only emits `closed` drifts on
- *  the exact transition "was on exchange last poll, gone now". State-store
- *  entries that persist across a close-bypass that happened BEFORE the plugin
- *  started are invisible to that loop — they sit in `position-state.json`
- *  forever and the next entry on the same symbol gets mistaken for a scale-in.
- *
- *  This pass runs once at boot, after the live adapter is initialised:
- *  for every state-store entry, if the symbol isn't on the current exchange
- *  snapshot, fire the same cleanup as the runtime hook would.
- *
- *  Returns the count of entries cleaned (for log + telemetry).
- */
-export declare function reconcileStateStoreOnStartup(ctx: ReconcilerCleanupContext, exchangeSymbols: Iterable<string>): Promise<number>;

package/assets/plugin/ingest/reconciler-cleanup.js

@@ -1,147 +0,0 @@
-// Reconciler-driven cleanup for the close-bypass-leaks-state class-of-bug.
-//
-// Background: when a position closes via any path other than close_position()
-// — i.e., bracket SL/TP fill, opposite-side market order, or external close on
-// the exchange UI — onClosePositionFilled never runs. Two pieces of state leak:
-//
-//   1. webapp `positions.status` stays 'open' indefinitely (until a manual
-//      `scripts/reconcile-open-positions.py` sweep).
-//   2. `position-state.json` keeps the entry with its stale `webappPositionId`.
-//      The next entry on the same symbol is then mistaken for a scale-in and
-//      reviews silently drop because the cached id no longer maps to a live
-//      DB row.
-//
-// All three close-bypass paths converge on the same observable: the next
-// reconciler tick (60 s cadence) sees the symbol gone from `getPositions()`
-// and emits a `drift_detected` event with `type='closed'`. We hook there.
-//
-// Two-phase cleanup:
-//   Phase 1 — synthetic close to webapp (best-effort): if the state-store
-//             entry has a `webappPositionId` and we can fetch a last price,
-//             POST `/api/internal/position-closes` with a stub close payload
-//             tagged `closeReason='reconciler_observed_flat'`. Webapp
-//             recomputes realized PnL/R/MFE server-side from positionEntries +
-//             last review (the same path the close auto-capture uses).
-//   Phase 2 — state-store cleanup (unconditional): drop the entry. This is
-//             the more important half — it prevents the next entry on the
-//             same symbol from being mistaken for a scale-in.
-//
-// Idempotency:
-//   - webapp endpoint dedups via UNIQUE on position_id (onConflictDoNothing).
-//   - state-store remove is a no-op if the entry is already gone.
-// Re-firing on subsequent reconciler ticks is safe.
-//
-// Failure mode tradeoff: when no last-price is reachable, we skip the webapp
-// post but still clean state-store. The DB row stays 'open' until manual
-// reconcile (existing operator workflow). State-store cleanup alone closes
-// the next-entry-mistaken-for-scale-in failure mode, which is the harder one
-// to recover from.
-import { logger } from '../logger.js';
-const TAG = 'reconciler-cleanup';
-export async function onReconcilerObservedClose(ctx, args) {
-    if (!ctx.stateStore)
-        return;
-    const entry = ctx.stateStore.get(args.symbol);
-    if (!entry) {
-        // Already clean. Could happen if close_position fired between the WS
-        // close fill and this reconciler tick — onClosePositionFilled removed the
-        // entry first. Silent no-op.
-        return;
-    }
-    const webappPositionId = entry.webappPositionId;
-    const observedAtMs = args.observedAtMs ?? Date.now();
-    if (webappPositionId && ctx.decisionsClient && ctx.userId) {
-        let lastPrice = null;
-        if (ctx.lastPriceFn) {
-            try {
-                lastPrice = await ctx.lastPriceFn(args.symbol);
-            }
-            catch (err) {
-                logger.warn(TAG, `lastPriceFn(${args.symbol}) threw: ${err instanceof Error ? err.message : String(err)} — synthetic close will be skipped`);
-            }
-        }
-        const fillSize = Math.abs(args.lastContracts);
-        if (lastPrice !== null && lastPrice > 0 && fillSize > 0) {
-            const close = {
-                positionId: webappPositionId,
-                closeAt: observedAtMs,
-                closeReason: 'reconciler_observed_flat',
-                closeAssessment: {
-                    note: 'Position observed flat on exchange via reconciler. Close path ' +
-                        'bypassed close_position (likely bracket SL/TP fill, opposite-side ' +
-                        'market order, or external close). Synthetic close row.',
-                    observedAtMs,
-                    lastContracts: args.lastContracts,
-                },
-                scorecardVerdict: 'NO_GO',
-                confluenceScore: 0,
-                regime: 'unknown',
-                regimeConfidence: 0.5,
-                fillPrice: lastPrice,
-                fillSize,
-                // Webapp recomputes these server-side from positionEntries + last
-                // review when all four arrive as zero (same code path the close
-                // auto-capture uses).
-                realizedPnl: 0,
-                realizedR: 0,
-                mfeRAtClose: 0,
-                giveBackPctAtClose: 0,
-            };
-            ctx.decisionsClient.postClose(ctx.userId, close);
-            logger.info(TAG, `synthetic close posted ${args.symbol} ` +
-                `(positionId=${webappPositionId.slice(0, 8)}…, ` +
-                `price=${lastPrice}, size=${fillSize})`);
-        }
-        else {
-            logger.warn(TAG, `${args.symbol}: cannot post synthetic close ` +
-                `(lastPrice=${lastPrice ?? 'null'}, size=${fillSize}); ` +
-                `state-store entry will still be cleaned. DB row may stay ` +
-                `status='open' until reconcile-open-positions.py runs.`);
-        }
-    }
-    else if (!webappPositionId) {
-        logger.info(TAG, `${args.symbol}: orphan entry (no webappPositionId, parent row never created) — cleaning state-store only`);
-    }
-    ctx.stateStore.remove(args.symbol);
-}
-/** Startup-time reconciliation between state-store and exchange truth.
- *
- *  Why this exists: the in-memory reconciler only emits `closed` drifts on
- *  the exact transition "was on exchange last poll, gone now". State-store
- *  entries that persist across a close-bypass that happened BEFORE the plugin
- *  started are invisible to that loop — they sit in `position-state.json`
- *  forever and the next entry on the same symbol gets mistaken for a scale-in.
- *
- *  This pass runs once at boot, after the live adapter is initialised:
- *  for every state-store entry, if the symbol isn't on the current exchange
- *  snapshot, fire the same cleanup as the runtime hook would.
- *
- *  Returns the count of entries cleaned (for log + telemetry).
- */
-export async function reconcileStateStoreOnStartup(ctx, exchangeSymbols) {
-    if (!ctx.stateStore)
-        return 0;
-    // Normalise the exchange symbol list — state-store stores canonical form.
-    const exchangeSet = new Set();
-    for (const sym of exchangeSymbols) {
-        exchangeSet.add(sym.split(':')[0]);
-    }
-    const stale = ctx.stateStore.getAll().filter((e) => !exchangeSet.has(e.symbol));
-    if (stale.length === 0) {
-        logger.info(TAG, `startup reconcile: state-store clean (${ctx.stateStore.size()} entries match exchange)`);
-        return 0;
-    }
-    logger.warn(TAG, `startup reconcile: ${stale.length} stale state-store entr${stale.length === 1 ? 'y' : 'ies'} ` +
-        `not on exchange — cleaning: ${stale.map((e) => e.symbol).join(', ')}`);
-    for (const entry of stale) {
-        await onReconcilerObservedClose(ctx, {
-            symbol: entry.symbol,
-            // We don't know the closing size — pass 0 so the synthetic close
-            // post is skipped (size validation in cleanup). State-store entry
-            // is still removed. Operator runs reconcile-open-positions.py to
-            // close any matching DB rows.
-            lastContracts: 0,
-        });
-    }
-    return stale.length;
-}