@reefclaw/connect 0.1.12 → 0.1.13

package/assets/plugin/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/assets/plugin/tools/get-orderbook.d.ts

@@ -0,0 +1,21 @@
+import type { PublicMarketDataApi } from '../ccxt/public-market-data-api.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: PublicMarketDataApi;
+}): Promise<OrderbookResult | {
+    error: string;
+}>;

package/assets/plugin/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/assets/plugin/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/assets/plugin/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, resolveIntelSymbol } from './intel-api.js';
+export async function getPatternScanTool(args, deps) {
+    const intelSymbol = resolveIntelSymbol(deps, args.symbol);
+    const timeframe = args.timeframe ?? '1h';
+    return fetchIntelApi(`/api/patterns/${enc(intelSymbol)}?timeframe=${enc(timeframe)}&lookback=200`, deps);
+}

package/assets/plugin/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/assets/plugin/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, resolveIntelSymbol } from './intel-api.js';
+export async function getRegimeTool(args, deps) {
+    return fetchIntelApi(`/api/regime/${enc(resolveIntelSymbol(deps, args.symbol))}`, deps);
+}

package/assets/plugin/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/assets/plugin/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/assets/plugin/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/assets/plugin/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, resolveIntelSymbol } from './intel-api.js';
+export async function getRestingLiquidityTool(args, deps) {
+    return fetchIntelApi(`/api/resting-liquidity/${enc(resolveIntelSymbol(deps, args.symbol))}`, deps);
+}

package/assets/plugin/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/assets/plugin/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, resolveIntelSymbol } 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 = resolveIntelSymbol(deps.intelApiDeps, args.symbol);
+    const body = {
+        positions: apiPositions,
+        balance,
+        ...(scenarios && scenarios.length > 0 && { scenarios }),
+    };
+    return fetchIntelApi(`/api/risk-scenario/${enc(intelSymbol)}`, deps.intelApiDeps, {
+        method: 'POST',
+        body,
+    });
+}

package/assets/plugin/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/assets/plugin/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/assets/plugin/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/assets/plugin/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/assets/plugin/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/assets/plugin/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, resolveIntelSymbol } from './intel-api.js';
+export async function getSessionReviewTool(args, deps) {
+    const intelSymbol = resolveIntelSymbol(deps, args.symbol);
+    const hours = args.hours ?? 24;
+    return fetchIntelApi(`/api/session-review/${enc(intelSymbol)}?hours=${hours}`, deps);
+}

package/assets/plugin/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;
+}>;