@reefclaw/openclaw-plugin 0.1.0

package/tools/assessment-validation.js

@@ -0,0 +1,415 @@
+// Assessment-schema validators for agent tool calls (SKILL.md v2.10.0).
+//
+// The LLM's value is context-sensitive reasoning.  We don't want to gate
+// trading tools behind time floors (a thesis CAN legitimately invalidate
+// in 60 seconds).  We want to gate them behind PROOF that the reasoning
+// happened — a structured assessment the agent has to fill from real
+// scorecard data.  If it filled the fields, the reasoning happened.  If
+// it didn't, we reject.
+//
+// Used by:
+//   - close-position.ts   — requires `reason` + `assessment` on every call.
+//   - create-order.ts     — requires thesis + regime + confluence_score in
+//                           live mode.
+// Tested in: assessment-validation.test.ts.
+import { normalizeBracketSymbol } from '../live/bracket-ledger.js';
+// ---- close_position ----
+/** 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 const CLOSE_REASONS = [
+    'regime_flip',
+    // 'scorecard_reversal' — DEPRECATED 2026-06-16 (exit-discipline #2): a lower re-scored
+    // confluence is anti-predictive of outcome and is NOT a valid exit trigger. Removed from
+    // the menu; validateClosePosition rejects it early with a redirect to objective reasons.
+    'risk_limit',
+    'bracket_integrity',
+    'operator_command',
+];
+function nonEmptyString(v) {
+    return typeof v === 'string' && v.trim().length > 0;
+}
+function isScore(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 10;
+}
+/** 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 function validateClosePosition(args) {
+    if (!nonEmptyString(args.symbol)) {
+        return { ok: false, error: 'Symbol is required.' };
+    }
+    // `reason` is required.  Enum check first.
+    if (!args.reason) {
+        return {
+            ok: false,
+            error: `close_position requires a 'reason' param (one of: ${CLOSE_REASONS.join(', ')}). ` +
+                'See SKILL.md v2.10.0 Position Management Discipline.',
+        };
+    }
+    // scorecard_reversal DEPRECATED 2026-06-16 (exit-discipline #2). The entry scorecard is
+    // anti-predictive of MFE, so re-scoring an open position and exiting on a lower score cut
+    // undeveloped trades for no edge (108 such closes, 82% never developed). The exit gate
+    // already blocks premature exits by MFE/current_r regardless of reason; this closes the
+    // agent-facing menu. See docs/EXIT_DISCIPLINE_BUILD_PLAN.md Step 1 (#2).
+    if (args.reason === 'scorecard_reversal') {
+        return {
+            ok: false,
+            error: "close reason 'scorecard_reversal' is deprecated — a lower re-scored confluence is not a valid " +
+                'exit trigger (the entry score is anti-predictive of outcome). Exit on an objective trigger instead: ' +
+                "'regime_flip' (name the regime change + contradicting_metric), 'risk_limit', a pinned-invalidation hit, " +
+                "or 'operator_command'. If the thesis genuinely broke, use 'regime_flip' and name the signal that flipped.",
+        };
+    }
+    if (!CLOSE_REASONS.includes(args.reason)) {
+        return {
+            ok: false,
+            error: `Invalid close reason: '${args.reason}'. Must be one of: ${CLOSE_REASONS.join(', ')}.`,
+        };
+    }
+    const reason = args.reason;
+    // Operator commands bypass the assessment requirement — operator typing
+    // "close ADA now" via chat doesn't need structured justification.
+    if (reason === 'operator_command') {
+        return { ok: true };
+    }
+    // All other reasons need an assessment object.
+    const a = args.assessment;
+    if (!a || typeof a !== 'object') {
+        return {
+            ok: false,
+            error: `close_position with reason='${reason}' requires an 'assessment' object. ` +
+                'Include entry_score, current_score, entry_regime, current_regime, and contradicting_metric.',
+        };
+    }
+    // Reason-specific consistency checks.
+    switch (reason) {
+        // scorecard_reversal handled earlier by the deprecation reject — no case here.
+        case 'regime_flip': {
+            if (!nonEmptyString(a.entry_regime)) {
+                return { ok: false, error: 'regime_flip requires assessment.entry_regime.' };
+            }
+            if (!nonEmptyString(a.current_regime)) {
+                return { ok: false, error: 'regime_flip requires assessment.current_regime.' };
+            }
+            if (a.entry_regime === a.current_regime) {
+                return {
+                    ok: false,
+                    error: `regime_flip requires current_regime to differ from entry_regime. ` +
+                        `Got entry_regime=current_regime='${a.entry_regime}'. ` +
+                        'If regime is unchanged but you still want to close, this is probably "HOLD" per the decision matrix.',
+                };
+            }
+            if (!nonEmptyString(a.contradicting_metric)) {
+                return {
+                    ok: false,
+                    error: 'regime_flip requires assessment.contradicting_metric describing what changed ' +
+                        '(e.g., "multi-TF alignment flipped from RANGE_WIDE to TREND_DOWN with 4h MACD cross").',
+                };
+            }
+            return { ok: true };
+        }
+        case 'risk_limit': {
+            // Risk-limit triggers are time-sensitive; require a terse justification
+            // but not the full scorecard.
+            if (!nonEmptyString(a.contradicting_metric)) {
+                return {
+                    ok: false,
+                    error: 'risk_limit requires assessment.contradicting_metric naming the metric at threshold ' +
+                        '(e.g., "drawdown utilisation 82% — AMBER zone", "gross exposure 1.9x NAV").',
+                };
+            }
+            return { ok: true };
+        }
+        case 'bracket_integrity': {
+            // Bracket reconciliation edge cases — expect the operator to describe the
+            // condition (e.g., ledger_terminal_no_order + attach_brackets failed).
+            if (!nonEmptyString(a.contradicting_metric)) {
+                return {
+                    ok: false,
+                    error: 'bracket_integrity requires assessment.contradicting_metric with the audit output ' +
+                        '(e.g., "audit_bracket_protection has_stop=false + attach_brackets returned ledger_terminal_no_order after 3 retries").',
+                };
+            }
+            return { ok: true };
+        }
+    }
+    return { ok: true };
+}
+/** 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 function validateCreateOrder(args, isLive) {
+    if (!isLive)
+        return { ok: true };
+    if (!nonEmptyString(args.thesis) || args.thesis.length < 20) {
+        return {
+            ok: false,
+            error: 'create_order in live mode requires a thesis of at least 20 characters. ' +
+                'Briefly describe setup, regime, and the signal driving the entry.',
+        };
+    }
+    if (!nonEmptyString(args.setup_type)) {
+        return {
+            ok: false,
+            error: "create_order in live mode requires setup_type (e.g., 'pullback_to_ema', 'vwap_reversion', 'breakout'). " +
+                'The SKILL.md decision matrix expects it at heartbeat reassessment time.',
+        };
+    }
+    if (!nonEmptyString(args.regime)) {
+        return {
+            ok: false,
+            error: 'create_order in live mode requires regime (e.g., RANGE_WIDE, TREND_UP). ' +
+                'Heartbeat reassessment needs this to detect regime flips.',
+        };
+    }
+    if (typeof args.regime_confidence !== 'number' ||
+        !Number.isFinite(args.regime_confidence) ||
+        args.regime_confidence < 0 ||
+        args.regime_confidence > 100) {
+        return {
+            ok: false,
+            error: 'create_order in live mode requires regime_confidence as a number in [0, 100].',
+        };
+    }
+    if (!isScore(args.confluence_score)) {
+        return {
+            ok: false,
+            error: 'create_order in live mode requires confluence_score as a number in [0, 10]. ' +
+                'Heartbeat reassessment needs this to detect scorecard reversal.',
+        };
+    }
+    const validVerdicts = new Set(['STRONG_GO', 'GO', 'MARGINAL', 'NO_GO']);
+    if (!nonEmptyString(args.scorecard_verdict) || !validVerdicts.has(args.scorecard_verdict)) {
+        return {
+            ok: false,
+            error: `create_order in live mode requires scorecard_verdict in ${[...validVerdicts].join('/')}. ` +
+                "If you don't have a clear verdict, you don't have the setup — skip the trade.",
+        };
+    }
+    // Pinned plan — validate-if-present only (NOT required yet; we add the
+    // capability + indication first, per the 2026-06-05 governing principle).
+    if (args.invalidation_price != null &&
+        (typeof args.invalidation_price !== 'number' ||
+            !Number.isFinite(args.invalidation_price) ||
+            args.invalidation_price <= 0)) {
+        return {
+            ok: false,
+            error: 'create_order: invalidation_price, if provided, must be a positive number — ' +
+                'the price at which the entry thesis is wrong (your pinned "I am wrong here" level).',
+        };
+    }
+    return { ok: true };
+}
+const REALIZATION_RULE_TYPES = new Set(['fixed_target', 'trail', 'scale', 'manual']);
+/** 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 function sanitizeRealizationRule(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    const fin = (v) => typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+    const type = typeof r.type === 'string' && REALIZATION_RULE_TYPES.has(r.type)
+        ? r.type
+        : 'manual';
+    const out = { type };
+    const tp = fin(r.target_price);
+    if (tp != null && tp > 0)
+        out.targetPrice = tp;
+    const ta = fin(r.trail_after_r);
+    if (ta != null)
+        out.trailAfterR = ta;
+    const td = fin(r.trail_distance_r);
+    if (td != null && td > 0)
+        out.trailDistanceR = td;
+    if (Array.isArray(r.scale)) {
+        const rungs = [];
+        for (const s of r.scale) {
+            if (!s || typeof s !== 'object')
+                continue;
+            const o = s;
+            const atR = fin(o.at_r);
+            const fraction = fin(o.fraction);
+            if (atR == null || fraction == null || fraction <= 0 || fraction > 1)
+                continue;
+            rungs.push({ atR, fraction });
+            if (rungs.length >= 6)
+                break;
+        }
+        if (rungs.length > 0)
+            out.scale = rungs;
+    }
+    if (typeof r.note === 'string' && r.note.trim().length > 0) {
+        out.note = r.note.slice(0, 200);
+    }
+    return out;
+}
+// ---- record_position_reviews (Position Decision Journal) ----
+/** 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 const REVIEW_VERDICTS = ['hold', 'add_on', 'close_recommended'];
+export const THESIS_STATUSES = ['intact', 'weakening', 'invalidated', 'evolving'];
+/** 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 function validatePositionReviews(args, ctx) {
+    if (!Array.isArray(args.reviews)) {
+        return { ok: false, error: 'reviews must be an array' };
+    }
+    if (args.reviews.length === 0) {
+        return { ok: false, error: 'reviews must contain at least one entry' };
+    }
+    const seen = new Set();
+    for (let i = 0; i < args.reviews.length; i++) {
+        const r = args.reviews[i];
+        const where = `reviews[${i}]`;
+        if (!nonEmptyString(r.symbol)) {
+            return { ok: false, error: `${where}: symbol required` };
+        }
+        const symbol = r.symbol;
+        if (seen.has(symbol)) {
+            return { ok: false, error: `${where}: duplicate symbol '${symbol}' — one review per position per call` };
+        }
+        seen.add(symbol);
+        if (typeof r.position_open_at !== 'number' || !Number.isFinite(r.position_open_at) || r.position_open_at <= 0) {
+            return { ok: false, error: `${where}: position_open_at required (positive epoch ms)` };
+        }
+        if (!REVIEW_VERDICTS.includes(r.verdict)) {
+            return {
+                ok: false,
+                error: `${where}: verdict must be one of: ${REVIEW_VERDICTS.join(', ')}`,
+            };
+        }
+        const verdict = r.verdict;
+        if (!THESIS_STATUSES.includes(r.thesis_status)) {
+            return {
+                ok: false,
+                error: `${where}: thesis_status must be one of: ${THESIS_STATUSES.join(', ')}`,
+            };
+        }
+        const thesisStatus = r.thesis_status;
+        // Rule 1 — verdict='hold' AND thesis_status='invalidated' is a logical contradiction.
+        if (verdict === 'hold' && thesisStatus === 'invalidated') {
+            return {
+                ok: false,
+                error: `${where}: verdict='hold' contradicts thesis_status='invalidated'. If thesis is invalidated, file verdict='close_recommended' or call close_position.`,
+            };
+        }
+        // Numeric required fields.
+        if (!isFiniteNumber(r.entry_score))
+            return { ok: false, error: `${where}: entry_score required (number)` };
+        if (!isFiniteNumber(r.current_score))
+            return { ok: false, error: `${where}: current_score required (number)` };
+        if (!isFiniteNumber(r.score_delta))
+            return { ok: false, error: `${where}: score_delta required (number)` };
+        // Rule 3 — internal consistency between scores and delta (float tolerance).
+        const computedDelta = r.current_score - r.entry_score;
+        if (Math.abs(computedDelta - r.score_delta) > 0.01) {
+            return {
+                ok: false,
+                error: `${where}: score_delta=${r.score_delta} inconsistent with current_score=${r.current_score} - entry_score=${r.entry_score} = ${computedDelta.toFixed(3)}`,
+            };
+        }
+        if (!isFiniteNumber(r.regime_confidence) || r.regime_confidence < 0 || r.regime_confidence > 1) {
+            return { ok: false, error: `${where}: regime_confidence required in [0, 1]` };
+        }
+        if (!isFiniteNumber(r.r_multiple))
+            return { ok: false, error: `${where}: r_multiple required` };
+        if (!isFiniteNumber(r.distance_to_stop_bps))
+            return { ok: false, error: `${where}: distance_to_stop_bps required` };
+        if (!isFiniteNumber(r.time_in_position_minutes) || r.time_in_position_minutes < 0) {
+            return { ok: false, error: `${where}: time_in_position_minutes required (non-negative)` };
+        }
+        if (!isFiniteNumber(r.mfe_r))
+            return { ok: false, error: `${where}: mfe_r required` };
+        if (!isFiniteNumber(r.give_back_pct))
+            return { ok: false, error: `${where}: give_back_pct required` };
+        // Rule 5 — r_multiple cannot exceed mfe_r (mfe_r is by definition the max
+        // favourable R seen since entry).
+        if (r.r_multiple > r.mfe_r + 0.01) {
+            return {
+                ok: false,
+                error: `${where}: r_multiple=${r.r_multiple} > mfe_r=${r.mfe_r} is impossible (MFE is the running max).`,
+            };
+        }
+        if (!nonEmptyString(r.regime_entry))
+            return { ok: false, error: `${where}: regime_entry required` };
+        if (!nonEmptyString(r.regime_current))
+            return { ok: false, error: `${where}: regime_current required` };
+        if (!r.confluence_components || typeof r.confluence_components !== 'object' || Array.isArray(r.confluence_components)) {
+            return {
+                ok: false,
+                error: `${where}: confluence_components required (named-boolean object). ` +
+                    `Example: {regime: true, structure: true, momentum: false, flow: true}. ` +
+                    `One key per scorecard gate firing or not firing NOW.`,
+            };
+        }
+        // Rule 4 — what_changed minimum length. Fuzzy-match-against-prior-reviews
+        // is a server-side concern (the validator doesn't have history); enforce
+        // length only here.
+        if (!nonEmptyString(r.what_changed) || r.what_changed.length < 20) {
+            return { ok: false, error: `${where}: what_changed required (≥20 chars describing what shifted since last review)` };
+        }
+        if (!nonEmptyString(r.invalidation_trigger)) {
+            return { ok: false, error: `${where}: invalidation_trigger required (the price/event/time that flips this to CLOSE)` };
+        }
+        // Rule 2 — verdict='add_on' requires +0.5R AND +1.5 score delta vs entry.
+        // Already-prose rule from SKILL.md v2.9; now mechanical.
+        if (verdict === 'add_on') {
+            const r1 = r.r_multiple;
+            const dScore = r.current_score - r.entry_score;
+            if (r1 < 0.5 || dScore < 1.5) {
+                return {
+                    ok: false,
+                    error: `${where}: verdict='add_on' requires r_multiple ≥ +0.5 AND score_delta ≥ +1.5. Got r_multiple=${r1.toFixed(2)}, score_delta=${dScore.toFixed(2)}. Either HOLD this position or wait for confirmation.`,
+                };
+            }
+        }
+    }
+    // Top-level superset rule — every open position must have a review when
+    // gate-mode is 'enforce'. Soft warning at lower modes happens at the call
+    // site, not here.
+    //
+    // Symbol form caveat: Binance live `getPositions()` returns settle-suffixed
+    // unified symbols ('SOL/USDT:USDT'), while the state-store + agent-side
+    // reviews use the canonical 'SOL/USDT'. Normalize BOTH sides — the call site
+    // normalizes openSymbols defensively too, but doing it here as well makes
+    // the validator robust against any caller that forwards raw forms.
+    if (ctx?.openSymbols && ctx.gateMode === 'enforce') {
+        const reviewedSymbols = new Set();
+        for (const r of args.reviews) {
+            if (typeof r.symbol === 'string')
+                reviewedSymbols.add(normalizeBracketSymbol(r.symbol));
+        }
+        const missing = [];
+        for (const s of ctx.openSymbols) {
+            if (!reviewedSymbols.has(normalizeBracketSymbol(s)))
+                missing.push(s);
+        }
+        if (missing.length > 0) {
+            return {
+                ok: false,
+                error: `record_position_reviews missing reviews for open positions: ${missing.join(', ')}. Pass one entry per open position.`,
+            };
+        }
+    }
+    return { ok: true };
+}
+function isFiniteNumber(v) {
+    return typeof v === 'number' && Number.isFinite(v);
+}

package/tools/attach-brackets.d.ts

@@ -0,0 +1,34 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+interface AttachBracketsArgs {
+    symbol: string;
+    stop_price?: number;
+    target_price?: number;
+}
+interface AttachBracketsSuccess {
+    ok: true;
+    symbol: string;
+    bracket_id: string;
+    entry_side: 'buy' | 'sell';
+    stop_price?: number;
+    target_price?: number;
+    sl_cid?: string;
+    tp_cid?: string;
+    attach_latency_ms: number;
+    cancelled_stale_bracket_orders: number;
+    cleared_stale_ledger_row: boolean;
+    attempts: number;
+    /** True when the call short-circuited because the requested protection
+     *  is already live on the exchange with matching prices — no new orders
+     *  were placed. Set by the 2026-05-15 idempotency change so the agent's
+     *  defensive re-attach loop doesn't tear down and reattach a working
+     *  bracket pair, which is what produced the audit→reattach spiral.
+     */
+    idempotent_no_op?: boolean;
+    note?: string;
+}
+export declare function attachBracketsTool(args: AttachBracketsArgs, deps: {
+    adapter: IExchangeAdapter;
+}): Promise<AttachBracketsSuccess | {
+    error: string;
+}>;
+export {};