@reefclaw/openclaw-plugin 0.1.0

package/tools/check-position-health.js

@@ -0,0 +1,194 @@
+// Tool: check_position_health — Real-time position health monitor.
+// Computes heat, stop proximity, time-in-trade, and risk flags for open positions.
+// Pure local computation — no API calls needed.
+export function checkPositionHealthTool(args) {
+    const { positions, account_balance } = args;
+    if (!positions || positions.length === 0) {
+        return {
+            positions: [],
+            portfolio: {
+                totalHeat: 0,
+                totalNotional: 0,
+                totalPnl: 0,
+                positionCount: 0,
+                heatStatus: 'LOW',
+                alerts: [],
+            },
+        };
+    }
+    if (account_balance <= 0) {
+        return {
+            positions: [],
+            portfolio: {
+                totalHeat: 0,
+                totalNotional: 0,
+                totalPnl: 0,
+                positionCount: 0,
+                heatStatus: 'CRITICAL',
+                alerts: ['Account balance is zero or negative'],
+            },
+        };
+    }
+    const now = Date.now();
+    const portfolioAlerts = [];
+    let totalHeat = 0;
+    let totalNotional = 0;
+    let totalPnl = 0;
+    const healthResults = positions.map((pos) => {
+        const alerts = [];
+        const dirMul = pos.side === 'LONG' ? 1 : -1;
+        // ── P&L ──
+        const pnl = (pos.current_price - pos.entry_price) * pos.quantity * dirMul;
+        const notional = pos.entry_price * pos.quantity;
+        const pnlPercent = notional > 0 ? (pnl / notional) * 100 : 0;
+        // Risk per unit = distance from entry to stop
+        const riskPerUnit = Math.abs(pos.entry_price - pos.stop_price);
+        const riskAmount = riskPerUnit * pos.quantity;
+        const pnlR = riskAmount > 0 ? pnl / riskAmount : 0;
+        // ── Stop tracking ──
+        const distToStop = pos.side === 'LONG'
+            ? pos.current_price - pos.stop_price
+            : pos.stop_price - pos.current_price;
+        const distanceToStopPercent = pos.current_price > 0 ? (distToStop / pos.current_price) * 100 : 0;
+        const distanceToStopR = riskPerUnit > 0 ? distToStop / riskPerUnit : 0;
+        let stopStatus;
+        if (distToStop <= 0) {
+            stopStatus = 'BREACHED';
+            alerts.push(`STOP BREACHED — price has passed stop level ($${pos.stop_price})`);
+        }
+        else if (distanceToStopR < 0.3) {
+            stopStatus = 'CRITICAL';
+            alerts.push(`Stop critically close (${distanceToStopR.toFixed(2)}R away)`);
+        }
+        else if (distanceToStopR < 0.7) {
+            stopStatus = 'CLOSE';
+            alerts.push(`Stop approaching (${distanceToStopR.toFixed(2)}R away)`);
+        }
+        else {
+            stopStatus = 'SAFE';
+        }
+        // ── Target tracking ──
+        let distanceToTargetPercent = null;
+        let distanceToTargetR = null;
+        let targetReached = false;
+        if (pos.target_price != null) {
+            const distToTarget = pos.side === 'LONG'
+                ? pos.target_price - pos.current_price
+                : pos.current_price - pos.target_price;
+            distanceToTargetPercent = pos.current_price > 0 ? (distToTarget / pos.current_price) * 100 : 0;
+            distanceToTargetR = riskPerUnit > 0 ? distToTarget / riskPerUnit : 0;
+            targetReached = distToTarget <= 0;
+            if (targetReached) {
+                alerts.push('TARGET REACHED — consider taking profit');
+            }
+        }
+        // If past target but still holding
+        if (pnlR >= 2 && !targetReached) {
+            alerts.push(`At ${pnlR.toFixed(1)}R profit — consider trailing stop or partial take-profit`);
+        }
+        // ── Heat (position risk as % of account) ──
+        const heatPercent = (riskAmount / account_balance) * 100;
+        const notionalPercent = (notional / account_balance) * 100;
+        if (heatPercent > 5) {
+            alerts.push(`High heat: ${heatPercent.toFixed(1)}% of account at risk in this position`);
+        }
+        else if (heatPercent > 3) {
+            alerts.push(`Elevated heat: ${heatPercent.toFixed(1)}% of account at risk`);
+        }
+        totalHeat += heatPercent;
+        totalNotional += notional;
+        totalPnl += pnl;
+        // ── Time in trade ──
+        const entryMs = new Date(pos.entry_time).getTime();
+        const elapsed = Math.max(0, now - entryMs);
+        const minutes = Math.floor(elapsed / 60_000);
+        const hours = Math.floor(minutes / 60);
+        let timeFormatted;
+        if (hours >= 24) {
+            const days = Math.floor(hours / 24);
+            timeFormatted = `${days}d ${hours % 24}h`;
+        }
+        else if (hours > 0) {
+            timeFormatted = `${hours}h ${minutes % 60}m`;
+        }
+        else {
+            timeFormatted = `${minutes}m`;
+        }
+        let timeStatus;
+        if (minutes < 15)
+            timeStatus = 'FRESH';
+        else if (minutes < 240)
+            timeStatus = 'NORMAL';
+        else if (minutes < 720) {
+            timeStatus = 'EXTENDED';
+            if (pnlR < 0)
+                alerts.push(`Held ${timeFormatted} underwater — review thesis`);
+        }
+        else {
+            timeStatus = 'STALE';
+            alerts.push(`Position held ${timeFormatted} — is original thesis still valid?`);
+        }
+        // Underwater for too long
+        if (pnlR < -0.5 && minutes > 60) {
+            alerts.push(`Underwater (${pnlR.toFixed(1)}R) for ${timeFormatted} — thesis may be invalid`);
+        }
+        return {
+            symbol: pos.symbol,
+            side: pos.side,
+            pnl: +pnl.toFixed(2),
+            pnlPercent: +pnlPercent.toFixed(2),
+            pnlR: +pnlR.toFixed(2),
+            distanceToStopPercent: +distanceToStopPercent.toFixed(2),
+            distanceToStopR: +distanceToStopR.toFixed(2),
+            stopStatus,
+            distanceToTargetPercent: distanceToTargetPercent != null ? +distanceToTargetPercent.toFixed(2) : null,
+            distanceToTargetR: distanceToTargetR != null ? +distanceToTargetR.toFixed(2) : null,
+            targetReached,
+            heatPercent: +heatPercent.toFixed(2),
+            notionalPercent: +notionalPercent.toFixed(2),
+            timeInTradeMinutes: minutes,
+            timeInTradeFormatted: timeFormatted,
+            timeStatus,
+            alerts,
+        };
+    });
+    // ── Portfolio-level assessment ──
+    let heatStatus;
+    if (totalHeat >= 15) {
+        heatStatus = 'CRITICAL';
+        portfolioAlerts.push(`CRITICAL portfolio heat: ${totalHeat.toFixed(1)}% — reduce exposure immediately`);
+    }
+    else if (totalHeat >= 10) {
+        heatStatus = 'HIGH';
+        portfolioAlerts.push(`High portfolio heat: ${totalHeat.toFixed(1)}% — no new positions`);
+    }
+    else if (totalHeat >= 6) {
+        heatStatus = 'ELEVATED';
+        portfolioAlerts.push(`Elevated portfolio heat: ${totalHeat.toFixed(1)}% — be cautious with new entries`);
+    }
+    else if (totalHeat >= 3) {
+        heatStatus = 'MODERATE';
+    }
+    else {
+        heatStatus = 'LOW';
+    }
+    const breachedCount = healthResults.filter(p => p.stopStatus === 'BREACHED').length;
+    if (breachedCount > 0) {
+        portfolioAlerts.push(`${breachedCount} position(s) past stop level — exit immediately`);
+    }
+    const criticalCount = healthResults.filter(p => p.stopStatus === 'CRITICAL').length;
+    if (criticalCount > 0) {
+        portfolioAlerts.push(`${criticalCount} position(s) critically close to stop`);
+    }
+    return {
+        positions: healthResults,
+        portfolio: {
+            totalHeat: +totalHeat.toFixed(2),
+            totalNotional: +totalNotional.toFixed(2),
+            totalPnl: +totalPnl.toFixed(2),
+            positionCount: positions.length,
+            heatStatus,
+            alerts: portfolioAlerts,
+        },
+    };
+}

package/tools/clear-exchange-credentials.d.ts

@@ -0,0 +1,24 @@
+import type { PluginRuntime } from '../onboarding/runtime.js';
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { TradingMode } from '../types.js';
+export interface ClearExchangeCredentialsArgs {
+    /** Must be `true`. Required so the skill's tool-discovery probe (which
+     *  passes empty args) never accidentally wipes credentials on startup. */
+    confirm?: boolean;
+}
+export interface ClearExchangeCredentialsResult {
+    ok: boolean;
+    message: string;
+    modeBefore: TradingMode;
+    mode: TradingMode;
+    rolledBackToPaper: boolean;
+    readiness: string;
+}
+export interface ClearExchangeCredentialsDeps {
+    runtime: PluginRuntime;
+    adapterDeps: {
+        adapter: IExchangeAdapter;
+    };
+    configPath?: string;
+}
+export declare function clearExchangeCredentialsTool(args: ClearExchangeCredentialsArgs, deps: ClearExchangeCredentialsDeps): Promise<ClearExchangeCredentialsResult>;

package/tools/clear-exchange-credentials.js

@@ -0,0 +1,70 @@
+// clear_exchange_credentials — operator-only plugin tool.
+//
+// Removes the `exchange` section from ~/.reefclaw/plugin-config.json and,
+// if the plugin is currently running in a mode that requires credentials
+// (SHADOW, MICRO_LIVE, LIVE), de-escalates to PAPER via runtime.reconnect().
+// This is the "pull the plug" button for when the operator wants to
+// remove Binance keys from the machine entirely.
+//
+// Security:
+//   - Does NOT accept a new secret — pure delete.
+//   - Always de-escalates to PAPER on mode rollback; never stays in a
+//     live mode without credentials (would crash the adapter on first
+//     order anyway).
+import { updatePluginConfig } from '../config/plugin-config-io.js';
+import { logger } from '../logger.js';
+const TAG = 'clear-exchange-credentials';
+export async function clearExchangeCredentialsTool(args, deps) {
+    const modeBefore = deps.runtime.mode;
+    if (args?.confirm !== true) {
+        return {
+            ok: false,
+            message: 'clear_exchange_credentials requires confirm: true (prevents accidental probe wipes)',
+            modeBefore,
+            mode: modeBefore,
+            rolledBackToPaper: false,
+            readiness: deps.runtime.adapter.readiness,
+        };
+    }
+    try {
+        updatePluginConfig({ exchange: undefined }, deps.configPath);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.error(TAG, `Failed to clear credentials: ${msg}`);
+        return {
+            ok: false,
+            message: `Failed to remove credentials from config: ${msg}`,
+            modeBefore,
+            mode: modeBefore,
+            rolledBackToPaper: false,
+            readiness: deps.runtime.adapter.readiness,
+        };
+    }
+    logger.info(TAG, 'Exchange credentials cleared from plugin-config.json');
+    // If we were in a live mode, fall back to PAPER — running SHADOW or
+    // MICRO_LIVE without credentials is a guaranteed broken state.
+    let rolledBackToPaper = false;
+    if (modeBefore !== 'PAPER') {
+        try {
+            // Also persist the mode downgrade so a subsequent restart doesn't
+            // try to bring up a live adapter with no credentials.
+            updatePluginConfig({ tradingMode: 'PAPER' }, deps.configPath);
+        }
+        catch (err) {
+            logger.warn(TAG, `Failed to persist PAPER fallback: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        await deps.runtime.reconnect({ mode: 'PAPER', exchange: null }, { adapterDeps: deps.adapterDeps });
+        rolledBackToPaper = true;
+    }
+    return {
+        ok: true,
+        message: rolledBackToPaper
+            ? `Credentials cleared and trading mode rolled back from ${modeBefore} to PAPER`
+            : 'Credentials cleared',
+        modeBefore,
+        mode: deps.runtime.mode,
+        rolledBackToPaper,
+        readiness: deps.runtime.adapter.readiness,
+    };
+}

package/tools/close-position.d.ts

@@ -0,0 +1,22 @@
+import type { BinancePublicApi } from '../ccxt/binance-public.js';
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { CcxtOrder } from '../types.js';
+import { type ClosePositionArgs } from './assessment-validation.js';
+import { type AutoCaptureContext } from '../ingest/position-auto-capture.js';
+import { type ExitGateMode } from '../config/position-review-config.js';
+export declare function closePositionTool(args: ClosePositionArgs, deps: {
+    binanceApi: BinancePublicApi;
+    adapter: IExchangeAdapter;
+    autoCapture?: AutoCaptureContext;
+    /** Override for tests — production reads from plugin-config.json on each
+     *  call so the flag can be flipped without a restart. */
+    exitGateMode?: ExitGateMode;
+}): Promise<CcxtOrder | {
+    error: string;
+}>;
+/** Test seam — clears the circuit-breaker state between unit tests. */
+export declare const __testing__: {
+    resetCircuitBreaker(): void;
+    /** Inspect current circuit-breaker state — for assertions. */
+    getCircuitBreakerCount(): number;
+};