@reefclaw/connect 0.1.0

package/assets/bridge/bridge.js

@@ -0,0 +1,969 @@
+// Bridge: wires an OpenClawProvider to a Connector.
+// Provider events → EventFrames with seq tracking → Connector → Relay → Browser.
+// Incoming requests from Connector → routed to Provider methods.
+import { writeFileSync, readFileSync, renameSync, existsSync, mkdirSync, unlinkSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { logger } from './logger.js';
+import { Connector } from './connector.js';
+import { readLocalSkillVersion, validateSkillContent, compareSemver } from './utils/skill-version.js';
+import { verifySkillSignature, signatureRequired, readLastAppliedSignedAtMs, recordAppliedSignedAt, } from './utils/skill-signing.js';
+import { isTradingMode, validateModeTransition, redactTokens } from '@reefclaw/shared';
+import { OPERATOR_WRITE_METHODS } from './types.js';
+import { EventReplayBuffer } from './event-replay-buffer.js';
+const TAG = 'bridge';
+const AUDIT_TAG = 'bridge-audit';
+/** Write a structured audit log line. Goes through the normal logger today —
+ *  a future PR may tee this to a dedicated audit sink. Must NEVER include raw
+ *  secrets; use the `fingerprint` field in payload instead of `secret`. */
+function audit(event, payload) {
+    // JSON-encoded payload keeps fields greppable and machine-parseable without
+    // a dedicated audit schema. Secrets must be redacted BEFORE calling this.
+    logger.info(AUDIT_TAG, `${event} ${JSON.stringify(payload)}`);
+}
+/** Best-effort redaction helper — first 4 + last 2 chars, or `***` for short
+ *  strings. Mirrors plugin/src/config/plugin-config-io.ts:redactCredential. */
+function fingerprint(value) {
+    if (!value)
+        return '(empty)';
+    if (value.length <= 8)
+        return '***';
+    return `${value.slice(0, 4)}…${value.slice(-2)}`;
+}
+// ---- Event priority throttler ----
+// Critical events (trades, risk, chat, fill errors) are sent immediately.
+// Low-priority events (ticker, candles, market structure, crypto metrics, volume, regime,
+// signals, missions, analytics, decision traces, shadows) are coalesced: only the latest
+// value per event type is kept, flushed every THROTTLE_INTERVAL_MS.
+const THROTTLE_INTERVAL_MS = 500; // Flush low-priority events every 500ms
+/** Events that must NEVER be dropped or delayed */
+const CRITICAL_EVENTS = new Set([
+    'order_update', // Trade fills, submissions, cancellations
+    'fill_error', // Execution failures
+    'risk_update', // Risk breach alerts
+    'trade_journal', // Trade journal entries
+    'state_update', // Agent mode changes (ACTIVE/PAUSED/STOPPED)
+    'trading_mode', // Paper/live mode changes
+    'skill_update_applied', // OTA SKILL.md confirmation
+    // All chat events are on the 'chat' channel and always sent immediately
+]);
+export class Bridge {
+    provider;
+    connector;
+    seqs = {
+        market_data: 0,
+        trade_events: 0,
+        agent_state: 0,
+        chat: 0,
+    };
+    // Throttle buffer: keyed by "channel:event", holds latest payload
+    throttleBuffer = new Map();
+    throttleTimer = null;
+    /**
+     * Bounded ring buffer of every frame this bridge has emitted to the relay.
+     * On a `reconcile` request the bridge populates `snapshot.gapFill` with
+     * everything the browser hasn't seen yet (per-channel `seq > lastSeq`).
+     * Defaults: 500 events × 4 channels × 5 min age cap. See
+     * event-replay-buffer.ts for the rationale.
+     */
+    replayBuffer = new EventReplayBuffer();
+    /** Current local SKILL.md version (from frontmatter) */
+    currentSkillVersion;
+    /** Last trading mode observed from either a tradingMode event or a
+     *  successful set_trading_mode outcome. Used by the skill-side ladder
+     *  check so the dashboard can be rejected quickly without a plugin
+     *  round-trip. `null` means "unknown yet" — the plugin is the authority. */
+    lastKnownTradingMode = null;
+    // Bound listeners for cleanup
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    listeners = [];
+    constructor(provider, connectorConfig) {
+        this.provider = provider;
+        this.currentSkillVersion = readLocalSkillVersion();
+        logger.info(TAG, `Local SKILL.md version: ${this.currentSkillVersion ?? 'unknown'}`);
+        this.connector = new Connector(connectorConfig, {
+            onRequest: (frame) => this.handleRequest(frame),
+            onStateChange: (state) => this.handleStateChange(state),
+            onConnectAck: (payload) => this.handleConnectAck(payload),
+        });
+    }
+    /** Start the bridge: connect to relay + start provider */
+    start() {
+        logger.info(TAG, 'Starting bridge');
+        this.wireProviderEvents();
+        this.startThrottleTimer();
+        this.provider.start();
+        this.connector.connect();
+    }
+    /** Stop the bridge: disconnect + stop provider */
+    stop() {
+        logger.info(TAG, 'Stopping bridge');
+        this.stopThrottleTimer();
+        this.unwireProviderEvents();
+        this.connector.destroy();
+        this.provider.stop();
+    }
+    // ---- Wire provider events to connector ----
+    wireProviderEvents() {
+        this.addListener('ticker', (data) => {
+            // Wrap in MarketDataEvent format expected by webapp
+            this.emit('market_data', 'ticker', {
+                symbol: data.symbol,
+                ticker: data,
+                timestamp: data.timestamp,
+            });
+        });
+        this.addListener('candle', (data) => {
+            this.emit('market_data', 'candle', data);
+        });
+        this.addListener('orderUpdate', (data) => {
+            this.emit('trade_events', 'order_update', data);
+        });
+        this.addListener('agentState', (data) => {
+            this.emit('agent_state', 'state_update', data);
+        });
+        this.addListener('riskUpdate', (data) => {
+            this.emit('agent_state', 'risk_update', data);
+        });
+        this.addListener('chatMessage', (data) => {
+            this.emit('chat', 'message', data);
+        });
+        // Streaming chat events
+        this.addListener('chatMessageStart', (data) => {
+            this.emit('chat', 'message_start', data);
+        });
+        this.addListener('chatMessageChunk', (data) => {
+            this.emit('chat', 'message_chunk', data);
+        });
+        this.addListener('chatMessageEnd', (data) => {
+            this.emit('chat', 'message_end', data);
+        });
+        this.addListener('chatStreamingKeepAlive', (data) => {
+            this.emit('chat', 'streaming_keepalive', data);
+        });
+        this.addListener('marketStructure', (data) => {
+            this.emit('agent_state', 'market_structure', {
+                event: 'market_structure',
+                ...data,
+            });
+        });
+        this.addListener('cryptoMetrics', (data) => {
+            this.emit('agent_state', 'crypto_metrics', {
+                event: 'crypto_metrics',
+                ...data,
+            });
+        });
+        this.addListener('volumeAnalysis', (data) => {
+            this.emit('agent_state', 'volume_analysis', {
+                event: 'volume_analysis',
+                ...data,
+            });
+        });
+        this.addListener('tradeJournal', (data) => {
+            this.emit('trade_events', 'trade_journal', {
+                event: 'trade_journal',
+                ...data,
+            });
+        });
+        this.addListener('regimeUpdate', (data) => {
+            this.emit('agent_state', 'regime_update', data);
+        });
+        this.addListener('signalUpdate', (data) => {
+            this.emit('agent_state', 'signal_update', data);
+        });
+        this.addListener('missionUpdate', (data) => {
+            this.emit('agent_state', 'mission_update', data);
+        });
+        this.addListener('analyticsUpdate', (data) => {
+            this.emit('agent_state', 'analytics_update', data);
+        });
+        this.addListener('fillError', (data) => {
+            this.emit('agent_state', 'fill_error', {
+                event: 'fill_error',
+                orderId: data.orderId,
+                symbol: data.symbol,
+                error: data.error,
+                timestamp: data.timestamp,
+            });
+        });
+        // Phase 9b: Shadow mode events
+        // Normalize side/type from CCXT lowercase to protocol uppercase
+        this.addListener('shadowComparison', (data) => {
+            this.emit('agent_state', 'shadow_comparison', {
+                ...data,
+                side: data.side.toUpperCase(),
+                type: data.type.toUpperCase(),
+            });
+        });
+        this.addListener('tradingModeUpdate', (data) => {
+            // Keep the skill-side ladder cache in sync with the plugin's view.
+            this.lastKnownTradingMode = data.mode;
+            this.emit('agent_state', 'trading_mode', data);
+        });
+        // Phase 9c: Decision trace events
+        this.addListener('decisionTraceUpdate', (data) => {
+            this.emit('agent_state', 'decision_trace', data);
+        });
+    }
+    addListener(event, fn) {
+        this.provider.on(event, fn);
+        this.listeners.push({ event, fn });
+    }
+    unwireProviderEvents() {
+        for (const { event, fn } of this.listeners) {
+            this.provider.off(event, fn);
+        }
+        this.listeners.length = 0;
+    }
+    // ---- Emit event frames with seq tracking + priority throttling ----
+    emit(channel, event, payload) {
+        // Deliberately NO `isConnected()` short-circuit. Every emitted event must
+        // reach `sendFrame` so it lands in the replay buffer — that buffer is
+        // what we replay via `gapFill` when a browser reconciles after the
+        // skill→relay link recovers from a transient drop. The wire-side send
+        // inside sendFrame is gated by the connector and no-ops cleanly when the
+        // socket is closed, so emitting while disconnected is safe.
+        // Critical events and all chat events: send immediately, never throttle
+        if (channel === 'chat' || CRITICAL_EVENTS.has(event)) {
+            this.sendFrame(channel, event, payload);
+            return;
+        }
+        // Low-priority events: coalesce in buffer, flush periodically.
+        // Key by symbol when present so multi-symbol data doesn't overwrite each other.
+        let key = `${channel}:${event}`;
+        if (payload && typeof payload === 'object' && 'symbol' in payload) {
+            key = `${channel}:${event}:${payload.symbol}`;
+        }
+        this.throttleBuffer.set(key, { channel, event, payload });
+    }
+    /** Send a frame to the relay AND record it in the replay buffer.
+     *
+     *  Both writes happen unconditionally:
+     *    - replayBuffer.record() is the canonical wire-history; gapFill draws
+     *      from it on the next reconcile, even if this frame's wire send was
+     *      a no-op because the connector was disconnected.
+     *    - connector.sendEvent() internally checks readyState and silently
+     *      no-ops when the socket is closed (connector.ts:164), so calling it
+     *      during a disconnect is safe and we don't have to mirror the gate
+     *      here. */
+    sendFrame(channel, event, payload) {
+        const seq = this.seqs[channel]++;
+        const frame = {
+            type: 'event',
+            event,
+            channel,
+            payload,
+            seq,
+        };
+        this.replayBuffer.record(channel, event, payload, seq);
+        this.connector.sendEvent(frame);
+    }
+    /** Flush all buffered low-priority events (latest value per type).
+     *
+     *  Drains through sendFrame regardless of connector state — the replay
+     *  buffer is the authoritative record and must capture coalesced events
+     *  even when the link is down. The wire send inside sendFrame is a no-op
+     *  until the connector reconnects, at which point new events flow live and
+     *  the offline coalesced ones are available via gapFill on reconcile. */
+    flushThrottleBuffer() {
+        if (this.throttleBuffer.size === 0)
+            return;
+        for (const [, { channel, event, payload }] of this.throttleBuffer) {
+            this.sendFrame(channel, event, payload);
+        }
+        this.throttleBuffer.clear();
+    }
+    startThrottleTimer() {
+        this.stopThrottleTimer();
+        this.throttleTimer = setInterval(() => this.flushThrottleBuffer(), THROTTLE_INTERVAL_MS);
+    }
+    stopThrottleTimer() {
+        if (this.throttleTimer) {
+            clearInterval(this.throttleTimer);
+            this.throttleTimer = null;
+        }
+        // Flush remaining on stop
+        this.flushThrottleBuffer();
+    }
+    // ---- Handle incoming requests ----
+    async handleRequest(frame) {
+        const { id, method, params } = frame;
+        try {
+            // ---- Operator-write scope gate ----
+            // Methods in OPERATOR_WRITE_METHODS require an elevated scope. Today,
+            // all connected sessions inherit operator.write from the relay-level
+            // authentication (Clerk-issued token), so this check is effectively a
+            // whitelist — it exists so a future PR can attach per-session roles
+            // without restructuring the dispatcher. Emergency methods are on the
+            // list for the same reason (they are already covered today, but the
+            // list is the forward-compatible gate).
+            if (OPERATOR_WRITE_METHODS.has(method) && !this.hasOperatorWriteScope()) {
+                audit('operator_write.denied', { method, id });
+                this.connector.sendResponse(id, false, undefined, {
+                    code: 403,
+                    message: 'operator.write scope required',
+                });
+                return;
+            }
+            if (method.startsWith('emergency.')) {
+                const action = method.split('.')[1];
+                logger.info(TAG, `Emergency command: ${action}`);
+                const result = await this.provider.executeEmergency(action);
+                this.connector.sendResponse(id, true, result);
+                return;
+            }
+            if (method === 'reconcile') {
+                logger.info(TAG, 'Reconciliation requested');
+                const snapshot = await this.provider.getSnapshot();
+                const lastSequences = parseLastSequences(params);
+                const gapFill = this.replayBuffer
+                    .sinceMany(lastSequences)
+                    .map((e) => ({
+                    type: 'event',
+                    channel: e.channel,
+                    event: e.event,
+                    payload: e.payload,
+                    seq: e.seq,
+                }));
+                if (gapFill.length > 0) {
+                    logger.info(TAG, `gapFill: ${gapFill.length} events replayed (lastSeqs=${JSON.stringify(lastSequences)})`);
+                }
+                // Provider hardcodes gapFill: []; bridge owns the wire-side seq
+                // counter so it is the canonical source. Overwrite unconditionally.
+                const enriched = { ...snapshot, gapFill };
+                this.connector.sendResponse(id, true, enriched);
+                return;
+            }
+            if (method === 'chat.send') {
+                const rawContent = params?.content ?? '';
+                // Redact rc_* tokens BEFORE we touch the message anywhere downstream:
+                //   - the log line below
+                //   - the provider (which may forward to the OpenClaw agent's session
+                //     JSONL, the mock provider's stdout, etc.)
+                // Onboarding directs users to paste their token into the local
+                // OpenClaw terminal; a confused operator pasting into the dashboard
+                // chat lands here, and the webapp + relay have already auto-revoked
+                // the token by now. Forwarding the raw bytes any further has no
+                // legitimate purpose — the agent can react to "rc_***" the same way
+                // it would react to the original message.
+                const safeContent = redactTokens(rawContent);
+                if (safeContent !== rawContent) {
+                    logger.warn(TAG, 'Chat contained a connection token — webapp/relay should have auto-revoked. ' +
+                        'If the agent is still connected after this, generate a new token in Settings.');
+                }
+                // Approval Mode Phase C — when the operator is discussing a pending
+                // proposal in the chat panel, the webapp attaches a compact blob so
+                // we can prefix a context note. The agent then knows which trade
+                // the operator is asking about for THIS turn, and may emit a new
+                // create_order with `supersedes_id` to modify the proposal.
+                // Fail-open: if the context is malformed, we just pass through the
+                // raw chat content without crashing the bridge.
+                let augmentedContent = safeContent;
+                const proposalContext = params?.proposalContext;
+                if (proposalContext && typeof proposalContext === 'object') {
+                    try {
+                        const c = proposalContext;
+                        const header = `[Operator is discussing your pending proposal — ` +
+                            `id=${c.id} ${c.symbol} ${c.side} size=${c.size} ` +
+                            `entry=${c.proposedEntry} stop=${c.stopPrice} target=${c.targetPrice} ` +
+                            `risk=$${c.riskUsd} setup=${c.setupType} regime=${c.regime} ` +
+                            `conf=${c.confluenceScore}. Thesis: ${String(c.thesis ?? '').slice(0, 200)}. ` +
+                            `If they want a modification, use create_order with supersedes_id=${c.id}.]\n\n`;
+                        augmentedContent = header + safeContent;
+                    }
+                    catch (err) {
+                        logger.warn(TAG, `Failed to render proposalContext header: ${String(err)}`);
+                    }
+                }
+                // Phase 4 learning curation — operator may be discussing a learning
+                // rule (confirmed / hypothesis / retired). The webapp pins the
+                // learning via the LearningsTab 💬 button and attaches a compact
+                // blob with the learning's identity, directive, trigger, and
+                // mined-pattern evidence stats. The agent's job in that turn is to
+                // help the operator refine the rule — soften/tighten the trigger,
+                // re-word the directive, point out gaps in evidence, or argue for
+                // retiring/re-confirming. The agent does NOT mutate the learning
+                // directly; concrete edits flow through the operator's Edit dialog.
+                // Independent from proposalContext — both may fire on the same turn.
+                const learningContext = params?.learningContext;
+                if (learningContext && typeof learningContext === 'object') {
+                    try {
+                        const l = learningContext;
+                        const trig = l.triggerCondition && typeof l.triggerCondition === 'object'
+                            ? Object.entries(l.triggerCondition)
+                                .map(([k, v]) => `${k}=${Array.isArray(v) ? v.join('|') : String(v)}`)
+                                .join(' ')
+                            : '∅';
+                        const evidence = (typeof l.sampleSize === 'number' ? `n=${l.sampleSize}` : '') +
+                            (typeof l.effect === 'number' ? ` Δ=${l.effect.toFixed(2)}R` : '') +
+                            (typeof l.pValue === 'number' ? ` p=${l.pValue.toFixed(3)}` : '');
+                        const header = `[Operator is discussing learning id=${l.id} (${l.confidence} · ${l.appliesAt}) ` +
+                            `"${String(l.title ?? '').slice(0, 120)}". ` +
+                            `Directive: ${String(l.directive ?? '').slice(0, 400)} | ` +
+                            `Trigger: ${trig} | Evidence: ${evidence || 'none'}. ` +
+                            `Help them refine: argue for softer/tighter triggers, more specific override ` +
+                            `conditions, or that the pattern no longer holds. You do NOT mutate the ` +
+                            `learning directly — concrete edits flow through the operator's UI.]\n\n`;
+                        augmentedContent = header + augmentedContent;
+                    }
+                    catch (err) {
+                        logger.warn(TAG, `Failed to render learningContext header: ${String(err)}`);
+                    }
+                }
+                logger.info(TAG, `Chat received${proposalContext ? ' (with proposal context)' : ''}${learningContext ? ' (with learning context)' : ''}: "${safeContent.slice(0, 50)}${safeContent.length > 50 ? '...' : ''}"`);
+                const result = await this.provider.handleChat(augmentedContent);
+                this.connector.sendResponse(id, true, result);
+                return;
+            }
+            if (method === 'close_position') {
+                const symbol = params?.symbol ?? '';
+                if (!symbol) {
+                    this.connector.sendResponse(id, false, undefined, { code: 400, message: 'Missing symbol' });
+                    return;
+                }
+                logger.info(TAG, `Close position requested: ${symbol}`);
+                const result = await this.provider.closePosition(symbol);
+                this.connector.sendResponse(id, true, result);
+                return;
+            }
+            if (method === 'set_trading_mode') {
+                const result = await this.handleSetTradingMode(id, params);
+                if (result !== 'responded') {
+                    // Handler returned a structured outcome — forward as success frame.
+                    this.connector.sendResponse(id, true, result);
+                }
+                return;
+            }
+            if (method === 'set_exchange_credentials') {
+                const result = await this.handleSetExchangeCredentials(id, params);
+                if (result !== 'responded') {
+                    this.connector.sendResponse(id, true, result);
+                }
+                return;
+            }
+            if (method === 'test_exchange_credentials') {
+                const result = await this.handleTestExchangeCredentials(id, params);
+                if (result !== 'responded') {
+                    this.connector.sendResponse(id, true, result);
+                }
+                return;
+            }
+            if (method === 'clear_exchange_credentials') {
+                const result = await this.handleClearExchangeCredentials(id);
+                this.connector.sendResponse(id, true, result);
+                return;
+            }
+            if (method === 'get_bracket_config') {
+                if (!this.provider.getBracketConfig) {
+                    this.connector.sendResponse(id, false, undefined, {
+                        code: 501,
+                        message: 'Provider does not support getBracketConfig',
+                    });
+                    return;
+                }
+                const result = await this.provider.getBracketConfig();
+                this.connector.sendResponse(id, true, result);
+                return;
+            }
+            if (method === 'set_bracket_requirement') {
+                const flag = params?.flag;
+                const value = params?.value;
+                if ((flag !== 'requireStopLoss' && flag !== 'requireTakeProfit') || typeof value !== 'boolean') {
+                    this.connector.sendResponse(id, false, undefined, {
+                        code: 400,
+                        message: 'set_bracket_requirement requires { flag: "requireStopLoss"|"requireTakeProfit", value: boolean }',
+                    });
+                    return;
+                }
+                if (!this.provider.setBracketRequirement) {
+                    this.connector.sendResponse(id, false, undefined, {
+                        code: 501,
+                        message: 'Provider does not support setBracketRequirement',
+                    });
+                    return;
+                }
+                logger.info(TAG, `set_bracket_requirement ${flag}=${value}`);
+                const result = await this.provider.setBracketRequirement(flag, value);
+                this.connector.sendResponse(id, true, result);
+                return;
+            }
+            if (method === 'skill.update') {
+                // SECURITY: the frame's content is UNTRUSTED. The relay forwards
+                // browser request frames to the skill, so (on a relay without the
+                // matching browser-side block) any authenticated dashboard session
+                // could forge a `skill.update` req carrying attacker instructions.
+                // Treat the frame as a DOORBELL only: ignore its payload and pull the
+                // authoritative envelope from the relay's Durable-Object store, which
+                // is writable exclusively through the ADMIN_SECRET-gated HTTP push
+                // (party.ts handleSkillPush). A forged frame can therefore at most
+                // trigger (re)application of the legitimately-stored SKILL.md — and
+                // the C1 signature gate inside applySkillUpdate still applies when
+                // enforcement is on.
+                const pushedVersion = typeof params?.version === 'string' ? params.version : 'unknown';
+                logger.info(TAG, `Received SKILL.md OTA update notification (v${pushedVersion}) — pulling authoritative copy from relay store`);
+                let result;
+                try {
+                    result = await this.pullAndApplySkillUpdate();
+                }
+                catch (pullErr) {
+                    this.connector.sendResponse(id, false, undefined, {
+                        code: 502,
+                        message: `Failed to fetch SKILL.md from relay store: ${pullErr instanceof Error ? pullErr.message : String(pullErr)}`,
+                    });
+                    return;
+                }
+                if (!result) {
+                    this.connector.sendResponse(id, false, undefined, {
+                        code: 404,
+                        message: 'No stored SKILL.md on relay — push via the admin HTTP path first',
+                    });
+                    return;
+                }
+                this.connector.sendResponse(id, true, result);
+                return;
+            }
+            // Should not reach here — connector whitelist blocks unknown methods
+            this.connector.sendResponse(id, false, undefined, {
+                code: 400,
+                message: `Unhandled method: ${method}`,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.error(TAG, `Error handling ${method}: ${message}`);
+            this.connector.sendResponse(id, false, undefined, {
+                code: 500,
+                message,
+            });
+        }
+    }
+    handleStateChange(state) {
+        logger.info(TAG, `Connector state: ${state}`);
+    }
+    // ---- Operator onboarding (PR2) ----
+    /** Today every authenticated session carries operator.write via the
+     *  relay-level Clerk token. This method exists as the enforcement seam —
+     *  a future PR can drop per-session roles in here without restructuring
+     *  the dispatcher. Returning true keeps current behavior identical. */
+    hasOperatorWriteScope() {
+        return true;
+    }
+    /** Handle a set_trading_mode request. Returns 'responded' if the handler
+     *  already wrote the response frame (e.g. on validation failure), otherwise
+     *  returns the structured outcome for the caller to wrap in a success
+     *  frame. Ladder validation runs here for fast dashboard feedback and
+     *  again in the plugin (defense in depth). */
+    async handleSetTradingMode(id, params) {
+        const rawMode = params?.mode;
+        const acknowledged = params?.acknowledged === true;
+        if (!isTradingMode(rawMode)) {
+            this.connector.sendResponse(id, false, undefined, {
+                code: 400,
+                message: 'mode must be one of PAPER, MICRO_LIVE, LIVE',
+            });
+            return 'responded';
+        }
+        // Fast skill-side ladder check so the dashboard gets an error without
+        // round-tripping to the plugin. We use the current tradingMode from the
+        // latest snapshot — if we don't have one yet, skip the check and let the
+        // plugin enforce.
+        const currentMode = this.lastKnownTradingMode;
+        if (currentMode) {
+            const ladder = validateModeTransition(currentMode, rawMode);
+            if (!ladder.allowed) {
+                audit('set_trading_mode.rejected', {
+                    id,
+                    from: currentMode,
+                    to: rawMode,
+                    reason: 'ladder',
+                });
+                return {
+                    ok: false,
+                    message: ladder.reason ?? 'Mode transition not allowed',
+                    previousMode: currentMode,
+                    mode: currentMode,
+                    readiness: 'UNKNOWN',
+                    reason: 'ladder',
+                };
+            }
+        }
+        const provider = this.provider;
+        if (!provider.setTradingMode) {
+            return {
+                ok: false,
+                message: 'Provider does not support set_trading_mode (likely mock provider)',
+                previousMode: currentMode ?? 'PAPER',
+                mode: currentMode ?? 'PAPER',
+                readiness: 'UNKNOWN',
+            };
+        }
+        audit('set_trading_mode.start', { id, from: currentMode ?? 'unknown', to: rawMode, acknowledged });
+        const outcome = await provider.setTradingMode(rawMode, acknowledged);
+        audit('set_trading_mode.complete', {
+            id,
+            ok: outcome.ok,
+            previousMode: outcome.previousMode,
+            mode: outcome.mode,
+            reason: outcome.reason,
+        });
+        if (outcome.ok) {
+            this.lastKnownTradingMode = outcome.mode;
+        }
+        return outcome;
+    }
+    /** Handle a set_exchange_credentials request. The secret value passes
+     *  through once and is never cached or logged; only a redacted fingerprint
+     *  appears in the audit trail. */
+    async handleSetExchangeCredentials(id, params) {
+        const apiKey = typeof params?.apiKey === 'string' ? params.apiKey : '';
+        const secret = typeof params?.secret === 'string' ? params.secret : '';
+        const testnet = params?.testnet === true;
+        if (apiKey.length < 8 || secret.length < 8) {
+            this.connector.sendResponse(id, false, undefined, {
+                code: 400,
+                message: 'apiKey and secret must be at least 8 characters each',
+            });
+            return 'responded';
+        }
+        const fp = fingerprint(apiKey);
+        const provider = this.provider;
+        if (!provider.setExchangeCredentials) {
+            return {
+                ok: false,
+                message: 'Provider does not support set_exchange_credentials (likely mock provider)',
+                fingerprint: fp,
+                reconnected: false,
+                mode: this.lastKnownTradingMode ?? 'PAPER',
+                readiness: 'UNKNOWN',
+            };
+        }
+        audit('set_exchange_credentials.start', { id, fingerprint: fp, testnet });
+        const outcome = await provider.setExchangeCredentials(apiKey, secret, testnet);
+        audit('set_exchange_credentials.complete', {
+            id,
+            ok: outcome.ok,
+            fingerprint: outcome.fingerprint,
+            reconnected: outcome.reconnected,
+            mode: outcome.mode,
+        });
+        return outcome;
+    }
+    /** Handle a test_exchange_credentials request — transient read-only
+     *  verification, nothing persisted. Same input validation + secret
+     *  redaction rules as set_exchange_credentials. */
+    async handleTestExchangeCredentials(id, params) {
+        const apiKey = typeof params?.apiKey === 'string' ? params.apiKey : '';
+        const secret = typeof params?.secret === 'string' ? params.secret : '';
+        const testnet = params?.testnet === true;
+        if (apiKey.length < 8 || secret.length < 8) {
+            this.connector.sendResponse(id, false, undefined, {
+                code: 400,
+                message: 'apiKey and secret must be at least 8 characters each',
+            });
+            return 'responded';
+        }
+        const fp = fingerprint(apiKey);
+        const provider = this.provider;
+        if (!provider.testExchangeCredentials) {
+            return {
+                ok: false,
+                message: 'Provider does not support test_exchange_credentials (likely mock provider)',
+                fingerprint: fp,
+                canReadBalance: false,
+                canReadPositions: false,
+                balanceUSDT: null,
+                testnet,
+                errors: ['provider-unsupported'],
+            };
+        }
+        audit('test_exchange_credentials.start', { id, fingerprint: fp, testnet });
+        const outcome = await provider.testExchangeCredentials(apiKey, secret, testnet);
+        audit('test_exchange_credentials.complete', {
+            id,
+            ok: outcome.ok,
+            fingerprint: outcome.fingerprint,
+            canReadBalance: outcome.canReadBalance,
+            canReadPositions: outcome.canReadPositions,
+            balanceUSDT: outcome.balanceUSDT,
+        });
+        return outcome;
+    }
+    /** Handle a clear_exchange_credentials request. No input — the method
+     *  itself is the "yes I want this" signal; the webapp is expected to
+     *  gate this behind a confirmation dialog before calling. */
+    async handleClearExchangeCredentials(id) {
+        const provider = this.provider;
+        if (!provider.clearExchangeCredentials) {
+            return {
+                ok: false,
+                message: 'Provider does not support clear_exchange_credentials (likely mock provider)',
+                modeBefore: this.lastKnownTradingMode ?? 'PAPER',
+                mode: this.lastKnownTradingMode ?? 'PAPER',
+                rolledBackToPaper: false,
+                readiness: 'UNKNOWN',
+            };
+        }
+        audit('clear_exchange_credentials.start', { id });
+        const outcome = await provider.clearExchangeCredentials();
+        audit('clear_exchange_credentials.complete', {
+            id,
+            ok: outcome.ok,
+            modeBefore: outcome.modeBefore,
+            mode: outcome.mode,
+            rolledBackToPaper: outcome.rolledBackToPaper,
+        });
+        if (outcome.ok && outcome.rolledBackToPaper) {
+            this.lastKnownTradingMode = 'PAPER';
+        }
+        return outcome;
+    }
+    // ---- OTA SKILL.md update ----
+    /** Apply a SKILL.md update: verify signature (C1), write to workspace +
+     *  installed skill dir, clear session cache, notify agent. */
+    async applySkillUpdate(env) {
+        const { version, content } = env;
+        const workspacePath = join(homedir(), '.openclaw', 'workspace');
+        const skillMdPath = join(workspacePath, 'SKILL.md');
+        const tempPath = join(workspacePath, 'SKILL.md.tmp');
+        const sessionsJsonPath = join(homedir(), '.openclaw', 'agents', 'main', 'sessions', 'sessions.json');
+        // True only when the Ed25519 signature was actually checked AND passed —
+        // gates the replay-clock write below. An update applied UNVERIFIED
+        // (enforcement off) must never advance the clock: an unsigned push with a
+        // far-future signedAt would otherwise brick every future legitimately-
+        // signed update as "replay".
+        let signatureVerified = false;
+        try {
+            // 0. SIGNATURE GATE (C1) — verify BEFORE touching disk. The relay is a
+            //    dumb transport: only a payload signed by the operator's offline key
+            //    is applied. Fail closed when enforced.
+            if (signatureRequired()) {
+                const verdict = verifySkillSignature(env);
+                if (!verdict.ok) {
+                    logger.error(TAG, `OTA SKILL.md REJECTED (signature): ${verdict.reason}`);
+                    return { success: false, version, message: `signature rejected: ${verdict.reason}` };
+                }
+                // Replay/rollback guard: only accept a strictly newer signed artifact.
+                const sigMs = new Date(env.signedAt).getTime();
+                if (!(sigMs > readLastAppliedSignedAtMs())) {
+                    logger.error(TAG, `OTA SKILL.md REJECTED (replay): signedAt ${env.signedAt} not newer than last applied`);
+                    return { success: false, version, message: 'signature rejected: replay (stale signedAt)' };
+                }
+                signatureVerified = true;
+            }
+            else if (!env.signature) {
+                // C1 (signed OTA) is ON HOLD → verification off by default, so OTA works
+                // unsigned as before. To enforce: pin a key + SKILL_OTA_REQUIRE_SIGNATURE=on.
+                logger.warn(TAG, 'OTA SKILL.md applied WITHOUT signature verification — signed-OTA (C1) is disabled');
+            }
+            // 1. Validate content
+            const validation = validateSkillContent(content);
+            if (!validation.valid) {
+                return { success: false, version, message: `Invalid SKILL.md: ${validation.error}` };
+            }
+            // 2. Atomic write: temp file → rename (workspace copy)
+            mkdirSync(workspacePath, { recursive: true });
+            writeFileSync(tempPath, content, 'utf-8');
+            renameSync(tempPath, skillMdPath);
+            // 2b. Also write to the installed skill directory — this is what OpenClaw's
+            // skill system actually reads for agent instructions (not the workspace copy).
+            // Scan ~/.openclaw/skills/ for any reefclaw-related skill directories.
+            const skillsDir = join(homedir(), '.openclaw', 'skills');
+            if (existsSync(skillsDir)) {
+                try {
+                    const entries = readdirSync(skillsDir, { withFileTypes: true });
+                    for (const entry of entries) {
+                        if (entry.isDirectory() && entry.name.includes('reefclaw')) {
+                            const installedSkillMd = join(skillsDir, entry.name, 'SKILL.md');
+                            writeFileSync(installedSkillMd, content, 'utf-8');
+                            logger.info(TAG, `Updated installed skill SKILL.md: ${installedSkillMd}`);
+                        }
+                    }
+                }
+                catch (scanErr) {
+                    logger.warn(TAG, `Failed to update installed skill SKILL.md: ${scanErr instanceof Error ? scanErr.message : String(scanErr)}`);
+                }
+            }
+            // 2c. Also write to workspace/skills/ subdirectory if it exists
+            const wsSkillsDir = join(workspacePath, 'skills');
+            if (existsSync(wsSkillsDir)) {
+                try {
+                    const entries = readdirSync(wsSkillsDir, { withFileTypes: true });
+                    for (const entry of entries) {
+                        if (entry.isDirectory() && entry.name.includes('reefclaw')) {
+                            const wsSkillMd = join(wsSkillsDir, entry.name, 'SKILL.md');
+                            writeFileSync(wsSkillMd, content, 'utf-8');
+                            logger.info(TAG, `Updated workspace skill SKILL.md: ${wsSkillMd}`);
+                        }
+                    }
+                }
+                catch (scanErr) {
+                    logger.warn(TAG, `Failed to update workspace skill SKILL.md: ${scanErr instanceof Error ? scanErr.message : String(scanErr)}`);
+                }
+            }
+            // 3. Invalidate skillsSnapshot cache WITHOUT wiping sessions.json
+            // Previously we wrote '{}' to sessions.json which destroyed OpenClaw chat history.
+            // Now we surgically remove only the skillsSnapshot key from each session entry,
+            // preserving the session pointer and chat history.
+            if (existsSync(sessionsJsonPath)) {
+                try {
+                    const raw = readFileSync(sessionsJsonPath, 'utf-8');
+                    const sessions = JSON.parse(raw);
+                    let patched = false;
+                    for (const key of Object.keys(sessions)) {
+                        const entry = sessions[key];
+                        if (entry && typeof entry === 'object' && 'skillsSnapshot' in entry) {
+                            delete entry.skillsSnapshot;
+                            patched = true;
+                        }
+                    }
+                    if (patched) {
+                        writeFileSync(sessionsJsonPath, JSON.stringify(sessions, null, 2), 'utf-8');
+                        logger.info(TAG, 'Removed skillsSnapshot from sessions.json — agent will re-read SKILL.md (chat history preserved)');
+                    }
+                    else {
+                        logger.info(TAG, 'No skillsSnapshot found in sessions.json — nothing to invalidate');
+                    }
+                }
+                catch (parseErr) {
+                    // If sessions.json is corrupted or unparseable, fall back to resetting it
+                    logger.warn(TAG, `Failed to patch sessions.json, resetting: ${parseErr instanceof Error ? parseErr.message : String(parseErr)}`);
+                    writeFileSync(sessionsJsonPath, '{}', 'utf-8');
+                }
+            }
+            // 4. Send chat message to agent to trigger immediate re-read
+            try {
+                await this.provider.handleChat(`Your trading instructions (SKILL.md) have been updated to v${version}. ` +
+                    `Check for any open positions with fetch_positions() and fetch_open_orders(), then re-read SKILL.md to confirm you've processed the changes.`);
+            }
+            catch (chatErr) {
+                logger.warn(TAG, `Chat notification failed (non-fatal): ${chatErr instanceof Error ? chatErr.message : String(chatErr)}`);
+            }
+            // 5. Update local version tracker + advance the replay clock. The clock
+            // advances ONLY on a VERIFIED signature: recording an unverified
+            // signedAt (enforcement off) would let an unsigned push with a
+            // far-future timestamp poison the clock and reject all future
+            // legitimately-signed updates as replays.
+            this.currentSkillVersion = version;
+            if (signatureVerified && env.signedAt)
+                recordAppliedSignedAt(env.signedAt);
+            logger.info(TAG, `SKILL.md updated to v${version} successfully`);
+            return { success: true, version, message: `Updated to v${version}` };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.error(TAG, `Failed to apply SKILL.md update: ${message}`);
+            try {
+                unlinkSync(tempPath);
+            }
+            catch { /* ignore cleanup failure */ }
+            return { success: false, version, message };
+        }
+    }
+    /**
+     * Fetch the stored SKILL.md envelope from the relay's Durable-Object store
+     * and apply it. The DO store is writable exclusively through the
+     * ADMIN_SECRET-gated HTTP push (party.ts handleSkillPush) — pulling makes
+     * the STORE, not any WS frame, the trust anchor for OTA content. Refuses to
+     * downgrade below the local version (a stale relay copy must never clobber
+     * a newer local SKILL.md — prod incident 2026-05-13); an equal version
+     * re-applies (idempotent repair for a re-push). Returns null when the relay
+     * has nothing stored; throws on transport error.
+     */
+    async pullAndApplySkillUpdate() {
+        const result = await this.connector.sendRequest('skill.request_update', {});
+        if (!result?.content)
+            return null;
+        // Re-read local version (may have changed since startup) + downgrade guard.
+        this.currentSkillVersion = readLocalSkillVersion();
+        if (compareSemver(result.version, this.currentSkillVersion) < 0) {
+            const message = `refusing downgrade: relay v${result.version} is older than local v${this.currentSkillVersion ?? 'unknown'}`;
+            logger.warn(TAG, `SKILL.md pull: ${message}`);
+            return { success: false, version: result.version, message };
+        }
+        const updateResult = await this.applySkillUpdate({
+            version: result.version,
+            content: result.content,
+            contentSha256: result.contentSha256,
+            signedAt: result.signedAt,
+            signature: result.signature,
+        });
+        // Confirmation event to the dashboard — the operator pushed something and
+        // should see the outcome either way (relay audits skill_update_applied).
+        this.emit('agent_state', 'skill_update_applied', {
+            event: 'skill_update_applied',
+            version: result.version,
+            success: updateResult.success,
+            timestamp: new Date().toISOString(),
+        });
+        return updateResult;
+    }
+    /** Check relay's latest SKILL.md version against local and auto-update if stale */
+    async handleConnectAck(payload) {
+        const latestVersion = payload.latestSkillVersion;
+        if (!latestVersion)
+            return;
+        // Re-read local version (may have changed since startup)
+        this.currentSkillVersion = readLocalSkillVersion();
+        const cmp = compareSemver(latestVersion, this.currentSkillVersion);
+        if (cmp === 0) {
+            logger.debug(TAG, `SKILL.md up to date (v${latestVersion})`);
+            return;
+        }
+        if (cmp < 0) {
+            // Local is AHEAD of relay. Never downgrade: a stale relay copy must not
+            // clobber a freshly SFTP'd or hand-edited SKILL.md. (Prod incident
+            // 2026-05-13: relay was at v2.14 but local was v2.15; the old `===`
+            // check treated "not equal" as "behind" and silently downgraded to
+            // whatever the relay delivered — which was v2.11.) Log loudly so it's
+            // obvious the relay needs a push.
+            logger.warn(TAG, `Relay SKILL.md v${latestVersion} is OLDER than local v${this.currentSkillVersion ?? 'unknown'} — refusing to downgrade. Push current SKILL.md to relay to clear this warning.`);
+            return;
+        }
+        logger.info(TAG, `Local SKILL.md v${this.currentSkillVersion ?? 'unknown'} behind relay v${latestVersion} — requesting update`);
+        try {
+            await this.pullAndApplySkillUpdate();
+        }
+        catch (err) {
+            logger.warn(TAG, `Failed to fetch SKILL.md update from relay: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const VALID_GAPFILL_CHANNELS = [
+    'market_data',
+    'trade_events',
+    'agent_state',
+    'chat',
+];
+/**
+ * Parse the `lastSequences` array from a reconcile request into a per-channel
+ * map. Defaults to `-1` (i.e. "send everything you have") for any channel the
+ * client didn't include or that has a malformed entry. Hostile / malformed
+ * input is silently ignored — the gapFill replay is read-only and bounded by
+ * the buffer's age cap, so worst case is a slightly larger response.
+ */
+function parseLastSequences(params) {
+    const empty = {};
+    for (const ch of VALID_GAPFILL_CHANNELS)
+        empty[ch] = -1;
+    if (!params || typeof params !== 'object')
+        return empty;
+    const ls = params.lastSequences;
+    if (!Array.isArray(ls))
+        return empty;
+    const out = { ...empty };
+    for (const item of ls) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const obj = item;
+        if (typeof obj.channel === 'string' &&
+            VALID_GAPFILL_CHANNELS.includes(obj.channel) &&
+            typeof obj.lastSeq === 'number' &&
+            Number.isFinite(obj.lastSeq)) {
+            out[obj.channel] = obj.lastSeq;
+        }
+    }
+    return out;
+}