@reefclaw/openclaw-plugin 0.1.0

package/bridge/config.d.ts

@@ -0,0 +1,43 @@
+export interface ResolvedConfig {
+    token: string;
+    userId: string;
+    relayUrl: string;
+}
+/** Read the OpenClaw config file and extract ReefClaw skill settings.
+ *  Prefers the schema-valid nested shape (entry.config.*), falls back to the
+ *  legacy flat shape per-field. */
+export declare function readOpenClawConfig(): {
+    token?: string;
+    userId?: string;
+    relayUrl?: string;
+} | null;
+/** Write/merge token (and optional fields) into OpenClaw config */
+export declare function writeOpenClawConfig(token: string, userId?: string, relayUrl?: string): void;
+/**
+ * Check and fix gateway scope config on startup. Runs once — reads openclaw.json,
+ * applies missing settings if needed, writes back. No-op if already correct.
+ */
+export declare function ensureGatewayScopeConfigOnStartup(): void;
+export interface CliArgs {
+    provider: 'mock' | 'gateway';
+    token?: string;
+    userId?: string;
+    relayUrl?: string;
+    logLevel?: string;
+    setup?: boolean | string;
+}
+/**
+ * Resolve config with priority:
+ * 1. CLI args (--token, --user-id, --relay-url)
+ * 2. Environment variables (REEFCLAW_TOKEN, REEFCLAW_USER_ID, REEFCLAW_RELAY_URL)
+ * 3. OpenClaw config file (~/.openclaw/openclaw.json)
+ * 4. Fallback env vars (MOCK_TOKEN, USER_ID)
+ * 5. Defaults (relay URL)
+ *
+ * Returns null fields if token/userId can't be resolved.
+ */
+export declare function resolveConfig(args: CliArgs): {
+    token: string | null;
+    userId: string | null;
+    relayUrl: string;
+};

package/bridge/config.js

@@ -0,0 +1,176 @@
+// Config reader/writer for OpenClaw skill configuration.
+// Reads/writes token to ~/.openclaw/openclaw.json under skills.entries.reefclaw.
+// Provides unified config resolution: CLI args > env vars > OpenClaw config > fallback env > defaults.
+import { readFileSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import JSON5 from 'json5';
+import { logger } from './logger.js';
+const TAG = 'config';
+const OPENCLAW_DIR = join(homedir(), '.openclaw');
+const CONFIG_PATH = join(OPENCLAW_DIR, 'openclaw.json');
+const DEFAULT_RELAY_URL = 'wss://reefclaw.radunlupsa.partykit.dev';
+// ---- Read/write OpenClaw config ----
+/** Read the OpenClaw config file and extract ReefClaw skill settings.
+ *  Prefers the schema-valid nested shape (entry.config.*), falls back to the
+ *  legacy flat shape per-field. */
+export function readOpenClawConfig() {
+    try {
+        const raw = readFileSync(CONFIG_PATH, 'utf-8');
+        const config = JSON5.parse(raw);
+        const reefclaw = config?.skills?.entries?.reefclaw;
+        if (reefclaw) {
+            logger.debug(TAG, `Read config from ${CONFIG_PATH}`);
+            return {
+                token: reefclaw.config?.token ?? reefclaw.token,
+                userId: reefclaw.config?.userId ?? reefclaw.userId,
+                relayUrl: reefclaw.config?.relayUrl ?? reefclaw.relayUrl,
+            };
+        }
+        return null;
+    }
+    catch {
+        // File doesn't exist or isn't valid JSON
+        return null;
+    }
+}
+/** Write/merge token (and optional fields) into OpenClaw config */
+export function writeOpenClawConfig(token, userId, relayUrl) {
+    let config = {};
+    // Read existing config to merge
+    try {
+        const raw = readFileSync(CONFIG_PATH, 'utf-8');
+        config = JSON5.parse(raw);
+    }
+    catch {
+        // Start fresh
+    }
+    // Ensure nested structure
+    if (!config.skills)
+        config.skills = {};
+    if (!config.skills.entries)
+        config.skills.entries = {};
+    if (!config.skills.entries.reefclaw)
+        config.skills.entries.reefclaw = {};
+    const entry = config.skills.entries.reefclaw;
+    // Write the schema-valid nested shape and migrate any legacy flat keys away
+    // — flat keys fail OpenClaw config validation (2026.6+) and crash the
+    // gateway on its next restart.
+    if (!entry.config)
+        entry.config = {};
+    entry.config.token = token;
+    if (userId)
+        entry.config.userId = userId;
+    if (relayUrl)
+        entry.config.relayUrl = relayUrl;
+    delete entry.token;
+    delete entry.userId;
+    delete entry.relayUrl;
+    // Ensure gateway.controlUi settings for OpenClaw v2026.4.2+ scope compatibility.
+    // Without these, the skill's WS connection gets scopes cleared (missing scope: operator.write).
+    ensureGatewayScopeConfig(config);
+    // Write — file holds the connection token, so restrict to owner.
+    mkdirSync(OPENCLAW_DIR, { recursive: true, mode: 0o700 });
+    writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+    // writeFileSync's `mode` only applies when it CREATES the file; on an
+    // existing openclaw.json (the common case) the old — possibly world-readable
+    // — permissions survive. chmod every time so a token-bearing config is never
+    // left group/world-readable. Best-effort (no-op / unsupported on some FS).
+    restrictConfigPermissions();
+    logger.info(TAG, `Saved config to ${CONFIG_PATH}`);
+}
+/** Force owner-only (0600) perms on the config file. `writeFileSync`'s mode
+ *  option is ignored when the file already exists, so this must run after
+ *  every write to keep the token-bearing config from lingering world-readable.
+ *  Best-effort — never throws (chmod is a no-op on some Windows filesystems). */
+function restrictConfigPermissions() {
+    try {
+        chmodSync(CONFIG_PATH, 0o600);
+    }
+    catch (err) {
+        logger.debug(TAG, `Could not chmod ${CONFIG_PATH} to 0600: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+// ---- Gateway scope compatibility (OpenClaw v2026.4.2+) ----
+/**
+ * Ensure gateway.controlUi has the required settings for WS scope preservation.
+ * Without these, OpenClaw v2026.4.2+ clears operator.write scopes on connections
+ * without device identity, breaking mission presentation and chat RPCs.
+ */
+function ensureGatewayScopeConfig(config) {
+    if (!config.gateway)
+        config.gateway = {};
+    const gw = config.gateway;
+    if (!gw.controlUi)
+        gw.controlUi = {};
+    const cui = gw.controlUi;
+    let changed = false;
+    if (cui.dangerouslyDisableDeviceAuth !== true) {
+        cui.dangerouslyDisableDeviceAuth = true;
+        changed = true;
+    }
+    if (cui.allowInsecureAuth !== true) {
+        cui.allowInsecureAuth = true;
+        changed = true;
+    }
+    // Write-once: only flip (and disclose) when a flag was absent/false, so the
+    // security-relevant downgrade is announced the one time it actually happens,
+    // never on every boot. These flags relax the local gateway's device-identity
+    // auth (required for OpenClaw v2026.4.2+ WS scope preservation) — the
+    // operator should know they were set.
+    if (changed) {
+        logger.warn(TAG, 'Enabled gateway.controlUi.{dangerouslyDisableDeviceAuth,allowInsecureAuth} — this relaxes local gateway device-identity auth (needed for OpenClaw v2026.4.2+ WS scope preservation). Keep the gateway bound to localhost.');
+    }
+    return changed;
+}
+/**
+ * Check and fix gateway scope config on startup. Runs once — reads openclaw.json,
+ * applies missing settings if needed, writes back. No-op if already correct.
+ */
+export function ensureGatewayScopeConfigOnStartup() {
+    try {
+        const raw = readFileSync(CONFIG_PATH, 'utf-8');
+        const config = JSON5.parse(raw);
+        if (ensureGatewayScopeConfig(config)) {
+            writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+            restrictConfigPermissions(); // mode above is ignored on an existing file
+            logger.info(TAG, 'Applied gateway scope config for OpenClaw v2026.4.2+ compatibility');
+        }
+    }
+    catch {
+        // Config doesn't exist or can't be parsed — skip (setup hasn't run yet)
+    }
+}
+/**
+ * Resolve config with priority:
+ * 1. CLI args (--token, --user-id, --relay-url)
+ * 2. Environment variables (REEFCLAW_TOKEN, REEFCLAW_USER_ID, REEFCLAW_RELAY_URL)
+ * 3. OpenClaw config file (~/.openclaw/openclaw.json)
+ * 4. Fallback env vars (MOCK_TOKEN, USER_ID)
+ * 5. Defaults (relay URL)
+ *
+ * Returns null fields if token/userId can't be resolved.
+ */
+export function resolveConfig(args) {
+    // Read OpenClaw config
+    const savedConfig = readOpenClawConfig();
+    const token = args.token
+        || process.env.REEFCLAW_TOKEN
+        || savedConfig?.token
+        || process.env.MOCK_TOKEN
+        || null;
+    const userId = args.userId
+        || process.env.REEFCLAW_USER_ID
+        || savedConfig?.userId
+        || process.env.USER_ID
+        || null;
+    const relayUrl = args.relayUrl
+        || process.env.REEFCLAW_RELAY_URL
+        || savedConfig?.relayUrl
+        || process.env.RELAY_URL
+        || DEFAULT_RELAY_URL;
+    if (savedConfig?.token && !args.token && !process.env.REEFCLAW_TOKEN) {
+        logger.info(TAG, 'Using token from OpenClaw config');
+    }
+    return { token, userId, relayUrl };
+}

package/bridge/connector.d.ts

@@ -0,0 +1,52 @@
+import type { ConnectorConfig, RequestFrame, Frame } from './types.js';
+export type ConnectorState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'failed';
+export interface ConnectorCallbacks {
+    /** Called when a request frame arrives from the relay (browser command) */
+    onRequest: (frame: RequestFrame) => void;
+    /** Called when connection state changes */
+    onStateChange: (state: ConnectorState) => void;
+    /** Called when the relay sends a connection ACK with metadata */
+    onConnectAck?: (payload: Record<string, unknown>) => void;
+}
+export declare class Connector {
+    private readonly config;
+    private readonly callbacks;
+    private ws;
+    private state;
+    private attempt;
+    private reconnectTimer;
+    private pendingRequests;
+    private readonly reconnectConfig;
+    private readonly heartbeatConfig;
+    private heartbeatTimer;
+    private lastMessageAt;
+    private destroyed;
+    constructor(config: ConnectorConfig, callbacks: ConnectorCallbacks);
+    /** Build the relay WebSocket URL (token is sent via Authorization header, not URL) */
+    private buildUrl;
+    /** Start connecting to the relay */
+    connect(): void;
+    /** Send an event frame to the relay (provider → relay → browser) */
+    sendEvent(frame: Frame): void;
+    /** Send a response frame to the relay (answering a browser request) */
+    sendResponse(id: string, ok: boolean, payload?: unknown, error?: {
+        code: number;
+        message: string;
+    }): void;
+    /** Send a request and wait for a response (e.g. reconcile request originated by skill) */
+    sendRequest(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /** Check if currently connected */
+    isConnected(): boolean;
+    /** Get current state */
+    getState(): ConnectorState;
+    /** Gracefully disconnect and clean up */
+    destroy(): void;
+    private handleMessage;
+    private scheduleReconnect;
+    private setState;
+    private rejectAllPending;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private clearReconnectTimer;
+    private forceReconnect;
+}

package/bridge/connector.js

@@ -0,0 +1,293 @@
+// WebSocket client that connects to the ReefClaw relay server.
+// Handles reconnection with exponential backoff, command whitelist,
+// and pending request tracking.
+import WebSocket from 'ws';
+import { logger } from './logger.js';
+import { computeDelay } from './utils/reconnect.js';
+import { ALLOWED_METHODS as METHODS_LIST, FATAL_CLOSE_CODES, } from './types.js';
+const TAG = 'connector';
+const DEFAULT_HEARTBEAT = {
+    intervalMs: 30_000, // 30s — less aggressive than browser (15s) since skill runs on a stable server
+    timeoutMs: 10_000, // 10s — generous for server-to-edge latency
+};
+const DEFAULT_RECONNECT = {
+    baseDelayMs: 1000,
+    maxDelayMs: 30_000,
+    maxFastAttempts: 10,
+    jitterFactor: 0.3,
+    slowRetryMs: 60_000,
+};
+const REQUEST_TIMEOUT_MS = 15_000;
+export class Connector {
+    config;
+    callbacks;
+    ws = null;
+    state = 'disconnected';
+    attempt = 0;
+    reconnectTimer = null;
+    pendingRequests = new Map();
+    reconnectConfig;
+    heartbeatConfig;
+    heartbeatTimer = null;
+    lastMessageAt = 0;
+    destroyed = false;
+    constructor(config, callbacks) {
+        this.config = config;
+        this.callbacks = callbacks;
+        this.reconnectConfig = { ...DEFAULT_RECONNECT, ...config.reconnect };
+        this.heartbeatConfig = { ...DEFAULT_HEARTBEAT };
+    }
+    /** Build the relay WebSocket URL (token is sent via Authorization header, not URL) */
+    buildUrl() {
+        const base = this.config.relayUrl.replace(/\/$/, '');
+        return `${base}/parties/reefclaw/${this.config.userId}`;
+    }
+    /** Start connecting to the relay */
+    connect() {
+        if (this.destroyed)
+            return;
+        // Guard against concurrent connect calls (e.g. forceReconnect + pending timer)
+        if (this.state === 'connecting' || this.state === 'connected')
+            return;
+        this.clearReconnectTimer();
+        this.setState(this.attempt === 0 ? 'connecting' : 'reconnecting');
+        const url = this.buildUrl();
+        logger.info(TAG, `Connecting to relay (attempt ${this.attempt + 1})`, { url });
+        // Token in Authorization header — keeps long-lived rc_* secret out of edge/proxy/access logs
+        // that capture full request URIs. Browsers can't set headers on WebSocket, so the browser
+        // path stays on ?jwt= (short-lived Clerk JWT, auto-rotated).
+        const ws = new WebSocket(url, {
+            headers: {
+                Authorization: `Bearer ${this.config.token}`,
+            },
+        });
+        this.ws = ws;
+        ws.on('open', () => {
+            logger.info(TAG, 'WebSocket open, awaiting auth ack');
+        });
+        ws.on('message', (data) => {
+            this.handleMessage(data);
+        });
+        ws.on('pong', () => {
+            this.lastMessageAt = Date.now();
+        });
+        ws.on('close', (code, reason) => {
+            logger.info(TAG, `WebSocket closed: ${code} ${reason.toString()}`);
+            this.ws = null;
+            this.stopHeartbeat();
+            this.rejectAllPending('Connection closed');
+            if (this.destroyed)
+                return;
+            // Fatal codes: do not reconnect
+            if (FATAL_CLOSE_CODES.includes(code)) {
+                logger.error(TAG, `Fatal close code ${code} — not reconnecting`);
+                this.setState('failed');
+                return;
+            }
+            // 4002 = stale skill connection on relay. Wait for it to time out, then retry.
+            if (code === 4002) {
+                logger.warn(TAG, 'Stale skill connection on relay — waiting 10s before retry');
+                this.setState('reconnecting');
+                this.reconnectTimer = setTimeout(() => {
+                    this.reconnectTimer = null;
+                    this.connect();
+                }, 10_000);
+                return;
+            }
+            this.scheduleReconnect();
+        });
+        ws.on('error', (err) => {
+            logger.error(TAG, `WebSocket error: ${err.message}`);
+        });
+    }
+    /** Send an event frame to the relay (provider → relay → browser) */
+    sendEvent(frame) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        this.ws.send(JSON.stringify(frame));
+    }
+    /** Send a response frame to the relay (answering a browser request) */
+    sendResponse(id, ok, payload, error) {
+        const frame = { type: 'res', id, ok, ...(payload !== undefined && { payload }), ...(error && { error }) };
+        this.sendEvent(frame);
+    }
+    /** Send a request and wait for a response (e.g. reconcile request originated by skill) */
+    sendRequest(method, params) {
+        return new Promise((resolve, reject) => {
+            const id = `skill-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            const frame = { type: 'req', id, method, ...(params && { params }) };
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new Error(`Request ${method} timed out`));
+            }, REQUEST_TIMEOUT_MS);
+            this.pendingRequests.set(id, { resolve, reject, timer });
+            this.sendEvent(frame);
+        });
+    }
+    /** Check if currently connected */
+    isConnected() {
+        return this.state === 'connected';
+    }
+    /** Get current state */
+    getState() {
+        return this.state;
+    }
+    /** Gracefully disconnect and clean up */
+    destroy() {
+        this.destroyed = true;
+        this.stopHeartbeat();
+        this.clearReconnectTimer();
+        this.rejectAllPending('Connector destroyed');
+        if (this.ws) {
+            this.ws.close(1000, 'Skill shutting down');
+            this.ws = null;
+        }
+        this.setState('disconnected');
+    }
+    // ---- Private ----
+    handleMessage(data) {
+        // Any message from relay proves the connection is alive
+        this.lastMessageAt = Date.now();
+        let frame;
+        try {
+            frame = JSON.parse(data.toString());
+        }
+        catch {
+            logger.warn(TAG, 'Received unparseable message');
+            return;
+        }
+        if (frame.type === 'res') {
+            // Connection ack
+            if (frame.id === '_connect' && frame.ok) {
+                logger.info(TAG, 'Authenticated with relay', frame.payload);
+                this.attempt = 0;
+                this.setState('connected');
+                this.startHeartbeat();
+                if (this.callbacks.onConnectAck && frame.payload && typeof frame.payload === 'object') {
+                    this.callbacks.onConnectAck(frame.payload);
+                }
+                return;
+            }
+            // Rate limit / error from relay
+            if (frame.id.startsWith('_')) {
+                if (!frame.ok) {
+                    const errMsg = frame.error?.message ?? 'unknown';
+                    if (frame.error?.code === 429) {
+                        logger.warn(TAG, `Rate limited by relay — non-chat events being dropped. Consider reducing market data frequency.`);
+                    }
+                    else {
+                        logger.warn(TAG, `Relay error: ${errMsg}`);
+                    }
+                }
+                return;
+            }
+            // Response to a pending request
+            const pending = this.pendingRequests.get(frame.id);
+            if (pending) {
+                clearTimeout(pending.timer);
+                this.pendingRequests.delete(frame.id);
+                if (frame.ok) {
+                    pending.resolve(frame.payload);
+                }
+                else {
+                    pending.reject(new Error(frame.error?.message ?? 'Request failed'));
+                }
+            }
+            return;
+        }
+        if (frame.type === 'req') {
+            // Validate against command whitelist
+            if (!METHODS_LIST.includes(frame.method)) {
+                logger.warn(TAG, `Unknown method: ${frame.method}`);
+                this.sendResponse(frame.id, false, undefined, {
+                    code: 400,
+                    message: `Unknown method: ${frame.method}`,
+                });
+                return;
+            }
+            this.callbacks.onRequest(frame);
+            return;
+        }
+        // Event frames from relay — unexpected for a skill connection, but log
+        if (frame.type === 'event') {
+            logger.debug(TAG, `Received event (unexpected for skill): ${frame.event}`);
+        }
+    }
+    scheduleReconnect() {
+        this.attempt++;
+        let delay;
+        if (this.attempt <= this.reconnectConfig.maxFastAttempts) {
+            // Fast phase: exponential backoff
+            delay = computeDelay(this.attempt - 1, this.reconnectConfig);
+            logger.info(TAG, `Reconnecting in ${Math.round(delay)}ms (attempt ${this.attempt}/${this.reconnectConfig.maxFastAttempts})`);
+        }
+        else {
+            // Slow phase: fixed interval, never give up
+            delay = this.reconnectConfig.slowRetryMs;
+            logger.info(TAG, `Slow retry in ${Math.round(delay)}ms (attempt ${this.attempt})`);
+        }
+        this.setState('reconnecting');
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delay);
+    }
+    setState(newState) {
+        if (this.state === newState)
+            return;
+        const prev = this.state;
+        this.state = newState;
+        logger.debug(TAG, `State: ${prev} → ${newState}`);
+        this.callbacks.onStateChange(newState);
+    }
+    rejectAllPending(reason) {
+        for (const [id, pending] of this.pendingRequests) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error(reason));
+        }
+        this.pendingRequests.clear();
+    }
+    // ---- Heartbeat ----
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.lastMessageAt = Date.now();
+        this.heartbeatTimer = setInterval(() => {
+            const silence = Date.now() - this.lastMessageAt;
+            if (silence > this.heartbeatConfig.intervalMs + this.heartbeatConfig.timeoutMs) {
+                // No message received for interval + timeout — connection is dead
+                logger.error(TAG, `Heartbeat timeout: no relay message for ${Math.round(silence / 1000)}s — forcing reconnect`);
+                this.stopHeartbeat();
+                this.forceReconnect();
+                return;
+            }
+            // Send a native WebSocket ping (protocol-level, handled by PartyKit automatically).
+            if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+                this.ws.ping();
+            }
+        }, this.heartbeatConfig.intervalMs);
+        logger.debug(TAG, `Heartbeat started: interval=${this.heartbeatConfig.intervalMs}ms timeout=${this.heartbeatConfig.timeoutMs}ms`);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    clearReconnectTimer() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    forceReconnect() {
+        if (this.ws) {
+            this.ws.removeAllListeners();
+            this.ws.close(1000, 'Heartbeat timeout');
+            this.ws = null;
+        }
+        this.rejectAllPending('Heartbeat timeout');
+        this.setState('disconnected');
+        this.clearReconnectTimer();
+        this.scheduleReconnect();
+    }
+}

package/bridge/event-replay-buffer.d.ts

@@ -0,0 +1,43 @@
+import type { Channel } from './types.js';
+export interface BufferedEvent {
+    channel: Channel;
+    event: string;
+    payload: unknown;
+    seq: number;
+    /** Wall-clock millis when the frame was recorded. Used for age eviction
+     *  and for cross-channel ordering when replayed in gapFill. */
+    timestamp: number;
+}
+export interface EventReplayBufferOptions {
+    /** Per-channel max events. Older entries dropped when capacity hit. */
+    perChannelCapacity?: number;
+    /** Per-channel max age (ms). Older entries dropped on append AND on `since`. */
+    maxAgeMs?: number;
+    /** Test-only injected clock. */
+    now?: () => number;
+}
+export declare class EventReplayBuffer {
+    private readonly perChannelCapacity;
+    private readonly maxAgeMs;
+    private readonly now;
+    private readonly buffers;
+    constructor(opts?: EventReplayBufferOptions);
+    /** Append a frame that was just sent to the relay. The seq must be the
+     *  same value placed on the wire so the browser's seq tracker matches. */
+    record(channel: Channel, event: string, payload: unknown, seq: number): void;
+    /** Return all buffered events on `channel` with seq > lastSeq, in seq order.
+     *  Lazy age-eviction keeps the buffer trim even when nothing has been
+     *  appended for a while. */
+    since(channel: Channel, lastSeq: number): BufferedEvent[];
+    /** Return all buffered events newer than the per-channel `lastSeq`, sorted
+     *  by timestamp so the browser replays them in roughly the order they
+     *  were originally emitted. Within a channel, seq is monotonic so the
+     *  timestamp sort still preserves per-channel ordering — frames emitted
+     *  in the same millisecond fall back to (channel, seq) for determinism. */
+    sinceMany(lastSequences: Partial<Record<Channel, number>>): BufferedEvent[];
+    /** Drop the buffer (e.g. on bridge shutdown). */
+    clear(): void;
+    /** Diagnostic — total events held across all channels. */
+    size(): number;
+    private evictExpired;
+}