openbroker 1.9.6 → 1.12.0

package/dist/guardian/rules.js

@@ -0,0 +1,237 @@
+// Guardian rule engine — pure arithmetic over in-memory target + price state,
+// zero API cost per tick. Ported 1:1 from openbroker-copilot src/watcher/risk.ts
+// (same thresholds, hysteresis, and cooldowns); position lifecycle events are
+// emitted by the engine's snapshot diff, not here. Alerts are suppressed while
+// the price feed is stale.
+import { DEFAULT_GUARDIAN_THRESHOLDS } from './types.js';
+const HOURS_PER_YEAR = 24 * 365;
+export class GuardianRiskEngine {
+    prices;
+    onAlert;
+    thresholds;
+    /** address:coin:threshold → state */
+    liqState = new Map();
+    /** address → state */
+    marginState = new Map();
+    /** address:coin → alerted */
+    tpslState = new Set();
+    /** address:oid → last fired */
+    staleOrderState = new Map();
+    /** address:coin → { since, firedAt } */
+    fundingState = new Map();
+    evaluations = 0;
+    constructor(prices, onAlert, thresholds) {
+        this.prices = prices;
+        this.onAlert = onAlert;
+        this.thresholds = { ...DEFAULT_GUARDIAN_THRESHOLDS, ...thresholds };
+    }
+    getStats() {
+        return { evaluations: this.evaluations };
+    }
+    /** One evaluation pass over the given targets. */
+    tick(targets, now = Date.now()) {
+        const stale = this.prices.stale;
+        for (const target of targets) {
+            if (!target.seeded)
+                continue;
+            this.updateLiqDistance(target);
+            if (stale)
+                continue; // keep distances fresh, but never alert on stale prices
+            this.evaluations++;
+            this.evalLiqProximity(target, now);
+            this.evalMarginUsage(target, now);
+            this.evalNoTpsl(target, now);
+            this.evalStaleOrders(target, now);
+            this.evalFundingBleed(target, now);
+            this.gcClosedPositions(target);
+        }
+    }
+    /** Distance = (mark − liqPx) / mark, signed by side. */
+    liqDistance(target, coin) {
+        const pos = target.positions.get(coin);
+        if (!pos || pos.liquidationPx === null || pos.liquidationPx <= 0)
+            return null;
+        const entry = this.prices.get(coin);
+        const mark = entry?.mark ?? entry?.mid;
+        if (!mark || mark <= 0)
+            return null;
+        return pos.side === 'long'
+            ? (mark - pos.liquidationPx) / mark
+            : (pos.liquidationPx - mark) / mark;
+    }
+    updateLiqDistance(target) {
+        let min = null;
+        for (const coin of target.positions.keys()) {
+            const d = this.liqDistance(target, coin);
+            if (d !== null && (min === null || d < min))
+                min = d;
+        }
+        target.minLiqDist = min;
+    }
+    evalLiqProximity(target, now) {
+        const t = this.thresholds;
+        for (const [coin, pos] of target.positions) {
+            const dist = this.liqDistance(target, coin);
+            if (dist === null)
+                continue;
+            for (const { pct, severity } of t.liqThresholds) {
+                const key = `${target.address}:${coin}:${pct}`;
+                const state = this.liqState.get(key) ?? { firedAt: 0, armed: true };
+                if (!state.armed && dist >= pct * t.liqRearmFactor) {
+                    state.armed = true; // hysteresis re-arm
+                }
+                if (state.armed && dist <= pct && now - state.firedAt >= t.liqCooldownMs) {
+                    state.armed = false;
+                    state.firedAt = now;
+                    const entry = this.prices.get(coin);
+                    const mark = entry?.mark ?? entry?.mid;
+                    this.onAlert({
+                        time: now,
+                        address: target.address,
+                        rule: 'liq_proximity',
+                        coin,
+                        severity,
+                        dedupKey: String(pct),
+                        message: `Liquidation risk on ${coin}: mark $${mark} is ${(dist * 100).toFixed(2)}% from ` +
+                            `liquidation price $${pos.liquidationPx} (${pos.side}, ${pos.leverage}x)`,
+                        payload: { coin, distancePct: dist * 100, thresholdPct: pct * 100, mark, liquidationPx: pos.liquidationPx, side: pos.side },
+                    });
+                }
+                this.liqState.set(key, state);
+            }
+        }
+    }
+    evalMarginUsage(target, now) {
+        const t = this.thresholds;
+        const key = target.address;
+        const state = this.marginState.get(key) ?? { firedAt: 0, armed: true };
+        if (!state.armed && target.marginUsedPct < t.marginRearmPct)
+            state.armed = true;
+        if (state.armed && target.marginUsedPct > t.marginThresholdPct && now - state.firedAt >= t.marginCooldownMs) {
+            state.armed = false;
+            state.firedAt = now;
+            this.onAlert({
+                time: now,
+                address: target.address,
+                rule: 'margin_usage',
+                coin: null,
+                severity: 'warning',
+                dedupKey: String(t.marginThresholdPct),
+                message: `Margin usage at ${target.marginUsedPct.toFixed(1)}% of equity ($${target.equity.toFixed(2)})`,
+                payload: { marginUsedPct: target.marginUsedPct, equity: target.equity, thresholdPct: t.marginThresholdPct },
+            });
+        }
+        this.marginState.set(key, state);
+    }
+    evalNoTpsl(target, now) {
+        if (target.lastOrdersAt === null || target.orders === null)
+            return; // no order data yet
+        for (const [coin, pos] of target.positions) {
+            const key = `${target.address}:${coin}`;
+            const openedAt = target.firstSeen.get(coin) ?? now;
+            const hasProtection = target.orders.some((o) => o.coin === coin && o.isTrigger && o.reduceOnly);
+            if (hasProtection) {
+                this.tpslState.delete(key);
+                continue;
+            }
+            if (this.tpslState.has(key))
+                continue;
+            if (now - openedAt < this.thresholds.noTpslAfterMs)
+                continue;
+            this.tpslState.add(key);
+            this.onAlert({
+                time: now,
+                address: target.address,
+                rule: 'no_tpsl',
+                coin,
+                severity: 'info',
+                dedupKey: 'no_tpsl',
+                message: `${coin} ${pos.side} position has been open ${Math.round((now - openedAt) / 60_000)} min with no TP/SL orders`,
+                payload: { coin, side: pos.side, size: pos.szi, openMinutes: Math.round((now - openedAt) / 60_000) },
+            });
+        }
+    }
+    evalStaleOrders(target, now) {
+        if (!target.orders)
+            return;
+        const t = this.thresholds;
+        for (const order of target.orders) {
+            if (order.isTrigger)
+                continue; // resting limit orders only
+            if (now - order.timestamp < t.staleOrderAgeMs)
+                continue;
+            const entry = this.prices.get(order.coin);
+            const mid = entry?.mid ?? entry?.mark;
+            const limitPx = parseFloat(order.limitPx);
+            if (!mid || mid <= 0 || !Number.isFinite(limitPx))
+                continue;
+            const dist = Math.abs(limitPx - mid) / mid;
+            if (dist <= t.staleOrderDist)
+                continue;
+            const key = `${target.address}:${order.oid}`;
+            const lastFired = this.staleOrderState.get(key) ?? 0;
+            if (now - lastFired < t.staleOrderCooldownMs)
+                continue;
+            this.staleOrderState.set(key, now);
+            const ageH = Math.round((now - order.timestamp) / 3600_000);
+            this.onAlert({
+                time: now,
+                address: target.address,
+                rule: 'stale_order',
+                coin: order.coin,
+                severity: 'info',
+                dedupKey: String(order.oid),
+                message: `Stale ${order.side === 'B' ? 'buy' : 'sell'} order on ${order.coin}: resting ${ageH}h, ` +
+                    `limit $${order.limitPx} is ${(dist * 100).toFixed(1)}% from mid $${mid}`,
+                payload: { coin: order.coin, oid: order.oid, limitPx, mid, distancePct: dist * 100, ageHours: ageH },
+            });
+        }
+    }
+    evalFundingBleed(target, now) {
+        const t = this.thresholds;
+        for (const [coin, pos] of target.positions) {
+            const funding = this.prices.get(coin)?.funding;
+            const key = `${target.address}:${coin}`;
+            if (funding === null || funding === undefined)
+                continue;
+            // Longs pay when funding > 0; shorts pay when funding < 0. Funding is hourly.
+            const paying = pos.side === 'long' ? funding > 0 : funding < 0;
+            const aprPct = Math.abs(funding) * HOURS_PER_YEAR * 100;
+            if (!paying || aprPct <= t.fundingBleedAprPct) {
+                this.fundingState.delete(key);
+                continue;
+            }
+            const state = this.fundingState.get(key) ?? { since: now, firedAt: null };
+            this.fundingState.set(key, state);
+            const bleedingFor = now - state.since;
+            const cooledDown = state.firedAt === null || now - state.firedAt >= t.fundingCooldownMs;
+            if (bleedingFor >= t.fundingBleedForMs && cooledDown) {
+                state.firedAt = now;
+                this.onAlert({
+                    time: now,
+                    address: target.address,
+                    rule: 'funding_bleed',
+                    coin,
+                    severity: 'warning',
+                    dedupKey: 'funding_bleed',
+                    message: `Funding bleed on ${coin}: paying ~${aprPct.toFixed(1)}% APR against your ${pos.side} ` +
+                        `for over ${Math.round(bleedingFor / 60_000)} min`,
+                    payload: { coin, side: pos.side, fundingHourly: funding, aprPct, bleedingMinutes: Math.round(bleedingFor / 60_000) },
+                });
+            }
+        }
+    }
+    /** Drop per-position rule state when positions close (prevents unbounded growth). */
+    gcClosedPositions(target) {
+        for (const key of this.tpslState) {
+            const [addr, coin] = [key.slice(0, 42), key.slice(43)];
+            if (addr === target.address && coin && !target.positions.has(coin))
+                this.tpslState.delete(key);
+        }
+        for (const key of this.fundingState.keys()) {
+            const [addr, coin] = [key.slice(0, 42), key.slice(43)];
+            if (addr === target.address && coin && !target.positions.has(coin))
+                this.fundingState.delete(key);
+        }
+    }
+}

package/dist/guardian/telegram.d.ts

@@ -0,0 +1,24 @@
+import type { GuardianAlert } from './types.js';
+export interface TelegramSettings {
+    token: string | null;
+    chatId: string | null;
+}
+/** Read TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID (dotenv is loaded by core/config on import). */
+export declare function loadTelegramSettings(): TelegramSettings;
+export declare function sendTelegramMessage(token: string, chatId: string | number, text: string): Promise<void>;
+export declare function getTelegramBotInfo(token: string): Promise<{
+    id: number;
+    username: string;
+}>;
+/** Same message shape as the hosted guardian's Telegram channel. */
+export declare function formatTelegramAlert(alert: GuardianAlert): string;
+export declare function generateLinkCode(): string;
+/**
+ * Long-poll getUpdates until someone sends `/start <code>` (or the bare code)
+ * to the bot, then confirm in-chat and return the chat id. Returns null on
+ * timeout. Drains the update backlog first so old messages can't match.
+ */
+export declare function waitForTelegramLink(token: string, code: string, timeoutMs?: number): Promise<number | null>;
+/** Persist a key=value into the active openbroker config file (creates it if missing). */
+export declare function saveEnvVar(key: string, value: string): string;
+//# sourceMappingURL=telegram.d.ts.map

package/dist/guardian/telegram.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.d.ts","sourceRoot":"","sources":["../../scripts/guardian/telegram.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,8FAA8F;AAC9F,wBAAgB,oBAAoB,IAAI,gBAAgB,CAKvD;AAoBD,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO7G;AAED,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAEjG;AAMD,oEAAoE;AACpE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAIhE;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,SAAS,SAAc,GACtB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA4CxB;AAED,0FAA0F;AAC1F,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAiB7D"}

package/dist/guardian/telegram.js

@@ -0,0 +1,125 @@
+// Telegram delivery for the guardian via raw fetch — no SDK. Unlike the hosted
+// guardian (shared bot + DB-backed link codes), the CLI uses the user's OWN bot:
+// TELEGRAM_BOT_TOKEN comes from @BotFather, and `openbroker guardian connect`
+// runs a one-shot getUpdates loop that captures the chat id from a
+// `/start <code>` deep link and persists TELEGRAM_CHAT_ID to the config file.
+//
+// Caveat: getUpdates conflicts with any other consumer of the same bot token
+// (including a set webhook) — use a dedicated bot for the CLI guardian.
+import fs from 'fs';
+import crypto from 'crypto';
+import { ensureConfigDir, getConfigPath } from '../core/config.js';
+/** Read TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID (dotenv is loaded by core/config on import). */
+export function loadTelegramSettings() {
+    return {
+        token: process.env.TELEGRAM_BOT_TOKEN || null,
+        chatId: process.env.TELEGRAM_CHAT_ID || null,
+    };
+}
+function api(token, method) {
+    return `https://api.telegram.org/bot${token}/${method}`;
+}
+async function call(token, method, body, timeoutMs = 10_000) {
+    const res = await fetch(api(token, method), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    const data = (await res.json().catch(() => null));
+    if (!res.ok || !data?.ok) {
+        throw new Error(`telegram ${method} failed: HTTP ${res.status}${data?.description ? ` — ${data.description}` : ''}`);
+    }
+    return data.result;
+}
+export async function sendTelegramMessage(token, chatId, text) {
+    await call(token, 'sendMessage', {
+        chat_id: chatId,
+        text,
+        parse_mode: 'HTML',
+        disable_web_page_preview: true,
+    });
+}
+export async function getTelegramBotInfo(token) {
+    return call(token, 'getMe', {});
+}
+function shortAddr(address) {
+    return `${address.slice(0, 6)}…${address.slice(-4)}`;
+}
+/** Same message shape as the hosted guardian's Telegram channel. */
+export function formatTelegramAlert(alert) {
+    const tag = alert.severity === 'critical' ? 'CRITICAL' : alert.severity === 'warning' ? 'WARNING' : 'INFO';
+    const scope = alert.coin ? `${alert.coin} — ` : '';
+    return `<b>[${tag}]</b> ${scope}${shortAddr(alert.address)}\n${alert.message}`;
+}
+export function generateLinkCode() {
+    return crypto.randomBytes(4).toString('hex');
+}
+/**
+ * Long-poll getUpdates until someone sends `/start <code>` (or the bare code)
+ * to the bot, then confirm in-chat and return the chat id. Returns null on
+ * timeout. Drains the update backlog first so old messages can't match.
+ */
+export async function waitForTelegramLink(token, code, timeoutMs = 10 * 60_000) {
+    const deadline = Date.now() + timeoutMs;
+    let offset = -1; // -1 = skip backlog, start from the next incoming update
+    while (Date.now() < deadline) {
+        let updates;
+        try {
+            updates = await call(token, 'getUpdates', {
+                offset,
+                timeout: 25,
+                allowed_updates: ['message'],
+            }, 35_000);
+        }
+        catch (err) {
+            if (Date.now() >= deadline)
+                break;
+            await new Promise((r) => setTimeout(r, 3_000));
+            continue;
+        }
+        for (const update of updates ?? []) {
+            offset = update.update_id + 1;
+            const msg = update.message;
+            const text = msg?.text?.trim();
+            if (!msg || !text)
+                continue;
+            const m = text.match(/^\/start(?:\s+(\S+))?$/);
+            const supplied = m ? m[1] : text;
+            if (supplied === code) {
+                try {
+                    await sendTelegramMessage(token, msg.chat.id, 'Linked. This chat will receive OpenBroker guardian alerts (liquidation proximity, missing TP/SL, funding bleed and more).');
+                }
+                catch { /* link still succeeded */ }
+                return msg.chat.id;
+            }
+            if (m && !supplied) {
+                try {
+                    await sendTelegramMessage(token, msg.chat.id, 'OpenBroker guardian bot. Run <code>openbroker guardian connect</code> in the terminal and follow the link it prints.');
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    return null;
+}
+/** Persist a key=value into the active openbroker config file (creates it if missing). */
+export function saveEnvVar(key, value) {
+    ensureConfigDir();
+    const configPath = getConfigPath();
+    const line = `${key}=${value}`;
+    let content = '';
+    if (fs.existsSync(configPath)) {
+        content = fs.readFileSync(configPath, 'utf8');
+    }
+    const re = new RegExp(`^${key}=.*$`, 'm');
+    if (re.test(content)) {
+        content = content.replace(re, line);
+    }
+    else {
+        content = content.length > 0 && !content.endsWith('\n') ? `${content}\n${line}\n` : `${content}${line}\n`;
+    }
+    fs.writeFileSync(configPath, content, { mode: 0o600 });
+    process.env[key] = value;
+    return configPath;
+}

package/dist/guardian/types.d.ts

@@ -0,0 +1,90 @@
+import type { FrontendOpenOrder } from '../core/types.js';
+export type GuardianRuleId = 'liq_proximity' | 'no_tpsl' | 'stale_order' | 'margin_usage' | 'funding_bleed' | 'position_lifecycle';
+export declare const GUARDIAN_RULE_IDS: GuardianRuleId[];
+export declare const GUARDIAN_RULE_LABELS: Record<GuardianRuleId, string>;
+export type GuardianSeverity = 'info' | 'warning' | 'critical';
+export declare const GUARDIAN_SEVERITY_RANK: Record<GuardianSeverity, number>;
+export interface GuardianAlert {
+    time: number;
+    address: string;
+    rule: GuardianRuleId;
+    coin: string | null;
+    severity: GuardianSeverity;
+    /** Dedup discriminator within address+rule+coin (e.g. threshold pct). */
+    dedupKey: string;
+    message: string;
+    payload: Record<string, unknown>;
+}
+/** Per-run alert preferences — same contract as the hosted guardian's alert_prefs. */
+export interface GuardianPrefs {
+    /** Minimum severity to deliver. Default 'info'. */
+    minSeverity?: GuardianSeverity;
+    /** Per-rule opt-out, e.g. { position_lifecycle: false }. Default: all on. */
+    rules?: Partial<Record<GuardianRuleId, boolean>>;
+}
+/** Rule thresholds. Defaults mirror the hosted guardian. */
+export interface GuardianThresholds {
+    /** Liquidation-distance tiers (fraction of mark), tightest last. */
+    liqThresholds: Array<{
+        pct: number;
+        severity: GuardianSeverity;
+    }>;
+    /** Re-arm only after moving this multiple past a fired threshold. */
+    liqRearmFactor: number;
+    liqCooldownMs: number;
+    marginThresholdPct: number;
+    marginRearmPct: number;
+    marginCooldownMs: number;
+    /** Alert when a position has no reduce-only trigger after this long. */
+    noTpslAfterMs: number;
+    staleOrderAgeMs: number;
+    /** Distance from mid (fraction) before a resting order counts as stale. */
+    staleOrderDist: number;
+    staleOrderCooldownMs: number;
+    /** Annualized funding APR (%) the position must be paying to count as bleed. */
+    fundingBleedAprPct: number;
+    /** How long the bleed must persist before alerting. */
+    fundingBleedForMs: number;
+    fundingCooldownMs: number;
+}
+export declare const DEFAULT_GUARDIAN_THRESHOLDS: GuardianThresholds;
+export interface GuardianPositionSnap {
+    coin: string;
+    szi: number;
+    side: 'long' | 'short';
+    entryPx: number | null;
+    positionValue: number;
+    unrealizedPnl: number;
+    liquidationPx: number | null;
+    leverage: number;
+    marginUsed: number;
+}
+/** In-memory state per watched address. */
+export interface GuardianTargetState {
+    address: string;
+    positions: Map<string, GuardianPositionSnap>;
+    equity: number;
+    marginUsedPct: number;
+    seeded: boolean;
+    lastStateAt: number | null;
+    orders: FrontendOpenOrder[] | null;
+    lastOrdersAt: number | null;
+    /** First time each open position (coin) was observed — for the no-TP/SL rule. */
+    firstSeen: Map<string, number>;
+    /** Min liquidation distance (fraction) across open positions; set by the risk engine. */
+    minLiqDist: number | null;
+}
+/** Live price entry maintained by the guardian's price feed. */
+export interface GuardianPriceEntry {
+    mid: number | null;
+    mark: number | null;
+    /** Hourly funding rate (decimal, e.g. 0.0000125). */
+    funding: number | null;
+    updatedAt: number;
+}
+/** Narrow price view the rule engine reads — tests can pass plain fakes. */
+export interface GuardianPriceView {
+    get(coin: string): GuardianPriceEntry | undefined;
+    readonly stale: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/guardian/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../scripts/guardian/types.ts"],"names":[],"mappings":"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"}

package/dist/guardian/types.js

@@ -0,0 +1,45 @@
+// Guardian — read-only position risk monitoring for Hyperliquid addresses.
+// CLI/library port of the hosted copilot guardian (openbroker-copilot
+// src/watcher): same six rules, same default thresholds, same severity
+// contract, minus the multi-tenant DB. Alerts are delivered to the console,
+// Telegram, an OpenClaw agent hook, and/or an onAlert callback.
+export const GUARDIAN_RULE_IDS = [
+    'liq_proximity',
+    'no_tpsl',
+    'stale_order',
+    'margin_usage',
+    'funding_bleed',
+    'position_lifecycle',
+];
+export const GUARDIAN_RULE_LABELS = {
+    liq_proximity: 'Liquidation proximity',
+    no_tpsl: 'No TP/SL protection',
+    stale_order: 'Stale limit orders',
+    margin_usage: 'High margin usage',
+    funding_bleed: 'Funding bleed',
+    position_lifecycle: 'Position open / close / resize',
+};
+export const GUARDIAN_SEVERITY_RANK = {
+    info: 0,
+    warning: 1,
+    critical: 2,
+};
+export const DEFAULT_GUARDIAN_THRESHOLDS = {
+    liqThresholds: [
+        { pct: 0.10, severity: 'warning' },
+        { pct: 0.05, severity: 'critical' },
+        { pct: 0.02, severity: 'critical' },
+    ],
+    liqRearmFactor: 1.5,
+    liqCooldownMs: 30 * 60_000,
+    marginThresholdPct: 80,
+    marginRearmPct: 72,
+    marginCooldownMs: 60 * 60_000,
+    noTpslAfterMs: 15 * 60_000,
+    staleOrderAgeMs: 12 * 3600_000,
+    staleOrderDist: 0.03,
+    staleOrderCooldownMs: 12 * 3600_000,
+    fundingBleedAprPct: 15,
+    fundingBleedForMs: 60 * 60_000,
+    fundingCooldownMs: 6 * 3600_000,
+};

package/dist/lib.d.ts

@@ -2,7 +2,8 @@ export { HyperliquidClient, getClient, } from './core/client.js';
 export { WebSocketManager, getWebSocket, resetWebSocket, } from './core/ws.js';
 export type { WsEventMap, WsEventType, WsEventHandler } from './core/ws.js';
 export { loadConfig, isConfigured, getNetwork, isMainnet, ensureConfigDir, getConfigPath, GLOBAL_CONFIG_DIR, GLOBAL_ENV_PATH, OPEN_BROKER_BUILDER_ADDRESS, } from './core/config.js';
-export { roundPrice, roundSize, sleep, normalizeCoin, formatUsd, formatPercent, annualizeFundingRate, parseArgs, getSlippagePrice, getTimestampMs, generateCloid, orderToWire, checkBuilderFeeApproval, } from './core/utils.js';
+export { roundPrice, roundSize, sleep, normalizeCoin, formatUsd, formatPercent, annualizeFundingRate, parseArgs, getSlippagePrice, getTimestampMs, generateCloid, orderToWire, checkBuilderFeeApproval, MIN_ORDER_NOTIONAL_USD, parseOrderStatus, } from './core/utils.js';
+export type { ParsedOrderStatus } from './core/utils.js';
 export type * from './core/types.js';
 export { runBracket } from './operations/bracket.js';
 export type { BracketOptions, BracketResult } from './operations/bracket.js';
@@ -17,4 +18,12 @@ export { GuardrailViolation, CLIENT_WRITE_METHODS, canonicalMarket, validateAuto
 export type { GuardrailedClientOptions } from './auto/guardrails.js';
 export { registerAutomation, unregisterAutomation, cleanRegistry, getAutomationsToRestart, markAutomationError, } from './auto/registry.js';
 export type * from './auto/types.js';
+export { startGuardian, Guardian } from './guardian/engine.js';
+export type { GuardianOptions, GuardianHandle, GuardianStats, GuardianTelegramChannel, GuardianAgentHookChannel, } from './guardian/engine.js';
+export { GuardianRiskEngine } from './guardian/rules.js';
+export type { GuardianAlertHandler } from './guardian/rules.js';
+export { sendTelegramMessage, getTelegramBotInfo, formatTelegramAlert, loadTelegramSettings, waitForTelegramLink, generateLinkCode, saveEnvVar, } from './guardian/telegram.js';
+export type { TelegramSettings } from './guardian/telegram.js';
+export { GUARDIAN_RULE_IDS, GUARDIAN_RULE_LABELS, GUARDIAN_SEVERITY_RANK, DEFAULT_GUARDIAN_THRESHOLDS, } from './guardian/types.js';
+export type * from './guardian/types.js';
 //# sourceMappingURL=lib.d.ts.map

package/dist/lib.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../scripts/lib.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,iBAAiB,EACjB,SAAS,GACV,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE5E,OAAO,EACL,UAAU,EACV,YAAY,EACZ,UAAU,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,2BAA2B,GAC5B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,UAAU,EACV,SAAS,EACT,KAAK,EACL,aAAa,EACb,SAAS,EACT,aAAa,EACb,oBAAoB,EACpB,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,WAAW,EACX,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AAEzB,mBAAmB,iBAAiB,CAAC;AAIrC,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7E,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEvE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAClE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAInF,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,aAAa,EACb,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,4BAA4B,EAC5B,2BAA2B,EAC3B,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAErE,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,EACb,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAE5B,mBAAmB,iBAAiB,CAAC"}
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../scripts/lib.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,iBAAiB,EACjB,SAAS,GACV,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE5E,OAAO,EACL,UAAU,EACV,YAAY,EACZ,UAAU,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,2BAA2B,GAC5B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,UAAU,EACV,SAAS,EACT,KAAK,EACL,aAAa,EACb,SAAS,EACT,aAAa,EACb,oBAAoB,EACpB,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,WAAW,EACX,uBAAuB,EACvB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,mBAAmB,iBAAiB,CAAC;AAIrC,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7E,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEvE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAClE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAInF,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,aAAa,EACb,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,4BAA4B,EAC5B,2BAA2B,EAC3B,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAErE,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,EACb,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAE5B,mBAAmB,iBAAiB,CAAC;AAIrC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAC/D,YAAY,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACb,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAEhE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,GACX,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,qBAAqB,CAAC;AAC7B,mBAAmB,qBAAqB,CAAC"}

package/dist/lib.js

@@ -11,7 +11,7 @@ export { HyperliquidClient, getClient, } from './core/client.js';
 // REST-polling. `userFill` / `orderUpdate` are emitted per own-order event; see WsEventMap.
 export { WebSocketManager, getWebSocket, resetWebSocket, } from './core/ws.js';
 export { loadConfig, isConfigured, getNetwork, isMainnet, ensureConfigDir, getConfigPath, GLOBAL_CONFIG_DIR, GLOBAL_ENV_PATH, OPEN_BROKER_BUILDER_ADDRESS, } from './core/config.js';
-export { roundPrice, roundSize, sleep, normalizeCoin, formatUsd, formatPercent, annualizeFundingRate, parseArgs, getSlippagePrice, getTimestampMs, generateCloid, orderToWire, checkBuilderFeeApproval, } from './core/utils.js';
+export { roundPrice, roundSize, sleep, normalizeCoin, formatUsd, formatPercent, annualizeFundingRate, parseArgs, getSlippagePrice, getTimestampMs, generateCloid, orderToWire, checkBuilderFeeApproval, MIN_ORDER_NOTIONAL_USD, parseOrderStatus, } from './core/utils.js';
 // ── Operations (in-process callable) ────────────────────────────────
 export { runBracket } from './operations/bracket.js';
 export { runChase } from './operations/chase.js';
@@ -21,3 +21,8 @@ export { startAutomation, getRunningAutomations, getAutomation, getRegisteredAut
 export { resolveScriptPath, resolveExamplePath, listAutomations, listExamples, loadExampleConfigs, ensureAutomationsDir, loadAutomation, } from './auto/loader.js';
 export { GuardrailViolation, CLIENT_WRITE_METHODS, canonicalMarket, validateAutomationGuardrails, resolveAutomationGuardrails, createGuardrailedClient, } from './auto/guardrails.js';
 export { registerAutomation, unregisterAutomation, cleanRegistry, getAutomationsToRestart, markAutomationError, } from './auto/registry.js';
+// ── Guardian (read-only position risk monitoring) ───────────────────
+export { startGuardian, Guardian } from './guardian/engine.js';
+export { GuardianRiskEngine } from './guardian/rules.js';
+export { sendTelegramMessage, getTelegramBotInfo, formatTelegramAlert, loadTelegramSettings, waitForTelegramLink, generateLinkCode, saveEnvVar, } from './guardian/telegram.js';
+export { GUARDIAN_RULE_IDS, GUARDIAN_RULE_LABELS, GUARDIAN_SEVERITY_RANK, DEFAULT_GUARDIAN_THRESHOLDS, } from './guardian/types.js';