@reefclaw/openclaw-plugin 0.1.5 → 0.1.7

package/tools/close-position.js

@@ -26,7 +26,18 @@ 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';
+import { confirmWave9LivePositionFlat } from '../wave9/live-position-confirmation.js';
+import { reprotectWave9LiveResidual, } from '../wave9/live-residual-protection.js';
+import { captureWave9PaperPositionFingerprint, isWave9ManagedPosition, WAVE9_MECHANICAL_EXIT_REASON, } from '../wave9/paper-admission-guard.js';
 const TAG = 'close-position';
+function currentWave9ExecutionMode(deps) {
+    const runtimeMode = deps.wave9TradingModeCheck?.() ?? deps.adapter.mode;
+    if (!deps.adapter.isLive && deps.adapter.mode === 'PAPER' && runtimeMode === 'PAPER')
+        return 'PAPER';
+    if (deps.adapter.isLive && deps.adapter.mode === 'LIVE' && runtimeMode === 'LIVE')
+        return 'LIVE';
+    return null;
+}
 // 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
@@ -40,10 +51,131 @@ 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.' };
+    const wave9ExitClaimed = args.reason !== 'operator_command' && (args.reason === WAVE9_MECHANICAL_EXIT_REASON
+        || args.wave9_exit_token !== undefined
+        || args.candidate_id !== undefined);
+    if (wave9ExitClaimed && deps.wave9VenueCheck?.() !== 'binance') {
+        return { error: 'Wave 9 reversal close refused: execution is pinned to Binance USD-M futures.' };
+    }
+    if (wave9ExitClaimed && !deps.operationLock) {
+        return { error: 'Wave 9 reversal close refused: process-local trading operation lock is unavailable.' };
+    }
+    const initialWave9Mode = wave9ExitClaimed ? currentWave9ExecutionMode(deps) : null;
+    let wave9Lease;
+    if (wave9ExitClaimed) {
+        if (!initialWave9Mode) {
+            return {
+                error: 'Wave 9 reversal close refused: capability execution requires an exact PAPER/paper-adapter ' +
+                    'or LIVE/live-adapter runtime match.',
+            };
+        }
+        if (args.reason !== WAVE9_MECHANICAL_EXIT_REASON
+            || !args.wave9_exit_token
+            || !args.candidate_id
+            || !deps.wave9AdmissionGuard) {
+            return { error: 'Wave 9 reversal close requires its exact reason, candidate identity, and short-lived exit token.' };
+        }
+        const executionCanonical = args.symbol.toUpperCase().replace(/[^A-Z0-9]/g, '').replace(/USDTUSDT$/, 'USDT');
+        if (!executionCanonical.endsWith('USDT') || executionCanonical.length <= 4) {
+            return { error: `Wave 9 reversal close refused: unsupported execution symbol ${args.symbol}.` };
+        }
+        if (initialWave9Mode === 'LIVE' && (!deps.captureWave9PositionFingerprint || !deps.wave9LiveLedger)) {
+            return {
+                error: 'Wave 9 live reversal close refused: authoritative live position capture and the durable ' +
+                    'execution ledger are required.',
+            };
+        }
+        args = { ...args, symbol: `${executionCanonical.slice(0, -4)}/USDT:USDT` };
+        try {
+            wave9Lease = await deps.operationLock.withAccountLock(`wave9-begin-close:${args.candidate_id ?? args.symbol}`, async () => {
+                if (currentWave9ExecutionMode(deps) !== initialWave9Mode) {
+                    throw new Error('adapter or trading mode changed before Wave 9 reversal began');
+                }
+                let position;
+                let positionFingerprint;
+                if (initialWave9Mode === 'LIVE') {
+                    const capture = await deps.captureWave9PositionFingerprint(args.symbol);
+                    position = capture.position;
+                    positionFingerprint = capture.fingerprint;
+                }
+                else {
+                    deps.refreshPaperState?.();
+                    const positions = await deps.adapter.getPositionsOrNull();
+                    if (positions === null)
+                        throw new Error('paper position snapshot unavailable');
+                    const canonical = (value) => value.toUpperCase().replace(/[^A-Z0-9]/g, '').replace(/USDTUSDT$/, 'USDT');
+                    const matches = positions.filter((candidate) => canonical(candidate.symbol) === canonical(args.symbol));
+                    if (matches.length !== 1)
+                        throw new Error('exactly one matching held position is required');
+                    position = matches[0];
+                    positionFingerprint = captureWave9PaperPositionFingerprint(deps.adapter, args.symbol).fingerprint;
+                }
+                if (!isWave9ManagedPosition(position)
+                    || position.candidateId !== args.candidate_id
+                    || !position.missionId) {
+                    throw new Error('held position lacks exact Wave 9 identity/geometry');
+                }
+                return deps.wave9AdmissionGuard.beginExit({
+                    token: args.wave9_exit_token,
+                    candidateId: args.candidate_id,
+                    missionId: position.missionId,
+                    symbol: args.symbol,
+                    positionSide: position.side,
+                    setupType: position.setupType,
+                    reason: args.reason,
+                    positionFingerprint,
+                    tradingMode: initialWave9Mode,
+                });
+            });
+        }
+        catch (err) {
+            return { error: `Wave 9 reversal close refused: ${formatError(err)}` };
+        }
+    }
+    else {
+        // Preserve the generic tool contract: malformed calls are rejected before
+        // any adapter read. Wave 9 classification is an additional check only for
+        // already-valid, non-operator risk-reducing closes.
+        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.' };
+        }
+        if (args.reason !== 'operator_command'
+            && deps.adapter.isLive
+            && deps.checkWave9LiveSymbolOwnership
+            && !deps.operationLock) {
+            return {
+                error: 'Generic live close_position refused: the shared trading operation lock is required ' +
+                    'while Wave 9 LIVE ownership checks are enabled.',
+            };
+        }
+        // When a trusted position snapshot is available, do not route a held
+        // Wave 9 position through a generic thesis/risk/bracket reason. Snapshot
+        // failure stays fail-open because an ordinary risk-reducing close must not
+        // be trapped by extra strategy-lifecycle I/O. Operator remains unconditional.
+        if (args.reason !== 'operator_command') {
+            try {
+                const getTrusted = deps.adapter.getPositionsOrNull?.bind(deps.adapter);
+                const held = getTrusted ? await getTrusted() : undefined;
+                if (held) {
+                    const canonical = (value) => value.toUpperCase().replace(/[^A-Z0-9]/g, '').replace(/USDTUSDT$/, 'USDT');
+                    if (held.some((position) => canonical(position.symbol) === canonical(args.symbol)
+                        && isWave9ManagedPosition(position))) {
+                        return {
+                            error: `Wave 9 position close refused: call get_wave9_status and use reason=${WAVE9_MECHANICAL_EXIT_REASON} ` +
+                                'with its single-use exit token. Only an explicit operator_command bypasses the strategy exit policy.',
+                        };
+                    }
+                }
+                else if (held === null) {
+                    logger.warn(TAG, 'Wave 9 generic-close classification unavailable; proceeding with legacy risk-reducing close semantics.');
+                }
+            }
+            catch (err) {
+                logger.warn(TAG, `Wave 9 generic-close classification failed (${formatError(err)}); proceeding with legacy risk-reducing close semantics.`);
+            }
+        }
     }
     // 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.
@@ -63,7 +195,7 @@ export async function closePositionTool(args, deps) {
     // 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') {
+    if (!wave9ExitClaimed && 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})`);
@@ -80,13 +212,30 @@ export async function closePositionTool(args, deps) {
     }
     // 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;
+        try {
+            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)) {
+                // The helper updates the simulator mark used by the actual close fill.
+            }
+            else {
+                if (wave9Lease) {
+                    deps.wave9AdmissionGuard.abort(wave9Lease, 'exit_market_data_unavailable', { retryable: true });
+                    wave9Lease = undefined;
+                }
+                return priceResult;
+            }
+        }
+        catch (err) {
+            if (wave9Lease) {
+                deps.wave9AdmissionGuard.abort(wave9Lease, 'exit_market_data_threw', { retryable: true });
+                wave9Lease = undefined;
+            }
+            return { error: `close_position market-data refresh failed: ${formatError(err)}` };
+        }
     }
     // 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
@@ -133,7 +282,127 @@ export async function closePositionTool(args, deps) {
         logger.info(TAG, `bracket_integrity safeguard: ${integrity.detail} — allowing close`);
     }
     try {
-        const order = await deps.adapter.closePosition(args.symbol);
+        const close = async () => {
+            if (!wave9ExitClaimed && !deps.adapter.isLive && reason !== 'operator_command') {
+                deps.refreshPaperState?.();
+                const positions = await deps.adapter.getPositionsOrNull();
+                if (positions === null) {
+                    // Preserve the existing risk-reduction contract: the extra
+                    // classification read cannot trap an ordinary close.
+                    logger.warn(TAG, 'Wave 9 final close classification unavailable; proceeding risk-reducing fail-open.');
+                }
+                else {
+                    const canonical = (value) => value.toUpperCase().replace(/[^A-Z0-9]/g, '').replace(/USDTUSDT$/, 'USDT');
+                    const target = positions.find((position) => canonical(position.symbol) === canonical(args.symbol));
+                    if (target && isWave9ManagedPosition(target)) {
+                        throw new Error(`Generic close_position refused at mutation boundary: ${args.symbol} is now held by Wave 9.`);
+                    }
+                }
+            }
+            if (!wave9ExitClaimed
+                && deps.adapter.isLive
+                && reason !== 'operator_command'
+                && deps.checkWave9LiveSymbolOwnership) {
+                let ownership;
+                try {
+                    ownership = await deps.checkWave9LiveSymbolOwnership(args.symbol);
+                }
+                catch (err) {
+                    throw new Error(`Generic close_position refused at mutation boundary: Wave 9 LIVE ownership ` +
+                        `check failed for ${args.symbol} (${formatError(err)}).`);
+                }
+                if (ownership.status === 'owned' || ownership.status === 'ambiguous') {
+                    throw new Error(`Generic close_position refused at mutation boundary: ${args.symbol} has ` +
+                        `${ownership.status} Wave 9 LIVE ownership (${ownership.reason}). ` +
+                        'Use get_wave9_status for a reversal authorization or operator_command for an emergency close.');
+                }
+            }
+            return wave9ExitClaimed
+                ? deps.adapter.closePosition(args.symbol, 'wave9_signal_reversal')
+                : deps.adapter.closePosition(args.symbol);
+        };
+        const closeWave9 = async () => {
+            if (!wave9Lease)
+                throw new Error('Wave 9 exit lease is unavailable at mutation boundary.');
+            if (currentWave9ExecutionMode(deps) !== initialWave9Mode) {
+                deps.wave9AdmissionGuard.abort(wave9Lease, 'trading_mode_changed_before_exit_mutation', { retryable: true });
+                wave9Lease = undefined;
+                throw new Error('Wave 9 reversal close refused: adapter or trading mode changed before mutation.');
+            }
+            if (deps.wave9VenueCheck?.() !== 'binance') {
+                deps.wave9AdmissionGuard.abort(wave9Lease, 'execution_venue_changed_before_exit_mutation', { retryable: true });
+                wave9Lease = undefined;
+                throw new Error('Wave 9 reversal close refused: execution venue changed away from Binance before mutation.');
+            }
+            let currentFingerprint;
+            if (initialWave9Mode === 'LIVE') {
+                const capture = await deps.captureWave9PositionFingerprint(args.symbol);
+                if (!isWave9ManagedPosition(capture.position)
+                    || capture.position.candidateId !== args.candidate_id
+                    || !capture.position.missionId) {
+                    throw new Error('held live position no longer matches its exact Wave 9 identity');
+                }
+                currentFingerprint = capture.fingerprint;
+            }
+            else {
+                deps.refreshPaperState?.();
+                currentFingerprint = captureWave9PaperPositionFingerprint(deps.adapter, args.symbol).fingerprint;
+            }
+            deps.wave9AdmissionGuard.revalidate(wave9Lease, currentFingerprint);
+            let order;
+            let closeError;
+            try {
+                order = await close();
+            }
+            catch (err) {
+                if (initialWave9Mode !== 'LIVE')
+                    throw err;
+                closeError = formatError(err);
+            }
+            if (initialWave9Mode === 'LIVE') {
+                const flat = await confirmWave9LivePositionFlat(deps.adapter, args.symbol);
+                if (!flat.confirmed) {
+                    let protection;
+                    try {
+                        protection = await (deps.reprotectWave9LiveResidual ?? reprotectWave9LiveResidual)(deps.adapter, deps.wave9LiveLedger, args.candidate_id, args.symbol);
+                    }
+                    catch (err) {
+                        deps.wave9AdmissionGuard.abort(wave9Lease, `live_close_residual_reprotection_threw:${formatError(err)}`, { retryable: true });
+                        wave9Lease = undefined;
+                        throw new Error(`CRITICAL: Wave 9 LIVE reversal is not stably flat (${flat.detail}), and residual ` +
+                            `re-protection threw (${formatError(err)}). Durable ownership remains OPEN. ` +
+                            'IMMEDIATE MANUAL INTERVENTION REQUIRED; a fresh exit authorization may retry.');
+                    }
+                    if (protection.status === 'protected') {
+                        deps.wave9AdmissionGuard.abort(wave9Lease, `live_close_residual_reprotected:${protection.stopClientOrderId ?? 'exact_stop'}`, { retryable: true });
+                        wave9Lease = undefined;
+                        throw new Error(`Wave 9 LIVE reversal close${closeError ? ` threw (${closeError}) and` : ''} left ` +
+                            `${protection.residualQuantity ?? 'a'} residual ` +
+                            `contract position. Durable ownership remains OPEN and the exact frozen stop ` +
+                            `${protection.stopPrice} is proven live; refresh get_wave9_status and use the ` +
+                            'fresh exit authorization to retry the reduce-only close.');
+                    }
+                    deps.wave9AdmissionGuard.abort(wave9Lease, `live_close_residual_requires_manual_intervention:${protection.detail}`, { retryable: true });
+                    wave9Lease = undefined;
+                    throw new Error(`CRITICAL: Wave 9 LIVE reversal close${closeError ? ` threw (${closeError}) and` : ''} ` +
+                        `stable flat was not confirmed ` +
+                        `(${flat.detail}). Durable ownership remains OPEN. ${protection.detail}`);
+                }
+                await deps.wave9LiveLedger.markClosed(args.candidate_id);
+            }
+            deps.wave9AdmissionGuard.commit(wave9Lease);
+            wave9Lease = undefined;
+            if (closeError) {
+                throw new Error(`Wave 9 LIVE reversal close acknowledgement failed (${closeError}), but stable flat was ` +
+                    'proven and durable ownership is CLOSED. Do not retry this candidate.');
+            }
+            return order;
+        };
+        const order = wave9ExitClaimed
+            ? await deps.operationLock.withAccountLock(`wave9-close-final:${args.symbol}`, closeWave9)
+            : reason !== 'operator_command' && deps.operationLock
+                ? await deps.operationLock.withAccountLock(`generic-close-final:${args.symbol}`, close)
+                : await close();
         // 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) {
@@ -228,6 +497,10 @@ export async function closePositionTool(args, deps) {
         return order;
     }
     catch (err) {
+        if (wave9Lease) {
+            deps.wave9AdmissionGuard.abort(wave9Lease, `exit_execution_failed:${formatError(err)}`, { retryable: initialWave9Mode === 'LIVE' });
+            wave9Lease = undefined;
+        }
         return { error: formatError(err) };
     }
 }

package/tools/create-order.d.ts

@@ -3,6 +3,13 @@ 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';
+import type { TradingOperationLock } from '../lifecycle/trading-operation-lock.js';
+import { type Wave9LiveExecutionLedger } from '../wave9/live-execution-ledger.js';
+import type { Wave9LiveStopConfirmationInput } from '../wave9/live-account-capture.js';
+import { type Wave9LiveSymbolOwnershipCheck } from '../wave9/live-symbol-ownership.js';
+import { type Wave9LiveResidualProtectionResult } from '../wave9/live-residual-protection.js';
+import { type Wave9PaperAdmissionGuard } from '../wave9/paper-admission-guard.js';
+type Wave9LiveResidualProtector = (adapter: IExchangeAdapter, ledger: Wave9LiveExecutionLedger, candidateId: string, symbol: string) => Promise<Wave9LiveResidualProtectionResult>;
 export declare function createOrderTool(args: {
     symbol: string;
     side: string;
@@ -10,6 +17,10 @@ export declare function createOrderTool(args: {
     amount: number;
     price?: number;
     stopPrice?: number;
+    mission_id?: string;
+    /** Guarded Wave 9 identity/capability. Both are invalid on generic orders. */
+    candidate_id?: string;
+    wave9_admission_token?: string;
     setup_type?: string;
     thesis?: string;
     target_price?: number;
@@ -43,6 +54,22 @@ export declare function createOrderTool(args: {
     proposalManager?: ProposalManager;
     userId?: string;
     approvalMode?: 'off' | 'shadow' | 'per_trade';
+    wave9AdmissionGuard?: Wave9PaperAdmissionGuard;
+    wave9ActivationCheck?: () => Promise<{
+        available: boolean;
+        active: boolean;
+    }>;
+    refreshPaperState?: () => void;
+    wave9TradingModeCheck?: () => string;
+    wave9VenueCheck?: () => string;
+    captureWave9AccountFingerprint?: () => Promise<{
+        fingerprint: string;
+    }>;
+    confirmWave9LiveStop?: (input: Wave9LiveStopConfirmationInput) => Promise<boolean>;
+    wave9LiveLedger?: Wave9LiveExecutionLedger;
+    checkWave9LiveSymbolOwnership?: Wave9LiveSymbolOwnershipCheck;
+    reprotectWave9LiveResidual?: Wave9LiveResidualProtector;
+    operationLock?: TradingOperationLock;
 }): Promise<CcxtOrder | {
     error: string;
 } | {
@@ -52,3 +79,4 @@ export declare function createOrderTool(args: {
     setup_bucket: 'momentum' | 'mean_reversion';
     message: string;
 }>;
+export {};