@reefclaw/connect 0.1.12 → 0.1.14

package/assets/plugin/tools/get-setup-detail.js

@@ -0,0 +1,322 @@
+// 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 { resolveIntelSymbol } from './intel-api.js';
+import { evaluateStrategy, } from '../strategy/evaluator.js';
+import { getFactBySymbolCached, getStrategyRowsCached } from './intel-cache.js';
+export async function getSetupDetailTool(args, deps) {
+    // Venue-aware symbol resolution (plan §5.3). Binance keeps the historical
+    // sanitizer byte-identically; the hyperliquid arm maps agent-facing forms
+    // ('BTC/USDC', 'BTCUSDC') to the HL_ intel namespace and must NOT uppercase
+    // or strip '_' — HL coins are case-sensitive ('kPEPE' is real, 'KPEPE' is
+    // not) and the legacy sanitizer would mangle 'HL_BTC' into 'HLBTC'.
+    const symbol = (deps.venue ?? 'binance') === 'hyperliquid'
+        ? resolveIntelSymbol(deps, args.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) {
+    // 2 decimals for $1+ prices; below that, 6 significant digits — a flat
+    // 2-decimal round collapses entry/stop/targets onto the same value for the
+    // sub-cent class (1000PEPE/1000SHIB/…, ATR below the $0.01 granularity),
+    // tripping the zero-risk guard and refusing every setup on those symbols.
+    if (!Number.isFinite(p) || p === 0)
+        return p;
+    const abs = Math.abs(p);
+    if (abs >= 1)
+        return Math.round(p * 100) / 100;
+    const decimals = 5 - Math.floor(Math.log10(abs));
+    const f = Math.pow(10, decimals);
+    return Math.round(p * f) / f;
+}

package/assets/plugin/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/assets/plugin/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, resolveIntelSymbol } from './intel-api.js';
+async function central(args, deps) {
+    const s = enc(resolveIntelSymbol(deps, 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/assets/plugin/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;
+}>;

package/assets/plugin/tools/get-sizing.js

@@ -0,0 +1,6 @@
+// Tool: get_sizing — fetches Half-Kelly position sizing recommendation from Intelligence API.
+// Returns recommended size as % of account, Kelly fraction, win rate, avg W/L ratio, vol adjustment.
+import { fetchIntelApi, enc, resolveIntelSymbol } from './intel-api.js';
+export async function getSizingTool(args, deps) {
+    return fetchIntelApi(`/api/sizing/${enc(resolveIntelSymbol(deps, args.symbol))}`, deps);
+}

package/assets/plugin/tools/get-trade-feedback.d.ts

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

package/assets/plugin/tools/get-trade-feedback.js

@@ -0,0 +1,8 @@
+// Tool: get_trade_feedback — fetches structured performance feedback from Intelligence API.
+// Returns per-setup-type win rates, regime breakdown, recent outcomes, and current streak.
+// Designed for the agent to review before entering trades.
+import { fetchIntelApi, enc, resolveIntelSymbol } from './intel-api.js';
+export async function getTradeFeedbackTool(args, deps) {
+    const hours = args.hours ?? 168;
+    return fetchIntelApi(`/api/analytics/${enc(resolveIntelSymbol(deps, args.symbol))}/feedback?hours=${hours}`, deps);
+}

package/assets/plugin/tools/get-trade-flow.d.ts

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

package/assets/plugin/tools/get-trade-flow.js

@@ -0,0 +1,7 @@
+// Tool: get_trade_flow — fetches aggregated trade flow / institutional flow data.
+// Returns buy/sell volume, large trade (whale) activity, net delta, and whale pressure verdict.
+import { fetchIntelApi, enc, resolveIntelSymbol } from './intel-api.js';
+export async function getTradeFlowTool(args, deps) {
+    const minutes = args.minutes ?? 5;
+    return fetchIntelApi(`/api/trade-flow/${enc(resolveIntelSymbol(deps, args.symbol))}?minutes=${minutes}`, deps);
+}

package/assets/plugin/tools/get-volume-analysis.d.ts

@@ -0,0 +1,21 @@
+import type { PublicMarketDataApi } from '../ccxt/public-market-data-api.js';
+export interface VolumeAnalysisResult {
+    symbol: string;
+    timeframe: string;
+    volumeExpansion: number;
+    closePosition: number;
+    directionalThrust: number;
+    buyVolEstimate: number;
+    latestVolume: number;
+    avgVolume: number;
+    interpretation: string;
+    timestamp: string;
+}
+export declare function getVolumeAnalysisTool(args: {
+    symbol: string;
+    timeframe?: string;
+}, deps: {
+    binanceApi: PublicMarketDataApi;
+}): Promise<VolumeAnalysisResult | {
+    error: string;
+}>;

package/assets/plugin/tools/get-volume-analysis.js

@@ -0,0 +1,74 @@
+// Tool: get_volume_analysis — volume expansion, directional thrust, close position
+// Fetches 25 bars of 5m OHLCV and computes volume metrics for the latest bar.
+export async function getVolumeAnalysisTool(args, deps) {
+    const timeframe = args.timeframe ?? '5m';
+    try {
+        const candles = await deps.binanceApi.fetchOHLCV(args.symbol, timeframe, 25);
+        if (!candles || candles.length < 3) {
+            return { error: `Insufficient OHLCV data for ${args.symbol} ${timeframe}` };
+        }
+        // Filter valid bars (volume > 0)
+        const valid = candles.filter((c) => c[5] > 0);
+        if (valid.length < 3) {
+            return { error: `Insufficient valid bars for ${args.symbol} ${timeframe}` };
+        }
+        // Latest bar
+        const latest = valid[valid.length - 1];
+        const [, , latestHigh, latestLow, latestClose, latestVolume] = latest;
+        // 20-bar average volume (excluding latest bar)
+        const lookback = valid.slice(Math.max(0, valid.length - 21), valid.length - 1);
+        const avgVolume = lookback.length > 0
+            ? lookback.reduce((sum, r) => sum + r[5], 0) / lookback.length
+            : latestVolume;
+        // Volume expansion ratio
+        const volumeExpansion = avgVolume > 0 ? latestVolume / avgVolume : 1;
+        // Close position: where close sits in the bar's range (0 = low, 1 = high)
+        const range = latestHigh - latestLow;
+        const closePosition = range > 0 ? (latestClose - latestLow) / range : 0.5;
+        // Directional thrust: combines volume expansion with close position
+        // -1 = high volume bearish (close at low), +1 = high volume bullish (close at high)
+        const dirMultiplier = (closePosition - 0.5) * 2;
+        const cappedExpansion = Math.min(volumeExpansion, 5);
+        const directionalThrust = dirMultiplier * Math.min(1, cappedExpansion / 2);
+        // Buy volume estimate (proxy)
+        const buyVolEstimate = closePosition;
+        // Human-readable interpretation
+        let interpretation;
+        if (volumeExpansion > 2 && directionalThrust > 0.3) {
+            interpretation = 'Strong bullish volume surge — buyers aggressive';
+        }
+        else if (volumeExpansion > 2 && directionalThrust < -0.3) {
+            interpretation = 'Strong bearish volume surge — sellers aggressive';
+        }
+        else if (volumeExpansion > 1.5 && Math.abs(directionalThrust) < 0.15) {
+            interpretation = 'High volume indecision — battle between buyers and sellers';
+        }
+        else if (volumeExpansion < 0.5) {
+            interpretation = 'Low volume — lack of participation, potential breakout setup';
+        }
+        else if (directionalThrust > 0.2) {
+            interpretation = 'Moderate bullish bias — close near highs';
+        }
+        else if (directionalThrust < -0.2) {
+            interpretation = 'Moderate bearish bias — close near lows';
+        }
+        else {
+            interpretation = 'Normal volume, neutral positioning';
+        }
+        return {
+            symbol: args.symbol,
+            timeframe,
+            volumeExpansion: +volumeExpansion.toFixed(2),
+            closePosition: +closePosition.toFixed(3),
+            directionalThrust: +directionalThrust.toFixed(3),
+            buyVolEstimate: +buyVolEstimate.toFixed(3),
+            latestVolume: Math.round(latestVolume),
+            avgVolume: Math.round(avgVolume),
+            interpretation,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    catch (err) {
+        return { error: `get_volume_analysis failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}

package/assets/plugin/tools/get-volume-profile.d.ts

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

package/assets/plugin/tools/get-volume-profile.js

@@ -0,0 +1,7 @@
+// Tool: get_volume_profile — fetches volume profile from the Intelligence API.
+// Returns price buckets with buy/sell volume, POC, value area, and current price.
+import { fetchIntelApi, enc, resolveIntelSymbol } from './intel-api.js';
+export async function getVolumeProfileTool(args, deps) {
+    const period = args.period ?? 24;
+    return fetchIntelApi(`/api/volume-profile/${enc(resolveIntelSymbol(deps, args.symbol))}?period=${period}`, deps);
+}