@reefclaw/openclaw-plugin 0.1.0

package/tools/close-position.js

@@ -0,0 +1,449 @@
+// Tool: close_position — close a position at market (paper or live)
+// NO readiness gate — emergency control (flatten), must always work.
+//
+// SKILL.md v2.10.0 gate (Position Management Discipline): the agent must
+// submit a documented `reason` and (except for operator_command) a
+// structured `assessment` describing the reasoning behind the close.  The
+// LLM's value is context-sensitive reasoning; we enforce the reasoning
+// at the API boundary via a schema, not a time floor.
+//
+// 2026-04-21 false-bracket_integrity safeguard: audit_bracket_protection
+// was observed reporting has_stop=false while the reconciler (same data
+// source, same call) consistently confirmed 2 live bracket orders on the
+// exchange. Agent used this false negative to trigger close_position with
+// reason=bracket_integrity, burning ~8–20 bps per cycle, 14+ cycles today.
+// Fix: before executing a bracket_integrity close, the plugin independently
+// verifies the ledger + exchange state. If the bracket is genuinely live
+// (ledger active/partial AND an exchange order matches the stored cid),
+// reject the close — audit was wrong, the position is protected. This is
+// a same-signal re-check at the API boundary, not a duplicate of the
+// audit tool; it catches the observed class of false negatives without
+// trusting the audit's own verdict.
+import { formatError, logger } from '../logger.js';
+import { fetchCurrentPrice, fetchOrderBook, isError } from './helpers.js';
+import { validateClosePosition, } from './assessment-validation.js';
+import { onClosePositionFilled } from '../ingest/position-auto-capture.js';
+import { evaluateExitGate, } from './exit-gate.js';
+import { getRecentAuditVerdictHistory } from './audit-bracket-protection.js';
+import { loadExitGateMode } from '../config/position-review-config.js';
+const TAG = 'close-position';
+// Bracket-integrity circuit-breaker. Counts SUCCESSFUL close_position calls
+// with reason='bracket_integrity' in a rolling 60-min window. When the 3rd
+// such close is attempted, reject — repeated bracket-integrity flushes in
+// the same hour means EITHER the bracket subsystem is actually broken (in
+// which case the operator needs to know, not the agent quietly burning more
+// positions) OR the audit tool is false-negativing (same outcome: stop the
+// burn). 2026-05-15 session ran this exact pattern 3 times in 4 hours and
+// realised −$3.20 of bracket-integrity flushes before the operator caught it.
+const BRACKET_INTEGRITY_WINDOW_MS = 60 * 60 * 1000;
+const BRACKET_INTEGRITY_LIMIT = 3;
+let bracketIntegrityCloses = []; // timestamps of successful closes
+export async function closePositionTool(args, deps) {
+    // Schema gate FIRST — reject before touching the exchange.
+    const v = validateClosePosition(args);
+    if (!v.ok) {
+        logger.warn(TAG, `close_position rejected: ${v.error} (symbol=${args.symbol}, reason=${args.reason ?? 'missing'})`);
+        return { error: v.error ?? 'Invalid close_position arguments.' };
+    }
+    // Exit-gate check — see docs/EXIT_GATE_DESIGN.md. The gate is orthogonal to
+    // the bracket_integrity safeguard below; both can fire on the same call.
+    // Behaviour by mode:
+    //   off     — gate skipped entirely (no input fetch, no log).
+    //   shadow  — gate runs, verdict logged to close_assessment.metadata.gate_eval,
+    //             close_position always proceeds.
+    //   observe — gate runs; on BLOCK we still proceed but the verdict is logged
+    //             and a warning printed to journalctl.
+    //   enforce — gate runs; on BLOCK we hard-reject with the recovery hint.
+    const gateMode = deps.exitGateMode ?? loadExitGateMode();
+    let gateVerdict = null;
+    // 0a (2026-06-16): hoist the gate inputs to function scope so the post-close
+    // capture block can persist a full inputs snapshot. Previously `inputs` was a
+    // block-local const that went out of scope before the capture write, which is
+    // why only {mode,outcome,tier,code} ever reached the journal (the §5 `inputs`
+    // snapshot was never constructed). See docs/EXIT_DISCIPLINE_BUILD_PLAN.md
+    // Step 0a + docs/EXIT_GATE_DESIGN.md §5.
+    let gateInputs = null;
+    if (gateMode !== 'off') {
+        gateInputs = await buildExitGateInputs(args, deps);
+        gateVerdict = evaluateExitGate(gateInputs);
+        logger.info(TAG, `exit_gate mode=${gateMode} ${gateVerdict.outcome} tier=${gateVerdict.tier} code=${gateVerdict.code} (symbol=${args.symbol}, reason=${args.reason})`);
+        if (gateVerdict.outcome === 'BLOCK' && gateMode === 'enforce') {
+            logger.warn(TAG, `close_position REJECTED by exit gate (enforce): ${gateVerdict.code} — ${gateVerdict.recovery_hint ?? '(no hint)'}`);
+            return {
+                error: `close_position blocked by exit gate (${gateVerdict.code}). ` +
+                    (gateVerdict.recovery_hint ?? 'See docs/EXIT_GATE_DESIGN.md.'),
+            };
+        }
+        if (gateVerdict.outcome === 'BLOCK' && gateMode === 'observe') {
+            logger.warn(TAG, `close_position WOULD BE BLOCKED by exit gate (observe): ${gateVerdict.code} — ${gateVerdict.recovery_hint ?? '(no hint)'} — proceeding because mode=observe`);
+        }
+    }
+    // In paper mode, fetch latest ticker + order book for realistic fills
+    if (!deps.adapter.isLive) {
+        const paperDeps = { binanceApi: deps.binanceApi, simulator: deps.adapter.getSimulator() };
+        const [priceResult] = await Promise.all([
+            fetchCurrentPrice(args.symbol, paperDeps),
+            fetchOrderBook(args.symbol, paperDeps),
+        ]);
+        if (isError(priceResult))
+            return priceResult;
+    }
+    // Log the assessment so every agent close is auditable in the journal.
+    // We log after validation (we've confirmed the shape is sound) and before
+    // the adapter call so the record is written even if the close fails.
+    const reason = args.reason;
+    const summary = formatAssessmentSummary(args.assessment);
+    logger.info(TAG, `close_position ${args.symbol} reason=${reason}${summary ? ' | ' + summary : ''}`);
+    // Circuit-breaker: if we've already let 2 bracket_integrity closes through
+    // in the last hour, the 3rd is almost certainly the audit lying to us
+    // rather than a real protection failure. Force the operator to either ack
+    // by retrying with a different reason (regime_flip / risk_limit /
+    // operator_command) or investigate the bracket subsystem.
+    if (reason === 'bracket_integrity' && deps.adapter.isLive) {
+        const now = Date.now();
+        const windowStart = now - BRACKET_INTEGRITY_WINDOW_MS;
+        bracketIntegrityCloses = bracketIntegrityCloses.filter(ts => ts >= windowStart);
+        if (bracketIntegrityCloses.length >= BRACKET_INTEGRITY_LIMIT - 1) {
+            logger.warn(TAG, `BRACKET-INTEGRITY CIRCUIT-BREAKER TRIPPED for ${args.symbol}: ` +
+                `${bracketIntegrityCloses.length} prior bracket_integrity closes in the last ` +
+                `${BRACKET_INTEGRITY_WINDOW_MS / 60_000} min. Refusing the ${bracketIntegrityCloses.length + 1}th. ` +
+                `Audit-vs-reality bug is likelier than ${bracketIntegrityCloses.length + 1} consecutive real protection losses.`);
+            return {
+                error: `close_position rejected: circuit-breaker tripped — ` +
+                    `${bracketIntegrityCloses.length} bracket_integrity closes already fired in the last ` +
+                    `${BRACKET_INTEGRITY_WINDOW_MS / 60_000} min. This pattern almost always means the audit ` +
+                    `is unreliable, not that brackets are repeatedly failing on the exchange. ` +
+                    `Investigation steps: (1) run audit_bracket_protection and inspect 'reason' + ` +
+                    `ledger_state; (2) check the journal for 'AUDIT FLICKER' warnings; ` +
+                    `(3) if you truly need to exit, use reason='operator_command' (bypasses this check) ` +
+                    `or escalate to the operator.`,
+            };
+        }
+    }
+    // False-bracket_integrity safeguard — see module header comment.
+    if (reason === 'bracket_integrity' && deps.adapter.isLive) {
+        const integrity = await verifyBracketsGenuinelyMissing(deps.adapter, args.symbol);
+        if (integrity.protected) {
+            logger.warn(TAG, `close_position REJECTED — reason=bracket_integrity but plugin verified brackets live: ${integrity.detail} (symbol=${args.symbol}). This is the audit-vs-reality bug; the position is protected. If you want to close anyway, use reason=regime_flip, risk_limit, or operator_command.`);
+            return {
+                error: `close_position rejected: bracket_integrity claim contradicted by plugin (${integrity.detail}). ` +
+                    `Brackets are live on exchange. Use a different reason if you want to exit.`,
+            };
+        }
+        logger.info(TAG, `bracket_integrity safeguard: ${integrity.detail} — allowing close`);
+    }
+    try {
+        const order = await deps.adapter.closePosition(args.symbol);
+        // Successful close — record the bracket_integrity timestamp so the
+        // circuit-breaker can see the trend on the next attempt.
+        if (reason === 'bracket_integrity' && deps.adapter.isLive) {
+            bracketIntegrityCloses.push(Date.now());
+        }
+        // Auto-capture close to the Position Decision Journal — fail-open.
+        if (deps.autoCapture) {
+            const a = args.assessment;
+            const assessmentForCapture = {
+                ...a ?? {},
+            };
+            if (gateVerdict) {
+                // 0a: persist the full inputs snapshot + would_have_blocked so shadow
+                // verdicts are auditable from the journal (EXIT_GATE_DESIGN.md §5).
+                // Keys are snake_case per the canonical-JSONB-key rule; every input is
+                // null-coalesced so a MISSING input is recorded explicitly (that is the
+                // point — it makes the inputs_unavailable_* skips diagnosable). The key
+                // stays `outcome` (not §5's older `verdict`) to match the 148 historical
+                // rows. `gateInputs` is non-null whenever `gateVerdict` is set (both are
+                // assigned together when gateMode!=='off'); `gi` guard is for the type.
+                const gi = gateInputs;
+                const stopAtBE = gi && gi.side && typeof gi.stopPrice === 'number' && typeof gi.entryPrice === 'number'
+                    ? gi.side === 'long'
+                        ? gi.stopPrice >= gi.entryPrice
+                        : gi.stopPrice <= gi.entryPrice
+                    : null;
+                assessmentForCapture.metadata = {
+                    ...assessmentForCapture.metadata ?? {},
+                    gate_eval: {
+                        mode: gateMode,
+                        outcome: gateVerdict.outcome,
+                        tier: gateVerdict.tier,
+                        code: gateVerdict.code,
+                        would_have_blocked: gateVerdict.outcome === 'BLOCK',
+                        ...(gateVerdict.discipline_failure
+                            ? { discipline_failure: gateVerdict.discipline_failure }
+                            : {}),
+                        ...(gi
+                            ? {
+                                inputs: {
+                                    mfe_r_peak: gi.mfe_r_peak ?? null,
+                                    current_r: gi.current_r ?? null,
+                                    stop_at_BE: stopAtBE,
+                                    last_review_verdict: gi.lastReview?.verdict ?? null,
+                                    last_review_age_minutes: gi.lastReview
+                                        ? Math.round((gi.now_ms - gi.lastReview.review_at_ms) / 6000) / 10
+                                        : null,
+                                    thesis_status: gi.lastReview?.thesis_status ?? null,
+                                    // vol_shock is never computed by buildExitGateInputs yet, so
+                                    // this is always false until the 3xATR shock is wired — do
+                                    // NOT read it as a real signal during the soak.
+                                    vol_shock: gi.volShock ?? false,
+                                    // Provenance (set in buildExitGateInputs): which source
+                                    // supplied each value — makes the inputs_unavailable_* and
+                                    // computed-fallback paths diagnosable from the journal.
+                                    mfe_src: gi.mfe_src ?? null,
+                                    current_r_src: gi.current_r_src ?? null,
+                                },
+                            }
+                            : {}),
+                    },
+                };
+            }
+            // Forensics: snapshot the audit verdict history (last 60min, up to
+            // 120 samples) so the dashboard Position Timeline drawer can flag
+            // closes that look like audit-flicker artefacts rather than real
+            // market exits. The flicker-warn line in journal logs the same data
+            // in real time; this lets us audit historical closes after the fact.
+            // 2026-05-15 spiral root-cause work, item #8 of the bundle.
+            if (deps.adapter.isLive) {
+                const history = getRecentAuditVerdictHistory(args.symbol);
+                if (history.length > 0) {
+                    assessmentForCapture.metadata = {
+                        ...assessmentForCapture.metadata ?? {},
+                        bracket_health_history: history,
+                    };
+                }
+            }
+            onClosePositionFilled(deps.autoCapture, {
+                symbol: args.symbol,
+                closeReason: reason,
+                closeAssessment: assessmentForCapture,
+                scorecardVerdict: typeof a?.current_score === 'number' ? undefined : undefined,
+                confluenceScore: typeof a?.current_score === 'number' ? a.current_score : undefined,
+                regime: a?.current_regime,
+                regimeConfidence: undefined,
+            }, order).catch((err) => {
+                // eslint-disable-next-line no-console
+                console.warn(`[position-auto-capture] close capture threw: ${formatError(err)}`);
+            });
+        }
+        return order;
+    }
+    catch (err) {
+        return { error: formatError(err) };
+    }
+}
+/** Independent check used by the bracket_integrity safeguard. Looks at the
+ *  plugin's bracket ledger + a fresh exchange-side open-orders fetch; returns
+ *  `{protected: true}` only when BOTH confirm a live bracket (ledger row in a
+ *  non-terminal state with stored cids, AND at least one exchange order
+ *  carrying a matching `rc-<bracketId>-s` or `rc-<bracketId>-t` cid). Any
+ *  uncertainty (no ledger row, cids not stored, fetch error, nothing on
+ *  exchange) returns `{protected: false}` so the close is allowed — we only
+ *  block when we can definitively prove the audit was wrong. */
+async function verifyBracketsGenuinelyMissing(adapter, symbol) {
+    const ledger = adapter.getBracketLedger?.();
+    if (!ledger)
+        return { protected: false, detail: 'brackets disabled' };
+    const row = ledger.getBySymbol(symbol);
+    if (!row)
+        return { protected: false, detail: 'no ledger row' };
+    const NON_TERMINAL = new Set(['pending_entry', 'attaching', 'active', 'partial']);
+    if (!NON_TERMINAL.has(row.state)) {
+        return { protected: false, detail: `ledger state=${row.state} (terminal)` };
+    }
+    if (!row.slCid && !row.tpCid) {
+        return { protected: false, detail: `ledger state=${row.state} but no cids stored` };
+    }
+    let open = [];
+    try {
+        open = await adapter.getOpenOrders(symbol);
+    }
+    catch (err) {
+        return { protected: false, detail: `getOpenOrders failed: ${formatError(err)}` };
+    }
+    const liveCids = new Set();
+    for (const o of open) {
+        if (o.clientOrderId)
+            liveCids.add(o.clientOrderId);
+    }
+    const slLive = Boolean(row.slCid && liveCids.has(row.slCid));
+    const tpLive = Boolean(row.tpCid && liveCids.has(row.tpCid));
+    // Block the close only when BOTH bracket legs are live — that's the only
+    // shape that proves the audit was definitively wrong (the original 2026-04-21
+    // symbol-mapping bug). A position with only one leg live is half-bracketed:
+    // the audit's `has_stop=false` (or `has_target=false`) is correct, the
+    // operator/agent needs to flatten or re-attach, and the safeguard would
+    // wrongly trap them. Per the docstring: only block when we can prove the
+    // audit was wrong; one-leg-live does not prove that.
+    if (slLive && tpLive) {
+        return {
+            protected: true,
+            detail: `ledger state=${row.state}, exchange has SL(${row.slCid}) + TP(${row.tpCid}) open (${open.length} total orders on ${symbol})`,
+        };
+    }
+    const observed = [];
+    if (slLive)
+        observed.push(`SL(${row.slCid}) only`);
+    if (tpLive)
+        observed.push(`TP(${row.tpCid}) only`);
+    if (observed.length === 0)
+        observed.push('neither cid on exchange');
+    return {
+        protected: false,
+        detail: `ledger state=${row.state} (slCid=${row.slCid ?? '-'}, tpCid=${row.tpCid ?? '-'}) — ${observed.join(', ')} (${open.length} orders)`,
+    };
+}
+/** Gather inputs for the exit gate from adapter + bracket ledger + state store.
+ *  Best-effort: any missing piece becomes `undefined` so the pure gate function
+ *  can decide whether to PASS('skipped') or proceed. Never throws — gate
+ *  evaluation must never crash close_position.
+ */
+async function buildExitGateInputs(args, deps) {
+    const reason = (args.reason ?? 'regime_flip');
+    const a = args.assessment;
+    const inputs = {
+        reason,
+        now_ms: Date.now(),
+        mfe_r_peak: typeof a?.mfe_r_peak === 'number' ? a.mfe_r_peak : undefined,
+        current_r: typeof a?.r_multiple_at_close === 'number' ? a.r_multiple_at_close : undefined,
+    };
+    // Provenance: agent-supplied values win (set the src tags now); the adapter
+    // and computed fallbacks below only fire when these stay undefined.
+    if (inputs.mfe_r_peak !== undefined)
+        inputs.mfe_src = 'assessment';
+    if (inputs.current_r !== undefined)
+        inputs.current_r_src = 'assessment';
+    // Bracket ledger — stop price + (canonical) ledger entry.
+    // Only LiveAdapter exposes getBracketLedger; paper adapter falls back.
+    try {
+        const ledger = deps.adapter.getBracketLedger?.();
+        if (ledger) {
+            const row = ledger.getBySymbol(args.symbol);
+            if (row) {
+                if (typeof row.stopPrice === 'number' && Number.isFinite(row.stopPrice)) {
+                    inputs.stopPrice = row.stopPrice;
+                }
+                if (row.entrySide === 'buy')
+                    inputs.side = 'long';
+                else if (row.entrySide === 'sell')
+                    inputs.side = 'short';
+            }
+        }
+    }
+    catch (err) {
+        logger.warn(TAG, `exit_gate input fetch (bracket ledger): ${formatError(err)}`);
+    }
+    // Position — for entryPrice + side fallback, plus mfeR + bracket fallbacks.
+    // LiveAdapter.getPositions decorates each row with a running mfeR (updated
+    // from mark price on every call) and a bracket snapshot. When the agent
+    // omits `assessment.mfe_r_peak` (observed on ~77% of closes during the
+    // 2026-05-14 shadow soak), we read mfeR from the adapter so the gate can
+    // still tier the close instead of returning inputs_unavailable_mfe.
+    try {
+        const positions = await deps.adapter.getPositions(args.symbol);
+        const pos = positions.find((p) => p.contracts && p.contracts > 0);
+        if (pos) {
+            if (typeof pos.entryPrice === 'number' && Number.isFinite(pos.entryPrice)) {
+                inputs.entryPrice = pos.entryPrice;
+            }
+            if (!inputs.side && pos.side === 'long')
+                inputs.side = 'long';
+            if (!inputs.side && pos.side === 'short')
+                inputs.side = 'short';
+            if (inputs.mfe_r_peak === undefined
+                && typeof pos.mfeR === 'number'
+                && Number.isFinite(pos.mfeR)) {
+                inputs.mfe_r_peak = pos.mfeR;
+                inputs.mfe_src = 'pos.mfeR';
+            }
+            if (inputs.stopPrice === undefined
+                && pos.bracket
+                && typeof pos.bracket.slPrice === 'number'
+                && Number.isFinite(pos.bracket.slPrice)) {
+                inputs.stopPrice = pos.bracket.slPrice;
+            }
+            // 0b: plugin-computed fallbacks for current_r (SIGNED) + an mfe peak-FLOOR
+            // when the agent AND the adapter both left them undefined — the
+            // inputs_unavailable_* skips (~16-30% of evals). R denominator is the
+            // frozen entry→stop distance (originalStopPrice preferred; else the bracket
+            // stop resolved above). Both gated on `=== undefined` so agent-supplied
+            // values still win. current_r MUST stay signed (the T1-escape check
+            // compares current_r <= -0.5R); the mfe value is a NON-NEGATIVE FLOOR (true
+            // peak >= current excursion) — it lets the gate tier the close instead of
+            // skipping, at the cost of under-classifying a round-tripped winner as T1
+            // (acceptable: errs toward BLOCK in enforce). A position with no frozen
+            // stop (no originalStopPrice, no bracket) still legitimately skips.
+            // See docs/EXIT_DISCIPLINE_BUILD_PLAN.md Step 0b.
+            const denomStop = typeof pos.originalStopPrice === 'number' && Number.isFinite(pos.originalStopPrice)
+                ? pos.originalStopPrice
+                : inputs.stopPrice;
+            if (inputs.side
+                && typeof pos.entryPrice === 'number' && Number.isFinite(pos.entryPrice)
+                && typeof pos.markPrice === 'number' && Number.isFinite(pos.markPrice)
+                && typeof denomStop === 'number' && Number.isFinite(denomStop)) {
+                const denom = Math.abs(pos.entryPrice - denomStop);
+                if (denom > 0) {
+                    const fav = inputs.side === 'long'
+                        ? pos.markPrice - pos.entryPrice
+                        : pos.entryPrice - pos.markPrice;
+                    if (inputs.current_r === undefined) {
+                        inputs.current_r = fav / denom; // signed
+                        inputs.current_r_src = 'computed';
+                    }
+                    if (inputs.mfe_r_peak === undefined) {
+                        inputs.mfe_r_peak = Math.max(0, fav / denom); // non-negative floor
+                        inputs.mfe_src = 'computed_floor';
+                    }
+                }
+            }
+        }
+    }
+    catch (err) {
+        logger.warn(TAG, `exit_gate input fetch (positions): ${formatError(err)}`);
+    }
+    // Last review — from state store, for contradicts-own-review + review override.
+    try {
+        const entry = deps.autoCapture?.stateStore?.get(args.symbol);
+        if (entry?.lastVerdict && typeof entry.lastReviewAt === 'number') {
+            inputs.lastReview = {
+                verdict: entry.lastVerdict,
+                thesis_status: entry.lastThesisStatus ?? 'intact',
+                review_at_ms: entry.lastReviewAt,
+            };
+        }
+    }
+    catch (err) {
+        logger.warn(TAG, `exit_gate input fetch (state store): ${formatError(err)}`);
+    }
+    return inputs;
+}
+/** Test seam — clears the circuit-breaker state between unit tests. */
+export const __testing__ = {
+    resetCircuitBreaker() {
+        bracketIntegrityCloses = [];
+    },
+    /** Inspect current circuit-breaker state — for assertions. */
+    getCircuitBreakerCount() {
+        const windowStart = Date.now() - BRACKET_INTEGRITY_WINDOW_MS;
+        return bracketIntegrityCloses.filter(ts => ts >= windowStart).length;
+    },
+};
+function formatAssessmentSummary(a) {
+    if (!a)
+        return '';
+    const parts = [];
+    if (typeof a.entry_score === 'number')
+        parts.push(`entry=${a.entry_score}`);
+    if (typeof a.current_score === 'number')
+        parts.push(`current=${a.current_score}`);
+    if (a.entry_regime)
+        parts.push(`er=${a.entry_regime}`);
+    if (a.current_regime)
+        parts.push(`cr=${a.current_regime}`);
+    if (a.contradicting_metric)
+        parts.push(`metric="${a.contradicting_metric.slice(0, 80)}"`);
+    if (typeof a.position_age_seconds === 'number')
+        parts.push(`age=${a.position_age_seconds}s`);
+    if (typeof a.r_multiple_at_close === 'number')
+        parts.push(`R=${a.r_multiple_at_close}`);
+    return parts.join(' ');
+}

package/tools/create-order.d.ts

@@ -0,0 +1,54 @@
+import type { BinancePublicApi } from '../ccxt/binance-public.js';
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { CcxtOrder } from '../types.js';
+import { type AutoCaptureContext } from '../ingest/position-auto-capture.js';
+import type { ProposalManager } from '../live/proposal-manager.js';
+export declare function createOrderTool(args: {
+    symbol: string;
+    side: string;
+    type: string;
+    amount: number;
+    price?: number;
+    stopPrice?: number;
+    setup_type?: string;
+    thesis?: string;
+    target_price?: number;
+    regime?: string;
+    regime_confidence?: number;
+    scorecard_verdict?: string;
+    confluence_score?: number;
+    invalidation_price?: number;
+    realization_rule?: unknown;
+    supersedes_id?: string;
+}, deps: {
+    binanceApi: BinancePublicApi;
+    adapter: IExchangeAdapter;
+    autoCapture?: AutoCaptureContext;
+    /** Approval-mode wiring. The same ProposalManager handles both modes;
+     *  `approvalMode` selects the branch:
+     *
+     *    'off'       — fire normally. proposalManager is ignored.
+     *    'shadow'    — Phase A telemetry. Dual-write proposal row AND fire
+     *                  the real order. Used to collect setup distribution
+     *                  before flipping per_trade. See APPROVAL_MODE_DESIGN.md §12.
+     *    'per_trade' — THE feature. Propose only — DO NOT fire. Return
+     *                  pending_approval; the operator approves on the dashboard
+     *                  and ProposalDecisionListener fires via this same tool
+     *                  with proposalManager omitted (which goes through the
+     *                  normal real-fire path).
+     *
+     *  The listener-side fire is the one path that calls createOrderTool
+     *  WITHOUT proposalManager — it bypasses the propose branch and runs
+     *  the real adapter.createOrder. */
+    proposalManager?: ProposalManager;
+    userId?: string;
+    approvalMode?: 'off' | 'shadow' | 'per_trade';
+}): Promise<CcxtOrder | {
+    error: string;
+} | {
+    status: 'pending_approval';
+    proposal_id: string;
+    hard_expires_at: string;
+    setup_bucket: 'momentum' | 'mean_reversion';
+    message: string;
+}>;