@reefclaw/connect 0.1.11 → 0.1.12

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

@@ -1,66 +0,0 @@
-// 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

@@ -1,21 +0,0 @@
-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

@@ -1,32 +0,0 @@
-// 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

@@ -1,7 +0,0 @@
-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

@@ -1,8 +0,0 @@
-// 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

@@ -1,6 +0,0 @@
-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

@@ -1,7 +0,0 @@
-// 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

@@ -1,21 +0,0 @@
-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

@@ -1,65 +0,0 @@
-// 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

@@ -1,6 +0,0 @@
-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

@@ -1,11 +0,0 @@
-// 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

@@ -1,29 +0,0 @@
-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

@@ -1,47 +0,0 @@
-// 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

@@ -1,51 +0,0 @@
-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

@@ -1,118 +0,0 @@
-// 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

@@ -1,4 +0,0 @@
-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

@@ -1,6 +0,0 @@
-// 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

@@ -1,7 +0,0 @@
-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

@@ -1,8 +0,0 @@
-// 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

@@ -1,7 +0,0 @@
-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;
-}>;