@reefclaw/connect 0.1.12 → 0.1.14

package/assets/plugin/tools/bracket-control.d.ts

@@ -0,0 +1,12 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { BracketLedger } from '../live/bracket-ledger.js';
+export interface BracketControl {
+    venue: 'binance' | 'hyperliquid';
+    ledger: BracketLedger;
+    modifyStop(symbol: string, newStopPrice: number): Promise<void>;
+    modifyTarget(symbol: string, newTargetPrice: number): Promise<void>;
+}
+/** Resolve the venue's bracket-mutation surface, or null when brackets are
+ *  not enabled (Binance with brackets.mode=off; never null on HL live —
+ *  exchange-side legs are HL live's ONLY protection, so they are always on). */
+export declare function resolveBracketControl(adapter: IExchangeAdapter): BracketControl | null;

package/assets/plugin/tools/bracket-control.js

@@ -0,0 +1,35 @@
+// Venue dispatch for the bracket-mutating tools (issue #209).
+//
+// modify_stop / modify_target need one seam: "give me the thing that can move
+// a leg, plus the ledger that knows the current geometry". On Binance that is
+// BracketManager (+ LiveAdapter's ledger); on Hyperliquid it is the
+// HlBracketCoordinator (which owns its own venue-distinct ledger). The tools
+// must never know which venue they are on beyond this resolver — the
+// hard-cast-to-LiveAdapter pattern is exactly what left the HL arm returning
+// "Bracket orders are not enabled" on every call (the #209 recovery gap).
+import { HyperliquidLiveAdapter } from '../venues/hyperliquid/hl-live-adapter.js';
+/** Resolve the venue's bracket-mutation surface, or null when brackets are
+ *  not enabled (Binance with brackets.mode=off; never null on HL live —
+ *  exchange-side legs are HL live's ONLY protection, so they are always on). */
+export function resolveBracketControl(adapter) {
+    if (adapter instanceof HyperliquidLiveAdapter) {
+        const coordinator = adapter.getHlBracketCoordinator();
+        return {
+            venue: 'hyperliquid',
+            ledger: coordinator.getLedger(),
+            modifyStop: (symbol, px) => coordinator.modifyStop(symbol, px),
+            modifyTarget: (symbol, px) => coordinator.modifyTarget(symbol, px),
+        };
+    }
+    const live = adapter;
+    const mgr = live.getBracketManager?.();
+    const ledger = live.getBracketLedger?.();
+    if (!mgr || !ledger)
+        return null;
+    return {
+        venue: 'binance',
+        ledger,
+        modifyStop: (symbol, px) => mgr.modifyStop(symbol, px),
+        modifyTarget: (symbol, px) => mgr.modifyTarget(symbol, px),
+    };
+}

package/assets/plugin/tools/cancel-all-orders.d.ts

@@ -0,0 +1,9 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
+import type { CcxtOrder } from '../types.js';
+export declare function cancelAllOrdersTool(args: {
+    symbol?: string;
+}, deps: {
+    adapter: IExchangeAdapter;
+    operationLock?: TradingOperationLock;
+}): Promise<CcxtOrder[]>;

package/assets/plugin/tools/cancel-all-orders.js

@@ -0,0 +1,8 @@
+// Tool: cancel_all_orders — cancel all open orders (paper or live)
+// NO readiness gate — emergency control (kill switch), must always work.
+export async function cancelAllOrdersTool(args, deps) {
+    const cancel = () => deps.adapter.cancelAllOrders(args.symbol);
+    return deps.adapter.isLive && deps.operationLock
+        ? deps.operationLock.withAccountLock(`generic-cancel-all-orders-final:${args.symbol ?? 'all'}`, cancel)
+        : cancel();
+}

package/assets/plugin/tools/cancel-order.d.ts

@@ -0,0 +1,14 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
+import type { CcxtOrder } from '../types.js';
+import type { Wave9LiveSymbolOwnershipCheck } from '../wave9/live-symbol-ownership.js';
+export declare function cancelOrderTool(args: {
+    id: string;
+    symbol?: string;
+}, deps: {
+    adapter: IExchangeAdapter;
+    operationLock?: TradingOperationLock;
+    checkWave9LiveSymbolOwnership?: Wave9LiveSymbolOwnershipCheck;
+}): Promise<CcxtOrder | {
+    error: string;
+}>;

package/assets/plugin/tools/cancel-order.js

@@ -0,0 +1,60 @@
+// Tool: cancel_order — cancel a single order (paper or live).
+// There is no readiness gate, but LIVE cancellation cannot individually strip
+// candidate-bound Wave 9 protection. The emergency escape is an explicit
+// operator close, which reduces exposure instead of leaving it naked.
+import { formatError } from '../logger.js';
+export async function cancelOrderTool(args, deps) {
+    if (!args.id) {
+        return { error: 'Order ID is required.' };
+    }
+    if (!deps.adapter.isLive) {
+        try {
+            return await deps.adapter.cancelOrder(args.id, args.symbol);
+        }
+        catch (err) {
+            return { error: formatError(err) };
+        }
+    }
+    if (deps.checkWave9LiveSymbolOwnership && !deps.operationLock) {
+        return {
+            error: 'Live cancel_order refused: the shared trading operation lock is required ' +
+                'while Wave 9 LIVE ownership checks are enabled.',
+        };
+    }
+    const cancelLive = async () => {
+        let symbol = args.symbol?.trim();
+        if (!symbol) {
+            const matches = (await deps.adapter.getOpenOrders())
+                .filter((order) => order.id === args.id);
+            if (matches.length !== 1 || !matches[0].symbol) {
+                throw new Error(`cancel_order refused: order ${args.id} could not be resolved to exactly one ` +
+                    `trusted open-order symbol (matches=${matches.length}).`);
+            }
+            symbol = matches[0].symbol;
+        }
+        if (deps.checkWave9LiveSymbolOwnership) {
+            let ownership;
+            try {
+                ownership = await deps.checkWave9LiveSymbolOwnership(symbol);
+            }
+            catch (err) {
+                throw new Error(`cancel_order refused at mutation boundary: Wave 9 LIVE ownership check failed ` +
+                    `for ${symbol} (${formatError(err)}).`);
+            }
+            if (ownership.status === 'owned' || ownership.status === 'ambiguous') {
+                throw new Error(`cancel_order refused at mutation boundary: ${symbol} has ` +
+                    `${ownership.status} Wave 9 LIVE ownership (${ownership.reason}). ` +
+                    'Use operator_command to close the position instead of stripping candidate-bound protection.');
+            }
+        }
+        return deps.adapter.cancelOrder(args.id, symbol);
+    };
+    try {
+        return deps.operationLock
+            ? await deps.operationLock.withAccountLock(`generic-cancel-order-final:${args.id}`, cancelLive)
+            : await cancelLive();
+    }
+    catch (err) {
+        return { error: formatError(err) };
+    }
+}

package/assets/plugin/tools/check-position-health.d.ts

@@ -0,0 +1,46 @@
+interface PositionInput {
+    symbol: string;
+    side: 'LONG' | 'SHORT';
+    entry_price: number;
+    current_price: number;
+    stop_price: number;
+    target_price?: number;
+    quantity: number;
+    entry_time: string;
+}
+interface CheckHealthArgs {
+    positions: PositionInput[];
+    account_balance: number;
+}
+interface PositionHealth {
+    symbol: string;
+    side: string;
+    pnl: number;
+    pnlPercent: number;
+    pnlR: number;
+    distanceToStopPercent: number;
+    distanceToStopR: number;
+    stopStatus: 'SAFE' | 'CLOSE' | 'CRITICAL' | 'BREACHED';
+    distanceToTargetPercent: number | null;
+    distanceToTargetR: number | null;
+    targetReached: boolean;
+    heatPercent: number;
+    notionalPercent: number;
+    timeInTradeMinutes: number;
+    timeInTradeFormatted: string;
+    timeStatus: 'FRESH' | 'NORMAL' | 'EXTENDED' | 'STALE';
+    alerts: string[];
+}
+interface HealthSummary {
+    positions: PositionHealth[];
+    portfolio: {
+        totalHeat: number;
+        totalNotional: number;
+        totalPnl: number;
+        positionCount: number;
+        heatStatus: 'LOW' | 'MODERATE' | 'ELEVATED' | 'HIGH' | 'CRITICAL';
+        alerts: string[];
+    };
+}
+export declare function checkPositionHealthTool(args: CheckHealthArgs): HealthSummary;
+export {};

package/assets/plugin/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/assets/plugin/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/assets/plugin/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/assets/plugin/tools/close-position.d.ts

@@ -0,0 +1,45 @@
+import type { PublicMarketDataApi } from '../ccxt/public-market-data-api.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';
+import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
+import type { Wave9LiveExecutionLedger } from '../wave9/live-execution-ledger.js';
+import type { Wave9LiveSymbolOwnershipCheck } from '../wave9/live-symbol-ownership.js';
+import { type Wave9LiveResidualProtectionResult } from '../wave9/live-residual-protection.js';
+import { type Wave9PaperAdmissionGuard } from '../wave9/paper-admission-guard.js';
+export declare function closePositionTool(args: ClosePositionArgs, deps: {
+    binanceApi: PublicMarketDataApi;
+    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;
+    wave9AdmissionGuard?: Wave9PaperAdmissionGuard;
+    refreshPaperState?: () => void;
+    wave9TradingModeCheck?: () => string;
+    wave9VenueCheck?: () => string;
+    captureWave9PositionFingerprint?: (symbol: string) => Promise<{
+        fingerprint: string;
+        position: {
+            candidateId?: string;
+            missionId?: string;
+            setupType?: string;
+            side: 'long' | 'short';
+        };
+    }>;
+    wave9LiveLedger?: Wave9LiveExecutionLedger;
+    checkWave9LiveSymbolOwnership?: Wave9LiveSymbolOwnershipCheck;
+    reprotectWave9LiveResidual?: (adapter: IExchangeAdapter, ledger: Wave9LiveExecutionLedger, candidateId: string, symbol: string) => Promise<Wave9LiveResidualProtectionResult>;
+    operationLock?: TradingOperationLock;
+    operationLockHeld?: boolean;
+}): 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;
+};