@reefclaw/openclaw-plugin 0.1.0

package/tools/attach-brackets.js

@@ -0,0 +1,363 @@
+// Tool: attach_brackets — bootstrap exchange-side protection on an existing
+// open live position that is currently naked (no STOP_MARKET / TAKE_PROFIT_MARKET
+// order). Complements modify_stop / modify_target, which can only MOVE an
+// already-active bracket — they can't attach one from nothing.
+//
+// Why this tool exists (2026-04-21 naked-position incident): kill-switch
+// sweeps were stripping bracket protective orders off open positions without
+// flattening them. The agent then had no recovery path because modify_*
+// requires state ∈ {active, partial}. This tool + the bracket-preserving
+// cancel filter in BinancePrivateApi together close the loop.
+//
+// Responsibilities:
+//   1. Validate inputs + mode (live only, brackets enabled).
+//   2. Confirm an open position exists with >0 contracts.
+//   3. Sanity-check stop / target direction vs the position side.
+//   4. Reject if a fresh bracket is already active (caller wants modify_*).
+//   5. Clear any stale bracket orders on the exchange for this symbol.
+//   6. Register a new bracket + attach it. Retries inherit BracketManager policy.
+//
+// Paper mode: rejected with an explanatory error (paper uses per-position
+// metadata + stop-watcher, not exchange orders).
+import { generateBracketId, buildBracketCid } from '../live/bracket-id.js';
+import { validateStopDirection, validateTargetDirection } from '../live/bracket-params.js';
+import { formatError, logger } from '../logger.js';
+const TAG = 'attach-brackets';
+export async function attachBracketsTool(args, deps) {
+    // ---- 1. Argument validation ----
+    if (!args.symbol || typeof args.symbol !== 'string') {
+        return { error: 'symbol is required.' };
+    }
+    if (args.stop_price === undefined && args.target_price === undefined) {
+        return { error: 'at least one of stop_price or target_price must be provided.' };
+    }
+    if (args.stop_price !== undefined && (!Number.isFinite(args.stop_price) || args.stop_price <= 0)) {
+        return { error: 'stop_price must be a positive finite number.' };
+    }
+    if (args.target_price !== undefined && (!Number.isFinite(args.target_price) || args.target_price <= 0)) {
+        return { error: 'target_price must be a positive finite number.' };
+    }
+    // ---- 2. Mode gate ----
+    if (!deps.adapter.isLive) {
+        return { error: 'attach_brackets is live-mode only (it places exchange-side STOP/TP orders). In paper mode, use modify_stop / modify_target to set or move the position\'s protective levels in place — the paper stop-watcher enforces metadata.stopPrice.' };
+    }
+    const live = deps.adapter;
+    const mgr = live.getBracketManager?.();
+    const ledger = live.getBracketLedger?.();
+    if (!mgr || !ledger) {
+        return { error: 'Bracket orders are not enabled. Set brackets.mode in plugin-config.json to "observe" or "enforce".' };
+    }
+    // ---- 3. Position must exist ----
+    // getPositionsOrNull() returns null when the fetch FAILED (429 / weight-
+    // paced / transient) — position state is UNKNOWN, NOT "no position". If
+    // we collapsed null→[] here, attach_brackets would tell the agent "No open
+    // position" for a position that is actually live and NAKED on Binance; the
+    // agent reads that as "nothing to protect", stops trying, and the naked
+    // position rides unprotected. Distinct error → agent retries next
+    // heartbeat. Same null≠empty contract as audit/closePosition/flatten.
+    const positions = await deps.adapter.getPositionsOrNull(args.symbol);
+    if (positions === null) {
+        return {
+            error: `Exchange data unavailable for ${args.symbol} (likely Binance 429 or transient ` +
+                `network) — position state UNKNOWN. NOT treating this as "no position"; ` +
+                `bracket attach skipped this cycle. Retry on next heartbeat.`,
+        };
+    }
+    const position = positions.find(p => p.symbol === args.symbol) ?? positions[0];
+    if (!position || position.contracts <= 0) {
+        return { error: `No open position for ${args.symbol}.` };
+    }
+    const entrySide = position.side === 'long' ? 'buy' : 'sell';
+    // ---- 4. Direction sanity check vs entry price ----
+    const refPrice = position.entryPrice > 0 ? position.entryPrice : await deps.adapter.getLastPrice(position.symbol);
+    if (refPrice != null && refPrice > 0) {
+        if (args.stop_price !== undefined) {
+            const msg = validateStopDirection(entrySide, refPrice, args.stop_price);
+            if (msg)
+                return { error: msg };
+        }
+        if (args.target_price !== undefined) {
+            const msg = validateTargetDirection(entrySide, refPrice, args.target_price);
+            if (msg)
+                return { error: msg };
+        }
+    }
+    // ---- 5. Handle existing ledger row ----
+    // If the ledger has a non-terminal row AND its stored SL/TP cids correspond
+    // to live exchange orders, a fresh bracket really is active. Two sub-cases:
+    //   (a) Caller passed the SAME prices the ledger already stores → idempotent
+    //       no-op success. This is the agent's defensive re-attach pattern: it
+    //       sees a flickery audit verdict, calls attach_brackets to "repair",
+    //       passes the same stop/target it remembers from the entry. Pre-fix
+    //       this returned an error, the agent escalated to close_position
+    //       (bracket_integrity), and we lost ~$3 of bracket-integrity flushes
+    //       on 2026-05-15. With idempotency, the defensive re-call costs
+    //       nothing and the position survives.
+    //   (b) Caller passed DIFFERENT prices → they want to change levels. Point
+    //       them at modify_stop / modify_target so we don't have two paths
+    //       that mutate the bracket geometry.
+    //
+    // If the ledger is non-terminal but the cids do NOT match any live exchange
+    // order, the row is stale (exchange brackets got cancelled out-of-band,
+    // plugin restart + lost attach, etc.). Force the row terminal so
+    // registerEntry below can seed a fresh pending_entry. Without this, stale
+    // rows deadlock recovery: audit reports has_stop=false (no exchange match),
+    // attach refuses (ledger says active), agent can't resolve. Incident:
+    // 2026-04-21 ADA death loop — 12 cycles panic-closed in 3 hours.
+    const existing = ledger.getBySymbol(position.symbol);
+    let clearedStaleLedgerRow = false;
+    if (existing && NON_TERMINAL_STATES.has(existing.state)) {
+        // Tri-state classification. `unknown` means we COULD NOT positively
+        // confirm the ledger's cids against live exchange orders — getOpenOrders
+        // threw (429 / weight-paced / sticky cooldown), OR the row has no cids to
+        // check (in-flight pending_entry/attaching). We must NOT collapse
+        // "unverifiable" into "live" — doing so makes attach_brackets return
+        // idempotent_no_op / "already active" for a position that is actually
+        // NAKED on the exchange, and the agent files a complacent hold/protected
+        // review on an unprotected live position. 2026-05-15 NEAR incident: a
+        // weight-paced getOpenOrders → verifyLedgerStale safe-defaulted to "not
+        // stale" → idempotent_no_op on an `attaching` row whose brackets were
+        // never placed. Same null≠empty / never-coerce-unverifiable-to-a-positive-
+        // safety-claim contract as getOpenOrders / getPositions / closePosition.
+        const cls = await classifyLedgerVsExchange(live, position.symbol, existing.slCid, existing.tpCid);
+        if (cls === 'unknown') {
+            logger.warn(TAG, `CANNOT CONFIRM bracket protection for ${position.symbol}: ledger row ` +
+                `state=${existing.state} (slCid=${existing.slCid ?? '-'}, tpCid=${existing.tpCid ?? '-'}) ` +
+                `but getOpenOrders unavailable or no cids to verify. Refusing to claim ` +
+                `protected; NOT clearing/reattaching (could race an in-flight attach).`);
+            return {
+                error: `Cannot confirm whether ${position.symbol} brackets are live on the exchange ` +
+                    `(getOpenOrders unavailable — Binance 429 / weight-paced / transient — or the ` +
+                    `ledger row is still in-flight with no cids yet). NOT assuming the position is ` +
+                    `protected and NOT reattaching this cycle. Retry on the next heartbeat. If this ` +
+                    `persists, treat the position as potentially NAKED: verify on the exchange and ` +
+                    `place a manual stop. Do NOT record a hold/protected review on the basis of this call.`,
+            };
+        }
+        if (cls === 'live') {
+            // Idempotency check: same protection levels = no-op success.
+            if (pricesMatch(args.stop_price, existing.stopPrice)
+                && pricesMatch(args.target_price, existing.targetPrice)) {
+                logger.info(TAG, `idempotent no-op for ${position.symbol}: bracket already ${existing.state} ` +
+                    `at stop=${existing.stopPrice ?? 'none'} target=${existing.targetPrice ?? 'none'} ` +
+                    `(slCid=${existing.slCid ?? '-'}, tpCid=${existing.tpCid ?? '-'})`);
+                return {
+                    ok: true,
+                    symbol: position.symbol,
+                    bracket_id: existing.bracketId,
+                    entry_side: entrySide,
+                    stop_price: existing.stopPrice,
+                    target_price: existing.targetPrice,
+                    sl_cid: existing.slCid,
+                    tp_cid: existing.tpCid,
+                    attach_latency_ms: 0,
+                    cancelled_stale_bracket_orders: 0,
+                    cleared_stale_ledger_row: false,
+                    attempts: 0,
+                    idempotent_no_op: true,
+                    note: `Bracket already ${existing.state} on exchange with matching prices — no-op. If the audit reports has_stop=false anyway, suspect audit unreliability, not protection loss.`,
+                };
+            }
+            return {
+                error: `Bracket already ${existing.state} for ${position.symbol} ` +
+                    `at stop=${formatPrice(existing.stopPrice)} target=${formatPrice(existing.targetPrice)}. ` +
+                    `Use modify_stop / modify_target to change levels, or close_position to exit.`,
+            };
+        }
+        logger.warn(TAG, `Ledger row for ${position.symbol} is stale (state=${existing.state}, slCid=${existing.slCid}, tpCid=${existing.tpCid} not on exchange); forcing terminal to re-attach`);
+        try {
+            ledger.markState(position.symbol, 'cancelled', {
+                closeReason: 'cancelled_auto',
+                lastError: 'stale_ledger_detected_by_attach_brackets',
+            });
+            clearedStaleLedgerRow = true;
+        }
+        catch (err) {
+            return { error: `failed to clear stale ledger row: ${formatError(err)}` };
+        }
+    }
+    // ---- 6. Clear any stale bracket orders on the exchange for this symbol ----
+    // The ledger row (if any) is terminal at this point; its stored SL/TP cids
+    // may or may not still be live on the exchange. Orphan bracket orders not
+    // tracked by the ledger may also exist. Cancel all bracket-cid orders on
+    // this symbol so only our fresh pair remains after attach.
+    let cancelledOrphans = 0;
+    try {
+        cancelledOrphans = await live.cancelSymbolBracketOrders(position.symbol);
+    }
+    catch (err) {
+        logger.warn(TAG, `orphan cleanup failed for ${position.symbol}: ${formatError(err)}`);
+    }
+    // ---- 7. Register + attach ----
+    // BracketManager.registerEntry auto-clears terminal rows for the same symbol
+    // (see ledger-hygiene change landed alongside this tool).
+    const bracketId = generateBracketId();
+    try {
+        mgr.registerEntry({
+            symbol: position.symbol,
+            side: entrySide,
+            stopPrice: args.stop_price,
+            targetPrice: args.target_price,
+        }, bracketId, buildBracketCid(bracketId, 'entry'));
+    }
+    catch (err) {
+        return { error: `registerEntry failed: ${formatError(err)}` };
+    }
+    let attachResult;
+    try {
+        attachResult = await mgr.attachBrackets(position.symbol, position.contracts);
+    }
+    catch (err) {
+        return { error: `attachBrackets threw: ${formatError(err)}` };
+    }
+    if (!attachResult.ok) {
+        return {
+            error: `Bracket attach failed after ${attachResult.attempts} attempt(s): ${attachResult.error ?? 'unknown error'}. ` +
+                `Position remains open. Try again with adjusted levels, or close_position to exit.`,
+        };
+    }
+    return {
+        ok: true,
+        symbol: position.symbol,
+        bracket_id: bracketId,
+        entry_side: entrySide,
+        stop_price: args.stop_price,
+        target_price: args.target_price,
+        sl_cid: attachResult.slCid,
+        tp_cid: attachResult.tpCid,
+        attach_latency_ms: attachResult.latencyMs,
+        cancelled_stale_bracket_orders: cancelledOrphans,
+        cleared_stale_ledger_row: clearedStaleLedgerRow || (!!existing && !NON_TERMINAL_STATES.has(existing.state)),
+        attempts: attachResult.attempts,
+    };
+}
+// Non-terminal bracket states — a row in any of these means brackets are
+// either in-flight or fully live; attach_brackets refuses to clobber them
+// UNLESS the ledger cids don't match any live exchange order (stale row).
+const NON_TERMINAL_STATES = new Set([
+    'pending_entry',
+    'attaching',
+    'active',
+    'partial',
+]);
+/** Classify a non-terminal ledger row against live exchange open orders.
+ *
+ *  - `'live'`    — getOpenOrders SUCCEEDED and at least one stored cid is
+ *                  positively present in the live open orders. Only this
+ *                  result may produce an idempotent_no_op / "already active"
+ *                  reply: protection is PROVEN on the exchange.
+ *  - `'stale'`   — getOpenOrders SUCCEEDED and NONE of the stored cids are
+ *                  present. The exchange definitively does not have our
+ *                  brackets → clear the row and re-attach.
+ *  - `'unknown'` — we could NOT positively verify: getOpenOrders threw
+ *                  (429 / weight-paced / sticky cooldown / transient), OR the
+ *                  row has no cids to check (in-flight pending_entry/attaching
+ *                  whose attach hasn't assigned cids yet). We must NOT treat
+ *                  this as `live` (false "protected" on a possibly-naked
+ *                  position — the 2026-05-15 NEAR incident) NOR as `stale`
+ *                  (clearing + reattaching could race a genuine in-flight
+ *                  attach and double up). The caller refuses honestly and
+ *                  tells the agent to retry / verify manually.
+ *
+ *  Same null≠empty / never-coerce-unverifiable-into-a-positive-safety-claim
+ *  contract as getOpenOrders / getPositions / closePosition / the reconciler. */
+async function classifyLedgerVsExchange(live, symbol, slCid, tpCid) {
+    if (!slCid && !tpCid)
+        return 'unknown';
+    // Cheap positive check first: a stored cid present in a SUCCESSFUL,
+    // non-empty getOpenOrders is immediate, zero-extra-weight proof of life.
+    // This keeps the common happy-path free. A throw or an empty set is NOT
+    // disconfirmation — fall through to the authoritative per-leg resolver.
+    try {
+        const openOrders = await live.getOpenOrders(symbol);
+        const liveCids = new Set();
+        for (const o of openOrders) {
+            if (o.clientOrderId)
+                liveCids.add(o.clientOrderId);
+        }
+        if ((slCid && liveCids.has(slCid)) || (tpCid && liveCids.has(tpCid))) {
+            return 'live';
+        }
+    }
+    catch (err) {
+        logger.warn(TAG, `classifyLedgerVsExchange: getOpenOrders(${symbol}) unavailable ` +
+            `(${formatError(err)}) — deferring to the per-leg liveness resolver, ` +
+            `NOT assuming protected or stale`);
+    }
+    // No positive snapshot match (empty, threw, or non-empty-without-our-cids).
+    // The SOL/INJ spiral root: a *successful* empty /fapi/v1/openAlgoOrders is
+    // NOT proof a leg is gone. Ask the authoritative per-leg resolver instead
+    // of inferring from absence — trusted-WS fast-path → weight-1 REST
+    // /fapi/v1/algoOrder → 'unknown' floor:
+    //   any leg 'live'                 → 'live'  (do NOT clobber)
+    //   ALL present legs 'terminal'    → 'stale' (POSITIVELY confirmed gone —
+    //                                    the only state that licenses repair)
+    //   otherwise (any 'unknown')      → 'unknown' (d59e51b safe floor)
+    const cids = [slCid, tpCid].filter((c) => !!c);
+    const verdicts = await Promise.all(cids.map(c => live.resolveBracketLegLiveness(c)));
+    if (verdicts.some(v => v === 'live'))
+        return 'live';
+    if (verdicts.length > 0 && verdicts.every(v => v === 'terminal')) {
+        // #2 — AUTHORITATIVE action-layer spiral guard (2026-05-16 INJ).
+        // The LEDGER's cids are positively terminal — but that is NOT proof the
+        // position is unprotected. A prior reattach's FRESH bracket may be live
+        // on the exchange under a NEW cid the ledger never caught up to.
+        // Returning 'stale' here licenses the clear+reattach that cancels that
+        // live bracket → naked → audit unprotected → attach → spiral. Before
+        // licensing repair, positively prove NO other rc-* leg for this symbol
+        // is live. Only positive evidence licenses the destructive action —
+        // same invariant as d59e51b / getOpenOrders / the reconciler.
+        const sweep = live.findTrustedLiveBracketCidsForSymbol(symbol);
+        if (sweep.trusted && sweep.liveCids.length > 0) {
+            logger.warn(TAG, `classifyLedgerVsExchange: ${symbol} ledger cids (slCid=${slCid ?? '-'}, ` +
+                `tpCid=${tpCid ?? '-'}) are terminal BUT the trusted WS shows live ` +
+                `rc-* leg(s) under other cid(s) [${sweep.liveCids.join(', ')}] — a prior ` +
+                `reattach's fresh bracket is live and the ledger row lagged. Returning ` +
+                `'live' (NOT 'stale') to break the clear+reattach spiral; the position ` +
+                `IS protected on the exchange.`);
+            return 'live';
+        }
+        if (!sweep.trusted) {
+            // WS store untrusted → we cannot rule out a live fresh bracket under
+            // an untracked cid using the zero-weight signal, and the spiral REST
+            // is weight-paced. Refuse the destructive 'stale' (retry next cycle);
+            // a genuinely-naked position is still caught by the reconciler /
+            // ALGO_UPDATE / audit backstops. Worst case is a one-cycle delayed
+            // repair — far safer than cancelling a live bracket on a false 'stale'.
+            logger.warn(TAG, `classifyLedgerVsExchange: ${symbol} ledger cids REST-confirmed terminal ` +
+                `but the WS store is UNTRUSTED — cannot positively rule out a live fresh ` +
+                `bracket under an untracked cid (weight-paced REST can't either). ` +
+                `Returning 'unknown' (NOT 'stale'); no force-reattach this cycle.`);
+            return 'unknown';
+        }
+        logger.info(TAG, `classifyLedgerVsExchange: ${symbol} legs POSITIVELY confirmed terminal ` +
+            `via per-leg resolver AND the trusted WS shows no other live rc-* leg ` +
+            `(slCid=${slCid ?? '-'}, tpCid=${tpCid ?? '-'}) — 'stale', safe to ` +
+            `clear+reattach.`);
+        return 'stale';
+    }
+    logger.warn(TAG, `classifyLedgerVsExchange: ${symbol} bracket liveness UNVERIFIABLE ` +
+        `(slCid=${slCid ?? '-'}, tpCid=${tpCid ?? '-'}; verdicts=${JSON.stringify(verdicts)}) ` +
+        `— returning 'unknown', NOT 'stale'. No force-reattach this cycle.`);
+    return 'unknown';
+}
+/** Compare a requested price against the ledger's stored price for the same
+ *  bracket leg. Match means: both undefined (caller didn't ask for that leg
+ *  and ledger doesn't have it) OR both defined within 0.01% relative
+ *  tolerance (covers exchange rounding of trigger prices vs the operator's
+ *  request). Any other shape is a mismatch — interpret as the caller wanting
+ *  to CHANGE the level, route to modify_*. */
+function pricesMatch(requested, stored) {
+    if (requested === undefined && stored === undefined)
+        return true;
+    if (requested === undefined || stored === undefined)
+        return false;
+    if (!Number.isFinite(requested) || !Number.isFinite(stored))
+        return false;
+    if (stored === 0)
+        return requested === 0;
+    return Math.abs(requested - stored) / Math.abs(stored) <= 1e-4;
+}
+function formatPrice(p) {
+    return p === undefined ? 'none' : String(p);
+}

package/tools/audit-bracket-protection.d.ts

@@ -0,0 +1,49 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { BracketState } from '../live/bracket-types.js';
+type ProtectionReason = 'bracket_active' | 'manual_order_protecting' | 'no_protective_order' | 'brackets_disabled' | 'stale_ledger_row' | 'ledger_terminal_no_order';
+interface PositionAuditEntry {
+    symbol: string;
+    side: 'long' | 'short';
+    contracts: number;
+    entry_price: number;
+    mark_price: number;
+    has_stop: boolean;
+    has_target: boolean;
+    stop_price?: number;
+    target_price?: number;
+    ledger_state: BracketState | 'no_ledger_row';
+    reason: ProtectionReason;
+    recommended_action: 'none' | 'attach_brackets' | 'close_position' | 'enable_brackets_mode';
+}
+interface AuditBracketProtectionResult {
+    ok: true;
+    mode: 'paper' | 'live';
+    brackets_enabled: boolean;
+    total_positions: number;
+    protected_count: number;
+    unprotected_count: number;
+    positions: PositionAuditEntry[];
+}
+export declare function auditBracketProtectionTool(_args: Record<string, never>, deps: {
+    adapter: IExchangeAdapter;
+}): Promise<AuditBracketProtectionResult | {
+    error: string;
+}>;
+/** Public getter — returns the recent audit verdict samples for a symbol so
+ *  close_position can copy them into the position's close record for the
+ *  dashboard Position Timeline drawer. Read-only snapshot; mutating the
+ *  return value does not affect internal state. */
+export declare function getRecentAuditVerdictHistory(symbol: string): ReadonlyArray<{
+    ts: number;
+    protected: boolean;
+}>;
+/** Test seam — clears the in-memory flicker history between unit tests. */
+export declare const __testing__: {
+    resetFlickerHistory(): void;
+    /** Inspect current history for a symbol — used by tests to assert state. */
+    getHistory(symbol: string): ReadonlyArray<{
+        ts: number;
+        protected: boolean;
+    }>;
+};
+export {};