@reefclaw/openclaw-plugin 0.1.0

package/strategy/condition-registry.js

@@ -0,0 +1,153 @@
+// Plugin-side condition registry — lightweight evaluators that read pre-computed facts.
+// Each evaluator reads booleans from fact.conditions and/or compares indicator values
+// against strategy params. Does NOT duplicate the full condition logic from intelligence.
+export const CONDITION_EVALUATORS = new Map();
+function register(type, fn) {
+    CONDITION_EVALUATORS.set(type, fn);
+}
+// ─── Helper to read indicator values ────────────────────────────────────
+function ind(fact, key) {
+    return fact.indicators[key];
+}
+function indNum(fact, key) {
+    return Number(fact.indicators[key] ?? 0);
+}
+// ─── Original 12 conditions (read booleans from fact.conditions) ────────
+// 1. ema_proximity — checks against parameterized threshold
+register('ema_proximity', (fact, params) => {
+    const period = params.period ?? 21;
+    const key = period <= 30 ? 'ema_proximity_20' : 'ema_proximity_50';
+    return { name: 'ema_proximity', met: fact.conditions[key] ?? false };
+});
+// 2. orderbook_imbalance
+register('orderbook_imbalance', (fact) => {
+    const bid = fact.conditions.orderbook_imbalance_bid ?? false;
+    const ask = fact.conditions.orderbook_imbalance_ask ?? false;
+    return { name: 'orderbook_imbalance', met: bid || ask };
+});
+// 3. funding_not_crowded
+register('funding_not_crowded', (fact) => ({
+    name: 'funding_not_crowded',
+    met: fact.conditions.funding_not_crowded ?? false,
+    value: indNum(fact, 'fundingZScore'),
+}));
+// 4. oi_slope
+register('oi_slope', (fact) => ({
+    name: 'oi_slope',
+    met: fact.conditions.oi_slope_up ?? false,
+}));
+// 5. no_liquidation_cluster — always passes in scan context (no live data)
+register('no_liquidation_cluster', () => ({
+    name: 'no_liquidation_cluster',
+    met: true,
+}));
+// 6. price_sweep
+register('price_sweep', (fact) => ({
+    name: 'price_sweep',
+    met: (fact.conditions.price_sweep_high ?? false) || (fact.conditions.price_sweep_low ?? false),
+}));
+// 7. liquidations_at_sweep — always passes in scan context
+register('liquidations_at_sweep', () => ({
+    name: 'liquidations_at_sweep',
+    met: true,
+}));
+// 8. order_flow_absorption
+register('order_flow_absorption', (fact) => ({
+    name: 'order_flow_absorption',
+    met: fact.conditions.orderbook_imbalance_bid ?? false, // Proxy via orderbook data
+}));
+// 9. funding_contrarian
+register('funding_contrarian', (fact) => ({
+    name: 'funding_contrarian',
+    met: fact.conditions.funding_not_crowded ?? false,
+    value: indNum(fact, 'fundingZScore'),
+}));
+// 10. funding_extreme
+register('funding_extreme', (fact) => ({
+    name: 'funding_extreme',
+    met: fact.conditions.funding_extreme ?? false,
+    value: indNum(fact, 'fundingZScore'),
+}));
+// 11. oi_elevated
+register('oi_elevated', (fact) => ({
+    name: 'oi_elevated',
+    met: fact.conditions.oi_elevated ?? false,
+    value: indNum(fact, 'oiRatio'),
+}));
+// 12. price_at_level
+register('price_at_level', (fact) => ({
+    name: 'price_at_level',
+    met: fact.conditions.ema_proximity_50 ?? false, // Closest proxy
+}));
+// ─── New 11 conditions (Phase 13) ──────────────────────────────────────
+// 13. macd_crossover
+register('macd_crossover', (fact) => ({
+    name: 'macd_crossover',
+    met: fact.conditions.macd_crossover ?? false,
+}));
+// 14. macd_divergence
+register('macd_divergence', (fact) => ({
+    name: 'macd_divergence',
+    met: fact.conditions.macd_divergence ?? false,
+}));
+// 15. bollinger_squeeze — supports custom maxBandwidth param
+register('bollinger_squeeze', (fact, params) => {
+    const maxBW = params.maxBandwidth ?? 3.0;
+    const bb = ind(fact, 'bb');
+    const bw = bb?.bandwidth ?? 0;
+    return {
+        name: 'bollinger_squeeze',
+        met: bw > 0 && bw < maxBW,
+        value: bw,
+    };
+});
+// 16. bollinger_breakout
+register('bollinger_breakout', (fact) => ({
+    name: 'bollinger_breakout',
+    met: fact.conditions.bollinger_breakout ?? false,
+}));
+// 17. vwap_position
+register('vwap_position', (fact) => ({
+    name: 'vwap_position',
+    met: fact.conditions.vwap_position_above ?? fact.conditions.vwap_position_below ?? false,
+}));
+// 18. stoch_rsi_extreme
+register('stoch_rsi_extreme', (fact) => ({
+    name: 'stoch_rsi_extreme',
+    met: (fact.conditions.stoch_rsi_oversold ?? false) || (fact.conditions.stoch_rsi_overbought ?? false),
+}));
+// 19. adx_trending
+register('adx_trending', (fact, params) => {
+    const minAdx = params.minAdx ?? 25;
+    const adx = indNum(fact, 'adx');
+    return {
+        name: 'adx_trending',
+        met: adx > minAdx,
+        value: adx,
+    };
+});
+// 20. adx_ranging
+register('adx_ranging', (fact, params) => {
+    const maxAdx = params.maxAdx ?? 20;
+    const adx = indNum(fact, 'adx');
+    return {
+        name: 'adx_ranging',
+        met: adx < maxAdx,
+        value: adx,
+    };
+});
+// 21. ichimoku_cloud
+register('ichimoku_cloud', (fact) => ({
+    name: 'ichimoku_cloud',
+    met: (fact.conditions.ichimoku_bullish ?? false) || (fact.conditions.ichimoku_bearish ?? false),
+}));
+// 22. obv_divergence
+register('obv_divergence', (fact) => ({
+    name: 'obv_divergence',
+    met: (fact.conditions.obv_divergence_bullish ?? false) || (fact.conditions.obv_divergence_bearish ?? false),
+}));
+// 23. supertrend_direction
+register('supertrend_direction', (fact) => ({
+    name: 'supertrend_direction',
+    met: (fact.conditions.supertrend_bullish ?? false) || (fact.conditions.supertrend_bearish ?? false),
+}));

package/strategy/evaluator.d.ts

@@ -0,0 +1,67 @@
+export interface SymbolFact {
+    symbol: string;
+    time: string;
+    indicators: Record<string, unknown>;
+    conditions: Record<string, boolean>;
+    regime: string;
+    regime_confidence: number;
+}
+export interface ConditionConfig {
+    type: string;
+    params: Record<string, number>;
+}
+export interface StrategyConfig {
+    name: string;
+    description: string;
+    version: number;
+    regimeWhitelist: string[];
+    minConfidence: number;
+    directionRule: string;
+    conditions: ConditionConfig[];
+    entryRule: {
+        type: string;
+        params: Record<string, number>;
+    };
+    stopRule: {
+        type: string;
+        params: Record<string, number>;
+    };
+    targetRMultiples: number[];
+}
+export interface StrategyRow {
+    id: number;
+    name: string;
+    description: string;
+    config: StrategyConfig;
+    is_builtin: boolean;
+    is_active: boolean;
+    backtest_result: unknown | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface ConditionEvalResult {
+    name: string;
+    met: boolean;
+    value?: number;
+}
+export interface StrategyEvalResult {
+    strategy: string;
+    symbol: string;
+    score: number;
+    conditionsMet: number;
+    conditionsTotal: number;
+    conditions: ConditionEvalResult[];
+    regime: string;
+    regime_confidence: number;
+    summary: string;
+}
+/**
+ * Evaluate a strategy against a symbol's fact object.
+ * Returns null if the strategy is regime-gated and the symbol's regime doesn't match.
+ */
+export declare function evaluateStrategy(strategy: StrategyConfig, fact: SymbolFact): StrategyEvalResult | null;
+/**
+ * Evaluate all active strategies against all symbol facts.
+ * Returns ranked results above minScore.
+ */
+export declare function scanAllPairs(strategies: StrategyConfig[], facts: SymbolFact[], minScore?: number): StrategyEvalResult[];

package/strategy/evaluator.js

@@ -0,0 +1,93 @@
+// Lightweight strategy evaluator for plugin-side condition checking.
+// Reads pre-computed fact objects from intelligence service (boolean conditions + indicator values).
+// Does NOT duplicate the full condition logic from intelligence — reads pre-evaluated booleans
+// and optionally checks threshold-based conditions against indicator values.
+import { CONDITION_EVALUATORS } from './condition-registry.js';
+import { getCachedTradingParams } from '../trading-params-cache.js';
+// ─── Evaluator ──────────────────────────────────────────────────────────
+/**
+ * Evaluate a strategy against a symbol's fact object.
+ * Returns null if the strategy is regime-gated and the symbol's regime doesn't match.
+ */
+export function evaluateStrategy(strategy, fact) {
+    // Check regime gate
+    if (strategy.regimeWhitelist.length > 0) {
+        const matchesRegime = strategy.regimeWhitelist.some(r => r === fact.regime || r === 'ANY');
+        if (!matchesRegime)
+            return null;
+    }
+    // Check regime confidence — use the LOWER of strategy minConfidence and user's global floor
+    const tp = getCachedTradingParams();
+    const effectiveMinConf = Math.min(strategy.minConfidence, tp.regimeConfidenceFloor || strategy.minConfidence);
+    if (fact.regime_confidence < effectiveMinConf)
+        return null;
+    // Evaluate each condition
+    const results = [];
+    for (const cond of strategy.conditions) {
+        const evaluator = CONDITION_EVALUATORS.get(cond.type);
+        if (evaluator) {
+            results.push(evaluator(fact, cond.params));
+        }
+        else {
+            // Fallback: try to read directly from fact.conditions map
+            const boolKey = cond.type;
+            const met = fact.conditions[boolKey] ?? false;
+            results.push({ name: cond.type, met });
+        }
+    }
+    const conditionsMet = results.filter(r => r.met).length;
+    const conditionsTotal = results.length;
+    const score = conditionsTotal > 0 ? (conditionsMet / conditionsTotal) * 10 : 0;
+    // Build summary
+    const metNames = results.filter(r => r.met).map(r => r.name).join(', ');
+    const summary = buildSummary(strategy, fact, results);
+    return {
+        strategy: strategy.name,
+        symbol: fact.symbol,
+        score: Math.round(score * 10) / 10,
+        conditionsMet,
+        conditionsTotal,
+        conditions: results,
+        regime: fact.regime,
+        regime_confidence: fact.regime_confidence,
+        summary,
+    };
+}
+/**
+ * Evaluate all active strategies against all symbol facts.
+ * Returns ranked results above minScore.
+ */
+export function scanAllPairs(strategies, facts, minScore = 4) {
+    const results = [];
+    for (const fact of facts) {
+        for (const strategy of strategies) {
+            const result = evaluateStrategy(strategy, fact);
+            if (result && result.score >= minScore) {
+                results.push(result);
+            }
+        }
+    }
+    // Sort by score descending
+    results.sort((a, b) => b.score - a.score);
+    return results;
+}
+// ─── Summary builder ────────────────────────────────────────────────────
+function buildSummary(strategy, fact, results) {
+    const ind = fact.indicators;
+    const parts = [];
+    // Regime context
+    parts.push(`${fact.regime} (${(fact.regime_confidence * 100).toFixed(0)}%)`);
+    // Key indicator values
+    if (ind.rsi14 !== undefined)
+        parts.push(`RSI ${ind.rsi14}`);
+    if (ind.adx !== undefined)
+        parts.push(`ADX ${ind.adx}`);
+    const macd = ind.macd;
+    if (macd?.crossover && macd.crossover !== 'none') {
+        parts.push(`MACD ${macd.crossover}`);
+    }
+    const funding = ind.fundingZScore;
+    if (funding !== undefined)
+        parts.push(`Funding ${funding > 0 ? '+' : ''}${funding.toFixed(1)}σ`);
+    return parts.join(', ');
+}

package/tools/assessment-validation.d.ts

@@ -0,0 +1,118 @@
+import type { RealizationRule } from '../simulator/types.js';
+/** The five legitimate reasons to manually close an otherwise-bracketed
+ *  position (see SKILL.md v2.10.0 Position Management Discipline).  Any other
+ *  value is rejected. */
+export declare const CLOSE_REASONS: readonly ["regime_flip", "risk_limit", "bracket_integrity", "operator_command"];
+export type CloseReason = (typeof CLOSE_REASONS)[number];
+export interface CloseAssessment {
+    /** Scorecard confluence score at entry (0-10). */
+    entry_score?: number;
+    /** Current scorecard confluence score from this heartbeat's fresh analysis. */
+    current_score?: number;
+    /** Regime at entry, e.g. 'RANGE_WIDE', 'TREND_UP'. */
+    entry_regime?: string;
+    /** Regime right now, from this heartbeat's fresh analysis. */
+    current_regime?: string;
+    /** Free-text naming the specific metric that flipped.  Required for
+     *  regime_flip, risk_limit, and bracket_integrity. */
+    contradicting_metric?: string;
+    /** Telemetry only — position age in seconds. Not gated. */
+    position_age_seconds?: number;
+    /** Telemetry only — R-multiple at close (= current_r in exit-gate inputs). */
+    r_multiple_at_close?: number;
+    /** Max favorable excursion in R-multiples ever reached during this position's
+     *  lifetime. Drives the exit-gate tier classification (see
+     *  docs/EXIT_GATE_DESIGN.md §3). Optional for backwards compatibility — the
+     *  gate falls back to PASS('inputs_unavailable_mfe') when absent so the
+     *  shadow soak can surface plumbing gaps before enforce. */
+    mfe_r_peak?: number;
+}
+export interface ClosePositionArgs {
+    symbol: string;
+    reason?: string;
+    assessment?: CloseAssessment;
+}
+export interface ValidationResult {
+    ok: boolean;
+    error?: string;
+}
+/** Validate a `close_position` call against the SKILL.md v2.10.0 contract.
+ *  Returns {ok:true} to proceed or {ok:false, error} to reject the tool call.
+ *
+ *  Philosophy: force the agent to submit structured proof that a real
+ *  reassessment happened.  No time gate — a 60-second close is legal if the
+ *  assessment holds up.  But blank or inconsistent fields mean no reasoning,
+ *  so we refuse.
+ */
+export declare function validateClosePosition(args: ClosePositionArgs): ValidationResult;
+export interface CreateOrderArgs {
+    symbol: string;
+    side: string;
+    type: string;
+    amount: number;
+    price?: number;
+    stopPrice?: number;
+    setup_type?: string;
+    thesis?: string;
+    target_price?: number;
+    regime?: string;
+    regime_confidence?: number;
+    scorecard_verdict?: string;
+    confluence_score?: number;
+    invalidation_price?: number;
+    realization_rule?: unknown;
+}
+/** Validate a `create_order` call against the SKILL.md v2.10.0 contract.
+ *  Only enforced in LIVE mode — paper mode is for exploration and allows
+ *  missing metadata so the agent can probe without full reasoning.  Live
+ *  mode = real money = must show your work.
+ */
+export declare function validateCreateOrder(args: CreateOrderArgs, isLive: boolean): ValidationResult;
+/** Coerce the agent-supplied `realization_rule` (snake_case from the tool
+ *  schema) into a clean RealizationRule, dropping garbage. Permissive by
+ *  design — this is the agent's stated PLAN (indication), not an enforced
+ *  mechanic, so we keep whatever is well-formed and default an unknown `type`
+ *  to 'manual' rather than rejecting. Returns undefined for non-objects. */
+export declare function sanitizeRealizationRule(raw: unknown): RealizationRule | undefined;
+/** Verdicts the agent can file at heartbeat for an open position. `trim` is
+ *  intentionally absent until `partial_close` exists as a real action — see
+ *  POSITION_DECISION_JOURNAL_PLAN.md §3 redirect #4. */
+export declare const REVIEW_VERDICTS: readonly ["hold", "add_on", "close_recommended"];
+export type ReviewVerdict = (typeof REVIEW_VERDICTS)[number];
+export declare const THESIS_STATUSES: readonly ["intact", "weakening", "invalidated", "evolving"];
+export type ThesisStatus = (typeof THESIS_STATUSES)[number];
+export interface PositionReviewItem {
+    symbol?: string;
+    position_open_at?: number;
+    verdict?: string;
+    thesis_status?: string;
+    entry_score?: number;
+    current_score?: number;
+    score_delta?: number;
+    confluence_components?: Record<string, unknown>;
+    regime_entry?: string;
+    regime_current?: string;
+    regime_confidence?: number;
+    r_multiple?: number;
+    distance_to_stop_bps?: number;
+    distance_to_target_bps?: number;
+    time_in_position_minutes?: number;
+    mfe_r?: number;
+    give_back_pct?: number;
+    what_changed?: string;
+    invalidation_trigger?: string;
+}
+export interface RecordPositionReviewsArgs {
+    reviews?: unknown;
+}
+/** Validate a `record_position_reviews` call. Per-review rules from
+ *  POSITION_REVIEW_PLAN.md §7.2 plus a top-level superset rule when the caller
+ *  passes the open-positions snapshot.
+ *
+ *  Returns either {ok:true} (proceed) or {ok:false, error} (reject the whole
+ *  call — partial-success would corrupt the audit trail).
+ */
+export declare function validatePositionReviews(args: RecordPositionReviewsArgs, ctx?: {
+    openSymbols?: ReadonlySet<string>;
+    gateMode?: 'off' | 'shadow' | 'observe' | 'enforce';
+}): ValidationResult;