@reefclaw/connect 0.1.11 → 0.1.12

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

@@ -1,12 +0,0 @@
-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

@@ -1,35 +0,0 @@
-// 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

@@ -1,9 +0,0 @@
-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

@@ -1,8 +0,0 @@
-// 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

@@ -1,14 +0,0 @@
-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

@@ -1,60 +0,0 @@
-// 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

@@ -1,46 +0,0 @@
-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

@@ -1,194 +0,0 @@
-// 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

@@ -1,24 +0,0 @@
-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

@@ -1,70 +0,0 @@
-// 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

@@ -1,45 +0,0 @@
-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;
-};