@reefclaw/openclaw-plugin 0.1.0

package/bridge/types.d.ts

@@ -0,0 +1,584 @@
+import type { EventFrame as _EventFrame } from '@reefclaw/shared';
+export type { Channel, RequestFrame, ResponseFrame, EventFrame, Frame, EmergencyAction } from '@reefclaw/shared';
+export { VALID_CHANNELS, VALID_EMERGENCY_ACTIONS } from '@reefclaw/shared';
+type EventFrame = _EventFrame;
+/** Methods the skill accepts from the relay (browser → skill) */
+export declare const ALLOWED_METHODS: readonly ["emergency.kill", "emergency.flatten", "emergency.pause", "emergency.resume", "reconcile", "chat.send", "skill.update", "close_position", "set_trading_mode", "set_exchange_credentials", "test_exchange_credentials", "clear_exchange_credentials", "get_bracket_config", "set_bracket_requirement"];
+/** Subset of ALLOWED_METHODS that require operator.write scope. The bridge
+ *  enforces this before dispatching — a session without the scope gets a
+ *  403 error. PR2 ships the scope as session-wide (inherited from the Clerk
+ *  authenticated browser session) because the skill trusts the relay to
+ *  scope rooms per user; per-method operator gating is defense-in-depth and
+ *  a hook for PR4 fine-grained roles. */
+export declare const OPERATOR_WRITE_METHODS: ReadonlySet<string>;
+export type AllowedMethod = (typeof ALLOWED_METHODS)[number];
+export interface TickerData {
+    symbol: string;
+    lastPrice: number;
+    bidPrice: number;
+    askPrice: number;
+    volume24h: number;
+    change24h: number;
+    change24hPercent: number;
+    timestamp: string;
+}
+export interface CandleData {
+    symbol: string;
+    candle: {
+        time: number;
+        open: number;
+        high: number;
+        low: number;
+        close: number;
+        volume: number;
+    };
+    timestamp: string;
+}
+export interface OrderData {
+    id: string;
+    symbol: string;
+    side: 'BUY' | 'SELL';
+    type: 'MARKET' | 'LIMIT';
+    status: string;
+    quantity: number;
+    filledQuantity: number;
+    averageFillPrice: number;
+    timeInForce: string;
+    createdAt: string;
+    updatedAt: string;
+    /**
+     * True when this order can only REDUCE/CLOSE a position — a protective
+     * bracket (STOP_MARKET / TAKE_PROFIT_MARKET, `reduceOnly` or `closePosition`),
+     * never a working entry/add. The kill switch preserves these so it never
+     * leaves an open position naked. Computed in `mapCcxtOrder`; undefined on
+     * paper / legacy paths (treated as a working order → cancellable).
+     */
+    protective?: boolean;
+}
+export interface FillData {
+    id: string;
+    orderId: string;
+    symbol: string;
+    side: 'BUY' | 'SELL';
+    quantity: number;
+    price: number;
+    expectedPrice: number;
+    slippage: number;
+    slippageBps: number;
+    fee: number;
+    feeCurrency: string;
+    timestamp: string;
+    /**
+     * True when the fill reduces (closes / partially trims) a position rather
+     * than opens or adds to one. Optional because legacy gateway payloads omit
+     * it — webapp degrades gracefully to direction-only rendering when absent.
+     */
+    reduceOnly?: boolean;
+}
+export interface OrderUpdatePayload {
+    orderId: string;
+    status: string;
+    order: OrderData;
+    fill?: FillData;
+    timestamp: string;
+}
+export interface AgentStateData {
+    state: {
+        mode: 'ACTIVE' | 'PAUSED' | 'STOPPED' | 'ERROR';
+        strategy: {
+            name: string;
+            version: string;
+        };
+        /** OpenClaw agent display name (identity), resolved from the gateway. Optional:
+         *  absent on older skills / when the gateway doesn't surface an identity. */
+        agentName?: string;
+        /** Live LLM model id the agent is running (e.g. "openai-codex/gpt-5.4-mini"),
+         *  resolved from the gateway. Optional: absent on older skills. */
+        model?: string;
+        health: {
+            uptime: number;
+            lastDecision: string;
+            lastTrade: string | null;
+            errorRate: number;
+            thinkingInterval: number;
+            /** Gateway WebSocket state — helps diagnose chat delivery failures */
+            gatewayWs?: string;
+        };
+    };
+    timestamp: string;
+}
+export interface RiskLimits {
+    position: {
+        maxPositionSize: number;
+        maxOpenPositions: number;
+        maxGrossExposure: number;
+        maxNetExposure: number;
+    };
+    loss: {
+        maxDailyDrawdown: number;
+        maxPerTradeLoss: number;
+        maxDailyLoss: number;
+    };
+    rate: {
+        maxOrdersPerMinute: number;
+        maxCancelsPerMinute: number;
+    };
+}
+export interface RiskUtilization {
+    currentPositionSize: Record<string, number>;
+    openPositionCount: number;
+    grossExposure: number;
+    netExposure: number;
+    dailyDrawdown: number;
+    dailyLoss: number;
+    ordersPerMinute: number;
+    cancelsPerMinute: number;
+}
+export interface RiskBreach {
+    metric: string;
+    limit: number;
+    current: number;
+    level: 'OK' | 'WARNING' | 'CRITICAL';
+    action: 'ALERT' | 'AUTO_PAUSE' | 'REJECT_ORDER';
+    timestamp: string;
+}
+export interface RiskUpdatePayload {
+    event: 'risk_update';
+    metrics: {
+        limits: RiskLimits;
+        utilization: RiskUtilization;
+        activeBreaches: RiskBreach[];
+        effectiveLimits?: RiskLimits;
+        volatility?: {
+            atr14: number;
+            baselineAtr: number;
+            volFactor: number;
+            adjusted: boolean;
+        };
+        drawdownZone?: 'GREEN' | 'YELLOW' | 'ORANGE' | 'RED';
+        drawdownZoneMessage?: string;
+        regime?: {
+            regime: string;
+            description: string;
+            adjusted: boolean;
+        };
+    };
+    timestamp: string;
+    positions?: Array<{
+        symbol: string;
+        side: 'LONG' | 'SHORT';
+        quantity: number;
+        entryPrice: number;
+        currentPrice: number;
+        unrealizedPnl: number;
+        unrealizedPnlPercent: number;
+        portfolioPercent: number;
+        mfeR?: number;
+        mfePeakPrice?: number;
+        giveBackRatio?: number;
+        originalStopPrice?: number;
+        liquidationPrice?: number;
+        leverage?: number;
+        maintenanceMargin?: number;
+        marginRatio?: number;
+        bracket?: {
+            slPrice?: number;
+            tpPrice?: number;
+            state: string;
+        };
+    }>;
+    balance?: {
+        total: number;
+        available: number;
+        locked: number;
+    };
+    sessionStartNav?: number;
+    /** Realized P&L for TODAY only (filtered by closedAt). Used by the skill's
+     *  daily-loss breach detection and the agent's daily-performance view. */
+    realizedPnlToday?: number;
+    /** Cumulative realized P&L across the entire trade history (incl. both open
+     *  and close fees). Used by the webapp KPI strip. Added Apr 2026 after the
+     *  original `realizedPnlToday` field was discovered to contain all-time
+     *  values, misleading the agent about today's performance. */
+    realizedPnlAllTime?: number;
+    /** Paper session execution costs (since plugin boot), already reflected in
+     *  equity/NAV — surfaced so the dashboard cost cells don't read $0 (M1).
+     *  Paper only; omitted in live. */
+    sessionFeesPaid?: number;
+    sessionAvgSlippageBps?: number;
+    /** Mark-to-market account value = wallet + collateral + unrealized P&L.
+     *  Use this (NOT balance.total) for heat / leverage / exposure math. */
+    equity?: number;
+}
+export interface ChatMessage {
+    id: string;
+    role: 'agent' | 'operator';
+    content: string;
+    timestamp: string;
+}
+export interface ReconciliationSnapshot {
+    positions: Array<{
+        symbol: string;
+        side: 'LONG' | 'SHORT';
+        quantity: number;
+        entryPrice: number;
+        currentPrice: number;
+        unrealizedPnl: number;
+        unrealizedPnlPercent: number;
+        portfolioPercent: number;
+        mfeR?: number;
+        mfePeakPrice?: number;
+        giveBackRatio?: number;
+        originalStopPrice?: number;
+        liquidationPrice?: number;
+        leverage?: number;
+        maintenanceMargin?: number;
+        marginRatio?: number;
+        bracket?: {
+            slPrice?: number;
+            tpPrice?: number;
+            state: string;
+        };
+    }>;
+    balance: {
+        currency: string;
+        total: number;
+        available: number;
+        locked: number;
+    };
+    openOrders: OrderData[];
+    agentState: AgentStateData['state'];
+    riskMetrics: RiskUpdatePayload['metrics'];
+    gapFill: EventFrame[];
+    /** Session start NAV — persisted across skill restarts within the same day. */
+    sessionStartNav?: number;
+    /** Realized P&L for TODAY only (filtered by closedAt, roundtrip-fee inclusive). */
+    realizedPnlToday?: number;
+    /** Cumulative realized P&L across all history (roundtrip-fee inclusive). */
+    realizedPnlAllTime?: number;
+    /** Paper session execution costs (since plugin boot) for the dashboard cost
+     *  cells (M1). Paper only; omitted in live. */
+    sessionFeesPaid?: number;
+    sessionAvgSlippageBps?: number;
+    /** Mark-to-market account value (wallet + collateral + unrealized P&L). */
+    equity?: number;
+    /** Current trading mode (Phase 9b) */
+    tradingMode?: TradingMode;
+}
+export type TrendDirection = 'bullish' | 'bearish' | 'neutral';
+export type MarketRegime = 'trending' | 'ranging';
+export type MomentumLevel = 'strong' | 'moderate' | 'weak';
+export interface TimeframeAnalysis {
+    timeframe: string;
+    direction: TrendDirection;
+    regime: MarketRegime;
+    momentum: MomentumLevel;
+    rsiValue: number | null;
+    priceVsSma: number | null;
+    emaFast: number | null;
+    emaSlow: number | null;
+    changePercent: number | null;
+    candles: number;
+    atr14?: number;
+}
+export interface MarketStructureData {
+    symbol: string;
+    timeframes: TimeframeAnalysis[];
+    alignment: {
+        bullish: number;
+        bearish: number;
+        neutral: number;
+        total: number;
+        summary: string;
+    };
+    atr?: {
+        atr14: number;
+        atrPercent: number;
+    };
+    timestamp: string;
+}
+export interface CryptoMetricsData {
+    symbol: string;
+    fundingRate: number | null;
+    fundingRateAnnualized: number | null;
+    nextFundingTime: string | null;
+    openInterest: number | null;
+    openInterestUsd: number | null;
+    timestamp: string;
+}
+export interface VolumeAnalysisData {
+    symbol: string;
+    timeframe: string;
+    volumeExpansion: number;
+    closePosition: number;
+    directionalThrust: number;
+    buyVolEstimate: number;
+    avgVolume: number;
+    currentVolume: number;
+    barsAnalyzed: number;
+    timestamp: string;
+}
+export interface RegimeData {
+    event: 'regime_update';
+    symbol: string;
+    regime: 'TREND_UP' | 'TREND_DOWN' | 'RANGE_TIGHT' | 'RANGE_WIDE' | 'VOLATILITY_EXPANSION' | 'AVOID' | 'UNKNOWN';
+    confidence: number;
+    probabilities: Record<string, number>;
+    featuresSnapshot: Record<string, number>;
+    durationSeconds: number | null;
+    timestamp: string;
+}
+export interface SignalConditionData {
+    name: string;
+    met: boolean;
+    currentValue: number;
+    threshold: number;
+    description: string;
+}
+export interface StrategyStateData {
+    strategy: string;
+    direction: 'LONG' | 'SHORT' | null;
+    regimeGated: boolean;
+    regimeRequired: string[];
+    currentRegime: string;
+    regimeConfidence: number;
+    confluenceScore: number;
+    conditions: SignalConditionData[];
+}
+export interface SignalEventData {
+    signalId: string;
+    timestamp: string;
+    symbol: string;
+    strategy: string;
+    direction: 'LONG' | 'SHORT';
+    regime: string;
+    regimeConfidence: number;
+    confluenceScore: number;
+    conditions: SignalConditionData[];
+    entryZone: {
+        low: number;
+        high: number;
+    };
+    stopLevel: number;
+    targets: number[];
+}
+export interface SignalData {
+    event: 'signal_update';
+    activeStrategies: StrategyStateData[];
+    recentSignals: SignalEventData[];
+    timestamp: string;
+}
+export type MissionStatusType = 'PENDING' | 'ACCEPTED' | 'EXECUTING' | 'FILLED' | 'EXPIRED' | 'REJECTED';
+export interface SizingDetailsData {
+    sizePct: number;
+    kellyFraction: number;
+    winRate: number;
+    avgWinLossRatio: number;
+    tradeCount: number;
+    volAdjustment: number;
+    cappedReason?: string;
+}
+export interface TradeMissionData {
+    missionId: string;
+    signalId: string;
+    symbol: string;
+    direction: 'LONG' | 'SHORT';
+    strategy: string;
+    regime: string;
+    regimeConfidence: number;
+    confluenceScore: number;
+    conditions: SignalConditionData[];
+    entryZone: {
+        low: number;
+        high: number;
+    };
+    stopLevel: number;
+    targets: Array<{
+        price: number;
+        pct: number;
+    }>;
+    sizePct: number;
+    sizingDetails: SizingDetailsData;
+    status: MissionStatusType;
+    statusDetails?: Record<string, unknown>;
+    expiresAt: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface MissionData {
+    event: 'mission_update';
+    activeMissions: TradeMissionData[];
+    recentCompleted: TradeMissionData[];
+    timestamp: string;
+}
+export interface StrategyMetricsData {
+    strategy: string;
+    winRate20: number;
+    winRate50: number;
+    winRateAll: number;
+    expectancy20: number;
+    expectancyAll: number;
+    profitFactor: number;
+    avgHoldWinners: number;
+    avgHoldLosers: number;
+    totalTrades: number;
+    bestTradePct: number;
+    worstTradePct: number;
+    avgPnlPct: number;
+    sharpe: number;
+    gated: boolean;
+    gatedReason?: string;
+    gatedAt?: string;
+}
+export interface RegimePerformanceData {
+    regime: string;
+    trades: number;
+    winRate: number;
+    expectancy: number;
+    avgPnlPct: number;
+}
+export interface EquityPointData {
+    timestamp: string;
+    cumulativePnl: number;
+    drawdownPct: number;
+}
+export interface DegradationAlertData {
+    strategy: string;
+    type: 'GATED' | 'UNGATED';
+    reason: string;
+    expectancy20: number;
+    timestamp: string;
+}
+export interface AnalyticsData {
+    event: 'analytics_update';
+    strategies: StrategyMetricsData[];
+    regimeBreakdown: RegimePerformanceData[];
+    equityCurve: EquityPointData[];
+    degradationAlerts: DegradationAlertData[];
+    summary: {
+        totalTrades: number;
+        overallWinRate: number;
+        overallExpectancy: number;
+        overallSharpe: number;
+        activeStrategies: number;
+        gatedStrategies: number;
+        peakDrawdownPct: number;
+    };
+    timestamp: string;
+}
+export interface DecisionTraceNearMiss {
+    strategy: string;
+    direction: 'LONG' | 'SHORT' | null;
+    confluenceScore: number;
+    totalConditions: number;
+    missingConditions: SignalConditionData[];
+    distanceToSignal: number;
+}
+export interface DecisionTraceFactor {
+    name: string;
+    value: string;
+    impact: 'bullish' | 'bearish' | 'neutral';
+    weight: number;
+}
+export interface DecisionTraceData {
+    event: 'decision_trace';
+    symbol: string;
+    regime: {
+        current: string;
+        confidence: number;
+        probabilities: Record<string, number>;
+    };
+    bias: 'LONG' | 'SHORT' | 'NEUTRAL';
+    biasStrength: number;
+    factors: DecisionTraceFactor[];
+    activeStrategies: Array<{
+        strategy: string;
+        direction: 'LONG' | 'SHORT' | null;
+        confluenceScore: number;
+        totalConditions: number;
+        regimeGated: boolean;
+        ready: boolean;
+    }>;
+    nearMisses: DecisionTraceNearMiss[];
+    recentSignalCount: number;
+    timestamp: string;
+}
+import type { TradingMode as _TradingMode } from '@reefclaw/shared';
+import { isTradingMode as _isTradingMode } from '@reefclaw/shared';
+export type TradingMode = _TradingMode;
+export declare const isTradingMode: typeof _isTradingMode;
+/** Shadow comparison event — paper fill vs live estimate. */
+export interface ShadowComparisonData {
+    event: 'shadow_comparison';
+    orderId: string;
+    symbol: string;
+    side: 'BUY' | 'SELL';
+    type: 'MARKET' | 'LIMIT';
+    amount: number;
+    paperFillPrice: number;
+    shadowEstimatePrice: number;
+    deltaBps: number;
+    paperFee: number;
+    shadowEstimateFee: number;
+    bookDepthUsed: number;
+    bookDepthAvailable: boolean;
+    timestamp: string;
+}
+/** Trading mode update event. */
+export interface TradingModeData {
+    event: 'trading_mode';
+    mode: TradingMode;
+    shadowMetrics?: {
+        totalShadowTrades: number;
+        avgDeltaBps: number;
+        worstDeltaBps: number;
+        tradingDays: number;
+        readyForUpgrade: boolean;
+        upgradeBlockers: string[];
+    };
+    timestamp: string;
+}
+export interface TradeJournalEntry {
+    id: string;
+    symbol: string;
+    side: 'BUY' | 'SELL';
+    action: 'OPEN' | 'CLOSE' | 'ADD' | 'REDUCE';
+    quantity: number;
+    price: number;
+    /** Market structure snapshot at trade time */
+    marketContext: {
+        direction5m: string | null;
+        direction1h: string | null;
+        direction4h: string | null;
+        alignment: string | null;
+        fundingRate: number | null;
+        volumeExpansion: number | null;
+        closePosition: number | null;
+    };
+    /** Risk snapshot at trade time */
+    riskContext: {
+        grossExposure: number;
+        netExposure: number;
+        dailyDrawdown: number;
+        heatScore: number;
+    };
+    timestamp: string;
+}
+export interface ConnectorConfig {
+    relayUrl: string;
+    userId: string;
+    token: string;
+    reconnect?: {
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+        maxFastAttempts?: number;
+        jitterFactor?: number;
+        slowRetryMs?: number;
+    };
+}
+/** Close codes that indicate fatal auth errors — do not reconnect.
+ *  4001 = invalid/mismatched token (permanent failure).
+ *  4002 removed — relay now evicts stale connections instead of rejecting new ones,
+ *  but even if an old relay is deployed, the connector should retry (old connection
+ *  will time out and the next attempt will succeed). */
+export declare const FATAL_CLOSE_CODES: readonly [4001];

package/bridge/types.js

@@ -0,0 +1,50 @@
+// Protocol types — re-exported from @reefclaw/shared (canonical source of truth).
+export { VALID_CHANNELS, VALID_EMERGENCY_ACTIONS } from '@reefclaw/shared';
+// ---- Command whitelist ----
+/** Methods the skill accepts from the relay (browser → skill) */
+export const ALLOWED_METHODS = [
+    'emergency.kill',
+    'emergency.flatten',
+    'emergency.pause',
+    'emergency.resume',
+    'reconcile',
+    'chat.send',
+    'skill.update',
+    'close_position',
+    // Operator-only onboarding methods (PR2+PR4). Gated by OPERATOR_WRITE_METHODS —
+    // the bridge refuses to handle these unless the call goes through the
+    // operator.write scope enforcement path. See bridge.ts.
+    'set_trading_mode',
+    'set_exchange_credentials',
+    'test_exchange_credentials',
+    'clear_exchange_credentials',
+    // Bracket-orders config (Phase 3.5b) — operator.write-gated.
+    'get_bracket_config',
+    'set_bracket_requirement',
+];
+/** Subset of ALLOWED_METHODS that require operator.write scope. The bridge
+ *  enforces this before dispatching — a session without the scope gets a
+ *  403 error. PR2 ships the scope as session-wide (inherited from the Clerk
+ *  authenticated browser session) because the skill trusts the relay to
+ *  scope rooms per user; per-method operator gating is defense-in-depth and
+ *  a hook for PR4 fine-grained roles. */
+export const OPERATOR_WRITE_METHODS = new Set([
+    'set_trading_mode',
+    'set_exchange_credentials',
+    'test_exchange_credentials',
+    'clear_exchange_credentials',
+    'get_bracket_config',
+    'set_bracket_requirement',
+    'emergency.kill',
+    'emergency.flatten',
+    'emergency.pause',
+    'emergency.resume',
+]);
+import { isTradingMode as _isTradingMode } from '@reefclaw/shared';
+export const isTradingMode = _isTradingMode;
+/** Close codes that indicate fatal auth errors — do not reconnect.
+ *  4001 = invalid/mismatched token (permanent failure).
+ *  4002 removed — relay now evicts stale connections instead of rejecting new ones,
+ *  but even if an old relay is deployed, the connector should retry (old connection
+ *  will time out and the next attempt will succeed). */
+export const FATAL_CLOSE_CODES = [4001];

package/bridge/utils/reconnect.d.ts

@@ -0,0 +1,6 @@
+export interface ReconnectConfig {
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitterFactor: number;
+}
+export declare function computeDelay(attempt: number, config: ReconnectConfig): number;

package/bridge/utils/reconnect.js

@@ -0,0 +1,6 @@
+// Shared reconnection utilities (exponential backoff with jitter)
+export function computeDelay(attempt, config) {
+    const base = Math.min(config.baseDelayMs * Math.pow(2, attempt), config.maxDelayMs);
+    const jitter = base * config.jitterFactor;
+    return base - jitter + Math.random() * jitter * 2;
+}

package/bridge/utils/skill-signing.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Pinned Ed25519 PUBLIC keys (base64 of the raw 32-byte key) trusted to sign OTA
+ * SKILL.md updates. Multiple entries enable key rotation (accept current + next,
+ * retire the old after every client has updated). EMPTY until the operator pins
+ * one — see the header for provisioning.
+ */
+export declare const TRUSTED_SKILL_SIGNING_KEYS: string[];
+export interface SignedSkillEnvelope {
+    version: string;
+    content: string;
+    contentSha256?: string;
+    signedAt?: string;
+    /** base64 Ed25519 signature over signedMessage(version, contentSha256, signedAt) */
+    signature?: string;
+}
+export interface VerifyResult {
+    ok: boolean;
+    reason?: string;
+}
+/** Lowercase hex SHA-256 of the UTF-8 content. MUST match the Python signer. */
+export declare function sha256Hex(content: string): string;
+/** Canonical signed message — MUST match deploy-skillmd-ota.py byte-for-byte. */
+export declare function signedMessage(version: string, contentSha256: string, signedAt: string): string;
+/**
+ * Is OTA signature verification enforced?
+ *
+ * Default **OFF** while C1 (signed OTA) is ON HOLD — see
+ * docs/PRE_LAUNCH_SECURITY_HARDENING.md §2.5. Keeping it off by default makes
+ * this whole module DORMANT, so deploying skill/relay for UNRELATED reasons can
+ * never break the existing (unsigned) OTA flow — no env flag to remember.
+ *
+ * To ENABLE signed-OTA (when the agent-update mechanism is finalized): pin a
+ * public key in TRUSTED_SKILL_SIGNING_KEYS **and** set
+ * SKILL_OTA_REQUIRE_SIGNATURE=on. Both are required — a pinned key alone does
+ * nothing without the flag, and the flag alone fails closed (no key → reject).
+ */
+export declare function signatureRequired(): boolean;
+/**
+ * Verify a signed OTA envelope against the pinned (or supplied) trusted keys.
+ * Checks: required fields present, content hash matches (no tampering), the
+ * frontmatter version matches the signed version (no number-bump replay), and
+ * the Ed25519 signature verifies under some trusted key. Pure — does NOT touch
+ * disk or the replay clock; the caller enforces monotonic signedAt.
+ */
+export declare function verifySkillSignature(env: SignedSkillEnvelope, opts?: {
+    trustedKeys?: string[];
+}): VerifyResult;
+/** Last applied signedAt as epoch ms, 0 if none/unreadable (replay clock). */
+export declare function readLastAppliedSignedAtMs(): number;
+/** Persist the signedAt of the just-applied update (monotonic replay clock). */
+export declare function recordAppliedSignedAt(signedAt: string): void;