@reefclaw/openclaw-plugin 0.1.23 → 0.1.25

package/tools/set-trading-mode.js

@@ -12,6 +12,7 @@
 // by design: the check lives once, at registration, for all operator tools.
 import { readPluginConfig } from '../config/plugin-config-io.js';
 import { validateModeTransition, modeRequiresCredentials } from '../onboarding/mode-ladder.js';
+import { checkHlAgentApproval, } from '../venues/hyperliquid/hl-agent-wallet.js';
 import { parseVenue } from '../venues/registry.js';
 import { logger } from '../logger.js';
 import { recordModeTransition } from '../audit/mode-transition-audit.js';
@@ -133,6 +134,48 @@ export async function setTradingModeTool(args, deps) {
             reason: 'acknowledgment_required',
         };
     }
+    // 4.5. HL agent-approval preflight (E2E audit 2026-08-11 #7). An agent key
+    // that is not in the master account's extraAgents list — or whose approval
+    // expired (they last ≤180 days) — signs orders Hyperliquid rejects one by
+    // one: the flip would "succeed", the dashboard would look healthy, and
+    // every order would bounce. Refuse ONLY on a definitive negative from the
+    // exchange; derivation/network failures fail OPEN with a warning (infra
+    // must never block a deliberate operator action — same rule as the
+    // credential-entry guards).
+    let preflightWarnings = [];
+    if (venue === 'hyperliquid' && hlCredentials) {
+        let verdict;
+        try {
+            verdict = await (deps.hlApprovalCheck ?? checkHlAgentApproval)(hlCredentials);
+        }
+        catch (err) {
+            verdict = {
+                approved: null,
+                validUntil: null,
+                warnings: [
+                    `Approval preflight errored (${err instanceof Error ? err.message : String(err)}) — approval not verified.`,
+                ],
+            };
+        }
+        if (verdict.approved === false) {
+            recordModeTransition({ previousMode, targetMode: target, acknowledged, ok: false, reason: 'hl_agent_not_approved' });
+            const why = verdict.warnings.length > 0 ? ` ${verdict.warnings.join(' ')}` : '';
+            return {
+                ok: false,
+                message: `Hyperliquid reports this agent wallet is NOT approved to trade for ${hlCredentials.walletAddress}.` +
+                    `${why} Every live order would be rejected. Approve it first: Dashboard → Settings → ` +
+                    `Exchange connection → Hyperliquid (the guided setup signs one approveAgent transaction), ` +
+                    `then retry ${target}.`,
+                previousMode,
+                mode: previousMode,
+                readiness: deps.runtime.adapter.readiness,
+                reason: 'hl_agent_not_approved',
+            };
+        }
+        preflightWarnings = verdict.warnings;
+        for (const w of preflightWarnings)
+            logger.warn(TAG, `HL preflight: ${w}`);
+    }
     // 5. Persist the new mode.
     try {
         const { updatePluginConfig } = await import('../config/plugin-config-io.js');
@@ -162,7 +205,11 @@ export async function setTradingModeTool(args, deps) {
     });
     return {
         ok: true,
-        message: `Trading mode changed from ${previousMode} to ${target}`,
+        // Preflight warnings (near-expiry approval, zero balance, unverifiable
+        // approval) ride the success message — the operator just took a real-money
+        // action and these are the things to fix before the first order.
+        message: `Trading mode changed from ${previousMode} to ${target}` +
+            (preflightWarnings.length > 0 ? `. Note: ${preflightWarnings.join(' ')}` : ''),
         previousMode,
         mode: deps.runtime.mode,
         readiness: deps.runtime.adapter.readiness,

package/types.d.ts

@@ -63,6 +63,13 @@ export interface CcxtPosition {
     contractSize: number;
     entryPrice: number;
     markPrice: number;
+    /** Paper only: true when NO quote was available for this symbol, so
+     *  `markPrice` is a fabricated fallback (entryPrice) rather than a real mark.
+     *  Consumers that make protective decisions MUST NOT read `markPrice` as
+     *  truth when this is set — a fabricated "flat since entry" mark reads as a
+     *  healthy position and is how a breached stop stayed invisible for 35h.
+     *  Undefined on live (real marks come from the exchange). */
+    markPriceStale?: boolean;
     notional: number;
     unrealizedPnl: number;
     percentage: number;

package/venues/hyperliquid/hl-agent-wallet.d.ts

@@ -27,3 +27,29 @@ export declare function __resetKeccakCacheForTests(): void;
 export declare function deriveAddressFromPrivateKey(privateKey: string): Promise<DeriveAddressResult>;
 /** Case-insensitive address equality (addresses may arrive checksummed). */
 export declare function sameAddress(a: string, b: string): boolean;
+/** One-call approval verdict for the STORED credentials — derivation + the
+ *  unsigned preflight, packaged for the live-flip gate in set_trading_mode
+ *  (E2E audit 2026-08-11 #7: an unapproved/expired agent key reached LIVE
+ *  with a healthy-looking dashboard and every order rejected).
+ *
+ *  Lives HERE, not in hl-preflight.ts, because it takes the PRIVATE KEY —
+ *  hl-preflight's module boundary is addresses-only by design.
+ *
+ *  Verdict semantics (the caller refuses ONLY on `approved === false`):
+ *    false = the exchange answered definitively — the agent address is not in
+ *            extraAgents, or its approval has expired. Real money would be
+ *            un-tradeable; block the flip.
+ *    null  = could not verify (derivation unavailable, HL unreachable,
+ *            extraAgents unreadable). Fail OPEN — infra must never block a
+ *            deliberate operator action; the warning travels instead.
+ *    true  = approved (warnings may still carry a near-expiry nudge). */
+export interface HlAgentApprovalVerdict {
+    approved: boolean | null;
+    validUntil: number | null;
+    warnings: string[];
+}
+export declare function checkHlAgentApproval(creds: {
+    walletAddress: string;
+    agentPrivateKey: string;
+    testnet?: boolean;
+}, fetchImpl?: typeof fetch): Promise<HlAgentApprovalVerdict>;

package/venues/hyperliquid/hl-agent-wallet.js

@@ -116,3 +116,35 @@ export async function deriveAddressFromPrivateKey(privateKey) {
 export function sameAddress(a, b) {
     return a.trim().toLowerCase() === b.trim().toLowerCase();
 }
+export async function checkHlAgentApproval(creds, fetchImpl) {
+    const derived = await deriveAddressFromPrivateKey(creds.agentPrivateKey);
+    if (!derived.ok) {
+        return {
+            approved: null,
+            validUntil: null,
+            warnings: [
+                derived.reason === 'invalid_key'
+                    ? 'The stored agent key looks malformed — approval could not be verified.'
+                    : 'Could not derive the agent wallet address on this host — approval not verified.',
+            ],
+        };
+    }
+    const { hlPreflight } = await import('./hl-preflight.js');
+    const pre = await hlPreflight({
+        walletAddress: creds.walletAddress,
+        agentAddress: derived.address,
+        testnet: creds.testnet === true,
+        fetchImpl,
+    });
+    if (!pre.reachable) {
+        return {
+            approved: null,
+            validUntil: null,
+            warnings: [
+                `Could not reach Hyperliquid to verify the agent approval (${pre.unreachableError ?? 'unknown error'}).`,
+                ...pre.warnings,
+            ],
+        };
+    }
+    return { approved: pre.agentApproved, validUntil: pre.agentValidUntil, warnings: pre.warnings };
+}

package/venues/hyperliquid/hl-live-adapter.d.ts

@@ -6,6 +6,7 @@ import { type HlCredentials } from './hl-private.js';
 import type { BracketId } from '../../live/bracket-types.js';
 import { BracketLedger } from '../../live/bracket-ledger.js';
 import { HlBracketCoordinator } from './hl-bracket-coordinator.js';
+import { type AutoCaptureContext } from '../../ingest/position-auto-capture.js';
 import type { TradeIngestWiring } from '../../live/live-adapter.js';
 export interface HlLiveAdapterOptions {
     credentials: HlCredentials;
@@ -23,6 +24,16 @@ export interface HlLiveAdapterOptions {
      *  via userFillsByTime. Same object boot passes the Binance adapter —
      *  `exchange` MUST be fillExchangeId('hyperliquid'). */
     tradeIngest?: TradeIngestWiring;
+    /** Position-decision journal wiring. When present, a close-direction user-
+     *  stream fill (dir "Close …" or a liquidation fill) is routed through
+     *  `onWsFillObserved` so an exchange-native bracket SL/TP fill journals an
+     *  EXACT close (reason `bracket_fill`) instead of leaking as status='open'
+     *  until the reconciler heals it as `reconciler_observed_flat` — the HL
+     *  analog of the wiring Binance's ws-ingest has carried since PR #205.
+     *  Entry/scale-in fills are deliberately NOT routed (the sync create_order
+     *  path captures them; the WS dedup key is unverified on HL — see
+     *  onUserFill). */
+    autoCapture?: AutoCaptureContext;
     /** Test seams. Production omits both. */
     bracketLedger?: BracketLedger;
     disableUserStream?: boolean;
@@ -54,6 +65,10 @@ export declare class HyperliquidLiveAdapter extends EventEmitter implements IExc
     /** exchangeTime of the newest fill ingested (WS or backfill) — the overlap
      *  low-water mark the reconnect gap backfill widens from. */
     private lastFillIngestMs;
+    /** oid → cloid backfill for fills that omit `cloid` (the journal close path
+     *  recognizes bracket legs by client id). Populated from `orderUpdates`,
+     *  which always carries both. Bounded, insertion-order eviction. */
+    private readonly oidToCloid;
     /** UTC-midnight Day-P&L anchor (KPI-must-equal-the-HL-app, §5.8). HL has no
      *  income endpoint, so the anchor is rebuilt from userFillsByTime + userFunding
      *  each balance fetch. Without this the skill self-computes a bogus anchor and
@@ -187,10 +202,20 @@ export declare class HyperliquidLiveAdapter extends EventEmitter implements IExc
      *  `startPosition` is the position BEFORE this fill — the WS-authoritative
      *  way to know the after-fill total without an extra REST read. */
     private onUserFill;
+    /** Close-direction fill → position-decision journal (close-bypass fix, HL
+     *  arm). Fire-and-forget: a journal POST blip must never touch the WS hot
+     *  path. Reduce-only is derived from `dir` (HL fills carry no reduceOnly
+     *  flag): "Close Long"/"Close Short", plus the liquidation marker. Flip
+     *  dirs ("Long > Short") are NOT closes of a tracked side we understand —
+     *  they stay with the reconciler backstop. */
+    private captureCloseFill;
     /** `orderUpdates` is authoritative for leg lifecycle (the ALGO_UPDATE
-     *  analog). A trigger = the exchange closed the position — surface the same
+     *  analog). A trigger = the exchange closed the position — surface the
      *  `drift_detected` close shape the Binance reconciler emits so the journal
-     *  close-bypass cleanup fires at once, not ≤5 min late. */
+     *  close-bypass cleanup fires fast — but AFTER a short grace, so the close
+     *  FILL (the exact-close journal path, `captureCloseFill`) wins the
+     *  undocumented orderUpdates/userFills frame ordering. The cleanup is
+     *  idempotent: state already dropped by the fill path ⇒ no-op. */
     private onUserOrderUpdate;
     /** T-5 REST truth-check — serialized so a slow pass can't stack. */
     private runTruthCheck;

package/venues/hyperliquid/hl-live-adapter.js

@@ -38,7 +38,8 @@ import { generateBracketId } from '../../live/bracket-id.js';
 import { validateStopDirection, validateTargetDirection } from '../../live/bracket-params.js';
 import { HlBracketCoordinator, isRejectedOrder, isTerminalBracketState, } from './hl-bracket-coordinator.js';
 import { HyperliquidUserStream } from './hl-user-stream.js';
-import { hlFillToFillEvent } from './hl-fill-ingest.js';
+import { hlFillToFillEvent, hlCoinToCanonical } from './hl-fill-ingest.js';
+import { onWsFillObserved } from '../../ingest/position-auto-capture.js';
 import { formatError } from '../../logger.js';
 const TAG = 'hl-live-adapter';
 /** Venue-distinct ledger storage — a venue switch on the same box must never
@@ -55,6 +56,21 @@ const DEFAULT_MARKET_SLIPPAGE = 0.005;
 /** Sticky cooldown after a failed open-orders fetch (the Binance lesson: the
  *  SKILL.md audit→attach loop re-calls every ~3s and would pin the budget). */
 const OPEN_ORDERS_COOLDOWN_MS = 45_000;
+/** Grace before a bracket-trigger `drift_detected` emit. A trigger's close FILL
+ *  arrives on `userFills` and journals the exact close (real price, real PnL,
+ *  reason `bracket_fill`); the drift path's cleanup can only post a generic
+ *  `reconciler_observed_flat`. HL's WS frame ordering between `orderUpdates`
+ *  and `userFills` is undocumented, so without this grace the generic close
+ *  routinely won the race and 50% of HL live closes carried no close reason
+ *  (wisekid, 30d to 2026-08-17: 150/299). The cleanup is idempotent — when the
+ *  fill already journaled + dropped state, the delayed drift is a no-op; when
+ *  the fill never arrives (T-5 gap), the drift still heals, 10s late instead
+ *  of instant (previously ≤5 min via the periodic sweep). */
+const TRIGGER_DRIFT_GRACE_MS = 10_000;
+/** Bound on the oid→cloid map (fills MAY omit `cloid` — facts ledger §3.4 —
+ *  while `orderUpdates` always carries both, so the map backfills the fill's
+ *  client id for bracket recognition). Insertion-ordered eviction. */
+const OID_CLOID_MAP_MAX = 512;
 export class HyperliquidLiveAdapter extends EventEmitter {
     opts;
     api;
@@ -82,6 +98,10 @@ export class HyperliquidLiveAdapter extends EventEmitter {
     /** exchangeTime of the newest fill ingested (WS or backfill) — the overlap
      *  low-water mark the reconnect gap backfill widens from. */
     lastFillIngestMs = 0;
+    /** oid → cloid backfill for fills that omit `cloid` (the journal close path
+     *  recognizes bracket legs by client id). Populated from `orderUpdates`,
+     *  which always carries both. Bounded, insertion-order eviction. */
+    oidToCloid = new Map();
     /** UTC-midnight Day-P&L anchor (KPI-must-equal-the-HL-app, §5.8). HL has no
      *  income endpoint, so the anchor is rebuilt from userFillsByTime + userFunding
      *  each balance fetch. Without this the skill self-computes a bogus anchor and
@@ -821,6 +841,19 @@ export class HyperliquidLiveAdapter extends EventEmitter {
         // healed it, in a repeating flap. Exchange truth is the resync's job.
         if (meta?.isSnapshot)
             return;
+        // Journal close capture: a close-direction fill (bracket SL/TP trigger,
+        // liquidation, external reduce) bypasses close_position, and before this
+        // wiring the journal only learned about it from the reconciler — 50% of
+        // wisekid's 30d closes were `reconciler_observed_flat` heals with the
+        // close reason lost. Route it through the SAME generic path Binance's
+        // ws-ingest uses; `handleReduceOnlyExit` posts the exact close when the
+        // position goes flat and defers to close_position/backstop otherwise.
+        // ONLY close-direction fills are routed: entry/scale-in fills stay with
+        // the synchronous create_order capture, because the WS dedup key
+        // (`openedFromExchangeTradeId === exchangeOrderId`) is unverified against
+        // ccxt's HL order.id shape and a dedup miss would re-mint the 38-duplicate-
+        // pairs class (issue #199 twin bug).
+        this.captureCloseFill(fill);
         try {
             // Matches the primary entry cid OR any additional cid recorded for a
             // scale-in / second resting entry (F5) — matching on `entryCid` alone
@@ -848,27 +881,82 @@ export class HyperliquidLiveAdapter extends EventEmitter {
             logger.error(TAG, `onUserFill handler error: ${formatError(err)}`);
         }
     }
+    /** Close-direction fill → position-decision journal (close-bypass fix, HL
+     *  arm). Fire-and-forget: a journal POST blip must never touch the WS hot
+     *  path. Reduce-only is derived from `dir` (HL fills carry no reduceOnly
+     *  flag): "Close Long"/"Close Short", plus the liquidation marker. Flip
+     *  dirs ("Long > Short") are NOT closes of a tracked side we understand —
+     *  they stay with the reconciler backstop. */
+    captureCloseFill(fill) {
+        const capture = this.opts.autoCapture;
+        if (!capture)
+            return;
+        const dir = (fill.dir ?? '').toLowerCase();
+        const isClose = dir.startsWith('close') || fill.liquidation !== undefined;
+        if (!isClose)
+            return;
+        const price = Number(fill.px);
+        const size = Number(fill.sz);
+        if (!Number.isFinite(price) || price <= 0 || !Number.isFinite(size) || size <= 0)
+            return;
+        const realizedPnl = Number(fill.closedPnl);
+        const cloid = typeof fill.cloid === 'string' && fill.cloid.length > 0
+            ? fill.cloid
+            : this.oidToCloid.get(fill.oid);
+        onWsFillObserved(capture, {
+            symbol: hlCoinToCanonical(fill.coin),
+            side: fill.side === 'B' ? 'buy' : 'sell',
+            exchangeOrderId: String(fill.oid),
+            exchangeTradeId: String(fill.tid),
+            fillPrice: price,
+            fillSize: size,
+            reduceOnly: true,
+            realizedPnl: Number.isFinite(realizedPnl) ? realizedPnl : undefined,
+            clientOrderId: cloid,
+            exchangeTimeMs: Number.isFinite(fill.time) ? fill.time : undefined,
+        }).catch((err) => {
+            logger.warn(TAG, `journal close capture failed for ${fill.coin} oid=${fill.oid}: ${msg(err)}`);
+        });
+    }
     /** `orderUpdates` is authoritative for leg lifecycle (the ALGO_UPDATE
-     *  analog). A trigger = the exchange closed the position — surface the same
+     *  analog). A trigger = the exchange closed the position — surface the
      *  `drift_detected` close shape the Binance reconciler emits so the journal
-     *  close-bypass cleanup fires at once, not ≤5 min late. */
+     *  close-bypass cleanup fires fast — but AFTER a short grace, so the close
+     *  FILL (the exact-close journal path, `captureCloseFill`) wins the
+     *  undocumented orderUpdates/userFills frame ordering. The cleanup is
+     *  idempotent: state already dropped by the fill path ⇒ no-op. */
     onUserOrderUpdate(update) {
         try {
+            // oid→cloid backfill for fills that omit their client id (see
+            // captureCloseFill). orderUpdates always carries both.
+            const { oid, cloid } = update.order;
+            if (typeof oid === 'number' && typeof cloid === 'string' && cloid.length > 0) {
+                this.oidToCloid.set(oid, cloid);
+                if (this.oidToCloid.size > OID_CLOID_MAP_MAX) {
+                    const oldest = this.oidToCloid.keys().next().value;
+                    if (oldest !== undefined)
+                        this.oidToCloid.delete(oldest);
+                }
+            }
             const transition = this.getHlBracketCoordinator().handleOrderUpdate(update);
             if (transition === 'triggered_sl' || transition === 'triggered_tp' || transition === 'forced_close') {
                 const row = this.getHlBracketCoordinator().getLedger().getAll().find((r) => update.order.cloid && (r.slCid === update.order.cloid || r.tpCid === update.order.cloid));
                 const symbol = row?.symbol;
                 if (symbol) {
-                    this.emit('drift_detected', {
-                        timestamp: new Date().toISOString(),
-                        drifts: [
-                            {
-                                type: 'closed',
-                                symbol,
-                                localContracts: row?.qty ?? 0,
-                            },
-                        ],
-                    });
+                    const qty = row?.qty ?? 0;
+                    const timer = setTimeout(() => {
+                        this.emit('drift_detected', {
+                            timestamp: new Date().toISOString(),
+                            drifts: [
+                                {
+                                    type: 'closed',
+                                    symbol,
+                                    localContracts: qty,
+                                },
+                            ],
+                        });
+                    }, TRIGGER_DRIFT_GRACE_MS);
+                    timer.unref?.();
                 }
             }
         }