@reefclaw/openclaw-plugin 0.1.0

package/bridge/gateway/poller.js

@@ -0,0 +1,505 @@
+// Polling orchestrator for the OpenClaw gateway.
+// Interval-based HTTP polling for market data, positions, balance, and open orders.
+// Polls are scheduled per-tool with independent intervals and in-flight guards.
+import { logger } from '../logger.js';
+import { mapCcxtTicker, mapCcxtBalance, mapCcxtOrder } from './event-parser.js';
+const TAG = 'poller';
+// ---- Polling intervals (ms) ----
+// 1s was redundant: price/mark already streams to the dashboard via the
+// WS subscription at 250ms (see CLAUDE.md "Rendering Throttle"). A 1s REST
+// ticker poll added constant per-IP weight pressure and amplified retries
+// under the pacer for zero UI benefit. 5s is operationally invisible.
+// Exported so tests advance timers relative to the cadence, not a literal.
+export const TICKER_INTERVAL_MS = 5_000;
+// 2026-05-15: 5s → 15s. Chart candles only need eventual consistency — the
+// live price/last-candle tip moves via the 250ms WS mark/ticker path, not
+// this REST backfill. 15s is operationally invisible and cuts this poll's
+// per-IP klines weight 3×. Exported so tests track the cadence.
+export const OHLCV_INTERVAL_MS = 15_000;
+// 2026-05-15 EFFICIENCY_QUICK_WINS Change 2: 3s → 10s. Position QUANTITY
+// only changes when we trade (heartbeats every 10 min); live P&L keeps
+// ticking via the mark-price path, and brackets are exchange-enforced. 10s
+// is operationally imperceptible and saves ~70 weight/min (100→30). The
+// plan's config-gating refinement is deliberately deferred — the constant
+// delivers the full saving; piping a new flag through the plugin→skill
+// startup handshake is extra live-system surface area for no extra weight.
+export const POSITIONS_INTERVAL_MS = 10_000;
+const BALANCE_INTERVAL_MS = 10_000;
+const OPEN_ORDERS_INTERVAL_MS = 3_000;
+// 2026-05-15: 30s → 60s. get_market_structure fetches SIX timeframes of
+// OHLCV per poll (the heaviest single skill poll). Multi-timeframe trend
+// structure does not meaningfully change in 30s; 60s keeps the Agent-State
+// panel current while halving this poll's klines weight. Exported for tests.
+export const MARKET_STRUCTURE_INTERVAL_MS = 60_000;
+const CRYPTO_METRICS_INTERVAL_MS = 60_000;
+const VOLUME_ANALYSIS_INTERVAL_MS = 15_000;
+// ---- Poller class ----
+/** 429 exponential-backoff schedule (ms). After each consecutive 429 we
+ *  advance one step; a clean poll resets to step 0. Capped so we never go
+ *  fully silent — at the cap we still probe once every 2 min, which is
+ *  enough to notice the limit clearing without re-triggering it. */
+const RATE_LIMIT_BACKOFF_MS = [5_000, 15_000, 45_000, 90_000, 120_000];
+/** Extra slack added on top of Binance's stated `banned until` timestamp
+ *  before we resume — clock skew + a margin so the very first post-ban poll
+ *  doesn't land on the boundary and immediately re-ban. */
+const BAN_RESUME_SLACK_MS = 8_000;
+/** True when an error message carries a Binance rate-limit / IP-ban signal
+ *  (418 ban, or 429 / -1003 "too many requests" soft limit). Poll methods that
+ *  wrap their own try/catch MUST rethrow these so guardedExec's catch can arm
+ *  the process-wide circuit-breaker (applyRateLimitBackoff). Swallowing them
+ *  internally as "supplementary/non-fatal" silently defeats the ban gate: a
+ *  fixed-cadence poller keeps hammering a banned IP, and every request during a
+ *  418 EXTENDS the ban (see docs/CLAUDE/binance-ratelimit.md). Kept in sync
+ *  with the classification branches in applyRateLimitBackoff. */
+export function isRateLimitShapedError(msg) {
+    return (msg.includes('418') ||
+        /banned until/i.test(msg) ||
+        msg.includes('429') ||
+        msg.includes('-1003') ||
+        /too many requests/i.test(msg));
+}
+export class Poller {
+    http;
+    toolMap;
+    symbol;
+    callbacks;
+    quoteCurrency;
+    running = false;
+    paused = false;
+    timers = [];
+    /** Prevents concurrent polls of the same type (if HTTP is slow) */
+    inflight = new Set();
+    /** Process-wide circuit-breaker. While `Date.now() < cooldownUntilMs`,
+     *  `guardedExec` skips EVERY poll regardless of type. Set when any poll
+     *  observes a Binance 418 (IP ban) or 429 (rate-limit) error.
+     *
+     *  Why this exists: pre-2026-05-15 the poller had no ban awareness — on a
+     *  418 every one of ~8 pollers (ticker 1s, positions/orders 3s, …) kept
+     *  firing on its original cadence straight through the ban, and since
+     *  Binance EXTENDS an IP ban every time you hit it during the ban, the
+     *  system never recovered on its own (self-perpetuating lockout that
+     *  zeroed the dashboard + blinded the agent for the whole window). The
+     *  breaker makes the whole poller go quiet until Binance's stated ban
+     *  expiry (+slack), or an exponential window for soft 429s. */
+    cooldownUntilMs = 0;
+    /** Index into RATE_LIMIT_BACKOFF_MS for consecutive soft 429s. Reset to
+     *  -1 (→ step 0 on first hit) after any clean poll. */
+    rateLimitStep = -1;
+    /** Throttles the "in cooldown, skipping" log to once per cooldown window
+     *  so a 2-min ban doesn't emit hundreds of identical skip lines. */
+    cooldownLogged = false;
+    /** Per-tool poll-attribution for the current 60s window (observability
+     *  only). The skill is a SEPARATE process from the plugin but shares the
+     *  Binance per-IP weight budget; the plugin's ban-gate weight summary
+     *  cannot see skill polls. This is the skill-side mirror so the IP load
+     *  split is provable, not guessed. */
+    pollWindowStart = 0;
+    pollCountByTool = new Map();
+    constructor(http, toolMap, symbol, callbacks, quoteCurrency = 'USDT') {
+        this.http = http;
+        this.toolMap = toolMap;
+        this.symbol = symbol;
+        this.callbacks = callbacks;
+        this.quoteCurrency = quoteCurrency;
+    }
+    /**
+     * Start all poll loops. Each tool is polled on its own interval.
+     * Tools not present in the ToolMap are silently skipped.
+     * Each poll fires immediately on start, then repeats on interval.
+     */
+    start() {
+        if (this.running) {
+            logger.warn(TAG, 'Poller already running');
+            return;
+        }
+        this.running = true;
+        this.paused = false;
+        this.cooldownUntilMs = 0;
+        this.rateLimitStep = -1;
+        this.cooldownLogged = false;
+        logger.info(TAG, `Starting poller for ${this.symbol}`);
+        this.scheduleIfAvailable('fetch_ticker', TICKER_INTERVAL_MS, () => this.pollTicker());
+        this.scheduleIfAvailable('fetch_ohlcv', OHLCV_INTERVAL_MS, () => this.pollOhlcv());
+        this.scheduleIfAvailable('fetch_positions', POSITIONS_INTERVAL_MS, () => this.pollPositions());
+        this.scheduleIfAvailable('fetch_balance', BALANCE_INTERVAL_MS, () => this.pollBalance());
+        this.scheduleIfAvailable('fetch_open_orders', OPEN_ORDERS_INTERVAL_MS, () => this.pollOpenOrders());
+        this.scheduleIfAvailable('get_market_structure', MARKET_STRUCTURE_INTERVAL_MS, () => this.pollMarketStructure());
+        // Crypto metrics: funding rate + open interest via dedicated get_crypto_metrics tool
+        // Delayed start (5s) to avoid interfering with initial polls
+        if (this.toolMap.get_crypto_metrics) {
+            const cryptoDelay = setTimeout(() => {
+                if (!this.running)
+                    return;
+                void this.guardedExec('crypto_metrics', () => this.pollCryptoMetrics());
+                const cryptoTimer = setInterval(() => void this.guardedExec('crypto_metrics', () => this.pollCryptoMetrics()), CRYPTO_METRICS_INTERVAL_MS);
+                this.timers.push(cryptoTimer);
+            }, 5_000);
+            this.timers.push(cryptoDelay);
+        }
+        // Volume analysis: computed from OHLCV data (uses fetch_ohlcv tool — no new tool needed)
+        // Delayed start (5s) to let initial OHLCV data arrive
+        if (this.toolMap.fetch_ohlcv) {
+            const volumeDelay = setTimeout(() => {
+                if (!this.running)
+                    return;
+                void this.guardedExec('volume_analysis', () => this.pollVolumeAnalysis());
+                const volumeTimer = setInterval(() => void this.guardedExec('volume_analysis', () => this.pollVolumeAnalysis()), VOLUME_ANALYSIS_INTERVAL_MS);
+                this.timers.push(volumeTimer);
+            }, 5_000);
+            this.timers.push(volumeDelay);
+        }
+    }
+    /** Stop all poll loops and clean up timers. */
+    stop() {
+        if (!this.running)
+            return;
+        logger.info(TAG, 'Stopping poller');
+        this.running = false;
+        this.paused = false;
+        for (const timer of this.timers) {
+            clearInterval(timer);
+        }
+        this.timers = [];
+        this.inflight.clear();
+    }
+    /** Pause polling (timers keep ticking but polls are skipped). */
+    pause() {
+        if (!this.running || this.paused)
+            return;
+        logger.info(TAG, 'Pausing poller');
+        this.paused = true;
+    }
+    /** Resume polling after a pause. */
+    resume() {
+        if (!this.running || !this.paused)
+            return;
+        logger.info(TAG, 'Resuming poller');
+        this.paused = false;
+    }
+    // ---- Scheduling ----
+    /**
+     * Schedule a poll loop for a logical tool, only if it was discovered.
+     * Fires immediately, then repeats on interval.
+     */
+    scheduleIfAvailable(logical, intervalMs, fn) {
+        if (!this.toolMap[logical]) {
+            logger.info(TAG, `Skipping ${logical} poll — tool not discovered`);
+            return;
+        }
+        // Fire immediately on start
+        void this.guardedExec(logical, fn);
+        const timer = setInterval(() => void this.guardedExec(logical, fn), intervalMs);
+        this.timers.push(timer);
+    }
+    /**
+     * Execute a poll function with error handling and in-flight guard.
+     * - Skipped when paused or stopped (checked before AND after acquiring inflight slot)
+     * - Skipped if a previous poll of the same type is still in-flight
+     * - Errors are logged and swallowed (never crash the provider)
+     */
+    async guardedExec(label, fn) {
+        if (this.paused || !this.running)
+            return;
+        // Process-wide circuit-breaker. While in cooldown, EVERY poll is
+        // skipped — the whole point is to stop hitting Binance so an IP ban
+        // can actually expire instead of being perpetually re-triggered.
+        const now = Date.now();
+        if (now < this.cooldownUntilMs) {
+            if (!this.cooldownLogged) {
+                const secs = Math.ceil((this.cooldownUntilMs - now) / 1000);
+                logger.warn(TAG, `Rate-limit cooldown active — ALL polls paused for ~${secs}s (Binance 418/429 backoff)`);
+                this.cooldownLogged = true;
+            }
+            return;
+        }
+        if (this.cooldownLogged) {
+            // We just crossed out of a cooldown window.
+            logger.info(TAG, 'Rate-limit cooldown cleared — resuming polls');
+            this.cooldownLogged = false;
+        }
+        if (this.inflight.has(label)) {
+            logger.debug(TAG, `Skipping ${label} — previous poll still in-flight`);
+            return;
+        }
+        this.inflight.add(label);
+        try {
+            // Re-check after acquiring slot — defensive against stop() during await
+            if (this.paused || !this.running)
+                return;
+            // Per-tool poll attribution (60s window). Counts polls that actually
+            // execute (past cooldown + in-flight guards) — the real Binance-bound
+            // call rate from this process.
+            if (this.pollWindowStart === 0)
+                this.pollWindowStart = now;
+            if (now - this.pollWindowStart >= 60_000) {
+                if (this.pollCountByTool.size > 0) {
+                    const top = [...this.pollCountByTool.entries()]
+                        .sort((a, b) => b[1] - a[1])
+                        .map(([k, v]) => `${k}=${v}`)
+                        .join(' ');
+                    logger.info(TAG, `poll window summary (60s, skill process): ${top}`);
+                }
+                this.pollWindowStart = now;
+                this.pollCountByTool.clear();
+            }
+            this.pollCountByTool.set(label, (this.pollCountByTool.get(label) ?? 0) + 1);
+            await fn();
+            // Clean poll — relax the soft-429 backoff ladder.
+            this.rateLimitStep = -1;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.applyRateLimitBackoff(label, msg);
+            logger.warn(TAG, `Poll ${label} failed: ${msg}`);
+        }
+        finally {
+            this.inflight.delete(label);
+        }
+    }
+    /** Inspect a failed poll's error for Binance rate-limit signals and arm
+     *  the process-wide circuit-breaker accordingly.
+     *
+     *  - **418** (IP ban): Binance returns `banned until <epoch-ms>` in the
+     *    message. We respect that exact timestamp + slack — guessing a
+     *    shorter window would just re-ban and extend it.
+     *  - **429 / -1003 "Too many requests"** (soft rate-limit, no ban yet):
+     *    exponential backoff so we stop climbing toward a 418.
+     *
+     *  Any non-rate-limit error is left alone (normal transient handling). */
+    applyRateLimitBackoff(label, msg) {
+        // 418 — hard IP ban with an explicit expiry Binance tells us.
+        if (msg.includes('418') || /banned until/i.test(msg)) {
+            const m = /banned until (\d{10,})/i.exec(msg);
+            const bannedUntil = m ? Number(m[1]) : 0;
+            const target = (Number.isFinite(bannedUntil) && bannedUntil > Date.now()
+                ? bannedUntil
+                : Date.now() + RATE_LIMIT_BACKOFF_MS[RATE_LIMIT_BACKOFF_MS.length - 1])
+                + BAN_RESUME_SLACK_MS;
+            if (target > this.cooldownUntilMs) {
+                this.cooldownUntilMs = target;
+                this.cooldownLogged = false; // force a fresh "paused for ~Ns" line
+                const secs = Math.ceil((target - Date.now()) / 1000);
+                logger.error(TAG, `Binance 418 IP BAN detected on ${label} — circuit-breaker engaged, ALL polls paused ~${secs}s (until Binance-stated expiry +slack)`);
+            }
+            return;
+        }
+        // 429 / -1003 — soft rate-limit. Exponential backoff, no ban yet.
+        if (msg.includes('429') || msg.includes('-1003') || /too many requests/i.test(msg)) {
+            this.rateLimitStep = Math.min(this.rateLimitStep + 1, RATE_LIMIT_BACKOFF_MS.length - 1);
+            const window = RATE_LIMIT_BACKOFF_MS[this.rateLimitStep];
+            const target = Date.now() + window;
+            if (target > this.cooldownUntilMs) {
+                this.cooldownUntilMs = target;
+                this.cooldownLogged = false;
+                logger.warn(TAG, `Binance 429 on ${label} — circuit-breaker backoff step ${this.rateLimitStep}, ALL polls paused ${window / 1000}s`);
+            }
+        }
+    }
+    // ---- Individual poll methods ----
+    async pollTicker() {
+        const tool = this.toolMap.fetch_ticker;
+        const result = await this.http.invoke(tool, { symbol: this.symbol });
+        const ticker = mapCcxtTicker(result.data);
+        if (ticker) {
+            this.callbacks.onTicker(ticker);
+        }
+    }
+    async pollOhlcv() {
+        const tool = this.toolMap.fetch_ohlcv;
+        const result = await this.http.invoke(tool, {
+            symbol: this.symbol,
+            timeframe: '1m',
+            limit: 2, // Last 2 candles — newest may still be forming
+        });
+        const rows = result.data;
+        if (!Array.isArray(rows) || rows.length === 0)
+            return;
+        // Emit the most recent candle
+        const row = rows[rows.length - 1];
+        if (!Array.isArray(row) || row.length < 6)
+            return;
+        const [ts, open, high, low, close, volume] = row;
+        // Validate all values are numbers — CCXT can return null for sparse candles
+        if (typeof ts !== 'number' ||
+            typeof open !== 'number' ||
+            typeof high !== 'number' ||
+            typeof low !== 'number' ||
+            typeof close !== 'number' ||
+            typeof volume !== 'number') {
+            logger.warn(TAG, `Invalid OHLCV values for ${this.symbol}, skipping`);
+            return;
+        }
+        this.callbacks.onCandle({
+            symbol: this.symbol,
+            candle: {
+                time: Math.floor(ts / 1000), // CCXT returns ms, LWC expects seconds
+                open,
+                high,
+                low,
+                close,
+                volume,
+            },
+            timestamp: new Date(ts).toISOString(),
+        });
+    }
+    async pollPositions() {
+        const tool = this.toolMap.fetch_positions;
+        // Fetch ALL positions (no symbol filter) so multi-symbol trades are visible
+        const result = await this.http.invoke(tool, {});
+        const positions = Array.isArray(result.data) ? result.data : [];
+        this.callbacks.onPositions(positions);
+    }
+    async pollBalance() {
+        const tool = this.toolMap.fetch_balance;
+        const result = await this.http.invoke(tool, {});
+        const balance = mapCcxtBalance(result.data, this.quoteCurrency);
+        this.callbacks.onBalance(balance);
+    }
+    async pollOpenOrders() {
+        const tool = this.toolMap.fetch_open_orders;
+        const result = await this.http.invoke(tool, { symbol: this.symbol });
+        const orders = [];
+        if (Array.isArray(result.data)) {
+            for (const ccxt of result.data) {
+                const mapped = mapCcxtOrder(ccxt);
+                if (mapped)
+                    orders.push(mapped);
+            }
+        }
+        this.callbacks.onOpenOrders(orders);
+    }
+    async pollMarketStructure() {
+        const tool = this.toolMap.get_market_structure;
+        logger.info(TAG, `Polling market structure (tool=${tool}, symbol=${this.symbol})`);
+        const result = await this.http.invoke(tool, {
+            symbol: this.symbol,
+        }, { timeoutMs: 30_000 }); // Higher timeout — fetches 6 TFs of OHLCV
+        const data = result.data;
+        if (data && typeof data === 'object' && 'timeframes' in data && Array.isArray(data.timeframes)) {
+            logger.info(TAG, `Market structure: ${data.timeframes.length} timeframes, alignment=${data.alignment?.summary ?? 'unknown'}`);
+            this.callbacks.onMarketStructure?.(data);
+        }
+        else {
+            logger.warn(TAG, `Market structure: unexpected response shape: ${JSON.stringify(data).slice(0, 200)}`);
+        }
+    }
+    // ---- Feature B: Crypto metrics (funding rate + open interest) ----
+    /**
+     * Fetch funding rate and open interest via the dedicated get_crypto_metrics tool.
+     * The plugin tool handles spot→perp symbol conversion and raw CCXT ticker parsing.
+     */
+    async pollCryptoMetrics() {
+        const tool = this.toolMap.get_crypto_metrics;
+        try {
+            const result = await this.http.invoke(tool, { symbol: this.symbol });
+            const data = result.data;
+            if (!data || typeof data !== 'object')
+                return;
+            if (data.error) {
+                logger.debug(TAG, `Crypto metrics tool error: ${data.error}`);
+                return;
+            }
+            // Only emit if we have at least one useful field
+            if (data.fundingRate !== null || data.openInterest !== null) {
+                const metrics = {
+                    symbol: this.symbol,
+                    fundingRate: data.fundingRate,
+                    fundingRateAnnualized: data.fundingRateAnnualized,
+                    nextFundingTime: data.nextFundingTime,
+                    openInterest: data.openInterest,
+                    openInterestUsd: data.openInterestUsd,
+                    timestamp: data.timestamp,
+                };
+                logger.info(TAG, `Crypto metrics: FR=${data.fundingRate}, OI=${data.openInterest}, OI_USD=${data.openInterestUsd}`);
+                this.callbacks.onCryptoMetrics?.(metrics);
+            }
+            else {
+                logger.debug(TAG, 'Crypto metrics: no funding rate or OI returned by tool');
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            // Rate-limit / IP-ban errors MUST propagate to guardedExec so the
+            // process-wide circuit-breaker arms — swallowing them here would let this
+            // fixed-cadence poll keep hitting a banned IP and extend the 418 ban.
+            if (isRateLimitShapedError(msg))
+                throw err;
+            // Otherwise non-fatal — crypto metrics are supplementary.
+            logger.debug(TAG, `Crypto metrics poll failed: ${msg}`);
+        }
+    }
+    // ---- Feature A: Volume / thrust analysis ----
+    /**
+     * Fetch 25 bars of 5m OHLCV and compute volume analysis metrics:
+     * - Volume expansion ratio (current vs 20-bar avg)
+     * - Close position (where close sits in bar's range, 0=low, 1=high)
+     * - Directional thrust (volume-weighted close position, -1 to +1)
+     * - Buy volume estimate (proxy using close position)
+     */
+    async pollVolumeAnalysis() {
+        const tool = this.toolMap.fetch_ohlcv;
+        try {
+            const result = await this.http.invoke(tool, {
+                symbol: this.symbol,
+                timeframe: '5m',
+                limit: 25, // 20 for avg + a few extra for robustness
+            });
+            const rows = result.data;
+            if (!Array.isArray(rows) || rows.length < 5)
+                return;
+            // Validate and filter valid rows
+            const valid = rows.filter((r) => Array.isArray(r) && r.length >= 6 &&
+                typeof r[0] === 'number' && typeof r[1] === 'number' &&
+                typeof r[2] === 'number' && typeof r[3] === 'number' &&
+                typeof r[4] === 'number' && typeof r[5] === 'number' &&
+                r[5] > 0 // Volume > 0
+            );
+            if (valid.length < 3)
+                return;
+            // Latest bar
+            const latest = valid[valid.length - 1];
+            const [, , latestHigh, latestLow, latestClose, latestVolume] = latest;
+            // Compute 20-bar average volume (excluding latest bar)
+            const lookback = valid.slice(Math.max(0, valid.length - 21), valid.length - 1);
+            const avgVolume = lookback.length > 0
+                ? lookback.reduce((sum, r) => sum + r[5], 0) / lookback.length
+                : latestVolume;
+            // Volume expansion ratio
+            const volumeExpansion = avgVolume > 0 ? latestVolume / avgVolume : 1;
+            // Close position: where close sits in the bar's range (0 = at low, 1 = at high)
+            const range = latestHigh - latestLow;
+            const closePosition = range > 0 ? (latestClose - latestLow) / range : 0.5;
+            // Directional thrust: combines volume expansion with close position
+            // -1 = high volume bearish (close at low), +1 = high volume bullish (close at high)
+            const dirMultiplier = (closePosition - 0.5) * 2; // -1 to +1
+            const cappedExpansion = Math.min(volumeExpansion, 5); // Cap at 5x to avoid outlier distortion
+            const directionalThrust = dirMultiplier * Math.min(1, cappedExpansion / 2);
+            // Buy volume estimate (proxy): close position as buy % approximation
+            const buyVolEstimate = closePosition;
+            const analysis = {
+                symbol: this.symbol,
+                timeframe: '5m',
+                volumeExpansion: +volumeExpansion.toFixed(2),
+                closePosition: +closePosition.toFixed(3),
+                directionalThrust: +directionalThrust.toFixed(3),
+                buyVolEstimate: +buyVolEstimate.toFixed(3),
+                avgVolume: +avgVolume.toFixed(2),
+                currentVolume: latestVolume,
+                barsAnalyzed: valid.length,
+                timestamp: new Date().toISOString(),
+            };
+            logger.debug(TAG, `Volume analysis: expansion=${analysis.volumeExpansion}x, close=${analysis.closePosition}, thrust=${analysis.directionalThrust}`);
+            this.callbacks.onVolumeAnalysis?.(analysis);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            // Rate-limit / IP-ban errors MUST propagate to guardedExec so the
+            // process-wide circuit-breaker arms — swallowing them here would let this
+            // fixed-cadence poll keep hitting a banned IP and extend the 418 ban.
+            if (isRateLimitShapedError(msg))
+                throw err;
+            // Otherwise non-fatal — volume analysis is supplementary.
+            logger.debug(TAG, `Volume analysis poll failed: ${msg}`);
+        }
+    }
+}

package/bridge/gateway/tool-discovery.d.ts

@@ -0,0 +1,25 @@
+import { GatewayHttpClient } from './gateway-http-client.js';
+/**
+ * Logical tool names used by ReefClaw internally.
+ * Each maps to one or more candidate actual tool names on the gateway.
+ */
+export type LogicalTool = 'fetch_ticker' | 'fetch_balance' | 'fetch_ohlcv' | 'fetch_positions' | 'fetch_open_orders' | 'cancel_all_orders' | 'cancel_order' | 'close_position' | 'create_order' | 'get_market_structure' | 'get_crypto_metrics' | 'get_market_intel' | 'set_trading_mode' | 'set_exchange_credentials' | 'test_exchange_credentials' | 'clear_exchange_credentials' | 'get_bracket_config' | 'set_bracket_requirement';
+/** Map of logical tool names to their discovered actual tool names on the gateway */
+export type ToolMap = Partial<Record<LogicalTool, string>>;
+export interface DiscoveryResult {
+    /** Map of logical names → actual gateway tool names */
+    toolMap: ToolMap;
+    /** Logical names of tools that were found */
+    found: LogicalTool[];
+    /** Logical names of required tools that are missing */
+    missingRequired: LogicalTool[];
+    /** Logical names of optional tools that are missing */
+    missingOptional: LogicalTool[];
+}
+/**
+ * Discover all available trading tools on the gateway.
+ *
+ * Probes required tools first, then optional tools in parallel.
+ * Fails fast if no required tools are found.
+ */
+export declare function discoverTools(http: GatewayHttpClient): Promise<DiscoveryResult>;