@reefclaw/openclaw-plugin 0.1.0

package/bridge/gateway/tool-discovery.js

@@ -0,0 +1,198 @@
+// Tool auto-discovery for the OpenClaw gateway.
+// Probes for available CCXT trading tools since OpenClaw has no GET /tools endpoint.
+// Builds a ToolMap mapping logical tool names to discovered actual tool names.
+import { logger } from '../logger.js';
+import { GatewayHttpError } from './gateway-http-client.js';
+const TAG = 'tool-discovery';
+const REQUIRED_TOOLS = ['fetch_ticker', 'fetch_balance'];
+const OPTIONAL_TOOLS = [
+    'fetch_ohlcv',
+    'fetch_positions',
+    'fetch_open_orders',
+    'cancel_all_orders',
+    'cancel_order',
+    'close_position',
+    'create_order',
+    'get_market_structure',
+    'get_crypto_metrics',
+    'get_market_intel',
+    'set_trading_mode',
+    'set_exchange_credentials',
+    'test_exchange_credentials',
+    'clear_exchange_credentials',
+    'get_bracket_config',
+    'set_bracket_requirement',
+];
+/**
+ * Candidate actual tool names to probe for each logical tool.
+ * Ordered by likelihood — first match wins.
+ */
+const CANDIDATES = {
+    fetch_ticker: ['fetch_ticker', 'ccxt_fetch_ticker', 'binance_fetch_ticker', 'get_ticker'],
+    fetch_balance: ['fetch_balance', 'ccxt_fetch_balance', 'binance_fetch_balance', 'get_balance'],
+    fetch_ohlcv: ['fetch_ohlcv', 'ccxt_fetch_ohlcv'],
+    fetch_positions: ['fetch_positions', 'fetch_open_positions', 'ccxt_fetch_positions'],
+    fetch_open_orders: ['fetch_open_orders', 'ccxt_fetch_open_orders'],
+    cancel_all_orders: ['cancel_all_orders', 'ccxt_cancel_all_orders'],
+    cancel_order: ['cancel_order', 'ccxt_cancel_order'],
+    close_position: ['close_position', 'close_all_positions', 'ccxt_close_position'],
+    create_order: ['create_order', 'ccxt_create_order'],
+    get_market_structure: ['get_market_structure'],
+    get_crypto_metrics: ['get_crypto_metrics'],
+    get_market_intel: ['get_market_intel'],
+    set_trading_mode: ['set_trading_mode'],
+    set_exchange_credentials: ['set_exchange_credentials'],
+    test_exchange_credentials: ['test_exchange_credentials'],
+    clear_exchange_credentials: ['clear_exchange_credentials'],
+    get_bracket_config: ['get_bracket_config'],
+    set_bracket_requirement: ['set_bracket_requirement'],
+};
+/**
+ * Test args used when probing each logical tool.
+ * Read tools (ticker, balance, etc.) use real args that return data.
+ * Write tools (create_order, cancel, close) use args that will be
+ * rejected by exchange validation (amount:0, etc.) — we only need
+ * to distinguish 400 (tool exists, bad args) from 404 (tool not found).
+ */
+const PROBE_ARGS = {
+    fetch_ticker: { symbol: 'BTC/USDT' },
+    fetch_balance: {},
+    fetch_ohlcv: { symbol: 'BTC/USDT', timeframe: '1h', limit: 1 },
+    fetch_positions: { symbol: 'BTC/USDT' },
+    fetch_open_orders: { symbol: 'BTC/USDT' },
+    // For write tools: probe with minimal args. We expect 400 (bad args) = tool exists.
+    cancel_all_orders: { symbol: 'BTC/USDT' },
+    cancel_order: { id: 'probe-0', symbol: 'BTC/USDT' },
+    close_position: { symbol: 'BTC/USDT' },
+    create_order: { symbol: 'BTC/USDT', type: 'limit', side: 'buy', amount: 0, price: 0 },
+    get_market_structure: { symbol: 'BTC/USDT' },
+    get_crypto_metrics: { symbol: 'BTC/USDT' },
+    get_market_intel: { category: 'sentiment' },
+    // Safe probe args — plugin tools early-return on invalid input without
+    // touching disk. `mode: '__probe__'` fails the VALID_MODES check; empty
+    // strings fail the length-8 validator in set_exchange_credentials. Both
+    // return HTTP 200 with ok:false, which the probe treats as "tool exists".
+    set_trading_mode: { mode: '__probe__' },
+    set_exchange_credentials: { apiKey: '', secret: '' },
+    // test_exchange_credentials: empty strings fail the length check and
+    // early-return without hitting Binance.
+    test_exchange_credentials: { apiKey: '', secret: '' },
+    // clear_exchange_credentials: tool requires confirm:true. Probing without
+    // it triggers the safety gate early-return — tool exists, nothing wiped.
+    clear_exchange_credentials: {},
+    // Bracket-config probes: no-arg read; set with an invalid flag triggers early-return.
+    get_bracket_config: {},
+    set_bracket_requirement: { flag: '__probe__', value: false },
+};
+// ---- Discovery logic ----
+/**
+ * Probe a single candidate tool name. Returns true if the tool exists.
+ *
+ * Strategy:
+ * - 200: tool exists and invocation succeeded
+ * - 400: tool exists but args were bad (still counts as found)
+ * - 404: tool does not exist
+ * - 401: auth error — rethrow (don't mask)
+ * - Other: treat as not found
+ */
+async function probeCandidate(http, candidateName, args) {
+    try {
+        await http.invoke(candidateName, args, { timeoutMs: 8_000 });
+        return true; // 200 — tool exists and works
+    }
+    catch (err) {
+        if (err instanceof GatewayHttpError) {
+            if (err.status === 400)
+                return true; // Tool exists, bad args
+            if (err.status === 404)
+                return false; // Tool not found
+            if (err.status === 401)
+                throw err; // Auth error — fatal
+        }
+        return false;
+    }
+}
+/**
+ * Discover the actual tool name for a logical tool by probing candidates in order.
+ * Returns the first candidate that exists, or null if none found.
+ */
+async function discoverTool(http, logical) {
+    const candidates = CANDIDATES[logical];
+    const args = PROBE_ARGS[logical];
+    for (const candidate of candidates) {
+        logger.debug(TAG, `Probing ${candidate} for ${logical}...`);
+        const exists = await probeCandidate(http, candidate, args);
+        if (exists) {
+            logger.debug(TAG, `Found: ${logical} → ${candidate}`);
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Discover all available trading tools on the gateway.
+ *
+ * Probes required tools first, then optional tools in parallel.
+ * Fails fast if no required tools are found.
+ */
+export async function discoverTools(http) {
+    logger.info(TAG, 'Starting tool auto-discovery...');
+    const toolMap = {};
+    const found = [];
+    const missingRequired = [];
+    const missingOptional = [];
+    // Discover required tools first (sequentially to fail fast on auth errors)
+    for (const logical of REQUIRED_TOOLS) {
+        const actual = await discoverTool(http, logical);
+        if (actual) {
+            toolMap[logical] = actual;
+            found.push(logical);
+        }
+        else {
+            missingRequired.push(logical);
+        }
+    }
+    // If all required tools are missing, log diagnostic and return (caller decides what to do)
+    if (found.length === 0) {
+        const tried = REQUIRED_TOOLS
+            .map(t => `${t}: [${CANDIDATES[t].join(', ')}]`)
+            .join('; ');
+        logger.warn(TAG, `No trading tools found. Is a CCXT trading plugin installed? Tried: ${tried}`);
+        logger.info(TAG, 'Hint: install a trading plugin with: openclaw skills install reefclaw-paper-trading');
+        // Still discover optional tools — some might exist even without required ones
+    }
+    // Log missing required tools
+    for (const logical of missingRequired) {
+        logger.error(TAG, `Required tool not found: ${logical} (tried: ${CANDIDATES[logical].join(', ')})`);
+    }
+    // Discover optional tools in parallel
+    const optionalResults = await Promise.allSettled(OPTIONAL_TOOLS.map(async (logical) => {
+        const actual = await discoverTool(http, logical);
+        return { logical, actual };
+    }));
+    for (const result of optionalResults) {
+        if (result.status === 'fulfilled') {
+            const { logical, actual } = result.value;
+            if (actual) {
+                toolMap[logical] = actual;
+                found.push(logical);
+            }
+            else {
+                missingOptional.push(logical);
+            }
+        }
+        else {
+            // Promise rejected (shouldn't happen unless auth error propagates)
+            logger.warn(TAG, `Discovery failed for optional tool: ${result.reason}`);
+        }
+    }
+    // Log summary
+    logger.info(TAG, `Tool discovery complete: ${found.length} found, ${missingRequired.length} required missing, ${missingOptional.length} optional missing`);
+    for (const [logical, actual] of Object.entries(toolMap)) {
+        logger.info(TAG, `  ${logical} → ${actual}`);
+    }
+    for (const logical of missingOptional) {
+        logger.warn(TAG, `Optional tool not found: ${logical}`);
+    }
+    return { toolMap, found, missingRequired, missingOptional };
+}

package/bridge/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/bridge/index.js

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+// ReefClaw Skill — CLI entry point
+// Usage:
+//   tsx src/index.ts --provider mock                    (standalone testing)
+//   tsx src/index.ts --provider gateway                 (real OpenClaw — not yet implemented)
+//   tsx src/index.ts --setup rc_TOKEN --user-id ID      (save token to config)
+//
+// Config precedence: CLI args > env vars > OpenClaw config > fallback env > defaults
+// See config.ts for full resolution logic.
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { logger, setLogLevel } from './logger.js';
+import { Bridge } from './bridge.js';
+import { MockProvider } from './providers/mock.js';
+import { GatewayProvider } from './providers/gateway.js';
+import { resolveConfig, ensureGatewayScopeConfigOnStartup } from './config.js';
+import { resolveGatewayConfig, validateGatewayConfig } from './gateway/gateway-config.js';
+import { runSetup } from './setup.js';
+const TAG = 'main';
+// ---- Load .env file (skill/.env only) ----
+function loadEnvFile() {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const envPath = resolve(__dirname, '..', '.env');
+    try {
+        const content = readFileSync(envPath, 'utf-8');
+        for (const line of content.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#'))
+                continue;
+            const eqIdx = trimmed.indexOf('=');
+            if (eqIdx === -1)
+                continue;
+            const key = trimmed.slice(0, eqIdx).trim();
+            const value = trimmed.slice(eqIdx + 1).trim();
+            if (!process.env[key])
+                process.env[key] = value;
+        }
+        logger.debug(TAG, `Loaded env from ${envPath}`);
+    }
+    catch {
+        // File not found — not an error
+    }
+}
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const cli = { provider: 'mock' };
+    const gateway = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const next = args[i + 1];
+        switch (arg) {
+            case '--provider':
+            case '-p':
+                if (next === 'mock' || next === 'gateway') {
+                    cli.provider = next;
+                    i++;
+                }
+                else {
+                    console.error(`Invalid provider: ${next}. Use "mock" or "gateway".`);
+                    process.exit(1);
+                }
+                break;
+            case '--token':
+            case '-t':
+                cli.token = next;
+                i++;
+                break;
+            case '--user-id':
+            case '-u':
+                cli.userId = next;
+                i++;
+                break;
+            case '--relay-url':
+            case '-r':
+                cli.relayUrl = next;
+                i++;
+                break;
+            case '--gateway-url':
+                gateway.gatewayUrl = next;
+                i++;
+                break;
+            case '--gateway-token':
+                gateway.gatewayToken = next;
+                i++;
+                break;
+            case '--symbol':
+                gateway.symbol = next;
+                i++;
+                break;
+            case '--log-level':
+            case '-l':
+                if (['debug', 'info', 'warn', 'error'].includes(next)) {
+                    cli.logLevel = next;
+                    i++;
+                }
+                break;
+            case '--setup':
+            case '-s':
+                // --setup with optional token as next arg
+                if (next && !next.startsWith('-')) {
+                    cli.setup = next;
+                    i++;
+                }
+                else {
+                    cli.setup = true;
+                }
+                break;
+            case '--help':
+            case '-h':
+                printUsage();
+                process.exit(0);
+        }
+    }
+    return { cli, gateway };
+}
+function printUsage() {
+    console.log(`
+ReefClaw Skill — Bridge between OpenClaw and ReefClaw relay
+
+Usage:
+  tsx src/index.ts [options]
+
+Options:
+  --provider, -p <mock|gateway>  Provider type (default: mock)
+  --token, -t <token>            Connection token (or REEFCLAW_TOKEN env)
+  --user-id, -u <id>             User ID (or REEFCLAW_USER_ID env)
+  --relay-url, -r <url>          Relay URL (default: wss://reefclaw.radunlupsa.partykit.dev)
+  --gateway-url <url>            OpenClaw gateway URL (or OPENCLAW_GATEWAY_URL env)
+  --gateway-token <token>        OpenClaw gateway token (or OPENCLAW_GATEWAY_TOKEN env)
+  --symbol <symbol>              Trading symbol (default: BTC/USDT, or REEFCLAW_SYMBOL env)
+  --log-level, -l <level>        Log level: debug, info, warn, error (default: info)
+  --setup, -s [token]            Run setup flow (validate token, test connection, save to config)
+  --help, -h                     Show this help
+
+Relay config resolution (highest priority first):
+  1. CLI arguments (--token, --user-id, --relay-url)
+  2. Environment variables (REEFCLAW_TOKEN, REEFCLAW_USER_ID, REEFCLAW_RELAY_URL)
+  3. OpenClaw config file (~/.openclaw/openclaw.json → skills.entries.reefclaw)
+  4. Fallback env vars (MOCK_TOKEN, USER_ID)
+  5. Defaults (relay URL → wss://reefclaw.radunlupsa.partykit.dev)
+
+Gateway config resolution (for --provider gateway):
+  1. CLI arguments (--gateway-url, --gateway-token, --symbol)
+  2. Environment variables (OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN, REEFCLAW_SYMBOL)
+  3. OpenClaw config file (~/.openclaw/openclaw.json → gateway.auth.token, gateway.port)
+  4. Defaults (http://localhost:18789, BTC/USDT)
+`);
+}
+// ---- Main ----
+async function main() {
+    loadEnvFile();
+    ensureGatewayScopeConfigOnStartup();
+    const { cli: args, gateway: gatewayArgs } = parseArgs();
+    if (args.logLevel) {
+        setLogLevel(args.logLevel);
+    }
+    // Handle --setup flow
+    if (args.setup !== undefined) {
+        const setupToken = typeof args.setup === 'string' ? args.setup : undefined;
+        await runSetup(setupToken, args.userId);
+        process.exit(0);
+    }
+    // Resolve config
+    const { token, userId, relayUrl } = resolveConfig(args);
+    if (!token || !userId) {
+        console.error('');
+        console.error('  ReefClaw: Missing configuration');
+        console.error('  ================================');
+        console.error('');
+        if (!token) {
+            console.error('  No connection token found.');
+        }
+        if (!userId) {
+            console.error('  No user ID found.');
+        }
+        console.error('');
+        console.error('  Quick setup:');
+        console.error('    node dist/index.js --setup rc_YOUR_TOKEN --user-id YOUR_USER_ID');
+        console.error('');
+        console.error('  Or set environment variables:');
+        console.error('    REEFCLAW_TOKEN=rc_xxx REEFCLAW_USER_ID=xxx node dist/index.js');
+        console.error('');
+        console.error('  Or paste the connect message from the onboarding page to your agent:');
+        console.error('    "Connect my agent to ReefClaw. Save these to my reefclaw skill config:');
+        console.error('     token: rc_...  userId: <uuid>  relayUrl: wss://..."');
+        console.error('  (A token alone is NOT enough — the userId is required to reach the relay.)');
+        console.error('');
+        console.error('  Get the full connect message at https://reefclaw.com/onboarding');
+        console.error('');
+        process.exit(1);
+    }
+    // Create provider
+    let provider;
+    if (args.provider === 'mock') {
+        logger.info(TAG, 'Using MockProvider');
+        provider = new MockProvider();
+    }
+    else {
+        // Resolve and validate gateway config for real OpenClaw connection
+        const gwResolved = resolveGatewayConfig(gatewayArgs);
+        const gwConfig = validateGatewayConfig(gwResolved);
+        if (!gwConfig) {
+            console.error('');
+            console.error('  ReefClaw: Missing gateway token');
+            console.error('  ================================');
+            console.error('');
+            console.error('  No OpenClaw gateway token found. The token is read from:');
+            console.error('    1. --gateway-token CLI arg');
+            console.error('    2. OPENCLAW_GATEWAY_TOKEN env var');
+            console.error('    3. ~/.openclaw/openclaw.json → gateway.auth.token');
+            console.error('');
+            console.error('  Make sure OpenClaw is configured and running.');
+            console.error('');
+            process.exit(1);
+        }
+        // Pass connection token so GatewayProvider can authenticate with intelligence service
+        gwConfig.connectionToken = token;
+        logger.info(TAG, `Using GatewayProvider (url=${gwConfig.gatewayUrl}, symbol=${gwConfig.symbol})`);
+        provider = new GatewayProvider(gwConfig);
+    }
+    // Create bridge
+    const connectorConfig = {
+        relayUrl,
+        userId,
+        token,
+    };
+    const bridge = new Bridge(provider, connectorConfig);
+    // Handle graceful shutdown
+    let shuttingDown = false;
+    async function shutdown(signal) {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        logger.info(TAG, `Received ${signal}, shutting down...`);
+        // Drain in-flight trade reports before stopping (prevents data loss during kill/flatten)
+        if ('drainReports' in provider && typeof provider.drainReports === 'function') {
+            try {
+                await provider.drainReports();
+            }
+            catch { /* best-effort */ }
+        }
+        bridge.stop();
+        // Allow 1s for final cleanup before force exit
+        setTimeout(() => process.exit(0), 1000);
+    }
+    process.on('SIGINT', () => void shutdown('SIGINT').catch(() => process.exit(1)));
+    process.on('SIGTERM', () => void shutdown('SIGTERM').catch(() => process.exit(1)));
+    // Start
+    logger.info(TAG, `Starting ReefClaw skill (provider=${args.provider}, relay=${relayUrl})`);
+    bridge.start();
+}
+main();

package/bridge/logger.d.ts

@@ -0,0 +1,2 @@
+export type { LogLevel } from '@reefclaw/shared';
+export { logger, setLogLevel, formatError } from '@reefclaw/shared';

package/bridge/logger.js

@@ -0,0 +1,2 @@
+// Re-export from @reefclaw/shared (canonical source of truth).
+export { logger, setLogLevel, formatError } from '@reefclaw/shared';

package/bridge/provider.d.ts

@@ -0,0 +1,156 @@
+import type { EmergencyAction, ReconciliationSnapshot, TickerData, CandleData, OrderUpdatePayload, AgentStateData, RiskUpdatePayload, ChatMessage, MarketStructureData, CryptoMetricsData, VolumeAnalysisData, TradeJournalEntry, RegimeData, SignalData, MissionData, AnalyticsData, ShadowComparisonData, TradingModeData, DecisionTraceData } from './types.js';
+import type { TradingMode } from '@reefclaw/shared';
+/** Fill error data emitted when a limit fill fails */
+export interface FillErrorData {
+    orderId: string;
+    symbol: string;
+    error: string;
+    timestamp: string;
+}
+/** Events emitted by the provider to be forwarded to the relay */
+export interface ProviderEvents {
+    ticker: (data: TickerData) => void;
+    candle: (data: CandleData) => void;
+    orderUpdate: (data: OrderUpdatePayload) => void;
+    agentState: (data: AgentStateData) => void;
+    riskUpdate: (data: RiskUpdatePayload) => void;
+    chatMessage: (data: {
+        message: ChatMessage;
+    }) => void;
+    /** Streaming chat: first chunk — creates the in-progress message */
+    chatMessageStart: (data: {
+        id: string;
+        runId: string;
+        timestamp: string;
+    }) => void;
+    /** Streaming chat: incremental text delta */
+    chatMessageChunk: (data: {
+        id: string;
+        delta: string;
+    }) => void;
+    /** Streaming chat: generation complete — final content for DB persistence */
+    chatMessageEnd: (data: {
+        id: string;
+        content: string;
+    }) => void;
+    /** Streaming chat: keep-alive during tool execution — prevents webapp timeout */
+    chatStreamingKeepAlive: (data: {
+        id: string;
+        toolName: string;
+    }) => void;
+    marketStructure: (data: MarketStructureData) => void;
+    cryptoMetrics: (data: CryptoMetricsData) => void;
+    volumeAnalysis: (data: VolumeAnalysisData) => void;
+    tradeJournal: (data: TradeJournalEntry) => void;
+    /** Regime classification from intelligence service */
+    regimeUpdate: (data: RegimeData) => void;
+    /** Signal engine updates from intelligence service */
+    signalUpdate: (data: SignalData) => void;
+    /** Trade mission updates from intelligence service */
+    missionUpdate: (data: MissionData) => void;
+    /** Edge analytics updates from intelligence service */
+    analyticsUpdate: (data: AnalyticsData) => void;
+    /** Background fill error (e.g., limit order fill failed due to insufficient balance) */
+    fillError: (data: FillErrorData) => void;
+    /** Shadow comparison event — paper vs live fill estimate (Phase 9b) */
+    shadowComparison: (data: ShadowComparisonData) => void;
+    /** Trading mode update (Phase 9b) */
+    tradingModeUpdate: (data: TradingModeData) => void;
+    /** Decision trace update (Phase 9c) */
+    decisionTraceUpdate: (data: DecisionTraceData) => void;
+}
+export type ProviderEventName = keyof ProviderEvents;
+/**
+ * Adapter interface between OpenClaw (or mock) and the ReefClaw relay.
+ * Implementations emit events via the on/off listener pattern.
+ */
+export interface OpenClawProvider {
+    /** Start the provider (begin emitting events) */
+    start(): void;
+    /** Stop the provider (clean up timers, connections) */
+    stop(): void;
+    /** Execute an emergency command */
+    executeEmergency(action: EmergencyAction): Promise<{
+        action: string;
+        executed: boolean;
+        timestamp: string;
+    }>;
+    /** Handle an incoming chat message from the operator */
+    handleChat(content: string): Promise<{
+        received: boolean;
+        error?: string;
+    }>;
+    /** Close a specific position by symbol (non-emergency, single-symbol close) */
+    closePosition(symbol: string): Promise<{
+        closed: boolean;
+        symbol: string;
+        error?: string;
+    }>;
+    /** Operator-only: set the trading mode. Plugin enforces the ladder. */
+    setTradingMode?(mode: TradingMode, acknowledged?: boolean): Promise<{
+        ok: boolean;
+        message: string;
+        previousMode: TradingMode;
+        mode: TradingMode;
+        readiness: string;
+        reason?: string;
+    }>;
+    /** Operator-only: set Binance API credentials. The raw secret is written
+     *  to the plugin-local config file and never retained by the skill. */
+    setExchangeCredentials?(apiKey: string, secret: string, testnet?: boolean): Promise<{
+        ok: boolean;
+        message: string;
+        fingerprint: string;
+        reconnected: boolean;
+        mode: TradingMode;
+        readiness: string;
+    }>;
+    /** Operator-only: verify Binance API credentials with a transient
+     *  read-only call. Nothing is persisted. */
+    testExchangeCredentials?(apiKey: string, secret: string, testnet?: boolean): Promise<{
+        ok: boolean;
+        message: string;
+        fingerprint: string;
+        canReadBalance: boolean;
+        canReadPositions: boolean;
+        balanceUSDT: number | null;
+        testnet: boolean;
+        errors: string[];
+    }>;
+    /** Operator-only: remove stored credentials from the plugin config and
+     *  de-escalate to PAPER mode if currently running in a live mode. */
+    clearExchangeCredentials?(): Promise<{
+        ok: boolean;
+        message: string;
+        modeBefore: TradingMode;
+        mode: TradingMode;
+        rolledBackToPaper: boolean;
+        readiness: string;
+    }>;
+    /** Operator-only: read current bracket-orders config (mode + require flags). */
+    getBracketConfig?(): Promise<{
+        ok: boolean;
+        message?: string;
+        mode: 'off' | 'observe' | 'enforce';
+        requireStopLoss: boolean;
+        requireTakeProfit: boolean;
+    }>;
+    /** Operator-only: flip requireStopLoss or requireTakeProfit. Returns a
+     *  warning string when a flag goes off so the dashboard can render the
+     *  confirmation banner without hardcoding copy. */
+    setBracketRequirement?(flag: 'requireStopLoss' | 'requireTakeProfit', value: boolean): Promise<{
+        ok: boolean;
+        flag: 'requireStopLoss' | 'requireTakeProfit';
+        previousValue: boolean;
+        value: boolean;
+        warning?: string;
+        error?: string;
+        message?: string;
+    }>;
+    /** Get a full reconciliation snapshot */
+    getSnapshot(): Promise<ReconciliationSnapshot>;
+    /** Register an event listener */
+    on<E extends ProviderEventName>(event: E, listener: ProviderEvents[E]): void;
+    /** Remove an event listener */
+    off<E extends ProviderEventName>(event: E, listener: ProviderEvents[E]): void;
+}

package/bridge/provider.js

@@ -0,0 +1,2 @@
+// OpenClawProvider interface — adapter pattern for mock vs real gateway
+export {};

package/bridge/providers/emergency-commands.d.ts

@@ -0,0 +1,54 @@
+import type { GatewayHttpClient } from '../gateway/gateway-http-client.js';
+import type { ToolMap } from '../gateway/tool-discovery.js';
+import type { OrderData } from '../types.js';
+import type { CcxtPosition } from '../gateway/poller.js';
+export interface EmergencyResult {
+    action: string;
+    executed: boolean;
+    timestamp: string;
+    details?: string;
+}
+export type AgentMode = 'ACTIVE' | 'PAUSED' | 'STOPPED' | 'ERROR';
+export interface EmergencyContext {
+    http: GatewayHttpClient | null;
+    toolMap: ToolMap;
+    symbol: string;
+}
+/**
+ * Kill: stop the agent and cancel WORKING orders, while PRESERVING protective
+ * brackets. A protective order (exchange-side STOP_MARKET / TAKE_PROFIT_MARKET)
+ * is the only thing guarding an open position once the agent is halted (nothing
+ * will re-attach a stop). Kill cancels only the agent's working orders (pending
+ * entries / adds), PORTFOLIO-WIDE, and keeps every protective leg in place. To
+ * actually exit a position, use Flatten.
+ *
+ * Bracket preservation is defence-in-depth: the plugin's `cancelAllOrders`
+ * already skips ReefClaw-cid brackets, so the old per-symbol kill never stripped
+ * a ReefClaw bracket — this skill-side `protective` filter is BROADER (it also
+ * preserves externally-placed / non-ReefClaw-cid stops) and portfolio-wide.
+ *
+ * Caller must set agentMode = 'STOPPED' after this returns, and should pass a
+ * FRESH all-symbols order snapshot (see the gateway wrapper).
+ */
+export declare function executeKill(ctx: EmergencyContext, openOrders: OrderData[]): Promise<EmergencyResult>;
+/**
+ * Flatten: close all open positions at market.
+ * Caller must set agentMode = 'STOPPED' after this returns.
+ */
+export declare function executeFlatten(ctx: EmergencyContext, cachedPositions: CcxtPosition[]): Promise<EmergencyResult>;
+/**
+ * Pause: prevent new entries, keep existing positions.
+ * Returns the new agent mode if the transition is valid.
+ */
+export declare function executePause(currentMode: AgentMode): {
+    result: EmergencyResult;
+    newMode: AgentMode;
+};
+/**
+ * Resume: re-enable entries.
+ * Returns the new agent mode if the transition is valid.
+ */
+export declare function executeResume(currentMode: AgentMode): {
+    result: EmergencyResult;
+    newMode: AgentMode;
+};