@reefclaw/openclaw-plugin 0.1.0

package/tools/get-market-structure.js

@@ -0,0 +1,198 @@
+// Tool: get_market_structure — multi-timeframe technical analysis via CCXT
+// Fetches OHLCV for multiple timeframes and computes trend, regime, momentum.
+// Used by the agent (via tool call) and broadcast to the dashboard (via poller).
+// --- Technical indicator helpers ---
+function sma(values, period) {
+    if (values.length < period)
+        return null;
+    const slice = values.slice(-period);
+    return slice.reduce((s, v) => s + v, 0) / period;
+}
+function ema(values, period) {
+    if (values.length < period)
+        return null;
+    const k = 2 / (period + 1);
+    let e = values.slice(0, period).reduce((s, v) => s + v, 0) / period;
+    for (let i = period; i < values.length; i++) {
+        e = values[i] * k + e * (1 - k);
+    }
+    return e;
+}
+/**
+ * Average True Range using Wilder's smoothing.
+ * Input: OHLCV candles array, period (default 14).
+ * Returns null if insufficient data.
+ */
+export function atr(candles, period = 14) {
+    if (candles.length < period + 1)
+        return null;
+    // Compute true range for each bar (starting from index 1)
+    const trueRanges = [];
+    for (let i = 1; i < candles.length; i++) {
+        const high = candles[i][2];
+        const low = candles[i][3];
+        const prevClose = candles[i - 1][4];
+        const tr = Math.max(high - low, Math.abs(high - prevClose), Math.abs(low - prevClose));
+        trueRanges.push(tr);
+    }
+    if (trueRanges.length < period)
+        return null;
+    // Initial ATR: simple average of first `period` true ranges
+    let atrVal = trueRanges.slice(0, period).reduce((s, v) => s + v, 0) / period;
+    // Wilder's smoothing for remaining
+    for (let i = period; i < trueRanges.length; i++) {
+        atrVal = (atrVal * (period - 1) + trueRanges[i]) / period;
+    }
+    return atrVal;
+}
+function rsi(closes, period = 14) {
+    if (closes.length < period + 1)
+        return null;
+    const recent = closes.slice(-(period + 1));
+    let gains = 0, losses = 0;
+    for (let i = 1; i < recent.length; i++) {
+        const diff = recent[i] - recent[i - 1];
+        if (diff > 0)
+            gains += diff;
+        else
+            losses -= diff;
+    }
+    if (losses === 0)
+        return 100;
+    const rs = (gains / period) / (losses / period);
+    return 100 - (100 / (1 + rs));
+}
+// --- Timeframes to analyze ---
+const TIMEFRAMES = [
+    { id: '5m', ccxt: '5m', limit: 50 },
+    { id: '15m', ccxt: '15m', limit: 50 },
+    { id: '1h', ccxt: '1h', limit: 50 },
+    { id: '4h', ccxt: '4h', limit: 50 },
+    { id: '1d', ccxt: '1d', limit: 30 },
+    { id: '1w', ccxt: '1w', limit: 20 },
+];
+// --- Analysis logic ---
+function analyzeCandles(timeframe, candles) {
+    const closes = candles.map((c) => c[4]);
+    const atr14 = atr(candles, 14);
+    const rsiVal = rsi(closes, 14);
+    const sma20 = sma(closes, 20);
+    const emaFastVal = ema(closes, 9);
+    const emaSlowVal = ema(closes, 21);
+    const lastClose = closes.length > 0 ? closes[closes.length - 1] : null;
+    // Price vs SMA20 (%)
+    const priceVsSma = lastClose !== null && sma20 !== null && sma20 > 0
+        ? ((lastClose - sma20) / sma20) * 100
+        : null;
+    // Change % over period
+    const changePercent = closes.length >= 2
+        ? ((closes[closes.length - 1] - closes[0]) / closes[0]) * 100
+        : null;
+    // Direction: EMA crossover
+    let direction = 'neutral';
+    if (emaFastVal !== null && emaSlowVal !== null) {
+        const emaDiff = ((emaFastVal - emaSlowVal) / emaSlowVal) * 100;
+        if (emaDiff > 0.05)
+            direction = 'bullish';
+        else if (emaDiff < -0.05)
+            direction = 'bearish';
+    }
+    else if (priceVsSma !== null) {
+        if (priceVsSma > 0.1)
+            direction = 'bullish';
+        else if (priceVsSma < -0.1)
+            direction = 'bearish';
+    }
+    // Regime: trending vs ranging
+    let regime = 'ranging';
+    if (closes.length >= 10 && sma20 !== null) {
+        const recentCloses = closes.slice(-10);
+        const avgDeviation = recentCloses.reduce((s, c) => s + Math.abs((c - sma20) / sma20), 0) / recentCloses.length;
+        regime = avgDeviation > 0.002 ? 'trending' : 'ranging';
+    }
+    // Momentum
+    let momentum = 'weak';
+    if (rsiVal !== null) {
+        const rsiDist = Math.abs(rsiVal - 50);
+        if (rsiDist > 20)
+            momentum = 'strong';
+        else if (rsiDist > 10)
+            momentum = 'moderate';
+    }
+    return {
+        timeframe,
+        direction,
+        regime,
+        momentum,
+        rsiValue: rsiVal !== null ? +rsiVal.toFixed(1) : null,
+        priceVsSma: priceVsSma !== null ? +priceVsSma.toFixed(3) : null,
+        emaFast: emaFastVal !== null ? +emaFastVal.toFixed(2) : null,
+        emaSlow: emaSlowVal !== null ? +emaSlowVal.toFixed(2) : null,
+        changePercent: changePercent !== null ? +changePercent.toFixed(3) : null,
+        candles: closes.length,
+        atr14: atr14 !== null ? +atr14.toFixed(2) : undefined,
+    };
+}
+// --- Tool implementation ---
+export async function getMarketStructureTool(args, deps) {
+    const symbol = args.symbol;
+    const requestedTFs = args.timeframes
+        ? TIMEFRAMES.filter((tf) => args.timeframes.includes(tf.id))
+        : TIMEFRAMES;
+    if (requestedTFs.length === 0) {
+        return { error: `No valid timeframes. Available: ${TIMEFRAMES.map((t) => t.id).join(', ')}` };
+    }
+    // Fetch all timeframes in parallel
+    const results = await Promise.allSettled(requestedTFs.map(async (tf) => {
+        const candles = await deps.binanceApi.fetchOHLCV(symbol, tf.ccxt, tf.limit);
+        if (!candles || candles.length === 0) {
+            return { tf: tf.id, analysis: null };
+        }
+        return { tf: tf.id, analysis: analyzeCandles(tf.id, candles) };
+    }));
+    const timeframes = [];
+    for (const r of results) {
+        if (r.status === 'fulfilled' && r.value.analysis) {
+            timeframes.push(r.value.analysis);
+        }
+    }
+    if (timeframes.length === 0) {
+        return { error: `Failed to fetch candle data for ${symbol}` };
+    }
+    // Compute alignment
+    const withData = timeframes.filter((t) => t.candles >= 5);
+    const bullish = withData.filter((t) => t.direction === 'bullish').length;
+    const bearish = withData.filter((t) => t.direction === 'bearish').length;
+    const neutral = withData.filter((t) => t.direction === 'neutral').length;
+    const total = withData.length;
+    let summary;
+    if (bullish === total)
+        summary = 'All timeframes bullish — strong alignment';
+    else if (bearish === total)
+        summary = 'All timeframes bearish — strong alignment';
+    else if (bullish >= total - 1)
+        summary = `${bullish}/${total} bullish — mostly aligned up`;
+    else if (bearish >= total - 1)
+        summary = `${bearish}/${total} bearish — mostly aligned down`;
+    else
+        summary = 'Mixed signals — timeframes conflicting';
+    // Extract 1h ATR for top-level summary (primary risk reference timeframe)
+    const hourlyTf = timeframes.find(t => t.timeframe === '1h');
+    const lastClose = hourlyTf?.emaFast ?? null; // approximate; use actual last close below
+    const hourlyAtr14 = hourlyTf?.atr14;
+    // Compute atrPercent relative to last close of the 1h timeframe
+    let topLevelAtr;
+    if (hourlyAtr14 !== undefined && hourlyTf) {
+        // Use emaSlow as a stable price reference (if available), else emaFast
+        const refPrice = hourlyTf.emaSlow ?? hourlyTf.emaFast ?? 0;
+        const atrPct = refPrice > 0 ? (hourlyAtr14 / refPrice) * 100 : 0;
+        topLevelAtr = { atr14: hourlyAtr14, atrPercent: +atrPct.toFixed(4) };
+    }
+    return {
+        symbol,
+        timeframes,
+        alignment: { bullish, bearish, neutral, total, summary },
+        atr: topLevelAtr,
+        timestamp: new Date().toISOString(),
+    };
+}

package/tools/get-my-mined-patterns.d.ts

@@ -0,0 +1,20 @@
+import type { PositionDecisionsClient, MyMinedPattern } from '../ingest/position-decisions-client.js';
+export interface GetMyMinedPatternsArgs {
+    within_days?: number;
+    min_sample_size?: number;
+    max_p_value?: number;
+    include_promoted?: boolean;
+}
+export interface GetMyMinedPatternsDeps {
+    decisionsClient?: PositionDecisionsClient;
+    userId?: string;
+}
+export type GetMyMinedPatternsResult = {
+    ok: true;
+    patterns: MyMinedPattern[];
+    total_returned: number;
+    note?: string;
+} | {
+    error: string;
+};
+export declare function getMyMinedPatternsTool(args: GetMyMinedPatternsArgs, deps: GetMyMinedPatternsDeps): Promise<GetMyMinedPatternsResult>;

package/tools/get-my-mined-patterns.js

@@ -0,0 +1,61 @@
+// Tool: get_my_mined_patterns — Phase 4.5 self-assessment read.
+//
+// Returns the agent's own statistically-significant patterns from its trade
+// history, surfaced by the daily pattern-mining cron. The agent uses this to
+// decide which patterns are worth proposing as learnings (via propose_learning).
+//
+// Agency-preserving READ surface: no validation, no gating. The agent reads
+// statistics, the agent decides. Per feedback_agent_agency_over_hardcoding.
+import { logger, formatError } from '../logger.js';
+const TAG = 'get-my-mined-patterns';
+export async function getMyMinedPatternsTool(args, deps) {
+    if (!deps.decisionsClient || !deps.userId) {
+        return {
+            ok: true,
+            patterns: [],
+            total_returned: 0,
+            note: 'Position-decisions ingest is not configured; no mined patterns available.',
+        };
+    }
+    // Defensive coercion — JSON-Schema validation upstream covers types, but
+    // out-of-range numbers (e.g. within_days=999) should clamp not error.
+    const within = clampInt(args.within_days, 1, 90, 14);
+    const minN = clampInt(args.min_sample_size, 1, 100_000, 20);
+    const maxP = clampFloat(args.max_p_value, 0, 1, 0.05);
+    let response;
+    try {
+        response = await deps.decisionsClient.getMyMinedPatterns(deps.userId, {
+            withinDays: within,
+            minSampleSize: minN,
+            maxPValue: maxP,
+            includePromoted: !!args.include_promoted,
+        });
+    }
+    catch (err) {
+        logger.warn(TAG, `getMyMinedPatterns threw: ${formatError(err)}`);
+        return { error: 'Failed to fetch mined patterns from webapp.' };
+    }
+    if (!response) {
+        return {
+            ok: true,
+            patterns: [],
+            total_returned: 0,
+            note: 'Webapp /api/internal/learnings/my-patterns returned no result; proceeding without mined-pattern data.',
+        };
+    }
+    return {
+        ok: true,
+        patterns: response.patterns,
+        total_returned: response.totalReturned,
+    };
+}
+function clampInt(v, lo, hi, def) {
+    if (typeof v !== 'number' || Number.isNaN(v))
+        return def;
+    return Math.max(lo, Math.min(hi, Math.trunc(v)));
+}
+function clampFloat(v, lo, hi, def) {
+    if (typeof v !== 'number' || Number.isNaN(v))
+        return def;
+    return Math.max(lo, Math.min(hi, v));
+}

package/tools/get-my-proposed-learnings.d.ts

@@ -0,0 +1,20 @@
+import type { PositionDecisionsClient, MyProposedLearning } from '../ingest/position-decisions-client.js';
+export interface GetMyProposedLearningsArgs {
+    include_hypothesis?: boolean;
+    include_confirmed?: boolean;
+    include_retired?: boolean;
+    proposed_by?: 'agent' | 'operator';
+}
+export interface GetMyProposedLearningsDeps {
+    decisionsClient?: PositionDecisionsClient;
+    userId?: string;
+}
+export type GetMyProposedLearningsResult = {
+    ok: true;
+    learnings: MyProposedLearning[];
+    total_returned: number;
+    note?: string;
+} | {
+    error: string;
+};
+export declare function getMyProposedLearningsTool(args: GetMyProposedLearningsArgs, deps: GetMyProposedLearningsDeps): Promise<GetMyProposedLearningsResult>;

package/tools/get-my-proposed-learnings.js

@@ -0,0 +1,55 @@
+// Tool: get_my_proposed_learnings — Phase 4.5 self-audit read.
+//
+// Returns this user's own learnings across confidence states (hypothesis,
+// confirmed, retired) so the agent can dedup before proposing a new
+// hypothesis. Distinct from get_relevant_learnings, which returns only
+// `confirmed` rows matching the current decision context.
+//
+// Agency-preserving READ surface.
+import { logger, formatError } from '../logger.js';
+const TAG = 'get-my-proposed-learnings';
+export async function getMyProposedLearningsTool(args, deps) {
+    if (!deps.decisionsClient || !deps.userId) {
+        return {
+            ok: true,
+            learnings: [],
+            total_returned: 0,
+            note: 'Position-decisions ingest is not configured; no learnings available.',
+        };
+    }
+    // Treat missing fields as defaults (hypothesis ON, confirmed ON, retired OFF).
+    const includeHypothesis = args.include_hypothesis !== false;
+    const includeConfirmed = args.include_confirmed !== false;
+    const includeRetired = !!args.include_retired;
+    if (!includeHypothesis && !includeConfirmed && !includeRetired) {
+        return {
+            error: 'At least one of include_hypothesis, include_confirmed, include_retired must be true.',
+        };
+    }
+    let response;
+    try {
+        response = await deps.decisionsClient.getMyProposedLearnings(deps.userId, {
+            includeHypothesis,
+            includeConfirmed,
+            includeRetired,
+            proposedBy: args.proposed_by,
+        });
+    }
+    catch (err) {
+        logger.warn(TAG, `getMyProposedLearnings threw: ${formatError(err)}`);
+        return { error: 'Failed to fetch proposed learnings from webapp.' };
+    }
+    if (!response) {
+        return {
+            ok: true,
+            learnings: [],
+            total_returned: 0,
+            note: 'Webapp /api/internal/learnings/my-proposals returned no result.',
+        };
+    }
+    return {
+        ok: true,
+        learnings: response.learnings,
+        total_returned: response.totalReturned,
+    };
+}

package/tools/get-my-recent-reviews.d.ts

@@ -0,0 +1,22 @@
+import type { PositionDecisionsClient, PositionReviewContext } from '../ingest/position-decisions-client.js';
+import type { PositionStateStore } from '../live/position-state-store.js';
+export interface GetMyRecentReviewsArgs {
+    /** Optional — when provided, returns context only for that symbol. When
+     *  omitted, returns context for every currently-open position. */
+    symbol?: string;
+    /** Number of reviews to include per position (1–10, default 3). */
+    review_limit?: number;
+}
+export interface GetMyRecentReviewsDeps {
+    decisionsClient?: PositionDecisionsClient;
+    stateStore?: PositionStateStore;
+    userId?: string;
+}
+export type GetMyRecentReviewsResult = {
+    ok: true;
+    positions: PositionReviewContext[];
+    note?: string;
+} | {
+    error: string;
+};
+export declare function getMyRecentReviewsTool(args: GetMyRecentReviewsArgs, deps: GetMyRecentReviewsDeps): Promise<GetMyRecentReviewsResult>;

package/tools/get-my-recent-reviews.js

@@ -0,0 +1,66 @@
+// Tool: get_my_recent_reviews — Phase 1 of the Agent Learning Loop.
+//
+// Returns, for each currently-open position (or just the requested symbol),
+// the agent's last N reviews + a verdict-streak counter + recent same-symbol
+// re-entry context. The agent calls this BEFORE record_position_reviews each
+// heartbeat so it can reference its prior reasoning instead of re-deriving in
+// isolation. Without this surface the journal is write-only — the agent files
+// reviews but never reads them, and "stale hold" remains structurally invisible
+// (the WIF 8.7h-underwater pattern from 2026-05-03).
+//
+// Resolves position UUIDs from the local PositionStateStore so callers don't
+// need to know about webappPositionId — the tool only returns context for
+// positions currently open on this plugin instance.
+//
+// See docs/AGENT_LEARNING_LOOP_PLAN.md §3 Phase 1.
+import { logger, formatError } from '../logger.js';
+import { normalizeBracketSymbol } from '../live/bracket-ledger.js';
+const TAG = 'get-my-recent-reviews';
+const DEFAULT_LIMIT = 3;
+const MAX_LIMIT = 10;
+export async function getMyRecentReviewsTool(args, deps) {
+    if (!deps.decisionsClient || !deps.userId || !deps.stateStore) {
+        // Mirrors record_position_reviews off-mode behaviour — tool callable, but
+        // without ingest wiring there is nothing to read.
+        return {
+            ok: true,
+            positions: [],
+            note: 'Position-decisions ingest is not configured; no reviews available.',
+        };
+    }
+    const limit = clampLimit(args.review_limit);
+    const allEntries = deps.stateStore.getAll();
+    const eligible = allEntries.filter((e) => typeof e.webappPositionId === 'string');
+    const targets = args.symbol
+        ? eligible.filter((e) => e.symbol === normalizeBracketSymbol(args.symbol))
+        : eligible;
+    if (targets.length === 0) {
+        return {
+            ok: true,
+            positions: [],
+            note: args.symbol
+                ? `No open position for ${args.symbol} (or it has not yet upserted to webapp).`
+                : 'No open positions with persisted webapp ids.',
+        };
+    }
+    const positionIds = targets.map((e) => e.webappPositionId);
+    let response;
+    try {
+        response = await deps.decisionsClient.getRecentReviews(deps.userId, positionIds, limit);
+    }
+    catch (err) {
+        logger.warn(TAG, `getRecentReviews threw: ${formatError(err)}`);
+        return { error: 'Failed to fetch reviews from webapp.' };
+    }
+    if (!response) {
+        return { error: 'Webapp /api/internal/position-reviews/recent returned no result.' };
+    }
+    return { ok: true, positions: response.positions };
+}
+function clampLimit(raw) {
+    if (raw === undefined || raw === null)
+        return DEFAULT_LIMIT;
+    if (!Number.isFinite(raw) || raw <= 0)
+        return DEFAULT_LIMIT;
+    return Math.min(Math.floor(raw), MAX_LIMIT);
+}

package/tools/get-orderbook.d.ts

@@ -0,0 +1,21 @@
+import type { BinancePublicApi } from '../ccxt/binance-public.js';
+export interface OrderbookResult {
+    symbol: string;
+    bids: [number, number][];
+    asks: [number, number][];
+    midPrice: number;
+    spread: number;
+    spreadBps: number;
+    bidVolume: number;
+    askVolume: number;
+    imbalance: number;
+    timestamp: string;
+}
+export declare function getOrderbookTool(args: {
+    symbol: string;
+    depth?: number;
+}, deps: {
+    binanceApi: BinancePublicApi;
+}): Promise<OrderbookResult | {
+    error: string;
+}>;

package/tools/get-orderbook.js

@@ -0,0 +1,32 @@
+// Tool: get_orderbook — fetches L2 order book depth from Binance.
+// Returns top N bids/asks with prices and quantities, plus computed
+// metrics: spread, mid-price, bid/ask volume, imbalance ratio.
+export async function getOrderbookTool(args, deps) {
+    const { symbol, depth = 20 } = args;
+    const limit = Math.min(Math.max(depth, 5), 100);
+    const book = await deps.binanceApi.fetchOrderBook(symbol, limit);
+    if (!book || book.bids.length === 0 || book.asks.length === 0) {
+        return { error: `Failed to fetch order book for ${symbol}` };
+    }
+    const bestBid = book.bids[0][0];
+    const bestAsk = book.asks[0][0];
+    const midPrice = (bestBid + bestAsk) / 2;
+    const spread = bestAsk - bestBid;
+    const spreadBps = (spread / midPrice) * 10_000;
+    const bidVolume = book.bids.reduce((sum, [, qty]) => sum + qty, 0);
+    const askVolume = book.asks.reduce((sum, [, qty]) => sum + qty, 0);
+    const totalVolume = bidVolume + askVolume;
+    const imbalance = totalVolume > 0 ? (bidVolume - askVolume) / totalVolume : 0;
+    return {
+        symbol,
+        bids: book.bids,
+        asks: book.asks,
+        midPrice: +midPrice.toFixed(2),
+        spread: +spread.toFixed(2),
+        spreadBps: +spreadBps.toFixed(2),
+        bidVolume: +bidVolume.toFixed(4),
+        askVolume: +askVolume.toFixed(4),
+        imbalance: +imbalance.toFixed(4),
+        timestamp: new Date().toISOString(),
+    };
+}

package/tools/get-pattern-scan.d.ts

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

package/tools/get-pattern-scan.js

@@ -0,0 +1,8 @@
+// Tool: get_pattern_scan — automated chart pattern recognition from OHLCV data.
+// Calls Intelligence API for swing points, trendlines, and 10 pattern types.
+import { fetchIntelApi, enc } from './intel-api.js';
+export async function getPatternScanTool(args, deps) {
+    const intelSymbol = args.symbol.replace('/', '');
+    const timeframe = args.timeframe ?? '1h';
+    return fetchIntelApi(`/api/patterns/${enc(intelSymbol)}?timeframe=${enc(timeframe)}&lookback=200`, deps);
+}

package/tools/get-regime.d.ts

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

package/tools/get-regime.js

@@ -0,0 +1,7 @@
+// Tool: get_regime — fetches regime classification from the Intelligence API.
+// Returns current market regime (trend_up, trend_down, range_tight, etc.)
+// with confidence, probabilities, and contributing features.
+import { fetchIntelApi, enc } from './intel-api.js';
+export async function getRegimeTool(args, deps) {
+    return fetchIntelApi(`/api/regime/${enc(args.symbol)}`, deps);
+}

package/tools/get-relevant-learnings.d.ts

@@ -0,0 +1,21 @@
+import type { PositionDecisionsClient, RelevantLearning } from '../ingest/position-decisions-client.js';
+export interface GetRelevantLearningsArgs {
+    applies_at: 'entry' | 'heartbeat' | 'close';
+    setup_type?: string;
+    regime?: string;
+    verdict?: 'hold' | 'add_on' | 'close_recommended';
+}
+export interface GetRelevantLearningsDeps {
+    decisionsClient?: PositionDecisionsClient;
+    userId?: string;
+}
+export type GetRelevantLearningsResult = {
+    ok: true;
+    learnings: RelevantLearning[];
+    total_candidates: number;
+    returned_count: number;
+    note?: string;
+} | {
+    error: string;
+};
+export declare function getRelevantLearningsTool(args: GetRelevantLearningsArgs, deps: GetRelevantLearningsDeps): Promise<GetRelevantLearningsResult>;

package/tools/get-relevant-learnings.js

@@ -0,0 +1,65 @@
+// Tool: get_relevant_learnings — Phase 4 of the Agent Learning Loop.
+//
+// Returns operator-curated `confirmed` learnings whose trigger_condition
+// matches the current decision context. The agent calls this at decision
+// time (before create_order, before record_position_reviews, before
+// close_position) to read the small set of curated rules that apply NOW.
+//
+// Output capped at 5 learnings per call (server-side enforced) — per
+// docs/AGENT_LEARNING_LOOP_PLAN.md §7 cognitive-load mitigation.
+//
+// Agency-preserving: this is a READ surface. The agent reads, the agent
+// decides. There is no validator that forces compliance. Per
+// memory/feedback_agent_agency_over_hardcoding.md, learnings inform,
+// they don't gate.
+import { logger, formatError } from '../logger.js';
+const TAG = 'get-relevant-learnings';
+const VALID_APPLIES_AT = new Set(['entry', 'heartbeat', 'close']);
+export async function getRelevantLearningsTool(args, deps) {
+    if (!deps.decisionsClient || !deps.userId) {
+        // Ingest not wired — return empty, callable. Same shape as
+        // get_my_recent_reviews under the same condition.
+        return {
+            ok: true,
+            learnings: [],
+            total_candidates: 0,
+            returned_count: 0,
+            note: 'Position-decisions ingest is not configured; no learnings available.',
+        };
+    }
+    if (!args.applies_at || !VALID_APPLIES_AT.has(args.applies_at)) {
+        return {
+            error: "applies_at is required and must be one of: 'entry', 'heartbeat', 'close'.",
+        };
+    }
+    let response;
+    try {
+        response = await deps.decisionsClient.getRelevantLearnings(deps.userId, {
+            appliesAt: args.applies_at,
+            setupType: args.setup_type,
+            regime: args.regime,
+            verdict: args.verdict,
+        });
+    }
+    catch (err) {
+        logger.warn(TAG, `getRelevantLearnings threw: ${formatError(err)}`);
+        return { error: 'Failed to fetch learnings from webapp.' };
+    }
+    if (!response) {
+        // Network/server failure — degrade quietly to empty. The agent should
+        // proceed; missing learnings is not a hard stop.
+        return {
+            ok: true,
+            learnings: [],
+            total_candidates: 0,
+            returned_count: 0,
+            note: 'Webapp /api/internal/learnings returned no result; proceeding without curated learnings.',
+        };
+    }
+    return {
+        ok: true,
+        learnings: response.learnings,
+        total_candidates: response.totalCandidates,
+        returned_count: response.returnedCount,
+    };
+}

package/tools/get-resting-liquidity.d.ts

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

package/tools/get-resting-liquidity.js

@@ -0,0 +1,11 @@
+// Tool: get_resting_liquidity — banded resting limit-order liquidity for a
+// symbol, sourced from the latest order_book_snapshots row. Returns USD
+// notional resting on each side at the 0.2 / 0.5 / 1.0 / 1.5 % bands plus
+// `coverage_pct` (the % range depth-20 actually reaches on this symbol).
+//
+// Returns `{ enabled: false, reason }` when the intel-side
+// `microstructure.bandedLiquidity` flag is off (= columns are NULL).
+import { fetchIntelApi, enc } from './intel-api.js';
+export async function getRestingLiquidityTool(args, deps) {
+    return fetchIntelApi(`/api/resting-liquidity/${enc(args.symbol)}`, deps);
+}