@reefclaw/openclaw-plugin 0.1.0

package/tools/get-risk-scenario.d.ts

@@ -0,0 +1,29 @@
+import type { IntelApiDeps } from './intel-api.js';
+/** Matches simulator Position type */
+interface SimPosition {
+    symbol: string;
+    side: 'long' | 'short';
+    entryPrice: number;
+    quantity: number;
+}
+/** Matches simulator Wallet shape */
+interface SimWallet {
+    [currency: string]: {
+        total: number;
+        available: number;
+        locked: number;
+    };
+}
+export interface RiskScenarioDeps {
+    getPositions(): SimPosition[];
+    getWallet(): SimWallet;
+    getLastPrice(symbol: string): number | null;
+    intelApiDeps: IntelApiDeps;
+}
+export declare function getRiskScenarioTool(args: {
+    symbol: string;
+    moves?: string;
+}, deps: RiskScenarioDeps): Promise<Record<string, unknown> | {
+    error: string;
+}>;
+export {};

package/tools/get-risk-scenario.js

@@ -0,0 +1,47 @@
+// Tool: get_risk_scenario — stress test current positions against hypothetical price moves.
+// Fetches positions + balance from simulator state, then calls Intelligence API for scenario analysis.
+// Returns: per-scenario P&L, heat, drawdown zone, stops triggered, limits breached.
+import { enc } from './intel-api.js';
+import { fetchIntelApi } from './intel-api.js';
+export async function getRiskScenarioTool(args, deps) {
+    const positions = deps.getPositions();
+    const wallet = deps.getWallet();
+    const balance = wallet.USDT?.total ?? 0;
+    if (balance <= 0) {
+        return { error: 'No balance found. Cannot compute risk scenarios.' };
+    }
+    // Build positions for the API
+    const apiPositions = positions.map(pos => {
+        const currentPrice = deps.getLastPrice(pos.symbol) ?? pos.entryPrice;
+        const side = pos.side === 'long' ? 'LONG' : 'SHORT';
+        // Default stop: 2% from entry (no stop data in simulator positions)
+        const stopPrice = side === 'LONG' ? pos.entryPrice * 0.98 : pos.entryPrice * 1.02;
+        return {
+            symbol: pos.symbol,
+            side,
+            entryPrice: pos.entryPrice,
+            currentPrice,
+            stopPrice,
+            quantity: pos.quantity,
+            notional: pos.quantity * currentPrice,
+        };
+    });
+    // Parse custom moves if provided
+    let scenarios;
+    if (args.moves) {
+        scenarios = args.moves.split(',').map(s => ({
+            movePct: parseFloat(s.trim()),
+        })).filter(s => !isNaN(s.movePct));
+    }
+    // Normalize symbol for intelligence API (BTC/USDT → BTCUSDT)
+    const intelSymbol = args.symbol.replace('/', '');
+    const body = {
+        positions: apiPositions,
+        balance,
+        ...(scenarios && scenarios.length > 0 && { scenarios }),
+    };
+    return fetchIntelApi(`/api/risk-scenario/${enc(intelSymbol)}`, deps.intelApiDeps, {
+        method: 'POST',
+        body,
+    });
+}

package/tools/get-risk-summary.d.ts

@@ -0,0 +1,51 @@
+import type { ExchangeSimulator } from '../simulator/exchange-simulator.js';
+import type { ShadowTracker } from '../shadow/shadow-tracker.js';
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { TradingMode } from '../types.js';
+export interface RiskSummaryResult {
+    tradingMode: TradingMode;
+    totalEquity: number;
+    availableBalance: number;
+    lockedBalance: number;
+    grossExposure: number;
+    grossExposurePercent: number;
+    netExposure: number;
+    netExposurePercent: number;
+    positionCount: number;
+    unrealizedPnl: number;
+    unrealizedPnlPercent: number;
+    positions: Array<{
+        symbol: string;
+        side: 'long' | 'short';
+        quantity: number;
+        entryPrice: number;
+        markPrice: number;
+        notional: number;
+        unrealizedPnl: number;
+        portfolioPercent: number;
+    }>;
+    heatScore: number;
+    heatLevel: 'low' | 'moderate' | 'elevated' | 'high' | 'critical';
+    executionStats?: {
+        totalTrades: number;
+        avgSlippageBps: number;
+        worstSlippageBps: number;
+        totalFeesPaid: number;
+        avgLatencyMs: number;
+    };
+    shadowMetrics?: {
+        totalShadowTrades: number;
+        avgDeltaBps: number;
+        worstDeltaBps: number;
+        tradingDays: number;
+        readyForUpgrade: boolean;
+        upgradeBlockers: string[];
+    };
+    timestamp: string;
+}
+export declare function getRiskSummaryTool(_args: Record<string, never>, deps: {
+    simulator: ExchangeSimulator;
+    tradingMode?: TradingMode;
+    shadowTracker?: ShadowTracker | null;
+    adapter?: IExchangeAdapter;
+}): Promise<RiskSummaryResult>;

package/tools/get-risk-summary.js

@@ -0,0 +1,118 @@
+// Tool: get_risk_summary — current portfolio risk metrics
+// Returns exposure, drawdown, heat score, position count — everything
+// the agent needs for risk-aware decision making.
+import { getQuoteBalance, getQuoteWalletBalance } from '../balance-utils.js';
+export async function getRiskSummaryTool(_args, deps) {
+    // In live modes, use real exchange data instead of simulator
+    let balance;
+    let positions;
+    if (deps.adapter?.isLive) {
+        [balance, positions] = await Promise.all([
+            deps.adapter.getBalance(),
+            deps.adapter.getPositions(),
+        ]);
+    }
+    else {
+        balance = deps.simulator.getBalance();
+        positions = deps.simulator.getPositions();
+    }
+    // Wallet values — totalEquity uses BNFCR-aware reader for Binance Futures
+    // multi-asset accounts; free/used stay map-based (those are derived
+    // cross-margin numbers that don't compose the same way).
+    const totalEquity = getQuoteWalletBalance(balance);
+    const availableBalance = getQuoteBalance(balance.free);
+    const lockedBalance = getQuoteBalance(balance.used);
+    // Exposure calculations
+    let grossExposure = 0;
+    let longExposure = 0;
+    let shortExposure = 0;
+    let totalUnrealizedPnl = 0;
+    const positionDetails = positions.map((pos) => {
+        const notional = Math.abs(pos.notional);
+        grossExposure += notional;
+        if (pos.side === 'long')
+            longExposure += notional;
+        else
+            shortExposure += notional;
+        totalUnrealizedPnl += pos.unrealizedPnl;
+        return {
+            symbol: pos.symbol,
+            side: pos.side,
+            quantity: pos.contracts,
+            entryPrice: +pos.entryPrice.toFixed(2),
+            markPrice: +pos.markPrice.toFixed(2),
+            notional: +notional.toFixed(2),
+            unrealizedPnl: +pos.unrealizedPnl.toFixed(2),
+            portfolioPercent: totalEquity > 0 ? +((notional / totalEquity) * 100).toFixed(1) : 0,
+        };
+    });
+    const netExposure = longExposure - shortExposure;
+    const grossExposurePercent = totalEquity > 0 ? (grossExposure / totalEquity) * 100 : 0;
+    const netExposurePercent = totalEquity > 0 ? (netExposure / totalEquity) * 100 : 0;
+    const unrealizedPnlPercent = totalEquity > 0 ? (totalUnrealizedPnl / totalEquity) * 100 : 0;
+    // Heat score: 0-100 composite
+    // Components: gross exposure (40%), unrealized loss (30%), position concentration (30%)
+    const exposureHeat = Math.min(grossExposurePercent / 100, 1) * 40; // 100% exposure = 40 heat
+    const lossHeat = totalUnrealizedPnl < 0
+        ? Math.min(Math.abs(unrealizedPnlPercent) / 5, 1) * 30 // 5% loss = 30 heat
+        : 0;
+    const concentrationHeat = positions.length > 0
+        ? Math.min(positions.length / 5, 1) * 30 // 5+ positions = 30 heat
+        : 0;
+    const heatScore = Math.round(exposureHeat + lossHeat + concentrationHeat);
+    let heatLevel;
+    if (heatScore >= 80)
+        heatLevel = 'critical';
+    else if (heatScore >= 60)
+        heatLevel = 'high';
+    else if (heatScore >= 40)
+        heatLevel = 'elevated';
+    else if (heatScore >= 20)
+        heatLevel = 'moderate';
+    else
+        heatLevel = 'low';
+    // Execution quality stats (Phase 9a)
+    const execStats = deps.simulator.getExecutionStats();
+    const executionStats = execStats && execStats.totalTrades > 0
+        ? {
+            totalTrades: execStats.totalTrades,
+            avgSlippageBps: +execStats.avgSlippageBps.toFixed(2),
+            worstSlippageBps: +execStats.worstSlippageBps.toFixed(2),
+            totalFeesPaid: +execStats.totalFeesPaid.toFixed(2),
+            avgLatencyMs: +execStats.avgLatencyMs.toFixed(0),
+        }
+        : undefined;
+    // Shadow metrics (Phase 9b)
+    let shadowMetrics;
+    if (deps.shadowTracker) {
+        const sm = deps.shadowTracker.getMetrics();
+        const upgrade = deps.shadowTracker.isReadyForUpgrade();
+        shadowMetrics = {
+            totalShadowTrades: sm.totalShadowTrades,
+            avgDeltaBps: +sm.avgDeltaBps.toFixed(2),
+            worstDeltaBps: +sm.worstDeltaBps.toFixed(2),
+            tradingDays: sm.tradingDays,
+            readyForUpgrade: upgrade.ready,
+            upgradeBlockers: upgrade.reasons,
+        };
+    }
+    return {
+        tradingMode: deps.tradingMode ?? 'PAPER',
+        totalEquity: +totalEquity.toFixed(2),
+        availableBalance: +availableBalance.toFixed(2),
+        lockedBalance: +lockedBalance.toFixed(2),
+        grossExposure: +grossExposure.toFixed(2),
+        grossExposurePercent: +grossExposurePercent.toFixed(1),
+        netExposure: +netExposure.toFixed(2),
+        netExposurePercent: +netExposurePercent.toFixed(1),
+        positionCount: positions.length,
+        unrealizedPnl: +totalUnrealizedPnl.toFixed(2),
+        unrealizedPnlPercent: +unrealizedPnlPercent.toFixed(2),
+        positions: positionDetails,
+        heatScore,
+        heatLevel,
+        executionStats,
+        shadowMetrics,
+        timestamp: new Date().toISOString(),
+    };
+}

package/tools/get-sentiment.d.ts

@@ -0,0 +1,4 @@
+import type { IntelApiDeps } from './intel-api.js';
+export declare function getSentimentTool(_args: Record<string, never>, deps: IntelApiDeps): Promise<Record<string, unknown> | {
+    error: string;
+}>;

package/tools/get-sentiment.js

@@ -0,0 +1,6 @@
+// Tool: get_sentiment — free Fear & Greed Index + BTC dominance + global market data.
+// No Pro subscription required. Calls free public APIs via the intelligence service.
+import { fetchIntelApi } from './intel-api.js';
+export async function getSentimentTool(_args, deps) {
+    return fetchIntelApi('/api/sentiment', deps);
+}

package/tools/get-session-review.d.ts

@@ -0,0 +1,7 @@
+import type { IntelApiDeps } from './intel-api.js';
+export declare function getSessionReviewTool(args: {
+    symbol: string;
+    hours?: number;
+}, deps: IntelApiDeps): Promise<Record<string, unknown> | {
+    error: string;
+}>;

package/tools/get-session-review.js

@@ -0,0 +1,8 @@
+// Tool: get_session_review — automated end-of-session performance summary.
+// Calls Intelligence API for trade stats, setup/regime breakdown, lessons, and session-over-session comparison.
+import { fetchIntelApi, enc } from './intel-api.js';
+export async function getSessionReviewTool(args, deps) {
+    const intelSymbol = args.symbol.replace('/', '');
+    const hours = args.hours ?? 24;
+    return fetchIntelApi(`/api/session-review/${enc(intelSymbol)}?hours=${hours}`, deps);
+}

package/tools/get-setup-detail.d.ts

@@ -0,0 +1,7 @@
+import type { IntelApiDeps } from './intel-api.js';
+export interface GetSetupDetailArgs {
+    symbol: string;
+}
+export declare function getSetupDetailTool(args: GetSetupDetailArgs, deps: IntelApiDeps): Promise<Record<string, unknown> | {
+    error: string;
+}>;

package/tools/get-setup-detail.js

@@ -0,0 +1,303 @@
+// Tool: get_setup_detail — detailed setup info for a specific symbol.
+// Fetches the symbol's fact, evaluates best-matching strategy,
+// computes entry/stop/targets, returns full detail (~500 tokens).
+//
+// 2026-05-15 hardening: this tool used to (a) silently zero entry/stop/target
+// when `currentPrice` or `atr14` were missing from the fact (the 1000PEPE
+// "zeroed levels" pattern, ~5 occurrences in one session) and (b) always
+// compute a LONG-style ladder regardless of the strategy's directionRule
+// (the AVAX/SUI/TIA "TREND_DOWN label + LONG geometry" pattern). Both surface
+// as the agent rejecting setups as "data integrity failure" or "directionally
+// inconsistent" and standing down. Now we (1) refuse-to-emit when key
+// indicators are missing, (2) resolve direction via the strategy's
+// directionRule + fact context, and (3) compute stop/target geometry from
+// that direction so long and short setups produce ladders that match.
+// Cache is shared with scan_pairs (intel-cache.ts) so drill-down sees the
+// same fact snapshot the scan ranked the symbol from.
+import { evaluateStrategy, } from '../strategy/evaluator.js';
+import { getFactBySymbolCached, getStrategyRowsCached } from './intel-cache.js';
+export async function getSetupDetailTool(args, deps) {
+    const symbol = args.symbol.toUpperCase().replace(/[^A-Z0-9]/g, '');
+    // 1. Fetch fact for this symbol — shared cache with scan_pairs, so a
+    //    drill-down after a heartbeat scan hits the same snapshot the scan
+    //    ranked the symbol from.
+    const factRes = await getFactBySymbolCached(symbol, deps);
+    if ('error' in factRes)
+        return factRes;
+    const fact = factRes;
+    if (!fact.symbol) {
+        return { error: `No facts available for ${symbol}` };
+    }
+    // 2. Fetch user's active strategy rows (cached, shared with scan_pairs).
+    const rowsRes = await getStrategyRowsCached(deps);
+    if ('error' in rowsRes)
+        return rowsRes;
+    const strategyRows = rowsRes;
+    // 3. Evaluate all strategies, pick best match
+    let bestResult = null;
+    let bestScore = -1;
+    for (const row of strategyRows) {
+        const result = evaluateStrategy(row.config, fact);
+        if (result && result.score > bestScore) {
+            bestScore = result.score;
+            bestResult = result;
+        }
+    }
+    // Validate indicators BEFORE branching on bestResult — even the "no setup"
+    // path returns price, and a zero/missing price is misleading.
+    const price = readNumericIndicator(fact, 'currentPrice');
+    if (price === null) {
+        return {
+            error: `Fact for ${symbol} is missing currentPrice — intelligence fact-computer ` +
+                `may still be warming up, or this symbol has no recent klines. Retry on ` +
+                `next heartbeat; do not size a trade off this payload.`,
+        };
+    }
+    if (!bestResult) {
+        return {
+            symbol,
+            price,
+            regime: fact.regime,
+            regime_confidence: fact.regime_confidence,
+            setup: 'none',
+            note: 'No active strategy matches this symbol\'s current conditions.',
+            indicators: buildIndicatorSummary(fact),
+        };
+    }
+    // 4. Validate that the inputs needed for stop/target geometry are present.
+    const atr = readNumericIndicator(fact, 'atr14');
+    if (atr === null || atr <= 0) {
+        return {
+            error: `Fact for ${symbol} is missing atr14 (got ${atr ?? 'undefined'}) — cannot ` +
+                `compute stop/target geometry without ATR. Retry on next heartbeat.`,
+        };
+    }
+    // 5. Resolve direction from the strategy's directionRule. Refuse to emit a
+    //    setup when direction is ambiguous — better to return no setup than to
+    //    fabricate a long ladder for what might be a short trade.
+    const strategyConfig = strategyRows.find(r => r.config.name === bestResult.strategy)?.config;
+    if (!strategyConfig) {
+        return {
+            error: `Internal: strategy ${bestResult.strategy} matched but its config ` +
+                `disappeared between scan and drill-down. Retry on next heartbeat.`,
+        };
+    }
+    const direction = resolveDirection(strategyConfig, fact);
+    if (direction === null) {
+        return {
+            symbol: fact.symbol,
+            price,
+            regime: fact.regime,
+            regime_confidence: fact.regime_confidence,
+            strategy: bestResult.strategy,
+            score: bestResult.score,
+            setup: 'ambiguous_direction',
+            note: `Strategy ${bestResult.strategy} matched but its directionRule ` +
+                `(${strategyConfig.directionRule}) could not resolve a clean long/short ` +
+                `from the current fact (regime=${fact.regime}). Skip — wait for cleaner ` +
+                `context or run score_setup with an explicit direction if you want to force the trade.`,
+            indicators: buildIndicatorSummary(fact),
+        };
+    }
+    // 6. Compute entry/stop/targets from the matching strategy + direction.
+    const entry = computeEntry(strategyConfig, fact, atr, price);
+    const stop = computeStop(strategyConfig, atr, entry.price, direction);
+    const risk = Math.abs(entry.price - stop.price);
+    // Sanity check: if risk collapsed to zero (rounding pathology, weird ATR),
+    // refuse rather than emit zeroed targets that look executable.
+    if (!Number.isFinite(risk) || risk <= 0) {
+        return {
+            error: `Computed risk for ${symbol} is ${risk} — entry=${entry.price} stop=${stop.price} ` +
+                `collapsed to a zero-risk ladder. Likely cause: ATR=${atr} too small relative to ` +
+                `rounding precision. Skip this symbol.`,
+        };
+    }
+    const sign = direction === 'long' ? 1 : -1;
+    const targets = (strategyConfig.targetRMultiples ?? [1.5, 2.5]).map(r => ({
+        price: roundPrice(entry.price + risk * r * sign),
+        r_multiple: r,
+    }));
+    // 7. Build risks list
+    const risks = [];
+    const ind = fact.indicators;
+    if (readNumericIndicator(fact, 'obImbalance') === 0.5) {
+        risks.push('Orderbook neutral - no clear bid/ask dominance');
+    }
+    const bb = ind.bb;
+    if (bb && bb.bandwidth && bb.bandwidth > 6) {
+        risks.push(`High volatility - BB bandwidth ${bb.bandwidth.toFixed(1)}%`);
+    }
+    const fundingZ = readNumericIndicator(fact, 'fundingZScore');
+    if (fundingZ !== null && Math.abs(fundingZ) > 2) {
+        risks.push(`Elevated funding z-score: ${fundingZ.toFixed(1)}σ`);
+    }
+    return {
+        symbol: fact.symbol,
+        price,
+        regime: fact.regime,
+        regime_confidence: fact.regime_confidence,
+        strategy: bestResult.strategy,
+        direction,
+        score: bestResult.score,
+        entry: { price: entry.price, type: entry.type, rationale: entry.rationale },
+        stop: { price: stop.price, type: stop.type, rationale: stop.rationale },
+        targets,
+        indicators: buildIndicatorSummary(fact),
+        conditions: `${bestResult.conditionsMet}/${bestResult.conditionsTotal} met`,
+        risks: risks.length > 0 ? risks : ['No significant risks identified'],
+    };
+}
+// ─── Helpers ────────────────────────────────────────────────────────────
+/** Read an indicator as a finite number. Returns null when the value is
+ *  missing, NaN, or non-finite — callers MUST handle null explicitly rather
+ *  than treating it as zero (the pre-fix `?? 0` behaviour was the root cause
+ *  of the 1000PEPE zeroed-levels bug). */
+function readNumericIndicator(fact, key) {
+    const raw = fact.indicators[key];
+    if (typeof raw === 'number' && Number.isFinite(raw))
+        return raw;
+    if (typeof raw === 'string') {
+        const n = Number(raw);
+        if (Number.isFinite(n))
+            return n;
+    }
+    return null;
+}
+/** Resolve a clean long/short for a strategy given the current fact. Returns
+ *  null when the directionRule cannot be unambiguously satisfied — the caller
+ *  must refuse to emit a setup in that case rather than guess. */
+function resolveDirection(strategy, fact) {
+    switch (strategy.directionRule) {
+        case 'fixed_long':
+            return 'long';
+        case 'fixed_short':
+            return 'short';
+        case 'from_regime': {
+            const r = (fact.regime || '').toUpperCase();
+            if (r === 'TREND_UP')
+                return 'long';
+            if (r === 'TREND_DOWN')
+                return 'short';
+            // RANGE_TIGHT / RANGE_WIDE / VOLATILITY_EXPANSION / UNKNOWN: ambiguous.
+            return null;
+        }
+        case 'from_funding': {
+            const z = readNumericIndicator(fact, 'fundingZScore');
+            if (z === null)
+                return null;
+            // Crowded longs (positive z) → contrarian short; crowded shorts → long.
+            if (z >= 1)
+                return 'short';
+            if (z <= -1)
+                return 'long';
+            return null; // Z between -1 and 1: no edge.
+        }
+        case 'from_sweep': {
+            // The sweep direction lives inside the price_sweep condition's metadata,
+            // which evaluateStrategy doesn't surface to us as a single field. Without
+            // that signal we'd be guessing; refuse to emit and let the agent run
+            // score_setup with an explicit direction.
+            return null;
+        }
+        default:
+            return null;
+    }
+}
+function buildIndicatorSummary(fact) {
+    const ind = fact.indicators;
+    const macd = ind.macd;
+    const stochRsi = ind.stochRsi;
+    const supertrend = ind.supertrend;
+    const price = readNumericIndicator(fact, 'currentPrice');
+    const vwap = readNumericIndicator(fact, 'vwap');
+    const fundingZ = readNumericIndicator(fact, 'fundingZScore');
+    const oi = readNumericIndicator(fact, 'oiRatio');
+    return {
+        rsi: ind.rsi14,
+        adx: ind.adx,
+        macd: macd?.crossover && macd.crossover !== 'none'
+            ? `${macd.crossover} cross`
+            : `histogram ${macd?.histogram ?? 0}`,
+        vwap: price !== null && vwap !== null && vwap !== 0
+            ? `price ${price > vwap ? 'above' : 'below'} (${((price - vwap) / vwap * 100).toFixed(2)}%)`
+            : 'vwap unavailable',
+        supertrend: supertrend?.direction,
+        stochRsi: stochRsi?.k,
+        funding: fundingZ !== null
+            ? `${fundingZ > 0 ? '+' : ''}${fundingZ.toFixed(1)}σ`
+            : 'unavailable',
+        oi: oi !== null ? `${oi.toFixed(2)}x avg` : 'unavailable',
+    };
+}
+function computeEntry(strategy, fact, atr, currentPrice) {
+    const ind = fact.indicators;
+    const { type, params } = strategy.entryRule;
+    switch (type) {
+        case 'ema_offset': {
+            const emaKey = `ema${params.period ?? 20}`;
+            const emaRaw = ind[emaKey];
+            const ema = typeof emaRaw === 'number' && Number.isFinite(emaRaw) ? emaRaw : currentPrice;
+            const offset = atr * (params.atrFraction ?? 0.3);
+            return {
+                price: roundPrice(ema),
+                type: 'ema_offset',
+                rationale: `EMA${params.period ?? 20} pullback (±${offset.toFixed(0)} ATR offset)`,
+            };
+        }
+        case 'atr_offset': {
+            const fraction = params.atrFraction ?? 0.2;
+            return {
+                price: roundPrice(currentPrice),
+                type: 'atr_offset',
+                rationale: `Current price ±${(fraction * atr).toFixed(0)} ATR offset`,
+            };
+        }
+        case 'sweep_range':
+        default:
+            return {
+                price: roundPrice(currentPrice),
+                type: type || 'market',
+                rationale: 'At current price',
+            };
+    }
+}
+function computeStop(strategy, atr, entryPrice, direction) {
+    const { type, params } = strategy.stopRule;
+    // Direction sign: long → stop below entry (entry - ATR*mult), short → above.
+    const sign = direction === 'long' ? -1 : 1;
+    switch (type) {
+        case 'swing_atr': {
+            const mult = params.atrFraction ?? 0.5;
+            return {
+                price: roundPrice(entryPrice + sign * atr * (1 + mult)),
+                type: 'swing_atr',
+                rationale: `${direction === 'long' ? 'Below' : 'Above'} swing - ${mult} ATR buffer`,
+            };
+        }
+        case 'fixed_atr': {
+            const mult = params.atrMultiple ?? 1.5;
+            return {
+                price: roundPrice(entryPrice + sign * atr * mult),
+                type: 'fixed_atr',
+                rationale: `${mult}x ATR ${direction === 'long' ? 'below' : 'above'} entry`,
+            };
+        }
+        case 'recent_extreme_atr': {
+            const mult = params.atrFraction ?? 0.3;
+            return {
+                price: roundPrice(entryPrice + sign * atr * (1 + mult)),
+                type: 'recent_extreme_atr',
+                rationale: `Recent extreme - ${mult} ATR`,
+            };
+        }
+        default:
+            return {
+                price: roundPrice(entryPrice + sign * atr * 1.5),
+                type: type || 'default',
+                rationale: `1.5x ATR default stop (${direction === 'long' ? 'below' : 'above'} entry)`,
+            };
+    }
+}
+function roundPrice(p) {
+    return Math.round(p * 100) / 100;
+}

package/tools/get-signals.d.ts

@@ -0,0 +1,15 @@
+import type { IntelApiDeps } from './intel-api.js';
+import type { LocalSignalService } from '../live/local-signal-service.js';
+export interface GetSignalsDeps extends IntelApiDeps {
+    evaluatorMode?: 'central' | 'shadow' | 'enforce';
+    localSignalService?: LocalSignalService | null;
+    logger?: {
+        info: (tag: string, msg: string) => void;
+    };
+}
+export declare function getSignalsTool(args: {
+    symbol: string;
+    hours?: number;
+}, deps: GetSignalsDeps): Promise<Record<string, unknown> | {
+    error: string;
+}>;

package/tools/get-signals.js

@@ -0,0 +1,54 @@
+// Tool: get_signals — active trading signals for a symbol.
+//
+// Default (`central`): fetches the snapshot + recent history from the intel
+// engine, exactly as before. With facts-out (docs/FACTS_OUT_ARCHITECTURE.md
+// step 5) the operator can flip `signals.evaluator`:
+//   shadow  — return central, but ALSO log the locally-evaluated snapshot for
+//             comparison (zero behaviour change).
+//   enforce — return the locally-evaluated snapshot, falling back to central
+//             when the local service has no fact for the symbol yet.
+import { fetchIntelApi, enc } from './intel-api.js';
+async function central(args, deps) {
+    const s = enc(args.symbol);
+    const [snapshot, history] = await Promise.all([
+        fetchIntelApi(`/api/signals/${s}`, deps),
+        fetchIntelApi(`/api/signals/${s}/history?hours=${args.hours ?? 24}`, deps),
+    ]);
+    if ('error' in snapshot)
+        return snapshot;
+    if ('error' in history)
+        return { ...snapshot, history: [] };
+    return { ...snapshot, history };
+}
+export async function getSignalsTool(args, deps) {
+    const mode = deps.evaluatorMode ?? 'central';
+    const svc = deps.localSignalService ?? null;
+    // ENFORCE — serve the local snapshot; fall back to central if no fact yet
+    // (or the streamed fact has gone stale — getSnapshot refuses those).
+    if (mode === 'enforce' && svc) {
+        const local = svc.getSnapshot(args.symbol);
+        if (local) {
+            return { ...local, history: local.recentSignals, source: 'local' };
+        }
+        // Fail open to central, but LOUDLY and tagged: during rollout the
+        // operator needs to see how often enforce actually serves local vs
+        // silently falling back (otherwise the capture rate is unmeasurable).
+        deps.logger?.info('signal-enforce-fallback', `${args.symbol} no fresh local fact — serving central`);
+        const fallback = await central(args, deps);
+        if (!('error' in fallback))
+            return { ...fallback, source: 'central_fallback' };
+        return fallback;
+    }
+    const result = await central(args, deps);
+    // SHADOW — central authoritative; log the local snapshot alongside for compare.
+    if (mode === 'shadow' && svc && !('error' in result)) {
+        const local = svc.getSnapshot(args.symbol);
+        const centralStrats = Array.isArray(result.activeStrategies)
+            ? result.activeStrategies.length
+            : 0;
+        deps.logger?.info('signal-shadow', `${args.symbol} central_strategies=${centralStrats} ` +
+            `local_strategies=${local ? local.activeStrategies.length : 'no-fact'} ` +
+            `local_signals=${local ? local.recentSignals.length : 'n/a'}`);
+    }
+    return result;
+}

package/tools/get-sizing.d.ts

@@ -0,0 +1,6 @@
+import type { IntelApiDeps } from './intel-api.js';
+export declare function getSizingTool(args: {
+    symbol: string;
+}, deps: IntelApiDeps): Promise<Record<string, unknown> | {
+    error: string;
+}>;