@reefclaw/openclaw-plugin 0.1.0

package/lifecycle/install-signal-handlers.js

@@ -0,0 +1,112 @@
+// Wires SIGTERM / SIGINT to the ShutdownCoordinator.
+//
+// Lives in its own file (separate from index.ts) so the compiled dist/index.js
+// — which reads env vars for the ingest-token / user-id — does not also contain
+// the network-send call site.  OpenClaw's plugin-install heuristic flags the
+// combination as possible credential harvesting (false positive, but worth
+// avoiding by keeping each compiled file single-purpose).
+//
+// All env-var-bearing context is passed in by the caller via the typed
+// argument shape, NOT read from process.env here.
+import { LiveAdapter } from '../live/live-adapter.js';
+import { logger, formatError } from '../logger.js';
+import { initiateShutdown } from './shutdown-coordinator.js';
+const TAG = 'shutdown';
+/** The phase-2 drain body. Exported for direct unit-testing of the teardown
+ *  ordering + the StateManager flush wiring (the signal handler itself can't
+ *  be tested without process.exit). Every step is individually guarded so one
+ *  failing teardown never aborts the rest. */
+export async function performShutdownDrain(deps) {
+    // Stop the approval-mode listener BEFORE the adapter shuts down.
+    // The listener's tick may call createOrderTool which needs the
+    // adapter; once stop() resolves, no new tick will fire.
+    if (deps.proposalListener) {
+        try {
+            await deps.proposalListener.stop();
+        }
+        catch (err) {
+            logger.warn(TAG, `proposalListener stop failed: ${formatError(err)}`);
+        }
+    }
+    // Flush any pending audit-trail POSTs.
+    if (deps.tradeStore) {
+        try {
+            await deps.tradeStore.drain();
+        }
+        catch (err) {
+            logger.warn(TAG, `tradeStore drain failed: ${formatError(err)}`);
+        }
+    }
+    // Stop background loops + close WS + DELETE listenKey.
+    const live = deps.runtime.adapter;
+    if (live instanceof LiveAdapter) {
+        try {
+            live.shutdown();
+        }
+        catch (err) {
+            logger.warn(TAG, `LiveAdapter.shutdown failed: ${formatError(err)}`);
+        }
+    }
+    // Stop the watcher last so it doesn't fire a stop after the
+    // adapter is gone.
+    const watcher = deps.runtime.stopWatcher;
+    if (watcher) {
+        try {
+            watcher.stop();
+        }
+        catch (err) {
+            logger.warn(TAG, `stopWatcher.stop failed: ${formatError(err)}`);
+        }
+    }
+    // Stop the paper market feed so its interval doesn't outlive the process.
+    const marketFeed = deps.runtime.marketFeed;
+    if (marketFeed) {
+        try {
+            marketFeed.stop();
+        }
+        catch (err) {
+            logger.warn(TAG, `marketFeed.stop failed: ${formatError(err)}`);
+        }
+    }
+    // Flush the paper StateManager AFTER all mutation sources are stopped, so
+    // the 1s debounce window doesn't drop the final fills/closes/PnL on restart.
+    // flush() clears the timer and awaits the atomic save; completes in ms
+    // inside the drain budget. Without this, every restart silently lost up to
+    // ~1s of paper state (a just-closed position would resurrect on boot).
+    if (deps.stateManager) {
+        try {
+            await deps.stateManager.flush();
+        }
+        catch (err) {
+            logger.warn(TAG, `stateManager flush failed: ${formatError(err)}`);
+        }
+    }
+}
+/** Register graceful-shutdown handlers.  Idempotent — repeat signals during
+ *  the drain are logged + ignored.  After the coordinator resolves we call
+ *  process.exit(0) so systemd doesn't escalate to SIGKILL. */
+export function installSignalHandlers(deps) {
+    let invoked = false;
+    const onSignal = (signal) => {
+        if (invoked) {
+            logger.info(TAG, `Received ${signal} during shutdown — ignoring`);
+            return;
+        }
+        invoked = true;
+        logger.info(TAG, `Received ${signal} — initiating graceful shutdown`);
+        void initiateShutdown({
+            reason: signal,
+            callbacks: {
+                onDrainComplete: () => performShutdownDrain(deps),
+            },
+        }).then(() => {
+            logger.info(TAG, 'Shutdown drain complete — exit(0)');
+            process.exit(0);
+        }).catch((err) => {
+            logger.error(TAG, `Shutdown threw: ${formatError(err)} — exit(1)`);
+            process.exit(1);
+        });
+    };
+    process.on('SIGTERM', onSignal);
+    process.on('SIGINT', onSignal);
+}

package/lifecycle/shutdown-coordinator.d.ts

@@ -0,0 +1,43 @@
+export declare class ShutdownInProgressError extends Error {
+    constructor(opName: string);
+}
+interface InFlightOp {
+    name: string;
+    startedAt: number;
+}
+/** True once SIGTERM/SIGINT has been received. New risky ops should be refused. */
+export declare function isShuttingDown(): boolean;
+/** Throw ShutdownInProgressError if shutdown has begun. Use as a guard at the
+ *  top of risky entry points (new bracket attach, modify_stop, new order). */
+export declare function assertNotShuttingDown(opName: string): void;
+/** Register an in-flight operation. The returned function MUST be called when
+ *  the op ends. Prefer `trackOp` for typical async cases. */
+export declare function registerOp(name: string): () => void;
+/** Convenience: register + auto-deregister around a promise. */
+export declare function trackOp<T>(name: string, fn: () => Promise<T>): Promise<T>;
+/** Snapshot of currently in-flight ops. Mainly for diagnostics + tests. */
+export declare function getInFlight(): InFlightOp[];
+export interface ShutdownCallbacks {
+    /** Run after in-flight ops drain (or phase-1 deadline hits). Last chance to
+     *  flush the trade ingest queue and tear down adapters. Errors are logged
+     *  + swallowed. */
+    onDrainComplete?: () => Promise<void>;
+}
+export interface ShutdownOptions {
+    reason: string;
+    /** Phase 1 budget — wait for tracked ops to settle. Default 3000 ms. */
+    inFlightDeadlineMs?: number;
+    /** Phase 2 budget — onDrainComplete callback. Default 2000 ms. */
+    drainCallbackDeadlineMs?: number;
+    /** Hard wall-clock deadline across both phases. Default 5000 ms. */
+    totalDeadlineMs?: number;
+    callbacks?: ShutdownCallbacks;
+}
+/** Run the drain sequence. Idempotent — second call returns the first call's
+ *  promise. Resolves when both phases are complete or the wall-clock deadline
+ *  is hit (whichever is first). The signal handler should `process.exit` after
+ *  this resolves. */
+export declare function initiateShutdown(opts: ShutdownOptions): Promise<void>;
+/** Test seam — reset module-level state. Do NOT call from production. */
+export declare function __resetForTesting(): void;
+export {};

package/lifecycle/shutdown-coordinator.js

@@ -0,0 +1,131 @@
+// Process-wide graceful shutdown coordinator.
+//
+// Two responsibilities:
+//   1. Track in-flight risky operations (bracket attach/modify, new entries)
+//      so a SIGTERM-driven shutdown can wait for them before exiting.
+//   2. Block NEW risky operations from starting once shutdown begins, while
+//      still allowing risk-reducing ops (closePosition, reduceOnly) through.
+//
+// Why a global module instead of a constructor-injected service:
+//   - Many files own the at-risk operations (BracketManager, LiveAdapter).
+//     Threading a coordinator through every constructor is mechanical noise
+//     and the caller graph is fixed for this process's lifetime.
+//   - Process-wide state is a fine match for a singleton — one shutdown event
+//     per process, ever.
+//   - Tests reset the singleton via `__resetForTesting()`.
+import { logger } from '../logger.js';
+const TAG = 'shutdown-coordinator';
+export class ShutdownInProgressError extends Error {
+    constructor(opName) {
+        super(`shutting_down: refused to start ${opName}`);
+        this.name = 'ShutdownInProgressError';
+    }
+}
+let _shuttingDown = false;
+const _inFlight = new Map();
+/** True once SIGTERM/SIGINT has been received. New risky ops should be refused. */
+export function isShuttingDown() {
+    return _shuttingDown;
+}
+/** Throw ShutdownInProgressError if shutdown has begun. Use as a guard at the
+ *  top of risky entry points (new bracket attach, modify_stop, new order). */
+export function assertNotShuttingDown(opName) {
+    if (_shuttingDown) {
+        throw new ShutdownInProgressError(opName);
+    }
+}
+/** Register an in-flight operation. The returned function MUST be called when
+ *  the op ends. Prefer `trackOp` for typical async cases. */
+export function registerOp(name) {
+    const handle = Symbol(name);
+    _inFlight.set(handle, { name, startedAt: Date.now() });
+    return () => { _inFlight.delete(handle); };
+}
+/** Convenience: register + auto-deregister around a promise. */
+export async function trackOp(name, fn) {
+    const done = registerOp(name);
+    try {
+        return await fn();
+    }
+    finally {
+        done();
+    }
+}
+/** Snapshot of currently in-flight ops. Mainly for diagnostics + tests. */
+export function getInFlight() {
+    return Array.from(_inFlight.values()).map(o => ({ ...o }));
+}
+/** Run the drain sequence. Idempotent — second call returns the first call's
+ *  promise. Resolves when both phases are complete or the wall-clock deadline
+ *  is hit (whichever is first). The signal handler should `process.exit` after
+ *  this resolves. */
+export function initiateShutdown(opts) {
+    if (_shuttingDownPromise)
+        return _shuttingDownPromise;
+    _shuttingDown = true;
+    _shuttingDownPromise = runShutdown(opts);
+    return _shuttingDownPromise;
+}
+let _shuttingDownPromise = null;
+async function runShutdown(opts) {
+    // Phase-1 default sized for the worst-case bracket retry loop:
+    //   3 attempts × ~500ms API + 1s + 2s backoff = ~4.5s.  6s leaves margin.
+    // Phase-2 default covers TradeStoreClient.drain (network-bounded) + listen
+    // key teardown (one DELETE).
+    // Total wall-clock 10s sits well inside systemd's default TimeoutStopSec.
+    const inFlightDeadline = opts.inFlightDeadlineMs ?? 6_000;
+    const callbackDeadline = opts.drainCallbackDeadlineMs ?? 3_000;
+    const totalDeadline = opts.totalDeadlineMs ?? 10_000;
+    const t0 = Date.now();
+    const remaining = () => Math.max(0, totalDeadline - (Date.now() - t0));
+    const opsAtStart = Array.from(_inFlight.values()).map(o => o.name);
+    logger.info(TAG, `Shutdown initiated (reason=${opts.reason}). In-flight ops: ${opsAtStart.length}` +
+        (opsAtStart.length ? ` [${opsAtStart.join(', ')}]` : ''));
+    // Phase 1: wait for in-flight ops to drain.
+    const phase1Budget = Math.min(inFlightDeadline, remaining());
+    await waitForInFlightDrain(phase1Budget);
+    if (_inFlight.size > 0) {
+        const stuckOps = Array.from(_inFlight.values()).map(o => o.name);
+        logger.warn(TAG, `Phase 1 timed out after ${phase1Budget}ms — ${_inFlight.size} op(s) still in flight: [${stuckOps.join(', ')}]`);
+    }
+    else if (opsAtStart.length > 0) {
+        logger.info(TAG, `Phase 1 complete: in-flight ops drained in ${Date.now() - t0}ms`);
+    }
+    // Phase 2: callback drain (trade-store + adapter).
+    if (opts.callbacks?.onDrainComplete) {
+        const phase2Budget = Math.min(callbackDeadline, remaining());
+        if (phase2Budget <= 0) {
+            logger.warn(TAG, 'Phase 2 skipped — total deadline exhausted by phase 1');
+        }
+        else {
+            try {
+                await Promise.race([
+                    opts.callbacks.onDrainComplete(),
+                    new Promise(resolve => setTimeout(resolve, phase2Budget)),
+                ]);
+                logger.info(TAG, `Phase 2 complete (total elapsed ${Date.now() - t0}ms)`);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                logger.warn(TAG, `Phase 2 callback threw: ${msg}`);
+            }
+        }
+    }
+    logger.info(TAG, `Shutdown coordinator finished in ${Date.now() - t0}ms`);
+}
+async function waitForInFlightDrain(budgetMs) {
+    if (_inFlight.size === 0)
+        return;
+    const start = Date.now();
+    // Poll-based; in-flight ops settle through their own promise chains and
+    // unregister themselves. Cheaper than wiring an emitter just for this.
+    while (_inFlight.size > 0 && Date.now() - start < budgetMs) {
+        await new Promise(r => setTimeout(r, 50));
+    }
+}
+/** Test seam — reset module-level state. Do NOT call from production. */
+export function __resetForTesting() {
+    _shuttingDown = false;
+    _shuttingDownPromise = null;
+    _inFlight.clear();
+}

package/live/bracket-id.d.ts

@@ -0,0 +1,18 @@
+import type { BracketId, BracketRole } from './bracket-types.js';
+/** Generate a fresh 16-char hex bracketId. */
+export declare function generateBracketId(): BracketId;
+/** Build a clientOrderId for a given bracket + role. Emits the CURRENT
+ *  (`bkt…`) scheme only — never the legacy `rc-` scheme. */
+export declare function buildBracketCid(bracketId: BracketId, role: BracketRole): string;
+/** Parse a clientOrderId. Recognises BOTH the current `bkt…` scheme and
+ *  the legacy `rc-…` scheme (so existing ledger rows / in-flight legs and
+ *  the cancelAllOrders bracket-preserve filter keep working through the
+ *  transition). Returns null for non-bracket orders (so this can be called
+ *  on every order Binance returns during reconciliation). */
+export declare function parseBracketCid(cid: string): {
+    bracketId: BracketId;
+    role: BracketRole;
+} | null;
+/** Cheap type-guard for "is this a reefclaw-managed bracket clientOrderId"
+ *  — true for both the current and legacy schemes. */
+export declare function isBracketCid(cid: string): boolean;

package/live/bracket-id.js

@@ -0,0 +1,81 @@
+// Deterministic clientOrderId scheme for bracket orders.
+//
+// CURRENT format: bkt<16hex><role>   (20 chars, well under Binance's 36)
+//   - "bkt"      fixed prefix (no dashes — does NOT look like a tagged pair)
+//   - <16hex>    shared bracketId linking entry + SL + TP of the same trade
+//   - <role>     'e' (entry), 's' (stop-loss), 't' (take-profit)
+//
+// LEGACY format (still PARSED, never EMITTED): rc-<16hex>-<role>
+//
+//   ROOT-CAUSE FIX 2026-05-16. Controlled prod reproduction proved the
+//   recurring ~20-45s bracket cancellation is keyed to the `rc-` cid
+//   pattern: a byte-identical-shape NON-rc closePosition pair survived
+//   30+ min on the SAME symbol/window where every `rc-<16hex>-{s,t}` pair
+//   died in ~42s, `reason=none`, server-side — with the 8-surface raw-ccxt
+//   WIDE-CANCEL-TRACE silent, the skill ccxt-less, the agent issuing zero
+//   tool/exec calls, and OpenClaw having no native exchange. i.e. an
+//   actor with Binance API access, OFF this VPS and outside our software,
+//   cancels orders whose clientOrderId matches the `rc-` bracket pattern.
+//   Renaming the scheme makes our protective brackets invisible to it —
+//   exactly why every `ctp-`/`opguard-`/`mctest-` test order survived.
+//
+//   Backward compat is load-bearing: in-flight brackets + the persisted
+//   bracket-ledger.json carry LEGACY `rc-*` cids. parseBracketCid /
+//   isBracketCid MUST keep recognising them so the reconciler still tracks
+//   them and — critically — `cancelAllOrders`'s bracket-preserve filter
+//   never strips a legacy leg off a live position during the transition.
+//   Only buildBracketCid changes (emits the new scheme); legacy ages out.
+//
+// Parseability is load-bearing: on restart, the reconciler fetches open
+// orders from Binance, parses each clientOrderId, and reassembles brackets
+// from the (bracketId, role) pairs. No reliance on local state to find them.
+//
+// Binance USDⓂ-Futures newClientOrderId charset is documented as
+// ^[\.A-Z\:/a-z0-9_-]{1,36}$ — `bkt[0-9a-f]{16}[est]` (20 chars, lowercase
+// alphanumeric) is well within it. Verified vs developers.binance.com
+// USDⓂ New-Order clientOrderId filter, 2026-05-16.
+import { randomBytes } from 'node:crypto';
+// Emitted scheme (no `rc-`, no dashes).
+const CID_REGEX = /^bkt([0-9a-f]{16})([est])$/;
+// Legacy scheme — still parsed for backward compat, never emitted again.
+const LEGACY_CID_REGEX = /^rc-([0-9a-f]{16})-([est])$/;
+const ROLE_TO_TAG = {
+    entry: 'e',
+    stop: 's',
+    target: 't',
+};
+const TAG_TO_ROLE = {
+    e: 'entry',
+    s: 'stop',
+    t: 'target',
+};
+/** Generate a fresh 16-char hex bracketId. */
+export function generateBracketId() {
+    return randomBytes(8).toString('hex');
+}
+/** Build a clientOrderId for a given bracket + role. Emits the CURRENT
+ *  (`bkt…`) scheme only — never the legacy `rc-` scheme. */
+export function buildBracketCid(bracketId, role) {
+    if (!/^[0-9a-f]{16}$/.test(bracketId)) {
+        throw new Error(`Invalid bracketId: ${bracketId} — expected 16 hex chars`);
+    }
+    return `bkt${bracketId}${ROLE_TO_TAG[role]}`;
+}
+/** Parse a clientOrderId. Recognises BOTH the current `bkt…` scheme and
+ *  the legacy `rc-…` scheme (so existing ledger rows / in-flight legs and
+ *  the cancelAllOrders bracket-preserve filter keep working through the
+ *  transition). Returns null for non-bracket orders (so this can be called
+ *  on every order Binance returns during reconciliation). */
+export function parseBracketCid(cid) {
+    const match = CID_REGEX.exec(cid) ?? LEGACY_CID_REGEX.exec(cid);
+    if (!match)
+        return null;
+    const bracketId = match[1];
+    const tag = match[2];
+    return { bracketId, role: TAG_TO_ROLE[tag] };
+}
+/** Cheap type-guard for "is this a reefclaw-managed bracket clientOrderId"
+ *  — true for both the current and legacy schemes. */
+export function isBracketCid(cid) {
+    return CID_REGEX.test(cid) || LEGACY_CID_REGEX.test(cid);
+}

package/live/bracket-ledger.d.ts

@@ -0,0 +1,54 @@
+import type { BracketId, BracketLedgerEntry, BracketState } from './bracket-types.js';
+/** Canonical form for a bracket-ledger symbol key.
+ *
+ *  CCXT returns Binance Futures symbols as `BTC/USDT:USDT` (the `:USDT`
+ *  suffix is the settlement asset); the skill + agent's tool args use the
+ *  un-suffixed `BTC/USDT`. Historically we keyed the ledger by whatever the
+ *  caller passed in — which produced doubled rows per symbol and caused the
+ *  2026-04-21 ADA audit-vs-attach deadlock (9 of 11 symbols had both keys;
+ *  see `memory/feedback_symbol_normalize_boundary.md`). This helper picks a
+ *  single canonical form (un-suffixed) and is applied at every public
+ *  BracketLedger entry point.
+ *
+ *  Matches `user-data-stream-controller.ts` and `webapp/src/lib/symbols.ts`
+ *  `normalizeSymbol`, so the bracket path lines up with the WS store + UI. */
+export declare function normalizeBracketSymbol(s: string): string;
+/** Test seam — lets tests override the clock for deterministic timestamps. */
+export type NowFn = () => string;
+export declare class BracketLedger {
+    private readonly filePath;
+    private readonly dir;
+    private readonly now;
+    private entries;
+    constructor(pluginId?: string, opts?: {
+        now?: NowFn;
+        basePath?: string;
+    });
+    /** Insert or replace the entry for a symbol. Persists synchronously.
+     *  Symbol is normalized; the stored entry carries the canonical form so
+     *  later readers see it regardless of whether the caller passed suffixed
+     *  or un-suffixed input. */
+    upsert(entry: Omit<BracketLedgerEntry, 'createdAt' | 'updatedAt'> & {
+        createdAt?: string;
+        updatedAt?: string;
+    }): BracketLedgerEntry;
+    /** Mutate the state of an existing entry. Throws if entry not found. */
+    markState(symbol: string, nextState: BracketState, extras?: Partial<Pick<BracketLedgerEntry, 'attachStartedAt' | 'attachCompletedAt' | 'attachLatencyMs' | 'closedAt' | 'closeReason' | 'lastError' | 'slCid' | 'tpCid' | 'qty'>>): BracketLedgerEntry;
+    getBySymbol(symbol: string): BracketLedgerEntry | undefined;
+    getByBracketId(bracketId: BracketId): BracketLedgerEntry | undefined;
+    /** All active (non-terminal) entries. Used by reconciler + telemetry. */
+    getActive(): BracketLedgerEntry[];
+    /** Every entry in the ledger, including terminal ones (kept for audit). */
+    getAll(): BracketLedgerEntry[];
+    /** Remove an entry — typically only called for very old terminal entries
+     *  during periodic cleanup. Does NOT persist unless mutated. */
+    remove(symbol: string): boolean;
+    /** Number of entries currently in the ledger. */
+    size(): number;
+    /** Test seam — full ledger file path. */
+    getFilePath(): string;
+    private loadOrInit;
+    private persist;
+    private validateFile;
+    private validateEntry;
+}