@reefclaw/connect 0.1.11 → 0.1.12

package/assets/plugin/persistence/state-manager.js

@@ -1,222 +0,0 @@
-// State persistence manager for the paper trading simulator.
-// Saves/loads state to ~/.openclaw/plugins/reefclaw-paper-trading/state.json
-// Uses atomic writes (temp file + rename) to prevent corruption.
-import { readFile, writeFile, rename, mkdir, unlink } from 'node:fs/promises';
-import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join, dirname } from 'node:path';
-import { randomUUID } from 'node:crypto';
-import { logger } from '../logger.js';
-import { createDefaultState } from '../simulator/types.js';
-const TAG = 'state-manager';
-export class StateManager {
-    statePath;
-    saveTimer = null;
-    pendingState = null;
-    constructor(pluginId, baseDir) {
-        const base = baseDir ?? join(homedir(), '.openclaw', 'plugins', pluginId);
-        this.statePath = join(base, 'state.json');
-    }
-    getStatePath() {
-        return this.statePath;
-    }
-    /** Quarantine a state file that exists but won't parse, instead of letting
-     *  the caller silently overwrite it with a fresh default (which would wipe
-     *  the positions/orders/realized-PnL ledger). The corrupt bytes are renamed
-     *  to `<state>.corrupt-<ts>` so an operator can recover them. Returns true if
-     *  a corrupt file was quarantined. */
-    quarantineCorruptSync() {
-        if (!existsSync(this.statePath))
-            return false;
-        const dest = `${this.statePath}.corrupt-${Date.now()}`;
-        try {
-            renameSync(this.statePath, dest);
-            logger.error(TAG, `State file at ${this.statePath} is unreadable/corrupt — quarantined to ${dest}. NOT resetting silently; a fresh default will be used. Investigate before trading.`);
-        }
-        catch (err) {
-            logger.error(TAG, `State file at ${this.statePath} is corrupt AND could not be quarantined: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        return true;
-    }
-    /** Load state from disk. Returns null when the file is MISSING (fresh start)
-     *  OR when it exists-but-is-unreadable (in which case the corrupt bytes are
-     *  quarantined first — never silently discarded). The two cases are
-     *  distinguished in the log; both yield null so the caller seeds a default,
-     *  but a corrupt file is preserved as `<state>.corrupt-<ts>`. */
-    async load() {
-        if (!existsSync(this.statePath)) {
-            logger.info(TAG, `No state file found at ${this.statePath}`);
-            return null;
-        }
-        try {
-            const raw = await readFile(this.statePath, 'utf-8');
-            const state = JSON.parse(raw);
-            logger.info(TAG, `Loaded state: ${state.positions.length} positions, ${state.openOrders.length} orders, ${state.tradeHistory.length} trades`);
-            return state;
-        }
-        catch {
-            // Exists but unreadable/corrupt — preserve, don't silently reset.
-            this.quarantineCorruptSync();
-            return null;
-        }
-    }
-    /** Save state atomically (write to a UNIQUE temp, rename to final). A unique
-     *  temp name (pid + uuid) is essential under the two-process model: both the
-     *  agent and gateway processes wire stateChanged→save, and a shared
-     *  `<state>.tmp` let their concurrent writes interleave into a torn file that
-     *  then parses as garbage on next boot. With a per-write temp, the worst case
-     *  degrades to a harmless last-writer-wins rename of two COMPLETE files. */
-    async save(state) {
-        const tmpPath = `${this.statePath}.${process.pid}.${randomUUID()}.tmp`;
-        try {
-            const dir = dirname(this.statePath);
-            if (!existsSync(dir)) {
-                await mkdir(dir, { recursive: true });
-            }
-            await writeFile(tmpPath, JSON.stringify(state, null, 2), 'utf-8');
-            await rename(tmpPath, this.statePath);
-            logger.debug(TAG, 'State saved');
-        }
-        catch (err) {
-            logger.error(TAG, `Failed to save state: ${err instanceof Error ? err.message : String(err)}`);
-            // Best-effort cleanup of the orphaned temp so they don't accumulate.
-            await unlink(tmpPath).catch(() => { });
-        }
-    }
-    /**
-     * Debounced save — coalesces rapid mutations into one write per second.
-     * Call this on every state change; it will save at most once per second.
-     */
-    debouncedSave(state) {
-        this.pendingState = state;
-        if (this.saveTimer)
-            return; // Already scheduled
-        this.saveTimer = setTimeout(() => {
-            this.saveTimer = null;
-            if (this.pendingState) {
-                const s = this.pendingState;
-                this.pendingState = null;
-                this.save(s).catch(() => { });
-            }
-        }, 1000);
-    }
-    /** Flush any pending debounced save immediately. */
-    async flush() {
-        if (this.saveTimer) {
-            clearTimeout(this.saveTimer);
-            this.saveTimer = null;
-        }
-        if (this.pendingState) {
-            const s = this.pendingState;
-            this.pendingState = null;
-            await this.save(s);
-        }
-    }
-    /** Load state or create default if not found. */
-    async loadOrDefault(startingBalance, quoteCurrency) {
-        const loaded = await this.load();
-        if (loaded)
-            return loaded;
-        const state = createDefaultState(startingBalance, quoteCurrency);
-        logger.info(TAG, `Initialized default state: ${startingBalance} ${quoteCurrency}`);
-        await this.save(state);
-        return state;
-    }
-    /** Synchronous load — for use in synchronous plugin register(). Same
-     *  missing-vs-corrupt distinction as load(): a corrupt file is quarantined
-     *  (preserved), never silently overwritten by the default the caller seeds. */
-    loadSync() {
-        if (!existsSync(this.statePath)) {
-            logger.info(TAG, `No state file found at ${this.statePath}`);
-            return null;
-        }
-        try {
-            const raw = readFileSync(this.statePath, 'utf-8');
-            const state = JSON.parse(raw);
-            logger.info(TAG, `Loaded state: ${state.positions.length} positions, ${state.openOrders.length} orders, ${state.tradeHistory.length} trades`);
-            return state;
-        }
-        catch {
-            this.quarantineCorruptSync();
-            return null;
-        }
-    }
-    /** Synchronous load-or-create-default — for use in synchronous plugin register(). */
-    loadOrDefaultSync(startingBalance, quoteCurrency) {
-        const loaded = this.loadSync();
-        if (loaded) {
-            // Venue switch heal (issue #174): a persisted wallet quoted in the OLD
-            // venue's currency reads as $0 equity on the new venue. Migrate 1:1
-            // (USDT↔USDC), preserving total equity exactly.
-            const mig = migratePaperQuoteCurrency(loaded, quoteCurrency);
-            if (mig.migrated) {
-                logger.info(TAG, `Paper wallet quote migrated ${mig.fromQuote} → ${quoteCurrency} (venue switch): ` +
-                    `released ${mig.releasedPositions} open position(s) at entry price, ` +
-                    `dropped ${mig.droppedOrders} unfilled order(s), balances carried 1:1`);
-                this.saveSyncSafe(mig.state, 'migrated');
-            }
-            return mig.state;
-        }
-        const state = createDefaultState(startingBalance, quoteCurrency);
-        logger.info(TAG, `Initialized default state: ${startingBalance} ${quoteCurrency}`);
-        // Save synchronously so state persists immediately
-        this.saveSyncSafe(state, 'initial');
-        return state;
-    }
-    saveSyncSafe(state, label) {
-        try {
-            const dir = dirname(this.statePath);
-            if (!existsSync(dir)) {
-                mkdirSync(dir, { recursive: true });
-            }
-            writeFileSync(this.statePath, JSON.stringify(state, null, 2), 'utf-8');
-        }
-        catch (err) {
-            logger.error(TAG, `Failed to save ${label} state: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-}
-/** Migrate a persisted paper state whose quote currency no longer matches the
- *  configured venue's (issue #174 — e.g. a USDT wallet after switching to the
- *  USDC-quoted hyperliquid venue). Pure; returns the input untouched when the
- *  quotes already match.
- *
- *  Semantics (equity-preserving):
- *  - Open positions are released at their entry price: opening deducted the
- *    full entry notional from the wallet (spot-collateral model), so that
- *    notional is credited back before the position rows — which reference the
- *    OLD venue's symbols and are unpriceable on the new one — are dropped.
- *  - Unfilled open orders never debited the wallet (fills do) — just dropped.
- *  - Balances carry 1:1 (USDT↔USDC are both dollar stables; paper precision),
- *    merging into any existing balance under the new quote.
- *  - Trade history is kept (display-only). savedAt is bumped so the other
- *    process's replaceState() staleness guard accepts the migrated snapshot. */
-export function migratePaperQuoteCurrency(state, expectedQuote) {
-    const fromQuote = state.config?.quoteCurrency ?? 'USDT';
-    if (fromQuote === expectedQuote) {
-        return { state, migrated: false, fromQuote, releasedPositions: 0, droppedOrders: 0 };
-    }
-    const next = JSON.parse(JSON.stringify(state));
-    next.config = { ...next.config, quoteCurrency: expectedQuote };
-    const old = next.wallet[fromQuote] ?? { total: 0, available: 0, locked: 0 };
-    let releasedPositions = 0;
-    for (const pos of next.positions ?? []) {
-        const notional = pos.entryPrice * pos.quantity;
-        if (Number.isFinite(notional) && notional > 0) {
-            old.total += notional;
-            old.available += notional;
-        }
-        releasedPositions++;
-    }
-    const droppedOrders = (next.openOrders ?? []).length;
-    next.positions = [];
-    next.openOrders = [];
-    const target = next.wallet[expectedQuote] ?? { total: 0, available: 0, locked: 0 };
-    target.total += old.total;
-    target.available += old.available;
-    target.locked += old.locked;
-    next.wallet[expectedQuote] = target;
-    delete next.wallet[fromQuote];
-    next.savedAt = Date.now();
-    return { state: next, migrated: true, fromQuote, releasedPositions, droppedOrders };
-}

package/assets/plugin/pinned-plan.d.ts

@@ -1,9 +0,0 @@
-/** Has the agent's pinned invalidation price been reached at the current mark?
- *
- *  Long: invalidated when mark <= invalidationPrice.
- *  Short: invalidated when mark >= invalidationPrice.
- *
- *  Returns undefined when there is nothing to check — no pinned invalidation,
- *  or no usable mark — so a missing plan reads as "unknown", never a false
- *  "not hit". Pure. */
-export declare function computeInvalidationHit(side: 'long' | 'short', markPrice: number | undefined, invalidationPrice: number | undefined): boolean | undefined;

package/assets/plugin/pinned-plan.js

@@ -1,23 +0,0 @@
-// Pinned trade plan — derived indication helpers (Slice 1, Task 5).
-//
-// Pure functions surfaced to the agent at heartbeat (via fetch_positions →
-// CcxtPosition) so it can hold to its OWN plan instead of re-litigating the
-// entry every cycle. Indication only — nothing here enforces anything; the
-// only forced thing on the position is that a protective stop exists.
-/** Has the agent's pinned invalidation price been reached at the current mark?
- *
- *  Long: invalidated when mark <= invalidationPrice.
- *  Short: invalidated when mark >= invalidationPrice.
- *
- *  Returns undefined when there is nothing to check — no pinned invalidation,
- *  or no usable mark — so a missing plan reads as "unknown", never a false
- *  "not hit". Pure. */
-export function computeInvalidationHit(side, markPrice, invalidationPrice) {
-    if (invalidationPrice == null ||
-        !Number.isFinite(invalidationPrice) ||
-        markPrice == null ||
-        !Number.isFinite(markPrice)) {
-        return undefined;
-    }
-    return side === 'long' ? markPrice <= invalidationPrice : markPrice >= invalidationPrice;
-}

package/assets/plugin/portfolio/reentry-tracker.d.ts

@@ -1,36 +0,0 @@
-export interface ReentryExitRecord {
-    /** Canonical symbol (no settle suffix). */
-    symbol: string;
-    /** setup_type / strategy name from the entry metadata, when known. */
-    setupType?: string;
-    side: 'long' | 'short';
-    /** Whether the closed trade realized a loss (drives the stronger caution). */
-    wasLoss?: boolean;
-    closedAtMs: number;
-}
-/** Signal-bar duration for a strategy/setup name. Name-suffix inference:
- *  `..._4h` → 240min, `..._1d` / daily → 1440min, `..._Nh` → N×60. Unknown
- *  shapes default to 60min so short-TF strategies are never over-warned. */
-export declare function strategyBarMinutes(name: string | undefined): number;
-export declare class ReentryTracker {
-    private records;
-    private readonly filePath;
-    private readonly dir;
-    constructor(pluginId?: string, opts?: {
-        basePath?: string;
-    });
-    /** Record a position exit. Never throws (best-effort persistence). */
-    recordExit(record: Omit<ReentryExitRecord, 'symbol'> & {
-        symbol: string;
-    }): void;
-    /** Most recent exit for (symbol[, setup]). A setup-specific record wins over
-     *  a symbol-only match so multi-strategy books get precise cautions. */
-    lastExit(symbol: string, setupType?: string): ReentryExitRecord | undefined;
-    /** Structured caution when (symbol, strategy) was already traded within the
-     *  current signal bar. Undefined = no caution. Pure indication (issue #204):
-     *  the agent decides; nothing here blocks an order. */
-    cautionFor(symbol: string, strategy: string | undefined, nowMs?: number): string | undefined;
-    /** Test seam. */
-    getRecords(): readonly ReentryExitRecord[];
-    private persist;
-}

package/assets/plugin/portfolio/reentry-tracker.js

@@ -1,127 +0,0 @@
-// Re-entry tracker — records recent position exits per (symbol, setup) so the
-// entry funnel (scan_pairs / get_signals) can flag setups the agent already
-// traded within the current signal bar (issue #204).
-//
-// WHY: the validated backtests for the 4h/1d templates have one-trade-per-
-// signal semantics — a signal bar produces at most one trade. Live, the 4h
-// condition stays true for hours, so after every exit the next heartbeat
-// re-entered the same setup: measured 19× the backtest cadence with 79-minute
-// median holds, including 22 same-direction re-entries within one bar of a
-// LOSING close (2026-07-14 → 07-20 HL soak). Per the tools-not-mandates
-// doctrine this ships as STRUCTURED INDICATION — the annotation tells the
-// agent the setup was already traded this bar; it never blocks the order.
-//
-// Persistence: small JSON in the plugins base dir (same pattern as
-// position-state-store) so restarts don't blind the indication. Best-effort —
-// a persistence failure degrades to in-memory-only, never throws into the
-// trading path.
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { logger, formatError } from '../logger.js';
-import { normalizeBracketSymbol } from '../live/bracket-ledger.js';
-import { resolvePluginsBaseDir } from '../util/plugin-paths.js';
-const TAG = 'reentry-tracker';
-const DEFAULT_PLUGIN_ID = 'reefclaw-paper-trading';
-const STATE_FILENAME = 'reentry-log.json';
-const MAX_RECORDS = 300;
-/** Signal-bar duration for a strategy/setup name. Name-suffix inference:
- *  `..._4h` → 240min, `..._1d` / daily → 1440min, `..._Nh` → N×60. Unknown
- *  shapes default to 60min so short-TF strategies are never over-warned. */
-export function strategyBarMinutes(name) {
-    if (!name)
-        return 60;
-    const lower = name.toLowerCase();
-    const hourMatch = lower.match(/_(\d{1,2})h\b|_(\d{1,2})h_|_(\d{1,2})h$/);
-    if (hourMatch) {
-        const h = Number(hourMatch[1] ?? hourMatch[2] ?? hourMatch[3]);
-        if (Number.isFinite(h) && h > 0)
-            return h * 60;
-    }
-    if (/_1d\b|_1d_|_1d$|daily/.test(lower))
-        return 1440;
-    return 60;
-}
-export class ReentryTracker {
-    records = [];
-    filePath;
-    dir;
-    constructor(pluginId, opts) {
-        const base = resolvePluginsBaseDir(opts?.basePath);
-        this.dir = join(base, pluginId ?? DEFAULT_PLUGIN_ID);
-        this.filePath = join(this.dir, STATE_FILENAME);
-        try {
-            if (!existsSync(this.dir))
-                mkdirSync(this.dir, { recursive: true });
-            if (existsSync(this.filePath)) {
-                const parsed = JSON.parse(readFileSync(this.filePath, 'utf-8'));
-                if (Array.isArray(parsed?.records)) {
-                    this.records = parsed.records.filter((r) => typeof r?.symbol === 'string' && Number.isFinite(r?.closedAtMs));
-                }
-            }
-        }
-        catch (err) {
-            logger.warn(TAG, `load failed (${formatError(err)}) — starting empty`);
-            this.records = [];
-        }
-    }
-    /** Record a position exit. Never throws (best-effort persistence). */
-    recordExit(record) {
-        try {
-            this.records.push({ ...record, symbol: normalizeBracketSymbol(record.symbol) });
-            if (this.records.length > MAX_RECORDS) {
-                this.records = this.records.slice(-MAX_RECORDS);
-            }
-            this.persist();
-        }
-        catch (err) {
-            logger.warn(TAG, `recordExit failed: ${formatError(err)}`);
-        }
-    }
-    /** Most recent exit for (symbol[, setup]). A setup-specific record wins over
-     *  a symbol-only match so multi-strategy books get precise cautions. */
-    lastExit(symbol, setupType) {
-        const key = normalizeBracketSymbol(symbol);
-        let bySetup;
-        let bySymbol;
-        for (let i = this.records.length - 1; i >= 0; i--) {
-            const r = this.records[i];
-            if (r.symbol !== key)
-                continue;
-            if (!bySymbol)
-                bySymbol = r;
-            if (setupType && r.setupType === setupType) {
-                bySetup = r;
-                break;
-            }
-            if (!setupType)
-                break;
-        }
-        return bySetup ?? bySymbol;
-    }
-    /** Structured caution when (symbol, strategy) was already traded within the
-     *  current signal bar. Undefined = no caution. Pure indication (issue #204):
-     *  the agent decides; nothing here blocks an order. */
-    cautionFor(symbol, strategy, nowMs = Date.now()) {
-        const last = this.lastExit(symbol, strategy);
-        if (!last)
-            return undefined;
-        const barMin = strategyBarMinutes(strategy ?? last.setupType);
-        const agoMin = Math.round((nowMs - last.closedAtMs) / 60_000);
-        if (agoMin < 0 || agoMin > barMin)
-            return undefined;
-        const lossNote = last.wasLoss ? ' at a LOSS' : '';
-        return (`already traded this signal bar: exited a ${last.side} on this setup ${agoMin}m ago${lossNote} ` +
-            `(bar=${barMin}m). The validated backtest takes ONE trade per signal bar — re-enter only if ` +
-            `you can name what NEW information arrived since that exit.`);
-    }
-    /** Test seam. */
-    getRecords() {
-        return this.records;
-    }
-    persist() {
-        const payload = { schemaVersion: 1, records: this.records };
-        const tmp = `${this.filePath}.tmp`;
-        writeFileSync(tmp, JSON.stringify(payload), 'utf-8');
-        renameSync(tmp, this.filePath);
-    }
-}

package/assets/plugin/portfolio/wave9-admission.d.ts

@@ -1,67 +0,0 @@
-import type { Direction } from '../signals/types.js';
-import { type Wave9StrategyName } from './wave9-policy.js';
-export interface Wave9AdmissionPolicy {
-    riskPct: number;
-    maxPositions: number;
-    maxOpenRiskPct: number;
-    maxGrossExposureMultiple: number;
-    maxPositionUsd: number;
-    feeBps: number;
-    slippageBps: number;
-    capEnforcement: 'admission_only_no_forced_deleveraging';
-    riskMeasure: 'fixed_initial_stop_risk_usd';
-}
-export declare const WAVE9_ADMISSION_POLICY: Readonly<Wave9AdmissionPolicy>;
-export interface Wave9AdmissionPosition {
-    candidateId: string;
-    symbol: string;
-    strategy: Wave9StrategyName;
-    direction: Direction;
-    entryPrice: number;
-    quantity: number;
-    markPrice: number;
-    initialStop: number;
-    dollarRiskUsd: number;
-    accruedFundingUsd: number;
-}
-export interface Wave9AdmissionState {
-    cashEquityUsd: number;
-    positions: Wave9AdmissionPosition[];
-}
-export interface Wave9AdmissionCandidate {
-    id: string;
-    eventTime: string;
-    symbol: string;
-    strategy: Wave9StrategyName;
-    direction: Direction;
-    referencePrice: number;
-    stopPrice: number;
-}
-export type Wave9AdmissionReason = 'accepted' | 'invalidGeometry' | 'symbolAlreadyOpen' | 'maxPositions' | 'maxGrossExposure' | 'maxOpenRisk' | 'invalidSizing';
-export interface Wave9AdmissionLedgerRow extends Wave9AdmissionPosition {
-    estimatedExitCostUsd: number;
-}
-export interface Wave9AdmissionDecision extends Wave9AdmissionCandidate {
-    accepted: boolean;
-    reason: Wave9AdmissionReason;
-    entryPrice?: number;
-    quantity?: number;
-    notionalUsd?: number;
-    riskUsd?: number;
-    projectedCashEquityUsd?: number;
-    projectedLiquidationEquityUsd?: number;
-    projectedGrossExposureUsd?: number;
-    projectedOpenRiskUsd?: number;
-    projectedOpenPositions?: number;
-    projectedPositionLedger?: Wave9AdmissionLedgerRow[];
-}
-export interface Wave9AdmissionBatchResult {
-    decisions: Wave9AdmissionDecision[];
-    state: Wave9AdmissionState;
-}
-/**
- * Apply a same-event candidate batch in the exact frozen priority. The caller
- * must release stops and completed-daily reversals before invoking this
- * function, just as the chronological research engine does.
- */
-export declare function applyWave9AdmissionBatch(inputState: Wave9AdmissionState, rawCandidates: readonly Wave9AdmissionCandidate[], policy?: Readonly<Wave9AdmissionPolicy>): Wave9AdmissionBatchResult;