@reefclaw/openclaw-plugin 0.1.0

package/ingest/pending-entry-metadata.d.ts

@@ -0,0 +1,52 @@
+import type { PositionMetadata } from '../simulator/types.js';
+export interface PendingEntry {
+    /** Exchange-issued orderId — the lookup key when the WS fill arrives. */
+    orderId: string;
+    /** Canonical (un-suffixed) symbol. */
+    symbol: string;
+    /** Side the agent intended at create_order time. */
+    side: 'buy' | 'sell';
+    metadata: PositionMetadata;
+    createdAt: number;
+    /** Epoch ms after which this entry is dropped. */
+    expiresAt: number;
+}
+export type NowFn = () => number;
+export interface PendingEntryStoreOptions {
+    pluginId?: string;
+    basePath?: string;
+    now?: NowFn;
+    ttlMs?: number;
+}
+export declare class PendingEntryStore {
+    private readonly filePath;
+    private readonly dir;
+    private readonly now;
+    private readonly ttlMs;
+    private entries;
+    constructor(opts?: PendingEntryStoreOptions);
+    /** Stash metadata until the WS fill for this orderId arrives. */
+    put(input: {
+        orderId: string;
+        symbol: string;
+        side: 'buy' | 'sell';
+        metadata: PositionMetadata;
+    }): void;
+    /** Retrieve metadata stashed for an orderId. Does NOT remove the entry —
+     *  callers should call `consume(orderId)` to remove on first match, since
+     *  multiple partial fills on the same limit order all share one orderId
+     *  and the FIRST fill is the entry; subsequent are scale-ins of an already-
+     *  registered position (state-store branch handles those). */
+    get(orderId: string): PendingEntry | undefined;
+    /** Atomic get + remove. Use this when you've already consumed the metadata
+     *  to post an entry row and don't want it picked up again. */
+    consume(orderId: string): PendingEntry | undefined;
+    /** Remove an entry without retrieval (e.g. on cancel). */
+    drop(orderId: string): boolean;
+    size(): number;
+    getFilePath(): string;
+    private pruneExpired;
+    private loadOrInit;
+    private persist;
+    private validateFile;
+}

package/ingest/pending-entry-metadata.js

@@ -0,0 +1,182 @@
+// Pending-entry metadata cache.
+//
+// When the agent calls create_order with v2.10.0 metadata (thesis, setup_type,
+// regime, scorecard_verdict, confluence_score, etc.) for a LIMIT order that
+// doesn't fill immediately, the metadata is stashed here keyed by the
+// exchange's orderId. When the WS-driven fill arrives later (could be seconds
+// or hours), `onWsFillObserved` looks up the metadata and posts the entry /
+// scale-in decision row with the original rationale intact.
+//
+// Without this cache, limit-order entries land in `position_entries` with
+// thesis='(no thesis recorded)' / setupType='unknown' — useless for Phase 2
+// outcome attribution and Phase 3 mining.
+//
+// Persistence: same atomic-rename pattern as bracket-ledger / position-state-
+// store. File at ~/.openclaw/plugins/<pluginId>/pending-entry-metadata.json.
+//
+// TTL: entries auto-expire 24 hours after creation (limit orders rarely live
+// longer; expired entries are pruned on every load + every write to keep the
+// file bounded).
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolvePluginsBaseDir } from '../util/plugin-paths.js';
+import { logger, formatError } from '../logger.js';
+const TAG = 'pending-entry-metadata';
+const DEFAULT_PLUGIN_ID = 'reefclaw-paper-trading';
+const STATE_FILENAME = 'pending-entry-metadata.json';
+const SCHEMA_VERSION = 1;
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+const defaultNow = () => Date.now();
+export class PendingEntryStore {
+    filePath;
+    dir;
+    now;
+    ttlMs;
+    entries = new Map();
+    constructor(opts) {
+        const base = resolvePluginsBaseDir(opts?.basePath);
+        this.dir = join(base, opts?.pluginId ?? DEFAULT_PLUGIN_ID);
+        this.filePath = join(this.dir, STATE_FILENAME);
+        this.now = opts?.now ?? defaultNow;
+        this.ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
+        if (!existsSync(this.dir))
+            mkdirSync(this.dir, { recursive: true });
+        this.loadOrInit();
+    }
+    /** Stash metadata until the WS fill for this orderId arrives. */
+    put(input) {
+        const ts = this.now();
+        this.entries.set(input.orderId, {
+            orderId: input.orderId,
+            symbol: input.symbol,
+            side: input.side,
+            metadata: input.metadata,
+            createdAt: ts,
+            expiresAt: ts + this.ttlMs,
+        });
+        this.persist();
+    }
+    /** Retrieve metadata stashed for an orderId. Does NOT remove the entry —
+     *  callers should call `consume(orderId)` to remove on first match, since
+     *  multiple partial fills on the same limit order all share one orderId
+     *  and the FIRST fill is the entry; subsequent are scale-ins of an already-
+     *  registered position (state-store branch handles those). */
+    get(orderId) {
+        this.pruneExpired();
+        return this.entries.get(orderId);
+    }
+    /** Atomic get + remove. Use this when you've already consumed the metadata
+     *  to post an entry row and don't want it picked up again. */
+    consume(orderId) {
+        this.pruneExpired();
+        const entry = this.entries.get(orderId);
+        if (!entry)
+            return undefined;
+        this.entries.delete(orderId);
+        this.persist();
+        return entry;
+    }
+    /** Remove an entry without retrieval (e.g. on cancel). */
+    drop(orderId) {
+        const existed = this.entries.delete(orderId);
+        if (existed)
+            this.persist();
+        return existed;
+    }
+    size() {
+        return this.entries.size;
+    }
+    getFilePath() {
+        return this.filePath;
+    }
+    // ---- Internals ----
+    pruneExpired() {
+        const ts = this.now();
+        let pruned = false;
+        for (const [orderId, entry] of this.entries) {
+            if (entry.expiresAt <= ts) {
+                this.entries.delete(orderId);
+                pruned = true;
+            }
+        }
+        if (pruned)
+            this.persist();
+    }
+    loadOrInit() {
+        if (!existsSync(this.filePath)) {
+            logger.info(TAG, `No state file at ${this.filePath}; starting empty`);
+            return;
+        }
+        let raw;
+        try {
+            raw = readFileSync(this.filePath, 'utf8');
+        }
+        catch (err) {
+            throw new Error(`pending-entry-metadata: failed to read ${this.filePath}: ${formatError(err)}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new Error(`pending-entry-metadata: ${this.filePath} is not valid JSON: ${formatError(err)}`);
+        }
+        const file = this.validateFile(parsed);
+        const ts = this.now();
+        let kept = 0;
+        let dropped = 0;
+        for (const entry of file.entries) {
+            if (entry.expiresAt > ts) {
+                this.entries.set(entry.orderId, entry);
+                kept++;
+            }
+            else {
+                dropped++;
+            }
+        }
+        logger.info(TAG, `Loaded ${kept} pending entries from ${this.filePath}` +
+            (dropped > 0 ? ` (pruned ${dropped} expired)` : ''));
+        if (dropped > 0)
+            this.persist();
+    }
+    persist() {
+        const file = {
+            schemaVersion: SCHEMA_VERSION,
+            entries: Array.from(this.entries.values()),
+        };
+        const tempPath = `${this.filePath}.tmp`;
+        writeFileSync(tempPath, JSON.stringify(file, null, 2));
+        renameSync(tempPath, this.filePath);
+    }
+    validateFile(raw) {
+        if (!isRecord(raw))
+            throw new Error('pending-entry-metadata: file root is not an object');
+        if (raw.schemaVersion !== SCHEMA_VERSION) {
+            throw new Error(`pending-entry-metadata: unsupported schemaVersion ${String(raw.schemaVersion)} (expected ${SCHEMA_VERSION})`);
+        }
+        if (!Array.isArray(raw.entries))
+            throw new Error('pending-entry-metadata: entries is not an array');
+        const entries = [];
+        for (const e of raw.entries) {
+            if (!isRecord(e))
+                throw new Error('pending-entry-metadata: entry is not an object');
+            if (typeof e.orderId !== 'string' || e.orderId.length === 0) {
+                throw new Error('pending-entry-metadata: entry missing orderId');
+            }
+            if (typeof e.symbol !== 'string' || e.symbol.length === 0) {
+                throw new Error('pending-entry-metadata: entry missing symbol');
+            }
+            if (e.side !== 'buy' && e.side !== 'sell') {
+                throw new Error(`pending-entry-metadata: bad side ${String(e.side)}`);
+            }
+            if (typeof e.expiresAt !== 'number' || !Number.isFinite(e.expiresAt)) {
+                throw new Error('pending-entry-metadata: missing/invalid expiresAt');
+            }
+            entries.push(e);
+        }
+        return { schemaVersion: SCHEMA_VERSION, entries };
+    }
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

package/ingest/position-auto-capture.d.ts

@@ -0,0 +1,98 @@
+import type { PositionDecisionsClient } from './position-decisions-client.js';
+import type { PositionStateStore } from '../live/position-state-store.js';
+import type { CcxtOrder } from '../types.js';
+import type { PositionMetadata } from '../simulator/types.js';
+import type { PendingEntryStore } from './pending-entry-metadata.js';
+export interface AutoCaptureContext {
+    decisionsClient?: PositionDecisionsClient;
+    stateStore?: PositionStateStore;
+    /** Stash for create_order metadata that arrives BEFORE the fill (limit
+     *  orders that don't fill immediately). Looked up by exchangeOrderId when
+     *  the WS fill arrives via `onWsFillObserved`. */
+    pendingEntries?: PendingEntryStore;
+    userId?: string;
+    /** When true, a reduce-only fill that takes a journaled position flat is
+     *  auto-captured as an exact close (bracket SL/TP fill or other close that
+     *  bypassed close_position). Default behaviour when unset is the legacy
+     *  no-op (reduce-only fills ignored). Env kill-switch: RC_JOURNAL_CLOSE_ON_FILL
+     *  (set 'off' to disable). See docs/CLAUDE/position-journal.md (close-bypass). */
+    closeOnReduceOnlyFill?: boolean;
+    /** Resolve the active trading book ('paper' | 'live') at capture time, read
+     *  from the current adapter (so it follows a runtime reconnect). Tags the
+     *  journal position row so paper and live entries can be segregated. */
+    resolveMode?: () => 'paper' | 'live';
+}
+export interface CreateOrderInputs {
+    symbol: string;
+    side: 'buy' | 'sell';
+    metadata?: PositionMetadata;
+}
+/** 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 declare function onCreateOrderFilled(ctx: AutoCaptureContext, inputs: CreateOrderInputs, order: CcxtOrder): Promise<void>;
+export interface ClosePositionInputs {
+    symbol: string;
+    closeReason: string;
+    closeAssessment: Record<string, unknown>;
+    /** Optional v2.10.0 inputs the agent may have passed alongside reason+assessment. */
+    scorecardVerdict?: string;
+    confluenceScore?: number;
+    regime?: string;
+    regimeConfidence?: number;
+}
+/** 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 declare function onClosePositionFilled(ctx: AutoCaptureContext, inputs: ClosePositionInputs, order: CcxtOrder): Promise<void>;
+/** WS-driven fill observed. Resolves the PR1 deferral that limit-order fills
+ *  + scale-ins were silently dropped. Branches on three cases:
+ *
+ *    - reduceOnly fill   →  ignored here (close path runs from close_position
+ *                            tool with v2.10.0 reason+assessment; bracket SL/TP
+ *                            fills also reduce-only and the legacy bracket
+ *                            handler covers those).
+ *    - new-symbol entry  →  no state-store row → register the position +
+ *                            post entry decision row (uses pending metadata
+ *                            from the cache, or '(no thesis recorded)' fallback).
+ *    - same-side fill on  →  state-store row exists with same side → SCALE-IN.
+ *      existing position    Posts a position_entries row with is_scale_in=true.
+ *                            Does NOT create a new positions row (single parent
+ *                            per open exposure).
+ *    - opposite-side fill →  state-store has same symbol but opposite side.
+ *      on existing position  Treated as a manual flatten that bypassed the
+ *                            close_position tool — skip (cleaner to require
+ *                            close_position for proper rationale capture).
+ *
+ *  Dedup: when create_order's market-order path already captured an entry
+ *  synchronously, the state-store entry's `openedFromExchangeTradeId` matches
+ *  this fill's orderId. We detect that and skip to avoid double-posting. */
+export interface WsFillInputs {
+    symbol: string;
+    side: 'buy' | 'sell';
+    exchangeOrderId: string;
+    exchangeTradeId: string;
+    fillPrice: number;
+    fillSize: number;
+    reduceOnly: boolean;
+    /** Binance-exact realised PnL on this specific fill (`o.rp`). Used to sum the
+     *  position's realised PnL when a reduce-only fill takes it flat. */
+    realizedPnl?: number;
+    /** Client order id of the fill. Lets the reduce-only close handler tag a
+     *  bracket SL/TP fill (cid is a bracket cid) vs an external reduce-only close. */
+    clientOrderId?: string;
+    /** Timestamp from the exchange. Falls back to Date.now() if not provided. */
+    exchangeTimeMs?: number;
+}
+export declare function onWsFillObserved(ctx: AutoCaptureContext, fill: WsFillInputs): Promise<void>;
+/** 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 declare function buildEntryPlanMetadata(md: PositionMetadata | undefined): Record<string, unknown> | undefined;