@reefclaw/openclaw-plugin 0.1.0

package/tools/scan-pairs.js

@@ -0,0 +1,220 @@
+// Tool: scan_pairs — scan all symbols for strategy setups.
+// Fetches pre-computed facts from intelligence, evaluates user's active strategies,
+// ranks by confluence score, returns concise summary (~300 tokens).
+//
+// Caching: facts and strategies share a process-wide cache with get_setup_detail
+// (see intel-cache.ts). The shared cache eliminates the 2026-05-15 scan vs
+// drill-down divergence — after a heartbeat scan, every get_setup_detail call
+// for a symbol in the scan set sees the same snapshot the scan ranked it from.
+//
+// Learning pre-filter (2026-05-15): when decisionsDeps are wired, the scan
+// fetches the user's confirmed entry-time learnings and splits results into
+// `rankings` (no matching learning) and `vetoed_setups` (matching learning
+// surfaced inline with the directive). The agent's eye lands on actionable
+// candidates first; vetoed candidates are still visible so the agent can
+// apply override conditions if the directive allows. Saves the drill-in
+// round-trip on the ~6 macd_oversold_reversal-style candidates per
+// heartbeat the agent was rejecting post-scorecard pre-fix.
+import { scanAllPairs } from '../strategy/evaluator.js';
+import { getAllFactsCached, getStrategiesCached, __testing__ as cacheTesting } from './intel-cache.js';
+import { normalizeSetupFamily, resolveTriggerFamilies } from '../learning/setup-family.js';
+const LEARNINGS_TTL_MS = 60_000;
+const entryLearningsCache = new Map();
+/** Family-keying gate (2026-06-22). Off by default → byte-identical exact-match
+ *  behaviour. On → scan veto matches by stable setup_family, surviving the agent's
+ *  free-text setup_type drift. See docs/CLAUDE/learning-loop.md. */
+function familyKeyingEnabled() {
+    return process.env.RC_LEARNING_FAMILY_KEYING === 'on';
+}
+async function getEntryLearningsCached(client, userId) {
+    const now = Date.now();
+    const cached = entryLearningsCache.get(userId);
+    if (cached && now < cached.expiry)
+        return cached.value;
+    // No setup_type / regime filter — we want ALL the user's entry-time
+    // learnings so we can match them against every candidate locally.
+    let resp;
+    try {
+        resp = await client.getRelevantLearnings(userId, { appliesAt: 'entry' });
+    }
+    catch {
+        return [];
+    }
+    const value = resp?.learnings ?? [];
+    entryLearningsCache.set(userId, { value, expiry: now + LEARNINGS_TTL_MS });
+    return value;
+}
+/** True iff the learning's triggerCondition applies to the (setup, regime)
+ *  pair, with rules tightened for scan-time pre-filter use.
+ *
+ *  Two key differences vs the looser webapp matcher in
+ *  /api/internal/learnings:
+ *
+ *  1. CAMEL/SNAKE TOLERANCE. The pattern miner emits `setupType` (camelCase)
+ *     into mined_patterns.match_conditions, which is copied verbatim into
+ *     learnings.trigger_condition on operator confirm. The webapp matcher
+ *     reads `setup_type` only, so every confirmed learning silently falls
+ *     through to the "missing key = wildcard" branch and matches every
+ *     query. That broke scan_pairs' vetoed_setups bucket on the first live
+ *     soak after the 2026-05-15 deploy — every candidate got pushed into
+ *     vetoed because every learning was matching every candidate. We
+ *     accept both forms here so the transition + write-side fix can land
+ *     without bricking the matcher in between.
+ *
+ *  2. NO WILDCARD MATCH AT SCAN TIME. A learning with empty / missing
+ *     trigger keys is intended as "applies broadly — remember this rule"
+ *     at decision time (entry/heartbeat/close), NOT as "veto every scan
+ *     candidate". For scan_pairs specifically, we require the trigger to
+ *     pin AT LEAST ONE of {setup, regime} explicitly. Otherwise scan
+ *     produces zero rankings and the agent has to bypass the scanner
+ *     entirely — which is what the 2026-05-15 16:53 UTC heartbeat reported.
+ */
+function learningMatches(learning, setupType, regime) {
+    const t = learning.triggerCondition;
+    if (!t || typeof t !== 'object')
+        return false; // no constraints → not a scan veto
+    const tObj = t;
+    // Accept either snake_case or camelCase from the JSONB. Snake_case is the
+    // canonical form (matches plugin tool args, SKILL.md, validator); camelCase
+    // is the transitional form the pattern miner emitted pre-2026-05-15.
+    const tSetup = tObj.setup_type ?? tObj.setupType;
+    const tRegime = tObj.regime ?? tObj.regimeKey;
+    const tFamily = tObj.setup_family ?? tObj.setupFamily;
+    if (familyKeyingEnabled()) {
+        // Family-aware scan veto (2026-06-22): match by stable setup_family so a
+        // confirmed "avoid X" learning keeps vetoing the family as the agent renames
+        // its setups. resolveTriggerFamilies normalizes setup_type → family, or uses
+        // an explicit setup_family from the family-keyed miner.
+        const targetFamilies = resolveTriggerFamilies(tFamily, tSetup);
+        // Still require at least one constraint (setup family OR regime) — an empty
+        // trigger must NOT veto every candidate (the 2026-05-15 wildcard bug).
+        if (targetFamilies == null && tRegime == null)
+            return false;
+        if (targetFamilies != null &&
+            !targetFamilies.includes(normalizeSetupFamily(setupType))) {
+            return false;
+        }
+        if (tRegime != null) {
+            if (Array.isArray(tRegime)) {
+                if (!tRegime.includes(regime))
+                    return false;
+            }
+            else if (tRegime !== regime)
+                return false;
+        }
+        return true;
+    }
+    // Legacy exact-match veto (default).
+    // Require at least one constraint to count as a scan-time veto.
+    if (tSetup == null && tRegime == null)
+        return false;
+    if (tSetup != null) {
+        if (Array.isArray(tSetup)) {
+            if (!tSetup.includes(setupType))
+                return false;
+        }
+        else if (tSetup !== setupType)
+            return false;
+    }
+    if (tRegime != null) {
+        if (Array.isArray(tRegime)) {
+            if (!tRegime.includes(regime))
+                return false;
+        }
+        else if (tRegime !== regime)
+            return false;
+    }
+    return true;
+}
+export async function scanPairsTool(args, deps, decisionsDeps) {
+    const minScore = args.min_score ?? 4;
+    // 1. Fetch all symbol facts (cached, shared with get_setup_detail)
+    const factsRes = await getAllFactsCached(deps);
+    if ('error' in factsRes)
+        return factsRes;
+    let facts = factsRes;
+    // Optional symbols filter — narrows the scan to a watchlist.
+    if (Array.isArray(args.symbols) && args.symbols.length > 0) {
+        const wl = new Set(args.symbols.map(s => s.toUpperCase()));
+        facts = facts.filter(f => wl.has(f.symbol.toUpperCase()));
+    }
+    if (facts.length === 0) {
+        return {
+            error: args.symbols && args.symbols.length > 0
+                ? `No facts available for the requested symbols (${args.symbols.join(', ')}). Intelligence may still be computing initial data, or the symbols are unsupported.`
+                : 'No symbol facts available. Intelligence service may still be computing initial data.',
+        };
+    }
+    // 2. Fetch user's active strategies (cached, shared with get_setup_detail)
+    const stratRes = await getStrategiesCached(deps);
+    if ('error' in stratRes)
+        return stratRes;
+    const strategies = stratRes;
+    if (strategies.length === 0) {
+        return {
+            timestamp: new Date().toISOString(),
+            pairs_scanned: facts.length,
+            setups_found: 0,
+            note: 'No active strategies. Create or activate strategies using save_strategy or toggle_strategy.',
+            rankings: [],
+            no_setup: facts.map(f => f.symbol),
+        };
+    }
+    // 3. Evaluate all strategies against all facts
+    const results = scanAllPairs(strategies, facts, minScore);
+    // 4. Fetch user's confirmed entry-time learnings (optional path — fail
+    //    quietly when the decisions client isn't wired, e.g. in dev or in
+    //    tests that exercise the pre-learning behaviour).
+    let entryLearnings = [];
+    if (decisionsDeps?.decisionsClient && decisionsDeps.userId) {
+        entryLearnings = await getEntryLearningsCached(decisionsDeps.decisionsClient, decisionsDeps.userId);
+    }
+    const rankings = [];
+    const vetoed = [];
+    for (const r of results) {
+        const matches = entryLearnings.filter(l => learningMatches(l, r.strategy, r.regime));
+        const out = {
+            symbol: r.symbol,
+            score: r.score,
+            regime: r.regime,
+            strategy: r.strategy,
+            conditions: `${r.conditionsMet}/${r.conditionsTotal} met: ${r.conditions.filter(c => c.met).map(c => c.name).join(', ')}`,
+            summary: r.summary,
+        };
+        if (matches.length === 0) {
+            rankings.push(out);
+        }
+        else {
+            vetoed.push({
+                ...out,
+                matched_learnings: matches.map(l => ({
+                    id: l.id, title: l.title, directive: l.directive,
+                })),
+            });
+        }
+        if (rankings.length >= 10)
+            break;
+    }
+    // 6. Build concise response
+    const setupSymbols = new Set(results.map(r => r.symbol));
+    const noSetup = facts
+        .map(f => f.symbol)
+        .filter(s => !setupSymbols.has(s));
+    return {
+        timestamp: new Date().toISOString(),
+        pairs_scanned: facts.length,
+        setups_found: results.length,
+        rankings,
+        vetoed_setups: vetoed.length > 0 ? vetoed : undefined,
+        no_setup: noSetup.length > 5
+            ? [...noSetup.slice(0, 5), `...${noSetup.length - 5} others`]
+            : noSetup,
+    };
+}
+// Test-only — clears the shared in-memory TTL caches between unit tests.
+export const __testing__ = {
+    resetCaches() {
+        cacheTesting.resetCaches();
+        entryLearningsCache.clear();
+    },
+};

package/tools/score-setup.d.ts

@@ -0,0 +1,31 @@
+import type { IntelApiDeps } from './intel-api.js';
+interface ScoreSetupArgs {
+    symbol: string;
+    direction: 'LONG' | 'SHORT';
+    setup_type: string;
+    entry_price: number;
+    stop_price: number;
+    target_price: number;
+}
+interface DimensionScore {
+    score: number;
+    detail: string;
+    pass: boolean;
+}
+interface ScorecardResult {
+    composite: number;
+    verdict: 'STRONG_GO' | 'GO' | 'MARGINAL' | 'NO_GO';
+    dimensions: {
+        riskReward: DimensionScore;
+        regimeAlignment: DimensionScore;
+        regimeConfidence: DimensionScore;
+        setupEdge: DimensionScore;
+        flowAlignment: DimensionScore;
+    };
+    flags: string[];
+    recommendation: string;
+}
+export declare function scoreSetupTool(args: ScoreSetupArgs, deps: IntelApiDeps): Promise<ScorecardResult | {
+    error: string;
+}>;
+export {};

package/tools/score-setup.js

@@ -0,0 +1,268 @@
+// Tool: score_setup — Pre-trade setup scorecard.
+// Consolidates regime, feedback, and flow data into a single scored verdict.
+// Forces the agent to only trade high-quality setups.
+import { fetchIntelApi, enc } from './intel-api.js';
+import { getTradingParams } from '../trading-params-cache.js';
+export async function scoreSetupTool(args, deps) {
+    const { symbol, direction, setup_type, entry_price, stop_price, target_price } = args;
+    // Validate inputs
+    if (direction === 'LONG' && stop_price >= entry_price) {
+        return { error: 'For LONG: stop_price must be below entry_price' };
+    }
+    if (direction === 'SHORT' && stop_price <= entry_price) {
+        return { error: 'For SHORT: stop_price must be above entry_price' };
+    }
+    // Fetch all intelligence data + trading params in parallel
+    const s = enc(symbol);
+    const [regimeData, feedbackData, flowData, tp] = await Promise.all([
+        fetchIntelApi(`/api/regime/${s}`, deps),
+        fetchIntelApi(`/api/analytics/${s}/feedback`, deps),
+        fetchIntelApi(`/api/trade-flow/${s}?minutes=5`, deps),
+        getTradingParams(deps),
+    ]);
+    const flags = [];
+    // ── Dimension 1: Risk/Reward ──
+    const risk = Math.abs(entry_price - stop_price);
+    const reward = Math.abs(target_price - entry_price);
+    const rr = risk > 0 ? reward / risk : 0;
+    let rrScore;
+    if (rr >= 3)
+        rrScore = 10;
+    else if (rr >= 2.5)
+        rrScore = 9;
+    else if (rr >= 2)
+        rrScore = 8;
+    else if (rr >= 1.5)
+        rrScore = 6;
+    else if (rr >= 1)
+        rrScore = 4;
+    else
+        rrScore = 2;
+    if (rr < tp.rrWarningThreshold)
+        flags.push(`Poor R:R (${rr.toFixed(2)}:1) — minimum ${tp.rrWarningThreshold}:1 recommended`);
+    const riskReward = {
+        score: rrScore,
+        detail: `R:R ${rr.toFixed(2)}:1 (risk $${risk.toFixed(2)}, reward $${reward.toFixed(2)})`,
+        pass: rrScore >= 5,
+    };
+    // ── Dimension 2: Regime Alignment ──
+    let regimeScore = 5; // neutral default
+    let regimeDetail = 'Regime data unavailable';
+    if (!('error' in regimeData)) {
+        const regime = String(regimeData.regime ?? '').toUpperCase();
+        const confidence = Number(regimeData.confidence ?? 0);
+        const bullishRegimes = ['TREND_UP', 'VOLATILITY_EXPANSION'];
+        const bearishRegimes = ['TREND_DOWN'];
+        const neutralRegimes = ['RANGE_TIGHT', 'RANGE_WIDE'];
+        const avoidRegimes = ['AVOID', 'UNKNOWN'];
+        if (avoidRegimes.includes(regime)) {
+            regimeScore = 1;
+            regimeDetail = `Regime ${regime} — NO trading recommended`;
+            flags.push(`Regime is ${regime} — do not trade`);
+        }
+        else if (direction === 'LONG' && bullishRegimes.includes(regime)) {
+            regimeScore = 9;
+            regimeDetail = `${regime} aligns with LONG direction`;
+        }
+        else if (direction === 'SHORT' && bearishRegimes.includes(regime)) {
+            regimeScore = 9;
+            regimeDetail = `${regime} aligns with SHORT direction`;
+        }
+        else if (direction === 'LONG' && bearishRegimes.includes(regime)) {
+            regimeScore = 2;
+            regimeDetail = `${regime} opposes LONG direction`;
+            flags.push(`Trading LONG against ${regime} regime`);
+        }
+        else if (direction === 'SHORT' && bullishRegimes.includes(regime)) {
+            regimeScore = 2;
+            regimeDetail = `${regime} opposes SHORT direction`;
+            flags.push(`Trading SHORT against ${regime} regime`);
+        }
+        else if (neutralRegimes.includes(regime)) {
+            regimeScore = 5;
+            regimeDetail = `${regime} — neutral for ${direction}. Mean reversion setups preferred.`;
+        }
+        // Adjust for confidence — only penalize below user-configured threshold
+        if (confidence < tp.confidencePenaltyThreshold && !avoidRegimes.includes(regime)) {
+            regimeScore = Math.max(3, regimeScore - 2);
+            flags.push(`Low regime confidence (${(confidence * 100).toFixed(0)}%) — treat with caution`);
+        }
+    }
+    const regimeAlignment = {
+        score: regimeScore,
+        detail: regimeDetail,
+        pass: regimeScore >= 5,
+    };
+    // ── Dimension 3: Regime Confidence ──
+    let confScore = 5;
+    let confDetail = 'Regime confidence unavailable';
+    if (!('error' in regimeData)) {
+        const confidence = Number(regimeData.confidence ?? 0);
+        confScore = Math.round(confidence * 10);
+        confDetail = `Regime confidence: ${(confidence * 100).toFixed(0)}%`;
+        if (confidence < tp.confidencePenaltyThreshold) {
+            flags.push(`Regime classifier uncertain (${(confidence * 100).toFixed(0)}%)`);
+        }
+    }
+    const regimeConfidence = {
+        score: confScore,
+        detail: confDetail,
+        pass: confScore >= 5,
+    };
+    // ── Dimension 4: Setup Edge (from feedback) ──
+    let edgeScore = 5;
+    let edgeDetail = 'No feedback data for this setup type';
+    if (!('error' in feedbackData)) {
+        const fb = feedbackData;
+        const bySetup = fb.bySetupType;
+        if (bySetup) {
+            const match = bySetup.find((s) => String(s.setupType).toLowerCase() === setup_type.toLowerCase());
+            if (match) {
+                const verdict = String(match.verdict ?? '');
+                const edgeTrend = String(match.edgeTrend ?? 'insufficient_data');
+                const winRate = Number(match.winRate ?? 0);
+                const winRate20 = match.winRate20 != null ? Number(match.winRate20) : null;
+                const trades = Number(match.trades ?? 0);
+                if (verdict === 'STRONG')
+                    edgeScore = 9;
+                else if (verdict === 'WORKING')
+                    edgeScore = 7;
+                else if (verdict === 'MARGINAL')
+                    edgeScore = 4;
+                else if (verdict === 'FAILING') {
+                    edgeScore = 2;
+                    flags.push(`Setup "${setup_type}" is FAILING — use half size or skip`);
+                }
+                // Adjust for edge trend
+                if (edgeTrend === 'declining') {
+                    edgeScore = Math.max(1, edgeScore - 2);
+                    flags.push(`Setup "${setup_type}" edge is declining — reduce size`);
+                }
+                else if (edgeTrend === 'improving') {
+                    edgeScore = Math.min(10, edgeScore + 1);
+                }
+                const wrStr = winRate20 != null
+                    ? `${(winRate20 * 100).toFixed(0)}% (last 20) / ${(winRate * 100).toFixed(0)}% (all)`
+                    : `${(winRate * 100).toFixed(0)}%`;
+                edgeDetail = `${setup_type}: ${verdict} (${wrStr}, ${trades} trades, trend: ${edgeTrend})`;
+            }
+            else {
+                edgeScore = tp.unprovenSetupScore;
+                edgeDetail = `No history for "${setup_type}" — new setup, proceed with reduced size`;
+                flags.push(`First time using setup "${setup_type}" — reduce size`);
+            }
+        }
+    }
+    const setupEdge = {
+        score: edgeScore,
+        detail: edgeDetail,
+        pass: edgeScore >= 5,
+    };
+    // ── Dimension 5: Institutional Flow Alignment ──
+    let flowScore = 5;
+    let flowDetail = 'Flow data unavailable';
+    if (!('error' in flowData)) {
+        const flow = flowData;
+        const pressure = String(flow.whalePressure ?? 'neutral').toLowerCase();
+        const ratio = Number(flow.buySellRatio ?? 1);
+        const largeRatio = Number(flow.largeTradeRatio ?? 0);
+        const bullishFlow = pressure === 'strong_buy' || pressure === 'buy';
+        const bearishFlow = pressure === 'strong_sell' || pressure === 'sell';
+        if (direction === 'LONG') {
+            if (pressure === 'strong_buy')
+                flowScore = 10;
+            else if (pressure === 'buy')
+                flowScore = 8;
+            else if (pressure === 'neutral')
+                flowScore = 5;
+            else if (pressure === 'sell')
+                flowScore = 3;
+            else if (pressure === 'strong_sell') {
+                flowScore = 1;
+                flags.push('Institutional flow strongly AGAINST your LONG direction');
+            }
+        }
+        else {
+            if (pressure === 'strong_sell')
+                flowScore = 10;
+            else if (pressure === 'sell')
+                flowScore = 8;
+            else if (pressure === 'neutral')
+                flowScore = 5;
+            else if (pressure === 'buy')
+                flowScore = 3;
+            else if (pressure === 'strong_buy') {
+                flowScore = 1;
+                flags.push('Institutional flow strongly AGAINST your SHORT direction');
+            }
+        }
+        // Bonus for high institutional activity
+        if (largeRatio > 0.15 && ((direction === 'LONG' && bullishFlow) || (direction === 'SHORT' && bearishFlow))) {
+            flowScore = Math.min(10, flowScore + 1);
+        }
+        flowDetail = `Whale pressure: ${pressure}, buy/sell ratio: ${ratio.toFixed(2)}, institutional volume: ${(largeRatio * 100).toFixed(1)}%`;
+    }
+    const flowAlignment = {
+        score: flowScore,
+        detail: flowDetail,
+        pass: flowScore >= 5,
+    };
+    // ── Composite Score (weighted average) ──
+    const weights = {
+        riskReward: 2, // R:R is fundamental
+        regimeAlignment: 3, // regime is the most important filter
+        regimeConfidence: 1, // confidence matters but less than alignment
+        setupEdge: 2.5, // your track record with this setup
+        flowAlignment: 1.5, // institutional confirmation
+    };
+    const totalWeight = weights.riskReward + weights.regimeAlignment + weights.regimeConfidence + weights.setupEdge + weights.flowAlignment;
+    const composite = (riskReward.score * weights.riskReward +
+        regimeAlignment.score * weights.regimeAlignment +
+        regimeConfidence.score * weights.regimeConfidence +
+        setupEdge.score * weights.setupEdge +
+        flowAlignment.score * weights.flowAlignment) / totalWeight;
+    // ── Verdict ──
+    let verdict;
+    if (composite >= tp.scorecardStrongGoThreshold)
+        verdict = 'STRONG_GO';
+    else if (composite >= tp.scorecardGoThreshold)
+        verdict = 'GO';
+    else if (composite >= tp.scorecardMarginalThreshold)
+        verdict = 'MARGINAL';
+    else
+        verdict = 'NO_GO';
+    // Hard vetoes — any critical failure overrides composite
+    if (regimeScore <= 2)
+        verdict = 'NO_GO';
+    if (edgeScore <= 1)
+        verdict = 'NO_GO';
+    // ── Recommendation ──
+    let recommendation;
+    switch (verdict) {
+        case 'STRONG_GO':
+            recommendation = `High-quality setup. ${setup_type} ${direction} with ${rr.toFixed(1)}:1 R:R — all dimensions aligned.`;
+            break;
+        case 'GO':
+            recommendation = `Acceptable setup. Proceed with standard sizing. Watch: ${flags.length > 0 ? flags[0] : 'no concerns'}.`;
+            break;
+        case 'MARGINAL':
+            recommendation = `Borderline setup. If you trade this, use half size. Issues: ${flags.join('; ') || 'multiple dimensions below threshold'}.`;
+            break;
+        case 'NO_GO':
+            recommendation = `Do not trade. ${flags.join('; ') || 'Multiple critical failures'}.`;
+            break;
+    }
+    return {
+        composite: +composite.toFixed(1),
+        verdict,
+        dimensions: {
+            riskReward,
+            regimeAlignment,
+            regimeConfidence,
+            setupEdge,
+            flowAlignment,
+        },
+        flags,
+        recommendation,
+    };
+}

package/tools/set-bracket-requirement.d.ts

@@ -0,0 +1,18 @@
+export type BracketRequirementFlag = 'requireStopLoss' | 'requireTakeProfit';
+export interface SetBracketRequirementArgs {
+    flag: BracketRequirementFlag;
+    value: boolean;
+}
+export interface SetBracketRequirementResult {
+    ok: boolean;
+    flag: BracketRequirementFlag;
+    previousValue: boolean;
+    value: boolean;
+    warning?: string;
+    error?: string;
+}
+export interface SetBracketRequirementDeps {
+    /** Override the config file path — tests use this. */
+    configPath?: string;
+}
+export declare function setBracketRequirementTool(args: SetBracketRequirementArgs, deps?: SetBracketRequirementDeps): SetBracketRequirementResult;

package/tools/set-bracket-requirement.js

@@ -0,0 +1,81 @@
+// set_bracket_requirement — operator-only plugin tool.
+//
+// Flips requireStopLoss or requireTakeProfit in plugin-config.json. The
+// dashboard's Trading Parameters panel calls this when the operator toggles
+// one of the TP/SL checkboxes.
+//
+// Design decisions:
+//   - No adapter swap needed — the pre-trade gate reads flags via
+//     loadBracketRequirements() on every create_order call, so changes take
+//     effect on the very next order.
+//   - Disabling either flag returns `warning: true` + a human message so the
+//     UI can render the confirmation banner ("you are accepting unprotected
+//     trades").
+//   - Default refusal: the agent must NOT call this — the skill layer is
+//     expected to guard with operator-only scope. This handler stays
+//     functional but unguarded for parity with set_trading_mode.
+import { readPluginConfig, updatePluginConfig } from '../config/plugin-config-io.js';
+import { getBracketRequirements } from '../config/brackets-config.js';
+import { formatError } from '../logger.js';
+export function setBracketRequirementTool(args, deps = {}) {
+    if (!args || (args.flag !== 'requireStopLoss' && args.flag !== 'requireTakeProfit')) {
+        return {
+            ok: false,
+            flag: args?.flag ?? 'requireStopLoss',
+            previousValue: true,
+            value: true,
+            error: `Invalid flag. Must be 'requireStopLoss' or 'requireTakeProfit'.`,
+        };
+    }
+    if (typeof args.value !== 'boolean') {
+        return {
+            ok: false,
+            flag: args.flag,
+            previousValue: true,
+            value: true,
+            error: `value must be a boolean.`,
+        };
+    }
+    let previousValue;
+    try {
+        const current = readPluginConfig(deps.configPath);
+        previousValue = getBracketRequirements(current)[args.flag];
+    }
+    catch (err) {
+        return {
+            ok: false,
+            flag: args.flag,
+            previousValue: true,
+            value: args.value,
+            error: `Cannot read config: ${formatError(err)}`,
+        };
+    }
+    try {
+        updatePluginConfig({ brackets: { [args.flag]: args.value } }, deps.configPath);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            flag: args.flag,
+            previousValue,
+            value: args.value,
+            error: `Cannot write config: ${formatError(err)}`,
+        };
+    }
+    const result = {
+        ok: true,
+        flag: args.flag,
+        previousValue,
+        value: args.value,
+    };
+    // Warning copy surfaces in the dashboard as a confirmation banner.
+    if (!args.value) {
+        if (args.flag === 'requireStopLoss') {
+            result.warning = 'Stop-loss requirement disabled. Live trades may be submitted without a stop — downside is unbounded on adverse moves. Re-enable as soon as you are done with the override.';
+        }
+        else {
+            result.warning = 'Take-profit requirement disabled. Live trades may run without a target — operator must monitor exits manually.';
+        }
+    }
+    return result;
+}

package/tools/set-exchange-credentials.d.ts

@@ -0,0 +1,25 @@
+import type { PluginRuntime } from '../onboarding/runtime.js';
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { TradingMode } from '../types.js';
+export interface SetExchangeCredentialsArgs {
+    apiKey: string;
+    secret: string;
+    testnet?: boolean;
+}
+export interface SetExchangeCredentialsResult {
+    ok: boolean;
+    message: string;
+    fingerprint: string;
+    reconnected: boolean;
+    mode: TradingMode;
+    readiness: string;
+}
+export interface SetExchangeCredentialsDeps {
+    runtime: PluginRuntime;
+    adapterDeps: {
+        adapter: IExchangeAdapter;
+    };
+    /** Override the config file path — tests use this. */
+    configPath?: string;
+}
+export declare function setExchangeCredentialsTool(args: SetExchangeCredentialsArgs, deps: SetExchangeCredentialsDeps): Promise<SetExchangeCredentialsResult>;