@reefclaw/openclaw-plugin 0.1.0

package/ingest/position-auto-capture.js

@@ -0,0 +1,394 @@
+// Auto-capture helper for the Position Decision Journal.
+//
+// Wires create_order / close_position / fill events into the webapp ingest:
+//
+//   ENTRY  — onCreateOrderFilled() upserts the parent positions row, gets back
+//             the UUID, persists it locally for restart-survival, then posts the
+//             entry decision row.
+//   CLOSE  — onClosePositionFilled() looks up the cached position UUID and posts
+//             the close decision row. Local position-state is dropped after the
+//             dispatch so the symbol can re-enter cleanly.
+//
+// Auto-capture is mode-agnostic — it runs whenever the decisions client is
+// configured (env vars present), regardless of trading mode (PAPER vs LIVE) or
+// positionReview.mode. Fail-open: a network blip on a webapp POST does not
+// block the trading hot path.
+//
+// PR 1 scope: market orders (immediate fill detection from CcxtOrder.filled).
+// Limit-order fill capture and scale-in detection are deferred to a follow-up
+// that hooks into the WS-ingest pipeline (see POSITION_DECISION_JOURNAL_PLAN
+// §5.1 for the longer-term design).
+import { logger } from '../logger.js';
+import { isBracketCid } from '../live/bracket-id.js';
+const TAG = 'position-auto-capture';
+/** Flatness tolerance for remaining-contracts tracking. Reduce-only fills sum
+ *  exactly to the position size on Binance, so any residual below this is noise
+ *  / float rounding and means the position is flat. */
+const FLAT_EPSILON = 1e-6;
+/** Called after a successful adapter.createOrder().
+ *
+ *  For PR 1, we treat any non-zero `filled` quantity as an entry event and
+ *  upsert the parent position + post the entry decision row. Limit orders that
+ *  haven't filled yet are skipped (caller can call us again from the WS-ingest
+ *  pipeline once they fill — that wiring is the follow-up).
+ *
+ *  Always-fail-open: webapp errors are logged but never thrown.
+ */
+export async function onCreateOrderFilled(ctx, inputs, order) {
+    if (!ctx.decisionsClient || !ctx.userId || !ctx.stateStore)
+        return;
+    const filledQty = typeof order.filled === 'number' && Number.isFinite(order.filled)
+        ? order.filled
+        : 0;
+    if (filledQty <= 0) {
+        // Limit order not yet filled — nothing to capture yet.
+        return;
+    }
+    const fillPrice = typeof order.average === 'number' && Number.isFinite(order.average) && order.average > 0
+        ? order.average
+        : typeof order.price === 'number' && Number.isFinite(order.price) && order.price > 0
+            ? order.price
+            : null;
+    if (fillPrice === null) {
+        logger.warn(TAG, `onCreateOrderFilled ${inputs.symbol}: missing fill price; skipping capture`);
+        return;
+    }
+    // Need v2.10.0 metadata to build a meaningful entry row. In paper mode the
+    // agent may omit them; we still capture an entry but mark missing fields.
+    const md = inputs.metadata;
+    if (!md) {
+        logger.info(TAG, `onCreateOrderFilled ${inputs.symbol}: no metadata; skipping (paper without rationale)`);
+        return;
+    }
+    const positionSide = inputs.side === 'buy' ? 'long' : 'short';
+    const openedAtMs = Date.now();
+    // Skip if state-store already knows about this position (scale-in / partial
+    // fill of an existing entry). PR 1 deferral: don't record additional entries.
+    // The follow-up that hooks WS-ingest will detect scale-ins explicitly.
+    const existing = ctx.stateStore.get(inputs.symbol);
+    if (existing) {
+        logger.info(TAG, `onCreateOrderFilled ${inputs.symbol}: existing position in state-store (openedAt=${existing.openedAt}); treating as scale-in (auto-capture deferred to v2)`);
+        return;
+    }
+    // Local state-store first — ensures restart-survival even if the webapp POST
+    // fails on the first attempt.
+    ctx.stateStore.upsert({
+        symbol: inputs.symbol,
+        openedAt: openedAtMs,
+        side: positionSide,
+        openedFromExchangeTradeId: typeof order.id === 'string' ? order.id : undefined,
+    });
+    const upsert = {
+        symbol: inputs.symbol,
+        positionOpenAt: openedAtMs,
+        side: positionSide,
+        currentSize: filledQty,
+        avgEntryPrice: fillPrice,
+        mode: ctx.resolveMode?.(),
+    };
+    // postPosition is awaited — we need the UUID before posting the entry row.
+    const positionId = await ctx.decisionsClient.postPosition(ctx.userId, upsert);
+    if (!positionId) {
+        logger.warn(TAG, `onCreateOrderFilled ${inputs.symbol}: webapp position upsert returned no id; entry row will not be posted (will retry on next observation)`);
+        return;
+    }
+    ctx.stateStore.setWebappId(inputs.symbol, positionId);
+    // Track size so a later reduce-only/bracket exit fill can detect flat + close.
+    ctx.stateStore.addOpenContracts(inputs.symbol, filledQty);
+    // Build entry decision payload from the v2.10.0 metadata.
+    // regime_confidence stored 0-100 in PositionMetadata (per validator), but the
+    // webapp schema expects 0-1. Normalize.
+    const regimeConfNormalized = typeof md.regimeConfidence === 'number'
+        ? Math.max(0, Math.min(1, md.regimeConfidence / 100))
+        : 0.5;
+    const entry = {
+        positionId,
+        entryAt: openedAtMs,
+        isScaleIn: false,
+        thesis: md.thesis ?? '(no thesis recorded)',
+        setupType: md.setupType ?? 'unknown',
+        regime: md.regime ?? 'unknown',
+        regimeConfidence: regimeConfNormalized,
+        scorecardVerdict: md.scorecardVerdict ?? 'GO',
+        confluenceScore: typeof md.confluenceScore === 'number' ? md.confluenceScore : 0,
+        fillPrice,
+        fillSize: filledQty,
+        exchangeTradeId: typeof order.id === 'string' ? order.id : undefined,
+        metadata: buildEntryPlanMetadata(md),
+    };
+    ctx.decisionsClient.postEntry(ctx.userId, entry);
+    logger.info(TAG, `entry captured ${inputs.symbol} ${positionSide} ${filledQty} @ ${fillPrice} (positionId=${positionId.slice(0, 8)}…)`);
+}
+/** Called after a successful adapter.closePosition() with the v2.10.0 reason +
+ *  assessment from close_position.ts. Looks up the cached position UUID, posts
+ *  the close decision row, and drops the local state entry. */
+export async function onClosePositionFilled(ctx, inputs, order) {
+    if (!ctx.decisionsClient || !ctx.userId || !ctx.stateStore)
+        return;
+    const stateEntry = ctx.stateStore.get(inputs.symbol);
+    if (!stateEntry || !stateEntry.webappPositionId) {
+        logger.warn(TAG, `onClosePositionFilled ${inputs.symbol}: no cached webappPositionId; close row will not be posted (entry was not captured)`);
+        return;
+    }
+    const filledQty = typeof order.filled === 'number' && Number.isFinite(order.filled)
+        ? order.filled
+        : 0;
+    const fillPrice = typeof order.average === 'number' && Number.isFinite(order.average) && order.average > 0
+        ? order.average
+        : typeof order.price === 'number' && Number.isFinite(order.price) && order.price > 0
+            ? order.price
+            : null;
+    if (filledQty <= 0 || fillPrice === null) {
+        logger.warn(TAG, `onClosePositionFilled ${inputs.symbol}: missing fill quantity or price; skipping capture`);
+        return;
+    }
+    const closeAtMs = Date.now();
+    // Realized PnL + R-multiple require entry-side state we don't have here for
+    // PR 1. The skill-side computation already produces these for the webapp;
+    // this auto-capture just records what the close tool input told us. Default
+    // numeric fields to 0 — webapp accepts and the operator will see the close
+    // card with zeros until the v2 ws-ingest hook fills them properly.
+    const regimeConfNormalized = typeof inputs.regimeConfidence === 'number'
+        ? Math.max(0, Math.min(1, inputs.regimeConfidence / 100))
+        : 0.5;
+    const close = {
+        positionId: stateEntry.webappPositionId,
+        closeAt: closeAtMs,
+        closeReason: inputs.closeReason,
+        closeAssessment: inputs.closeAssessment,
+        scorecardVerdict: inputs.scorecardVerdict ?? 'NO_GO',
+        confluenceScore: typeof inputs.confluenceScore === 'number' ? inputs.confluenceScore : 0,
+        regime: inputs.regime ?? 'unknown',
+        regimeConfidence: regimeConfNormalized,
+        fillPrice,
+        fillSize: filledQty,
+        realizedPnl: 0, // populated by v2 ws-ingest hook
+        realizedR: 0,
+        mfeRAtClose: 0,
+        giveBackPctAtClose: 0,
+        exchangeTradeId: typeof order.id === 'string' ? order.id : undefined,
+    };
+    ctx.decisionsClient.postClose(ctx.userId, close);
+    // Drop local state — symbol can re-enter as a new position.
+    ctx.stateStore.remove(inputs.symbol);
+    logger.info(TAG, `close captured ${inputs.symbol} reason=${inputs.closeReason} (positionId=${stateEntry.webappPositionId.slice(0, 8)}…)`);
+}
+export async function onWsFillObserved(ctx, fill) {
+    if (!ctx.decisionsClient || !ctx.userId || !ctx.stateStore)
+        return;
+    if (fill.fillPrice <= 0 || fill.fillSize <= 0)
+        return;
+    // Reduce-only fills are exit-side. close_position tool exits are journaled by
+    // onClosePositionFilled; bracket SL/TP fills and other reduce-only closes
+    // bypass that path entirely and used to leave the journal position open
+    // forever (close-bypass class). When closeOnReduceOnlyFill is enabled, detect
+    // the position going flat from the fill(s) and journal an exact close.
+    if (fill.reduceOnly) {
+        await handleReduceOnlyExit(ctx, fill);
+        return;
+    }
+    const stateEntry = ctx.stateStore.get(fill.symbol);
+    const fillSide = fill.side === 'buy' ? 'long' : 'short';
+    const ts = fill.exchangeTimeMs ?? Date.now();
+    if (stateEntry) {
+        // Dedup: if the synchronous create_order path already captured this
+        // exact order (orderId match), the WS event is the same fill — skip.
+        if (stateEntry.openedFromExchangeTradeId === fill.exchangeOrderId) {
+            return;
+        }
+        if (stateEntry.side !== fillSide) {
+            // Opposite-side fill on an existing position. Almost certainly a manual
+            // flatten that bypassed close_position. Don't journal here — the
+            // operator should use close_position with reason+assessment instead.
+            logger.warn(TAG, `onWsFillObserved ${fill.symbol}: opposite-side fill on existing ${stateEntry.side} position; skipping (use close_position for rationale capture)`);
+            return;
+        }
+        // SCALE-IN: same symbol, same side, fresh fill.
+        if (!stateEntry.webappPositionId) {
+            logger.warn(TAG, `onWsFillObserved ${fill.symbol}: scale-in observed but no webappPositionId yet — skipping (parent upsert may have failed; will retry next fill)`);
+            return;
+        }
+        const pending = ctx.pendingEntries?.consume(fill.exchangeOrderId);
+        const entry = buildEntryPayload({
+            positionId: stateEntry.webappPositionId,
+            isScaleIn: true,
+            ts,
+            fillPrice: fill.fillPrice,
+            fillSize: fill.fillSize,
+            exchangeTradeId: fill.exchangeTradeId,
+            metadata: pending?.metadata,
+        });
+        ctx.decisionsClient.postEntry(ctx.userId, entry);
+        // Grow tracked size so a later reduce-only exit detects flat correctly.
+        ctx.stateStore.addOpenContracts(fill.symbol, fill.fillSize);
+        logger.info(TAG, `scale-in captured ${fill.symbol} ${fillSide} ${fill.fillSize} @ ${fill.fillPrice} ` +
+            `(positionId=${stateEntry.webappPositionId.slice(0, 8)}…)`);
+        return;
+    }
+    // No state-store entry → NEW position via WS-driven fill. Replicates the
+    // synchronous-market-order path but pulls metadata from the pending cache
+    // (which create_order populated when the limit was placed).
+    const pending = ctx.pendingEntries?.consume(fill.exchangeOrderId);
+    ctx.stateStore.upsert({
+        symbol: fill.symbol,
+        openedAt: ts,
+        side: fillSide,
+        openedFromExchangeTradeId: fill.exchangeOrderId,
+    });
+    const upsert = {
+        symbol: fill.symbol,
+        positionOpenAt: ts,
+        side: fillSide,
+        currentSize: fill.fillSize,
+        avgEntryPrice: fill.fillPrice,
+        mode: ctx.resolveMode?.(),
+    };
+    const positionId = await ctx.decisionsClient.postPosition(ctx.userId, upsert);
+    if (!positionId) {
+        logger.warn(TAG, `onWsFillObserved ${fill.symbol}: webapp position upsert returned no id; entry row will not be posted`);
+        return;
+    }
+    ctx.stateStore.setWebappId(fill.symbol, positionId);
+    // Track size so a later reduce-only/bracket exit fill can detect flat + close.
+    ctx.stateStore.addOpenContracts(fill.symbol, fill.fillSize);
+    const entry = buildEntryPayload({
+        positionId,
+        isScaleIn: false,
+        ts,
+        fillPrice: fill.fillPrice,
+        fillSize: fill.fillSize,
+        exchangeTradeId: fill.exchangeTradeId,
+        metadata: pending?.metadata,
+    });
+    ctx.decisionsClient.postEntry(ctx.userId, entry);
+    logger.info(TAG, `entry captured (ws) ${fill.symbol} ${fillSide} ${fill.fillSize} @ ${fill.fillPrice} ` +
+        `(positionId=${positionId.slice(0, 8)}…, metadata=${pending ? 'cached' : 'none'})`);
+}
+/** Reduce-only exit fill handler — the close-bypass fix. When enabled, sums the
+ *  fill's realised PnL into the tracked position and, once remaining size hits
+ *  flat, posts an exact close decision row (Binance-exact realised PnL, real
+ *  exit price) and drops the local state entry. Idempotent at the webapp
+ *  (position_closes UNIQUE on position_id); fail-open. */
+async function handleReduceOnlyExit(ctx, fill) {
+    if (!ctx.decisionsClient || !ctx.userId || !ctx.stateStore)
+        return;
+    // Gated: when off, preserve the legacy behaviour (reduce-only fills ignored).
+    if (!ctx.closeOnReduceOnlyFill)
+        return;
+    const stateEntry = ctx.stateStore.get(fill.symbol);
+    // No tracked entry (already cleaned, or never journaled) → nothing to close.
+    if (!stateEntry || !stateEntry.webappPositionId)
+        return;
+    const updated = ctx.stateStore.applyExitContracts(fill.symbol, fill.fillSize, fill.realizedPnl ?? 0);
+    if (!updated) {
+        // Size unknown for this entry (opened before tracking existed and not yet
+        // seeded). Can't decide flatness from fills — leave the reconciler/ALGO
+        // close-bypass path as the backstop.
+        logger.info(TAG, `reduce-only fill ${fill.symbol}: size untracked; deferring close to reconciler/ALGO backstop`);
+        return;
+    }
+    const remaining = updated.remainingContracts ?? 0;
+    if (remaining > FLAT_EPSILON) {
+        logger.info(TAG, `partial exit ${fill.symbol}: ${fill.fillSize} reduce-only fill, ${remaining} contracts remaining`);
+        return; // not flat yet — keep accumulating
+    }
+    // FLAT. Auto-journal an exact close ONLY for exchange-native bracket fills
+    // (the cid is one of our bracket legs). Non-bracket reduce-only flats are
+    // either close_position's own order (its WS fill can race ahead of
+    // onClosePositionFilled) or a manual/external close — both are handled by
+    // their own paths (close_position's rich reason+assessment, or the reconciler
+    // backstop). Closing here would clobber the agent's close reasoning, so defer.
+    const isBracket = fill.clientOrderId ? isBracketCid(fill.clientOrderId) : false;
+    if (!isBracket) {
+        logger.info(TAG, `${fill.symbol} flat via non-bracket reduce-only fill (cid=${fill.clientOrderId ?? 'none'}) — ` +
+            `deferring close to close_position / reconciler backstop (no clobber)`);
+        return; // do NOT remove — onClosePositionFilled / backstop owns this close
+    }
+    const realizedPnl = updated.realizedPnlAccum ?? 0;
+    const close = {
+        positionId: stateEntry.webappPositionId,
+        closeAt: fill.exchangeTimeMs ?? Date.now(),
+        closeReason: 'bracket_fill',
+        closeAssessment: {
+            note: 'Position closed by an exchange-native bracket SL/TP fill (reduce-only). ' +
+                'Auto-journaled from the WS fill — no close_position call (close-bypass path).',
+            observedFrom: 'ws_reduce_only_fill',
+            clientOrderId: fill.clientOrderId,
+        },
+        scorecardVerdict: 'NO_GO',
+        confluenceScore: 0,
+        regime: 'unknown',
+        regimeConfidence: 0.5,
+        fillPrice: fill.fillPrice,
+        fillSize: Math.abs(fill.fillSize),
+        // realizedPnl is Binance-exact (summed across exit fills). When it's a true
+        // break-even 0 the webapp recomputes from entries server-side — harmless.
+        realizedPnl,
+        realizedR: 0,
+        mfeRAtClose: 0,
+        giveBackPctAtClose: 0,
+        exchangeTradeId: fill.exchangeTradeId,
+    };
+    ctx.decisionsClient.postClose(ctx.userId, close);
+    ctx.stateStore.remove(fill.symbol);
+    logger.info(TAG, `close captured (ws bracket fill) ${fill.symbol} pnl=${realizedPnl.toFixed(4)} ` +
+        `(positionId=${stateEntry.webappPositionId.slice(0, 8)}…)`);
+}
+/** Internal helper — builds the PositionEntryPayload from a fill, applying the
+ *  same regimeConfidence normalisation (0-100 → 0-1) as the synchronous path. */
+function buildEntryPayload(args) {
+    const md = args.metadata;
+    const regimeConfNormalized = typeof md?.regimeConfidence === 'number'
+        ? Math.max(0, Math.min(1, md.regimeConfidence / 100))
+        : 0.5;
+    return {
+        positionId: args.positionId,
+        entryAt: args.ts,
+        isScaleIn: args.isScaleIn,
+        thesis: md?.thesis ?? '(no thesis recorded)',
+        setupType: md?.setupType ?? 'unknown',
+        regime: md?.regime ?? 'unknown',
+        regimeConfidence: regimeConfNormalized,
+        scorecardVerdict: md?.scorecardVerdict ?? 'GO',
+        confluenceScore: typeof md?.confluenceScore === 'number' ? md.confluenceScore : 0,
+        fillPrice: args.fillPrice,
+        fillSize: args.fillSize,
+        exchangeTradeId: args.exchangeTradeId,
+        metadata: buildEntryPlanMetadata(md),
+    };
+}
+/** Pinned-plan subset persisted to position_entries.metadata (free-form JSONB).
+ *  Keys are snake_case per the canonical-JSONB-key rule (CLAUDE.md learning-loop:
+ *  a camelCase mismatch previously broke learning matching). Returns undefined
+ *  when neither field is present so we never write an empty object. */
+export function buildEntryPlanMetadata(md) {
+    if (!md)
+        return undefined;
+    const out = {};
+    if (typeof md.invalidationPrice === 'number' && Number.isFinite(md.invalidationPrice)) {
+        out.invalidation_price = md.invalidationPrice;
+    }
+    // Pin the planned profit target too — it's the agent's stated target (and the
+    // bracket TP in live), surfaced on the dashboard pinned-plan view. Distinct
+    // from realization_rule (which is mostly omitted); without this the target is
+    // blank on the journal/Trade-card pinned-plan surfaces in the common case.
+    if (typeof md.targetPrice === 'number' && Number.isFinite(md.targetPrice)) {
+        out.target_price = md.targetPrice;
+    }
+    const rr = md.realizationRule;
+    if (rr) {
+        const j = { type: rr.type };
+        if (rr.targetPrice != null)
+            j.target_price = rr.targetPrice;
+        if (rr.trailAfterR != null)
+            j.trail_after_r = rr.trailAfterR;
+        if (rr.trailDistanceR != null)
+            j.trail_distance_r = rr.trailDistanceR;
+        if (rr.scale)
+            j.scale = rr.scale.map((s) => ({ at_r: s.atR, fraction: s.fraction }));
+        if (rr.note)
+            j.note = rr.note;
+        out.realization_rule = j;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}