@reefclaw/openclaw-plugin 0.1.0

package/live/position-state-store.js

@@ -0,0 +1,237 @@
+// Position state store — restart-survival for the Position Decision Journal.
+//
+// Tracks the minimal per-open-position state the auto-capture pipeline needs
+// to keep the (symbol, positionOpenAt) join key stable across plugin restarts:
+//
+//   - openedAt:  authoritative timestamp of the first opening fill, used as the
+//                webapp's natural-key column. Without persistence, restart would
+//                reset every position's openedAt to "now" and break the join.
+//   - webappPositionId: the UUID returned by POST /api/internal/positions; needed
+//                so subsequent /position-{entries,reviews,closes} POSTs can
+//                reference the correct parent row.
+//   - lastReviewAt + lastVerdict: drives the stale-review gate (per
+//                POSITION_REVIEW_PLAN.md §7.4). Cheap to recompute from the
+//                webapp on boot, but persisting locally avoids a round-trip
+//                during the gate-check hot path.
+//
+// Storage: full JSON rewrite + atomic rename, same pattern as bracket-ledger.
+//   Path: ~/.openclaw/plugins/<pluginId>/position-state.json
+//   Symbols stored in canonical (un-suffixed) form via normalizeBracketSymbol.
+//
+// Recovery on boot:
+//   - If the file exists and is valid, load it.
+//   - If not, start empty. On the next position observation (live: getPositions
+//     tick; paper: state.json load) the auto-capture pipeline seeds new entries.
+//
+// See docs/POSITION_DECISION_JOURNAL_PLAN.md §4.5.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { logger, formatError } from '../logger.js';
+import { normalizeBracketSymbol } from './bracket-ledger.js';
+import { resolvePluginsBaseDir } from '../util/plugin-paths.js';
+const TAG = 'position-state-store';
+const DEFAULT_PLUGIN_ID = 'reefclaw-paper-trading';
+const STATE_FILENAME = 'position-state.json';
+const SCHEMA_VERSION = 1;
+const defaultNow = () => Date.now();
+export class PositionStateStore {
+    filePath;
+    dir;
+    now;
+    entries = new Map(); // key = canonical symbol
+    constructor(pluginId, opts) {
+        const base = resolvePluginsBaseDir(opts?.basePath);
+        this.dir = join(base, pluginId ?? DEFAULT_PLUGIN_ID);
+        this.filePath = join(this.dir, STATE_FILENAME);
+        this.now = opts?.now ?? defaultNow;
+        if (!existsSync(this.dir))
+            mkdirSync(this.dir, { recursive: true });
+        this.loadOrInit();
+    }
+    /** Insert or update a position. Caller is responsible for deciding when
+     *  to call this — typically on first observation of a new position. */
+    upsert(entry) {
+        const ts = this.now();
+        const symbol = normalizeBracketSymbol(entry.symbol);
+        const existing = this.entries.get(symbol);
+        const full = {
+            ...entry,
+            symbol,
+            createdAt: existing?.createdAt ?? entry.createdAt ?? ts,
+            updatedAt: ts,
+        };
+        this.entries.set(symbol, full);
+        this.persist();
+        return full;
+    }
+    /** Set the webapp positionId after the upsert returns. Idempotent. */
+    setWebappId(symbol, webappPositionId) {
+        const key = normalizeBracketSymbol(symbol);
+        const current = this.entries.get(key);
+        if (!current) {
+            logger.warn(TAG, `setWebappId: no entry for ${key} — dropping ${webappPositionId}`);
+            return;
+        }
+        if (current.webappPositionId === webappPositionId)
+            return;
+        this.entries.set(key, { ...current, webappPositionId, updatedAt: this.now() });
+        this.persist();
+    }
+    /** Update review tracking after a successful record_position_reviews call.
+     *  thesisStatus is optional for backwards compatibility — older callers that
+     *  predate the exit-gate work pass only verdict; the gate falls back to
+     *  PASS('inputs_unavailable_thesis_status') when the field isn't cached. */
+    recordReview(symbol, verdict, reviewAt, thesisStatus) {
+        const key = normalizeBracketSymbol(symbol);
+        const current = this.entries.get(key);
+        if (!current)
+            return;
+        this.entries.set(key, {
+            ...current,
+            lastReviewAt: reviewAt ?? this.now(),
+            lastVerdict: verdict,
+            lastThesisStatus: thesisStatus ?? current.lastThesisStatus,
+            updatedAt: this.now(),
+        });
+        this.persist();
+    }
+    /** Add opening contracts to the running size (first opening fill or a
+     *  scale-in). Initialises the realised-PnL accumulator on first open. No-op
+     *  if the entry doesn't exist yet (caller upserts the entry first). */
+    addOpenContracts(symbol, qty) {
+        const key = normalizeBracketSymbol(symbol);
+        const current = this.entries.get(key);
+        if (!current || !(qty > 0))
+            return;
+        this.entries.set(key, {
+            ...current,
+            remainingContracts: (current.remainingContracts ?? 0) + qty,
+            realizedPnlAccum: current.realizedPnlAccum ?? 0,
+            updatedAt: this.now(),
+        });
+        this.persist();
+    }
+    /** Seed remaining contracts from exchange truth at startup. Only sets when
+     *  the size is currently unknown — never clobbers live fill-tracked state. */
+    seedRemainingContracts(symbol, qty) {
+        const key = normalizeBracketSymbol(symbol);
+        const current = this.entries.get(key);
+        if (!current || current.remainingContracts !== undefined || !(qty > 0))
+            return;
+        this.entries.set(key, {
+            ...current,
+            remainingContracts: qty,
+            realizedPnlAccum: current.realizedPnlAccum ?? 0,
+            updatedAt: this.now(),
+        });
+        this.persist();
+    }
+    /** Apply a reduce-only exit fill: decrement remaining contracts and sum the
+     *  fill's realised PnL. Returns the updated entry so the caller can journal a
+     *  close when the position is flat, or null when there's no tracked entry or
+     *  the size is unknown (can't decide flatness — defer to the backstop). */
+    applyExitContracts(symbol, qty, realizedPnl) {
+        const key = normalizeBracketSymbol(symbol);
+        const current = this.entries.get(key);
+        if (!current || current.remainingContracts === undefined || !(qty > 0))
+            return null;
+        const updated = {
+            ...current,
+            remainingContracts: current.remainingContracts - qty,
+            realizedPnlAccum: (current.realizedPnlAccum ?? 0) + (Number.isFinite(realizedPnl) ? realizedPnl : 0),
+            updatedAt: this.now(),
+        };
+        this.entries.set(key, updated);
+        this.persist();
+        return updated;
+    }
+    get(symbol) {
+        return this.entries.get(normalizeBracketSymbol(symbol));
+    }
+    /** Returns all entries — used by the stale-gate to enumerate open positions. */
+    getAll() {
+        return Array.from(this.entries.values());
+    }
+    /** Drop an entry — called when the auto-capture pipeline observes the
+     *  position has closed (size dropped to zero on the exchange). */
+    remove(symbol) {
+        const existed = this.entries.delete(normalizeBracketSymbol(symbol));
+        if (existed)
+            this.persist();
+        return existed;
+    }
+    size() {
+        return this.entries.size;
+    }
+    getFilePath() {
+        return this.filePath;
+    }
+    // ---- Internals ----
+    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(`position-state-store: failed to read ${this.filePath}: ${formatError(err)}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new Error(`position-state-store: ${this.filePath} is not valid JSON: ${formatError(err)}`);
+        }
+        const file = this.validateFile(parsed);
+        for (const entry of file.entries) {
+            this.entries.set(entry.symbol, entry);
+        }
+        logger.info(TAG, `Loaded ${this.entries.size} entries from ${this.filePath}`);
+    }
+    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('position-state-store: file root is not an object');
+        if (raw.schemaVersion !== SCHEMA_VERSION) {
+            throw new Error(`position-state-store: unsupported schemaVersion ${String(raw.schemaVersion)} (expected ${SCHEMA_VERSION})`);
+        }
+        if (!Array.isArray(raw.entries))
+            throw new Error('position-state-store: entries is not an array');
+        const entries = [];
+        for (const e of raw.entries)
+            entries.push(this.validateEntry(e));
+        return { schemaVersion: SCHEMA_VERSION, entries };
+    }
+    validateEntry(raw) {
+        if (!isRecord(raw))
+            throw new Error('position-state-store: entry is not an object');
+        if (typeof raw.symbol !== 'string' || raw.symbol.length === 0) {
+            throw new Error('position-state-store: entry missing symbol');
+        }
+        if (typeof raw.openedAt !== 'number' || !Number.isFinite(raw.openedAt)) {
+            throw new Error('position-state-store: entry missing/invalid openedAt');
+        }
+        if (raw.side !== 'long' && raw.side !== 'short') {
+            throw new Error(`position-state-store: bad side ${String(raw.side)}`);
+        }
+        if (typeof raw.createdAt !== 'number' || typeof raw.updatedAt !== 'number') {
+            throw new Error('position-state-store: missing createdAt/updatedAt');
+        }
+        return raw;
+    }
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

package/live/proposal-decision-listener.d.ts

@@ -0,0 +1,64 @@
+import type { BinancePublicApi } from '../ccxt/binance-public.js';
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { AutoCaptureContext } from '../ingest/position-auto-capture.js';
+export interface ProposalDecisionListenerOptions {
+    baseUrl: string;
+    ingestToken: string;
+    userId: string;
+    adapter: IExchangeAdapter;
+    binanceApi: BinancePublicApi;
+    autoCapture?: AutoCaptureContext;
+    /** Active poll interval — used while there are pending proposals (or the
+     *  previous tick fetched any). Default 3 s. Keeps approval-to-fire latency
+     *  low when the operator is actively working through proposals. */
+    pollIntervalMs?: number;
+    /** Idle poll interval — used after a tick returns zero pending proposals.
+     *  Default 15 s. Cuts the constant-warm pressure on the webapp DB by ~5x
+     *  during idle stretches (no approvals queued). Reset to active on the
+     *  next non-empty tick. 15 s is well within the shortest hard-expiry
+     *  bucket (90 s momentum) even allowing for operator decision time. */
+    pollIntervalIdleMs?: number;
+    /** Maximum |markPrice − proposedEntry| / |proposedEntry − stopPrice|.
+     *  Default 0.3 per Locked Decision #6. */
+    driftAbandonR?: number;
+    /** Per-attempt request timeout for HTTP calls to the webapp. */
+    requestTimeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+export interface ProposalDecisionListenerHealth {
+    running: boolean;
+    ticksTotal: number;
+    ticksWithFires: number;
+    firesAttempted: number;
+    firesSucceeded: number;
+    firesAbandonedDrift: number;
+    firesFailedTrading: number;
+    patchFailures: number;
+    pollFailures: number;
+    lastTickAt: string | null;
+}
+export declare class ProposalDecisionListener {
+    private readonly opts;
+    private timer;
+    private inFlight;
+    /** Current scheduling interval. Starts at active (so the first tick after
+     *  start() fires promptly even if the queue is empty); switches to idle
+     *  after any tick that finds zero pending; resets to active on any tick
+     *  that finds ≥1 pending. */
+    private currentIntervalMs;
+    private health;
+    constructor(options: ProposalDecisionListenerOptions);
+    /** Begin the poll loop. Idempotent — subsequent calls are no-ops while
+     *  the listener is already running. */
+    start(): void;
+    /** Stop the poll loop. If a tick is in flight, awaits its completion so
+     *  the PATCH back to the webapp lands before the process exits. */
+    stop(): Promise<void>;
+    getHealth(): ProposalDecisionListenerHealth;
+    private scheduleNextTick;
+    private runTick;
+    private tick;
+    private fetchPending;
+    private firePending;
+    private patchResult;
+}

package/live/proposal-decision-listener.js

@@ -0,0 +1,288 @@
+// ProposalDecisionListener — background poller that fires operator-approved
+// proposals via the existing create_order backend path.
+//
+// Phase B implementation: polls GET /api/internal/proposed_orders/pending-decisions
+// at config.pollIntervalMs (default 3 sec). For each approved-but-unfired row:
+//   1. Drift abandon — if mark price has moved more than ±0.3 R from the
+//      proposed entry since the proposal was created, fail with a transparent
+//      `fireError` rather than firing into a different setup.
+//   2. Fire via createOrderTool — same backend function the toggle-off path
+//      calls directly. Reuses the pre-trade risk gate, bracket attach, and
+//      auto-capture entry-row write.
+//   3. PATCH /fire-result with either firedOrderId or fireError. Fired-once
+//      idempotency lives in the DB constraint (status='approved' AND
+//      fired_order_id IS NULL filter).
+//
+// Started by index.ts only when config.approval.mode === 'per_trade' AND
+// ingest credentials are present. Drained at shutdown so an in-flight fire
+// completes its PATCH before the process exits.
+//
+// Why polling and not relay events: simpler — no skill <-> plugin event-bus
+// changes needed. 3-sec poll is well under the latency a human approval flow
+// tolerates. Refactor to SSE/relay-push only if measurement shows the poll
+// load is meaningful (very unlikely — ~3 req/s per user is negligible).
+//
+// See docs/APPROVAL_MODE_DESIGN.md §2 (architecture) + §7.3 (re-validation) +
+// §10 failure matrix.
+import { logger, formatError } from '../logger.js';
+import { createOrderTool } from '../tools/create-order.js';
+const TAG = 'proposal-decision-listener';
+export class ProposalDecisionListener {
+    opts;
+    timer = null;
+    inFlight = null;
+    /** Current scheduling interval. Starts at active (so the first tick after
+     *  start() fires promptly even if the queue is empty); switches to idle
+     *  after any tick that finds zero pending; resets to active on any tick
+     *  that finds ≥1 pending. */
+    currentIntervalMs;
+    health = {
+        running: false,
+        ticksTotal: 0,
+        ticksWithFires: 0,
+        firesAttempted: 0,
+        firesSucceeded: 0,
+        firesAbandonedDrift: 0,
+        firesFailedTrading: 0,
+        patchFailures: 0,
+        pollFailures: 0,
+        lastTickAt: null,
+    };
+    constructor(options) {
+        this.opts = {
+            baseUrl: options.baseUrl.replace(/\/+$/, ''),
+            ingestToken: options.ingestToken,
+            userId: options.userId,
+            adapter: options.adapter,
+            binanceApi: options.binanceApi,
+            autoCapture: options.autoCapture,
+            pollIntervalMs: options.pollIntervalMs ?? 3_000,
+            pollIntervalIdleMs: options.pollIntervalIdleMs ?? 15_000,
+            driftAbandonR: options.driftAbandonR ?? 0.3,
+            requestTimeoutMs: options.requestTimeoutMs ?? 10_000,
+            fetchImpl: options.fetchImpl ?? fetch,
+        };
+        this.currentIntervalMs = this.opts.pollIntervalMs;
+    }
+    /** Begin the poll loop. Idempotent — subsequent calls are no-ops while
+     *  the listener is already running. */
+    start() {
+        if (this.health.running)
+            return;
+        this.health.running = true;
+        logger.info(TAG, `Listener started — polling ${this.opts.baseUrl}/api/internal/proposed_orders/pending-decisions (active ${this.opts.pollIntervalMs} ms / idle ${this.opts.pollIntervalIdleMs} ms; userId=${this.opts.userId.slice(0, 8)}…)`);
+        this.scheduleNextTick();
+    }
+    /** Stop the poll loop. If a tick is in flight, awaits its completion so
+     *  the PATCH back to the webapp lands before the process exits. */
+    async stop() {
+        this.health.running = false;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (this.inFlight) {
+            try {
+                await this.inFlight;
+            }
+            catch { /* tick errors are logged inside tick() */ }
+        }
+        logger.info(TAG, 'Listener stopped');
+    }
+    getHealth() {
+        return { ...this.health };
+    }
+    // ---- Internals ----
+    scheduleNextTick() {
+        if (!this.health.running)
+            return;
+        this.timer = setTimeout(() => {
+            void this.runTick();
+        }, this.currentIntervalMs);
+    }
+    async runTick() {
+        if (!this.health.running)
+            return;
+        this.inFlight = this.tick().catch((err) => {
+            logger.warn(TAG, `Tick threw (caught): ${formatError(err)}`);
+        });
+        try {
+            await this.inFlight;
+        }
+        finally {
+            this.inFlight = null;
+            this.scheduleNextTick();
+        }
+    }
+    async tick() {
+        this.health.ticksTotal++;
+        this.health.lastTickAt = new Date().toISOString();
+        const pending = await this.fetchPending();
+        if (pending.length === 0) {
+            // Idle backoff — schedule next tick at the longer idle interval until
+            // the queue becomes non-empty. This is the dominant cost-reduction lever
+            // when Approval Mode is active but the operator is not currently
+            // working through proposals. The next non-empty tick resets to active.
+            this.currentIntervalMs = this.opts.pollIntervalIdleMs;
+            return;
+        }
+        // Reset to fast polling so subsequent approvals fire with minimal latency.
+        this.currentIntervalMs = this.opts.pollIntervalMs;
+        this.health.ticksWithFires++;
+        logger.info(TAG, `${pending.length} approved proposal(s) pending fire`);
+        for (const p of pending) {
+            try {
+                await this.firePending(p);
+            }
+            catch (err) {
+                // Defensive — firePending should already write a fireError PATCH on
+                // any failure path. If something escapes, surface it loudly so the
+                // operator can diagnose; the proposal will remain in approved state
+                // and be retried on the next tick (idempotent because firedOrderId
+                // is still NULL until a successful PATCH writes it).
+                logger.error(TAG, `Unhandled exception firing proposal ${p.id} (will retry next tick): ${formatError(err)}`);
+            }
+        }
+    }
+    async fetchPending() {
+        const url = `${this.opts.baseUrl}/api/internal/proposed_orders/pending-decisions`;
+        try {
+            const ac = new AbortController();
+            const tid = setTimeout(() => ac.abort(), this.opts.requestTimeoutMs);
+            let res;
+            try {
+                res = await this.opts.fetchImpl(url, {
+                    method: 'GET',
+                    headers: {
+                        authorization: `Bearer ${this.opts.ingestToken}`,
+                        'x-user-id': this.opts.userId,
+                    },
+                    signal: ac.signal,
+                });
+            }
+            finally {
+                clearTimeout(tid);
+            }
+            if (!res.ok) {
+                this.health.pollFailures++;
+                logger.warn(TAG, `GET ${url} → ${res.status}`);
+                return [];
+            }
+            const body = await res.json();
+            return Array.isArray(body.proposals) ? body.proposals : [];
+        }
+        catch (err) {
+            this.health.pollFailures++;
+            logger.warn(TAG, `GET ${url} threw: ${formatError(err)}`);
+            return [];
+        }
+    }
+    async firePending(p) {
+        this.health.firesAttempted++;
+        // ---- 1. Drift abandon (Locked Decision #6) ----
+        // Skip if we can't read a current price — better to let the trading path
+        // surface the error than to silently abandon on a transient ticker miss.
+        const lastPrice = await this.opts.adapter.getLastPrice(p.symbol).catch(() => null);
+        if (lastPrice != null && Number.isFinite(lastPrice) && lastPrice > 0) {
+            const rDistance = Math.abs(p.proposedEntry - p.stopPrice);
+            if (rDistance > 0) {
+                const driftR = Math.abs(lastPrice - p.proposedEntry) / rDistance;
+                if (driftR > this.opts.driftAbandonR) {
+                    const msg = `price_drift: mark ${lastPrice} is ${driftR.toFixed(2)}R from proposed entry ${p.proposedEntry} (limit ${this.opts.driftAbandonR}R)`;
+                    logger.warn(TAG, `Abandoning proposal ${p.id} — ${msg}`);
+                    await this.patchResult(p.id, { fireError: msg });
+                    this.health.firesAbandonedDrift++;
+                    return;
+                }
+            }
+        }
+        // ---- 2. Fire via createOrderTool (same path toggle-off mode uses) ----
+        // CRITICAL: do NOT pass proposalManager + userId here. The listener IS the
+        // consumer of approved proposals; passing proposalManager would recursively
+        // dual-write another proposal row for the same intent. The agent's path
+        // dual-writes; the listener's path fires the underlying order.
+        const result = await createOrderTool({
+            symbol: p.symbol,
+            side: p.side,
+            type: p.orderType,
+            amount: p.size,
+            // For limit orders we honour the original proposed entry. For market,
+            // the create_order tool reads the live ticker (per existing semantics).
+            price: p.orderType === 'limit' ? p.proposedEntry : undefined,
+            stopPrice: p.stopPrice,
+            target_price: p.targetPrice,
+            setup_type: p.setupType,
+            thesis: p.thesis,
+            regime: p.regime,
+            regime_confidence: p.regimeConfidence,
+            scorecard_verdict: p.scorecardVerdict,
+            confluence_score: p.confluenceScore,
+        }, {
+            binanceApi: this.opts.binanceApi,
+            adapter: this.opts.adapter,
+            autoCapture: this.opts.autoCapture,
+            // proposalManager + userId deliberately omitted — see above.
+        });
+        if ('error' in result) {
+            // Trading-path rejection (risk gate, bracket attach failure, exchange
+            // rejection, etc.). Surface to the operator via the proposal row.
+            logger.warn(TAG, `Proposal ${p.id} fire rejected: ${result.error}`);
+            await this.patchResult(p.id, { fireError: result.error });
+            this.health.firesFailedTrading++;
+            return;
+        }
+        if ('status' in result && result.status === 'pending_approval') {
+            // Should be unreachable: the listener calls createOrderTool without
+            // proposalManager, so the per_trade branch can't trigger. If it does
+            // (config race or future refactor), surface as a fireError so we don't
+            // silently lose the proposal.
+            const msg = `unexpected pending_approval from listener-side fire (proposal_id=${result.proposal_id})`;
+            logger.error(TAG, msg);
+            await this.patchResult(p.id, { fireError: msg });
+            this.health.firesFailedTrading++;
+            return;
+        }
+        const firedOrderId = typeof result.id === 'string' ? result.id : `unknown-${Date.now()}`;
+        logger.info(TAG, `Proposal ${p.id} fired → order ${firedOrderId}`);
+        await this.patchResult(p.id, { firedOrderId });
+        this.health.firesSucceeded++;
+    }
+    async patchResult(proposalId, body) {
+        const url = `${this.opts.baseUrl}/api/internal/proposed_orders/${proposalId}/fire-result`;
+        try {
+            const ac = new AbortController();
+            const tid = setTimeout(() => ac.abort(), this.opts.requestTimeoutMs);
+            let res;
+            try {
+                res = await this.opts.fetchImpl(url, {
+                    method: 'PATCH',
+                    headers: {
+                        'content-type': 'application/json',
+                        authorization: `Bearer ${this.opts.ingestToken}`,
+                        'x-user-id': this.opts.userId,
+                    },
+                    body: JSON.stringify(body),
+                    signal: ac.signal,
+                });
+            }
+            finally {
+                clearTimeout(tid);
+            }
+            if (res.status === 409) {
+                // Already-recorded race — listener double-fired but webapp's idempotency
+                // guard caught the duplicate. Not an error.
+                logger.info(TAG, `Proposal ${proposalId} fire-result already recorded (409, expected on retry)`);
+                return;
+            }
+            if (!res.ok) {
+                this.health.patchFailures++;
+                logger.warn(TAG, `PATCH ${url} → ${res.status}`);
+                return;
+            }
+        }
+        catch (err) {
+            this.health.patchFailures++;
+            logger.warn(TAG, `PATCH ${url} threw: ${formatError(err)}`);
+        }
+    }
+}

package/live/proposal-manager.d.ts

@@ -0,0 +1,76 @@
+import { type SetupBucket } from './setup-buckets.js';
+/** Trade params + agent metadata composing a single proposal. Mirrors the
+ *  /api/internal/proposed_orders payload shape. */
+export interface ProposalRequest {
+    symbol: string;
+    side: 'buy' | 'sell';
+    orderType: 'market' | 'limit';
+    size: number;
+    proposedEntry: number;
+    stopPrice: number;
+    targetPrice: number;
+    riskUsd: number;
+    thesis: string;
+    setupType: string;
+    regime: string;
+    regimeConfidence: number;
+    scorecardVerdict: string;
+    confluenceScore: number;
+    /** Phase C — when set, the named proposal is atomically marked `superseded`
+     *  by the webapp and the new row links back via supersedes_id. Use this when
+     *  the agent is modifying a still-pending proposal (e.g. after operator
+     *  discussion). Must reference a pending/discussing proposal owned by the
+     *  same user, or the supersede half is a no-op. */
+    supersedesId?: string;
+    /** 'shadow' = Phase A telemetry-only row (agent's create_order also fires
+     *  the real order synchronously). The webapp filters these out of the
+     *  operator UI so they don't appear as actionable cards. 'real' = Phase B/C
+     *  actionable proposal the operator decides on. Defaults to 'real' on the
+     *  webapp side if omitted. */
+    origin?: 'shadow' | 'real';
+}
+export interface ProposalManagerOptions {
+    baseUrl: string;
+    ingestToken: string;
+    fetchImpl?: typeof fetch;
+    requestTimeoutMs?: number;
+    maxAttempts?: number;
+    baseBackoffMs?: number;
+    backoffCapMs?: number;
+    /** Override clock for tests. */
+    now?: () => Date;
+    /** Override UUID generator for tests. */
+    uuid?: () => string;
+}
+export interface ProposalManagerHealth {
+    inFlight: number;
+    totalPosted: number;
+    totalSucceeded: number;
+    totalDroppedTerminal: number;
+    totalDroppedRetriesExhausted: number;
+}
+/** Result of a propose() call. The proposal_uuid is generated synchronously
+ *  before any network I/O so the caller can correlate logs immediately. */
+export interface ProposeResult {
+    proposalUuid: string;
+    setupBucket: SetupBucket;
+    hardExpiresAt: Date;
+}
+export declare class ProposalManager {
+    private readonly opts;
+    private inFlight;
+    private totalPosted;
+    private totalSucceeded;
+    private totalDroppedTerminal;
+    private totalDroppedRetriesExhausted;
+    constructor(options: ProposalManagerOptions);
+    /** Submit a proposal. Generates the proposal_uuid + computes the bucket
+     *  + hard expiry synchronously; the actual POST runs in the background.
+     *  Caller may correlate via the returned proposalUuid before the post lands. */
+    propose(userId: string, req: ProposalRequest): ProposeResult;
+    /** Await all in-flight POSTs. Used at shutdown so we don't lose proposals. */
+    drain(): Promise<void>;
+    getHealth(): ProposalManagerHealth;
+    private run;
+    private sleepBackoff;
+}