@reefclaw/connect 0.1.12 → 0.1.13

package/assets/plugin/tools/exit-gate.d.ts

@@ -0,0 +1,58 @@
+export type ExitGateMode = 'off' | 'shadow' | 'observe' | 'enforce';
+export type ThesisStatusForGate = 'intact' | 'weakening' | 'invalidated' | 'evolving';
+export type ReviewVerdictForGate = 'hold' | 'add_on' | 'close_recommended';
+export interface ExitGateInputs {
+    /** The close_position reason the agent supplied. `operator_command` always
+     *  passes; the other five reasons go through tier evaluation. */
+    reason: 'regime_flip' | 'scorecard_reversal' | 'risk_limit' | 'bracket_integrity' | 'operator_command';
+    /** Max favorable excursion in R-multiples ever reached on this position.
+     *  Undefined => gate skips (PASS with code 'inputs_unavailable_mfe'). */
+    mfe_r_peak?: number;
+    /** Current R-multiple at the close price. Undefined => gate skips. */
+    current_r?: number;
+    /** Telemetry only (0a/0b) — provenance of the mfe_r_peak / current_r values
+     *  above. Ignored by evaluateExitGate; set by buildExitGateInputs and
+     *  persisted in gate_eval.inputs so the inputs_unavailable_* and
+     *  computed-fallback paths are diagnosable from the journal. */
+    mfe_src?: 'assessment' | 'pos.mfeR' | 'computed_floor';
+    current_r_src?: 'assessment' | 'computed';
+    /** Implied or explicit vol-shock flag from the caller. The caller computes
+     *  this from recent ATR vs latest adverse 5m bar. Default false. */
+    volShock?: boolean;
+    /** Position side — needed for the T2a stop-trail check (long stop ≥ entry,
+     *  short stop ≤ entry). */
+    side?: 'long' | 'short';
+    /** Current bracket stop price. Undefined => T2a check is skipped (PASS with
+     *  code 't2a_skipped_no_stop_known' rather than block). */
+    stopPrice?: number;
+    /** Entry price for the position. Used as the BE level in T2a. */
+    entryPrice?: number;
+    /** Most recent record_position_reviews entry for this position. Drives the
+     *  contradicts-own-review block and the review-override pass. */
+    lastReview?: {
+        verdict: ReviewVerdictForGate;
+        thesis_status: ThesisStatusForGate;
+        review_at_ms: number;
+    };
+    /** Current time in ms — explicit for testability. */
+    now_ms: number;
+}
+export type GateOutcome = 'PASS' | 'BLOCK';
+export interface GateVerdict {
+    outcome: GateOutcome;
+    /** Tier classification: T1 / T2a / T2b / override / skipped. */
+    tier: 'T1' | 'T2a' | 'T2b' | 'override' | 'skipped';
+    /** Stable code identifying the specific predicate that fired.
+     *  e.g. 't1_premature_exit', 't2a_stop_not_trailed_to_BE',
+     *  'operator_command', 'vol_shock', 'contradicts_own_recent_hold_verdict'. */
+    code: string;
+    /** Optional recovery hint for BLOCK outcomes — surfaced back to the agent
+     *  via the tool error so it can self-correct mid-turn. */
+    recovery_hint?: string;
+    /** Optional discipline-failure flag, currently only set on T2b passes so
+     *  we capture "winner peaked, reversed, no stop-trail done". */
+    discipline_failure?: string;
+}
+/** Evaluate the exit gate against the supplied inputs. Pure; safe to call
+ *  from anywhere. See module header for semantics. */
+export declare function evaluateExitGate(inputs: ExitGateInputs): GateVerdict;

package/assets/plugin/tools/exit-gate.js

@@ -0,0 +1,162 @@
+// Exit gate — prevents the agent from closing positions before they've
+// meaningfully developed, while preserving override paths for genuine adverse
+// signals. See docs/EXIT_GATE_DESIGN.md for the full spec and §3 for the
+// tier table this function implements.
+//
+// Pure function — caller supplies all inputs, including the mode flag, and the
+// function returns a structured verdict. Caller (close-position.ts) is
+// responsible for actually blocking, soft-warning, or logging based on mode.
+//
+// Design contract:
+//   - In `off` mode the gate is never called at all (don't pay the input
+//     computation cost).
+//   - In `shadow` / `observe` / `enforce` the gate runs; the caller decides
+//     what to do with BLOCK verdicts.
+//   - If inputs are partial (e.g., MFE not supplied), the gate returns
+//     PASS('inputs_unavailable') — never BLOCK on missing data. The shadow
+//     soak surfaces these so we can fix plumbing before enforce.
+//   - The "contradicts-own-review" rule applies pre-tier (blocks T2b too).
+//     See §8 R4 in the design doc — this is the conservative default; we
+//     watch shadow telemetry and demote to T1-only if it blocks legit exits.
+/** Window during which a hold-verdict review blocks a contradicting close. */
+const CONTRADICTS_OWN_REVIEW_WINDOW_MS = 5 * 60 * 1000;
+/** Developed-position threshold in R-multiples. */
+const DEVELOPED_MFE_R = 0.5;
+/** T1 escape threshold — position deteriorating fast. */
+const T1_ESCAPE_CURRENT_R = -0.5;
+/** 0c — floor for the 'weakening' review override. The t1_review_override pass
+ *  was the dominant exit (~42% of agent closes) and, by construction, every one
+ *  is a T1-premature position — the exact population the gate exists to BLOCK.
+ *  It was fully agent-self-served: file verdict='close_recommended' +
+ *  thesis_status='weakening' and the block lifted with zero objective
+ *  corroboration. We now split by strength of claim: 'invalidated' (a strong,
+ *  falsifiable thesis break — regime flip / level broken) keeps the FULL
+ *  override even at breakeven; 'weakening' (a soft, abuse-prone signal) only
+ *  overrides once price has ALSO moved adversely to at least this floor.
+ *  ⚠ This threshold is a value to SOAK in shadow (compare would_have_blocked vs
+ *  which positions later hit TP), NOT a derived optimum — tightening reclassifies
+ *  a large population. See docs/EXIT_DISCIPLINE_BUILD_PLAN.md Step 0c. */
+const T1_WEAKENING_OVERRIDE_FLOOR_R = -0.25;
+/** Evaluate the exit gate against the supplied inputs. Pure; safe to call
+ *  from anywhere. See module header for semantics. */
+export function evaluateExitGate(inputs) {
+    // 0. Always-allow overrides — checked first, before any input-availability
+    //    checks, so the operator can ALWAYS get out.
+    if (inputs.reason === 'operator_command') {
+        return { outcome: 'PASS', tier: 'override', code: 'operator_command' };
+    }
+    if (inputs.volShock === true) {
+        return { outcome: 'PASS', tier: 'override', code: 'vol_shock' };
+    }
+    // 1. Contradicts-own-review block — pre-tier.
+    //    The "intact + hold → close" pattern from the May 12 analysis. If the
+    //    agent's last review said hold AND was recent, refuse to immediately
+    //    contradict it. Operator command (above) is the only override.
+    const lr = inputs.lastReview;
+    if (lr && lr.verdict === 'hold') {
+        const age = inputs.now_ms - lr.review_at_ms;
+        if (age < CONTRADICTS_OWN_REVIEW_WINDOW_MS && age >= 0) {
+            return {
+                outcome: 'BLOCK',
+                tier: 'override',
+                code: 'contradicts_own_recent_hold_verdict',
+                recovery_hint: `Last record_position_reviews filed verdict='hold' ${Math.round(age / 1000)}s ago. ` +
+                    `If conditions have genuinely changed, file a fresh review with verdict='close_recommended' first. ` +
+                    `Operator can override via reason='operator_command'.`,
+            };
+        }
+    }
+    // 2. Input availability — we need mfe_r_peak + current_r to do tier work.
+    //    Missing => PASS with a skip code so shadow telemetry can surface the
+    //    plumbing gap.
+    if (typeof inputs.mfe_r_peak !== 'number' || !Number.isFinite(inputs.mfe_r_peak)) {
+        return { outcome: 'PASS', tier: 'skipped', code: 'inputs_unavailable_mfe' };
+    }
+    if (typeof inputs.current_r !== 'number' || !Number.isFinite(inputs.current_r)) {
+        return { outcome: 'PASS', tier: 'skipped', code: 'inputs_unavailable_current_r' };
+    }
+    // 3. Review override — well-formed close_recommended on a genuine adverse
+    //    signal. 0c split (see T1_WEAKENING_OVERRIDE_FLOOR_R): 'invalidated' (a
+    //    strong, falsifiable break) overrides outright; 'weakening' (soft, the
+    //    scratch-laundering vector) overrides ONLY with price confirmation
+    //    (current_r ≤ the floor). inputs.current_r is guaranteed finite here
+    //    (checked in step 2 above).
+    const reviewOverride = !!lr &&
+        lr.verdict === 'close_recommended' &&
+        (lr.thesis_status === 'invalidated' ||
+            (lr.thesis_status === 'weakening' && inputs.current_r <= T1_WEAKENING_OVERRIDE_FLOOR_R));
+    // 4. Tier classification.
+    const developed = inputs.mfe_r_peak >= DEVELOPED_MFE_R;
+    if (!developed) {
+        // ── Tier 1: never developed (mfe_r_peak < 0.5) ──
+        if (inputs.current_r <= T1_ESCAPE_CURRENT_R) {
+            return {
+                outcome: 'PASS',
+                tier: 'T1',
+                code: 't1_escape_deteriorating',
+            };
+        }
+        if (reviewOverride) {
+            return {
+                outcome: 'PASS',
+                tier: 'T1',
+                code: 't1_review_override',
+            };
+        }
+        return {
+            outcome: 'BLOCK',
+            tier: 'T1',
+            code: 't1_premature_exit',
+            recovery_hint: `Position has not developed (mfe_r_peak=${inputs.mfe_r_peak.toFixed(2)}R < 0.5R) and is not deteriorating ` +
+                `(current_r=${inputs.current_r.toFixed(2)}R > -0.5R). ` +
+                `Let the bracket be the exit. Override paths: ` +
+                `(a) file verdict='close_recommended' with thesis_status='invalidated' — a real, falsifiable ` +
+                `thesis break (regime flip, key level broken), not a soft read; ` +
+                `(b) thesis_status='weakening' overrides ONLY once current_r ≤ -0.25R (soft signals need price confirmation); ` +
+                `(c) wait for current_r ≤ -0.5R; (d) operator_command.`,
+        };
+    }
+    // ── Tier 2: developed (mfe_r_peak ≥ 0.5) ──
+    if (inputs.current_r >= 0) {
+        // T2a — in profit. Require stop has been trailed to BE-or-better.
+        // Need side + stopPrice + entryPrice to check; if any missing, pass with
+        // a skip code so shadow telemetry surfaces it.
+        if (!inputs.side ||
+            typeof inputs.stopPrice !== 'number' ||
+            !Number.isFinite(inputs.stopPrice) ||
+            typeof inputs.entryPrice !== 'number' ||
+            !Number.isFinite(inputs.entryPrice)) {
+            return {
+                outcome: 'PASS',
+                tier: 'T2a',
+                code: 't2a_skipped_no_stop_known',
+            };
+        }
+        const stopAtBE = inputs.side === 'long' ? inputs.stopPrice >= inputs.entryPrice : inputs.stopPrice <= inputs.entryPrice;
+        if (!stopAtBE) {
+            return {
+                outcome: 'BLOCK',
+                tier: 'T2a',
+                code: 't2a_stop_not_trailed_to_BE',
+                recovery_hint: `Position developed to mfe_r_peak=${inputs.mfe_r_peak.toFixed(2)}R and is currently in profit ` +
+                    `(current_r=${inputs.current_r.toFixed(2)}R), but stop is still at original level ` +
+                    `(stop=${inputs.stopPrice}, entry=${inputs.entryPrice}). ` +
+                    `Call modify_stop to move stop to ${inputs.entryPrice} (break-even) or better before closing. ` +
+                    `This locks in profit and is the v2.10.0 winner-protection rule.`,
+            };
+        }
+        return {
+            outcome: 'PASS',
+            tier: 'T2a',
+            code: 't2a_developed_in_profit_stop_trailed',
+        };
+    }
+    // T2b — developed, now in red. Horse has bolted; allow the exit but flag
+    // as discipline failure so we can study these later.
+    return {
+        outcome: 'PASS',
+        tier: 'T2b',
+        code: 't2b_developed_reversed',
+        discipline_failure: 'unmanaged_winner_reversed',
+    };
+}

package/assets/plugin/tools/fetch-balance.d.ts

@@ -0,0 +1,5 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { CcxtBalance } from '../types.js';
+export declare function fetchBalanceTool(_args: Record<string, unknown>, deps: {
+    adapter: IExchangeAdapter;
+}): Promise<CcxtBalance>;

package/assets/plugin/tools/fetch-balance.js

@@ -0,0 +1,4 @@
+// Tool: fetch_balance — wallet balance (paper or live)
+export async function fetchBalanceTool(_args, deps) {
+    return deps.adapter.getBalance();
+}

package/assets/plugin/tools/fetch-ohlcv.d.ts

@@ -0,0 +1,11 @@
+import type { PublicMarketDataApi } from '../ccxt/public-market-data-api.js';
+import type { CcxtOHLCV } from '../types.js';
+export declare function fetchOhlcvTool(args: {
+    symbol: string;
+    timeframe?: string;
+    limit?: number;
+}, deps: {
+    binanceApi: PublicMarketDataApi;
+}): Promise<CcxtOHLCV[] | {
+    error: string;
+}>;

package/assets/plugin/tools/fetch-ohlcv.js

@@ -0,0 +1,8 @@
+// Tool: fetch_ohlcv — real Binance OHLCV candles via CCXT
+export async function fetchOhlcvTool(args, deps) {
+    const candles = await deps.binanceApi.fetchOHLCV(args.symbol, args.timeframe ?? '1h', args.limit ?? 100);
+    if (!candles) {
+        return { error: `Failed to fetch OHLCV for ${args.symbol}` };
+    }
+    return candles;
+}

package/assets/plugin/tools/fetch-open-orders.d.ts

@@ -0,0 +1,7 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { CcxtOrder } from '../types.js';
+export declare function fetchOpenOrdersTool(args: {
+    symbol?: string;
+}, deps: {
+    adapter: IExchangeAdapter;
+}): Promise<CcxtOrder[]>;

package/assets/plugin/tools/fetch-open-orders.js

@@ -0,0 +1,4 @@
+// Tool: fetch_open_orders — pending orders (paper or live)
+export async function fetchOpenOrdersTool(args, deps) {
+    return deps.adapter.getOpenOrders(args.symbol);
+}

package/assets/plugin/tools/fetch-positions.d.ts

@@ -0,0 +1,7 @@
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { CcxtPosition } from '../types.js';
+export declare function fetchPositionsTool(args: {
+    symbol?: string;
+}, deps: {
+    adapter: IExchangeAdapter;
+}): Promise<CcxtPosition[]>;

package/assets/plugin/tools/fetch-positions.js

@@ -0,0 +1,4 @@
+// Tool: fetch_positions — open positions (paper or live)
+export async function fetchPositionsTool(args, deps) {
+    return deps.adapter.getPositions(args.symbol);
+}

package/assets/plugin/tools/fetch-ticker.d.ts

@@ -0,0 +1,11 @@
+import type { PublicMarketDataApi } from '../ccxt/public-market-data-api.js';
+import type { ExchangeSimulator } from '../simulator/exchange-simulator.js';
+import type { CcxtTicker } from '../types.js';
+export declare function fetchTickerTool(args: {
+    symbol: string;
+}, deps: {
+    binanceApi: PublicMarketDataApi;
+    simulator: ExchangeSimulator;
+}): Promise<CcxtTicker | {
+    error: string;
+}>;

package/assets/plugin/tools/fetch-ticker.js

@@ -0,0 +1,5 @@
+// Tool: fetch_ticker — real Binance market data via CCXT
+import { fetchCurrentPrice } from './helpers.js';
+export async function fetchTickerTool(args, deps) {
+    return fetchCurrentPrice(args.symbol, deps);
+}

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

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

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

@@ -0,0 +1,6 @@
+// Tool: get_agent_profile — returns earned autonomy tier and permissions.
+// The agent checks this at session start to know what it's allowed to adjust.
+import { fetchIntelApi } from './intel-api.js';
+export async function getAgentProfileTool(deps) {
+    return fetchIntelApi('/api/agent-profile', deps);
+}

package/assets/plugin/tools/get-analytics.d.ts

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

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

@@ -0,0 +1,7 @@
+// Tool: get_analytics — fetches edge analytics from the Intelligence API.
+// Returns per-strategy performance metrics (win rate, expectancy, Sharpe),
+// regime breakdown, equity curve, and degradation alerts.
+import { fetchIntelApi, enc, resolveIntelSymbol } from './intel-api.js';
+export async function getAnalyticsTool(args, deps) {
+    return fetchIntelApi(`/api/analytics/${enc(resolveIntelSymbol(deps, args.symbol))}`, deps);
+}

package/assets/plugin/tools/get-backtest.d.ts

@@ -0,0 +1,12 @@
+import type { IntelApiDeps } from './intel-api.js';
+export interface BacktestArgs {
+    symbol: string;
+    strategy?: string;
+    months?: number;
+    sizing?: string;
+    regime_filter?: string;
+    timeframe?: string;
+}
+export declare function getBacktestTool(args: BacktestArgs, deps: IntelApiDeps): Promise<Record<string, unknown> | {
+    error: string;
+}>;

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

@@ -0,0 +1,91 @@
+// Tool: get_backtest — backtest a trading strategy against historical data.
+// Calls Intelligence API to run walk-forward simulation and returns agent-friendly summary.
+//
+// Uses the async job pattern: POST /api/backtest/:symbol?async=true returns a
+// job_id immediately; we then poll GET /api/backtest/job/:id every 5s until
+// status='done' or timeout. This supports multi-year backtests (up to 15min
+// wall-clock on the intel worker) without coupling client-side timeouts to
+// server-side compute. See `docs/BACKTEST_CHUNKING_PLAN.md` for the engine-
+// side chunking that makes the worker complete in bounded time.
+import { fetchIntelApi, enc } from './intel-api.js';
+/** How long the plugin will keep polling before giving up. Independent of
+ *  the server-side worker timeout (currently 1800s = 30min); we add 60s
+ *  slack so a job that finishes RIGHT AT the server cap still gets one
+ *  last poll. Bump this in lockstep with `ASYNC_BACKTEST_TIMEOUT_MS` in
+ *  `intelligence/src/health/server.ts` — otherwise the plugin bails
+ *  before the worker is allowed to finish. */
+const MAX_POLL_DURATION_MS = 1_860_000; // 31 min
+const POLL_INTERVAL_MS = 5_000;
+/** Consecutive transient poll-error tolerance before bailing. Single 502s
+ *  during intel-api restarts are routine; >3 in a row indicates real
+ *  network/service failure and we surface the error to the agent. */
+const MAX_CONSECUTIVE_POLL_ERRORS = 5;
+export async function getBacktestTool(args, deps) {
+    const intelSymbol = args.symbol.replace('/', '');
+    const months = args.months ?? 6;
+    // Round to hour boundary for cache key stability (repeated calls within same hour hit cache)
+    const nowHour = Math.floor(Date.now() / 3600000) * 3600000;
+    const endDate = new Date(nowHour).toISOString();
+    const startDate = new Date(nowHour - months * 30 * 86400000).toISOString();
+    const body = {
+        strategy: args.strategy ?? 'all',
+        startDate,
+        endDate,
+        timeframe: args.timeframe ?? '1h',
+        initialCapital: 10000,
+        sizingMethod: args.sizing === 'kelly' ? 'kelly' : 'fixed',
+    };
+    if (args.regime_filter) {
+        body.regimeFilter = args.regime_filter.split(',').map((s) => s.trim());
+    }
+    // Kick off the async job. The POST returns within seconds with either a
+    // cache-hit result (status='done' inline) or a queued job_id to poll.
+    const kickoffRaw = await fetchIntelApi(`/api/backtest/${enc(intelSymbol)}?async=true`, deps, { method: 'POST', body, timeoutMs: 30_000 });
+    if ('error' in kickoffRaw && typeof kickoffRaw.error === 'string') {
+        return { error: kickoffRaw.error };
+    }
+    const kickoff = kickoffRaw;
+    // Cache hit short-circuit: server already had the result, no polling needed.
+    if (kickoff.status === 'done' && kickoff.result) {
+        return kickoff.result;
+    }
+    if (kickoff.status === 'error') {
+        return { error: `Backtest failed: ${kickoff.error ?? 'unknown error'}` };
+    }
+    const jobId = kickoff.job_id;
+    if (!jobId) {
+        return { error: 'Intelligence API did not return a job_id for async backtest request.' };
+    }
+    // Poll loop. We tolerate up to MAX_CONSECUTIVE_POLL_ERRORS transient errors
+    // (intel-api restart, brief network hiccup) before giving up — those return
+    // strings from fetchIntelApi look like {error: "..."} but don't mean the
+    // backtest itself failed.
+    const pollStart = Date.now();
+    let consecutiveErrors = 0;
+    while (Date.now() - pollStart < MAX_POLL_DURATION_MS) {
+        await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+        const statusRaw = await fetchIntelApi(`/api/backtest/job/${enc(jobId)}`, deps, { method: 'GET', timeoutMs: 15_000 });
+        if ('error' in statusRaw && typeof statusRaw.error === 'string') {
+            consecutiveErrors += 1;
+            if (consecutiveErrors >= MAX_CONSECUTIVE_POLL_ERRORS) {
+                return {
+                    error: `Lost contact with intel API while polling backtest job ${jobId}: ${statusRaw.error}. Job may still complete server-side; retry the same call to pick up the cached result.`,
+                };
+            }
+            continue;
+        }
+        consecutiveErrors = 0;
+        const status = statusRaw;
+        if (status.status === 'done' && status.result) {
+            return status.result;
+        }
+        if (status.status === 'error') {
+            return { error: `Backtest job ${jobId} failed: ${status.error ?? 'unknown error'}` };
+        }
+        // 'queued' or 'running' — continue polling
+    }
+    const elapsedMin = Math.round((Date.now() - pollStart) / 60_000);
+    return {
+        error: `Backtest job ${jobId} still running after ${elapsedMin} min. The intel worker has a 15-min server-side cap; retry the same call (cached if it finished after we gave up) or shorten the window.`,
+    };
+}

package/assets/plugin/tools/get-basis.d.ts

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

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

@@ -0,0 +1,7 @@
+// Tool: get_basis — fetches spot-futures basis (mark-spot premium) analysis.
+// Returns current premium/discount, historical basis, funding alignment, and dislocation detection.
+import { fetchIntelApi, enc, resolveIntelSymbol } from './intel-api.js';
+export async function getBasisTool(args, deps) {
+    const hours = args.hours ?? 24;
+    return fetchIntelApi(`/api/basis/${enc(resolveIntelSymbol(deps, args.symbol))}?hours=${hours}`, deps);
+}

package/assets/plugin/tools/get-bracket-config.d.ts

@@ -0,0 +1,11 @@
+import type { BracketMode } from '../config/brackets-config.js';
+export interface GetBracketConfigResult {
+    mode: BracketMode;
+    requireStopLoss: boolean;
+    requireTakeProfit: boolean;
+}
+export declare function getBracketConfigTool(_args: Record<string, never>, deps?: {
+    configPath?: string;
+}): GetBracketConfigResult | {
+    error: string;
+};

package/assets/plugin/tools/get-bracket-config.js

@@ -0,0 +1,24 @@
+// get_bracket_config — read current brackets section from plugin-config.
+//
+// Operator-only in spirit (the agent shouldn't care about the value — the
+// pre-trade gate already enforces it). Exposed so the dashboard's Trading
+// Parameters panel can fetch current state before rendering the toggles.
+import { readPluginConfig } from '../config/plugin-config-io.js';
+import { getBracketMode, getBracketRequirements } from '../config/brackets-config.js';
+import { formatError } from '../logger.js';
+export function getBracketConfigTool(_args, deps) {
+    try {
+        const cfg = readPluginConfig(deps?.configPath);
+        const mode = getBracketMode(cfg);
+        const req = getBracketRequirements(cfg);
+        return {
+            mode,
+            requireStopLoss: req.requireStopLoss,
+            requireTakeProfit: req.requireTakeProfit,
+        };
+    }
+    catch (err) {
+        // Missing file → defaults; any other error → surface it.
+        return { error: formatError(err) };
+    }
+}

package/assets/plugin/tools/get-cascade-risk.d.ts

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

package/assets/plugin/tools/get-cascade-risk.js

@@ -0,0 +1,8 @@
+// Tool: get_cascade_risk — fetches liquidation cascade risk assessment.
+// Returns proximity to liquidation clusters, cascade impact estimates,
+// recent liquidation activity, and overall risk score.
+import { fetchIntelApi, enc, resolveIntelSymbol } from './intel-api.js';
+export async function getCascadeRiskTool(args, deps) {
+    const hours = args.hours ?? 24;
+    return fetchIntelApi(`/api/cascade-risk/${enc(resolveIntelSymbol(deps, args.symbol))}?hours=${hours}`, deps);
+}

package/assets/plugin/tools/get-crypto-metrics.d.ts

@@ -0,0 +1,18 @@
+import type { PublicMarketDataApi } from '../ccxt/public-market-data-api.js';
+export interface CryptoMetricsResult {
+    symbol: string;
+    fundingRate: number | null;
+    fundingRateAnnualized: number | null;
+    openInterest: number | null;
+    openInterestUsd: number | null;
+    nextFundingTime: string | null;
+    lastPrice: number;
+    timestamp: string;
+}
+export declare function getCryptoMetricsTool(args: {
+    symbol: string;
+}, deps: {
+    binanceApi: PublicMarketDataApi;
+}): Promise<CryptoMetricsResult | {
+    error: string;
+}>;

package/assets/plugin/tools/get-crypto-metrics.js

@@ -0,0 +1,62 @@
+// Tool: get_crypto_metrics — funding rate + open interest from Binance perpetual futures
+// Uses dedicated CCXT methods (fetchFundingRate + fetchOpenInterest) instead of fetchTicker,
+// because Binance's 24hr ticker endpoint does NOT include funding/OI data.
+import { fromIntelSymbol } from '../venues/symbols.js';
+export async function getCryptoMetricsTool(args, deps) {
+    try {
+        // The agent routinely pastes intel-form ids into this tool ('ETHUSDT',
+        // 'HL_BTC' — ~100×/day live as of 2026-07-13). Handed to ccxt verbatim, a
+        // concatenated id resolves to the SPOT market and funding/OI fail
+        // ("supports linear and inverse contracts only"). Map both intel
+        // namespaces back to canonical BASE/QUOTE first; anything fromIntelSymbol
+        // can't map comes back verbatim (honest passthrough, no invented quote).
+        const canonical = args.symbol.includes('/') || args.symbol.includes(':')
+            ? args.symbol
+            : fromIntelSymbol(args.symbol.trim()).canonical;
+        // Funding rate & OI only exist on perpetual futures. Convert a canonical
+        // symbol to its linear-perp ccxt form by settling in the QUOTE currency
+        // (BTC/USDT → BTC/USDT:USDT on Binance, BTC/USDC → BTC/USDC:USDC on
+        // Hyperliquid). A hardcoded :USDT suffix produced the nonsense form
+        // BTC/USDC:USDT on the HL venue (seen live, wisekid soak 2026-07-12) —
+        // never silently translate quote assets across venues.
+        const quote = canonical.split('/')[1];
+        const perpSymbol = canonical.includes(':') || !quote
+            ? canonical
+            : `${canonical}:${quote}`;
+        // Fetch funding rate and open interest in parallel (separate API endpoints)
+        const [fundingData, oiData, tickerData] = await Promise.all([
+            deps.binanceApi.fetchFundingRate(perpSymbol),
+            deps.binanceApi.fetchOpenInterest(perpSymbol),
+            deps.binanceApi.fetchTickerRaw(perpSymbol), // for lastPrice
+        ]);
+        // Extract funding rate
+        const fundingRate = fundingData?.fundingRate ?? null;
+        const nextFundingTime = fundingData?.fundingDatetime
+            ?? (fundingData?.fundingTimestamp ? new Date(fundingData.fundingTimestamp).toISOString() : null);
+        // Annualized: funding rate * 3 periods/day * 365
+        const fundingRateAnnualized = fundingRate !== null
+            ? fundingRate * 3 * 365 * 100 // as percentage
+            : null;
+        // Extract open interest
+        const openInterest = oiData?.openInterestAmount ?? null;
+        let openInterestUsd = oiData?.openInterestValue ?? null;
+        // Estimate USD value if not provided directly
+        const lastPrice = tickerData?.last ?? 0;
+        if (openInterestUsd === null && openInterest !== null && lastPrice > 0) {
+            openInterestUsd = openInterest * lastPrice;
+        }
+        return {
+            symbol: args.symbol,
+            fundingRate: fundingRate !== null ? +fundingRate.toFixed(6) : null,
+            fundingRateAnnualized: fundingRateAnnualized !== null ? +fundingRateAnnualized.toFixed(2) : null,
+            openInterest: openInterest !== null ? +openInterest.toFixed(4) : null,
+            openInterestUsd: openInterestUsd !== null ? Math.round(openInterestUsd) : null,
+            nextFundingTime,
+            lastPrice,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    catch (err) {
+        return { error: `get_crypto_metrics failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}

package/assets/plugin/tools/get-cvd.d.ts

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

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

@@ -0,0 +1,6 @@
+// Tool: get_cvd — fetches CVD (Cumulative Volume Delta) analysis from the Intelligence API.
+// Returns buy/sell pressure, divergence detection, slope, z-score, and interpretation.
+import { fetchIntelApi, enc, resolveIntelSymbol } from './intel-api.js';
+export async function getCvdTool(args, deps) {
+    return fetchIntelApi(`/api/cvd/${enc(resolveIntelSymbol(deps, args.symbol))}`, deps);
+}

package/assets/plugin/tools/get-divergences.d.ts

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

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

@@ -0,0 +1,6 @@
+// Tool: get_divergences — multi-timeframe RSI/MACD divergence scanner.
+// Detects price-vs-indicator divergences across 15m, 1h, 4h, 1d timeframes.
+import { fetchIntelApi, enc, resolveIntelSymbol } from './intel-api.js';
+export async function getDivergencesTool(args, deps) {
+    return fetchIntelApi(`/api/divergences/${enc(resolveIntelSymbol(deps, args.symbol))}`, deps);
+}

package/assets/plugin/tools/get-funding-context.d.ts

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