hypervibes 0.0.0-stage → 0.4.0

package/dist/hyperliquid/orders/protection.js

@@ -0,0 +1,35 @@
+import { HyperliquidError } from "../errors.js";
+import { exchangeOid } from "./order-prepare.js";
+import { compare, positionSize } from "./order-math.js";
+export async function verifyProtection(info, account, positions, orders, quotes, signal) {
+    if (orders.length > 100 || positions.length > 100)
+        throw new HyperliquidError("Protection inspection exceeds the 100-order/position budget", 409);
+    const verified = [], statuses = new Map();
+    for (const order of orders)
+        if (order.isTrigger && order.reduceOnly) {
+            const oid = exchangeOid(String(order.oid));
+            const response = await info.orderStatus({ user: account, oid }, signal);
+            if (response.status === "order" && response.order.order.oid === oid && response.order.order.coin === order.coin) {
+                // Re-read size/side/type/trigger from the individual response too: an old
+                // frontendOpenOrders quantity must not mask a subsequent partial fill.
+                verified.push(response.order.order);
+                statuses.set(oid, response.order.status);
+            }
+        }
+    return inspectProtection(positions, verified, statuses, quotes);
+}
+/** Only top-level live triggers with individually verified statuses count.
+ * Parent.children/waitingForFill are deliberately NOT active position protection. */
+export function inspectProtection(positions, orders, statuses, quotes = {}) {
+    return positions.flatMap((position) => {
+        const exposure = positionSize(position.size);
+        if (exposure.side === "flat")
+            return [];
+        const side = exposure.side === "long" ? "A" : "B";
+        const candidates = orders.filter((order) => order.coin === position.coin && order.side === side && order.reduceOnly && order.isTrigger && ["open", "waitingForTrigger"].includes(statuses.get(order.oid) ?? "") && positionSize(order.sz).side !== "flat" && compare(order.sz, exposure.size) >= 0);
+        const quote = quotes[position.coin];
+        const tp = candidates.filter((order) => (order.orderType === "Take Profit Market" || order.orderType === "Take Profit Limit") && quote !== undefined && (exposure.side === "long" ? compare(order.triggerPx, quote) > 0 : compare(order.triggerPx, quote) < 0));
+        const sl = candidates.filter((order) => order.orderType === "Stop Market" && quote !== undefined && (exposure.side === "long" ? compare(order.triggerPx, quote) < 0 : compare(order.triggerPx, quote) > 0));
+        return [{ instrument: position.coin, side: exposure.side, size: exposure.size, takeProfitOids: tp.map((order) => String(order.oid)), stopLossOids: sl.map((order) => String(order.oid)), covered: tp.length > 0 && sl.length > 0, warning: "Observed per-leg state only, not a perpetual coverage guarantee. Stop-limit legs are not treated as reliable full-size loss protection. Inspect partial fills and uncertain/rejected legs; repair with standalone reduce-only orders, never blind cancel-all." }];
+    });
+}

package/dist/hyperliquid/orders/risk-settings.js

@@ -0,0 +1,44 @@
+import { AgentError } from "../../agents/agent-input.js";
+import { instrument } from "../../memory/memory-contracts.js";
+import { array, fields, object, positiveDecimal, unique } from "../../memory/validation.js";
+/** Operator-supplied settings are validated here; models never write them. */
+export function riskSettingsInput(value) {
+    const row = fields(object(value), ["tradingEnabled", "allowedInstruments", "maxOrderNotional", "maxTotalNotional"]);
+    if (typeof row.tradingEnabled !== "boolean")
+        throw new AgentError("Invalid trading enablement");
+    const allowed = row.allowedInstruments == null ? null : unique(array(row.allowedInstruments, 50, instrument));
+    if (allowed && !allowed.length)
+        throw new AgentError("Select at least one allowed instrument, or clear the list for no limit");
+    const notional = (candidate) => candidate == null || candidate === "" ? null : positiveDecimal(candidate);
+    return { tradingEnabled: row.tradingEnabled, allowedInstruments: allowed, maxOrderNotional: notional(row.maxOrderNotional), maxTotalNotional: notional(row.maxTotalNotional) };
+}
+const columns = "trading_enabled,allowed_instruments,max_order_notional,max_total_notional";
+function settings(row) {
+    return row ? { tradingEnabled: row.trading_enabled === 1, allowedInstruments: row.allowed_instruments == null ? null : JSON.parse(row.allowed_instruments), maxOrderNotional: row.max_order_notional, maxTotalNotional: row.max_total_notional }
+        : { tradingEnabled: false, allowedInstruments: null, maxOrderNotional: null, maxTotalNotional: null };
+}
+export class RiskSettingsService {
+    db;
+    changed;
+    constructor(db, changed) {
+        this.db = db;
+        this.changed = changed;
+    }
+    async get(agentId) {
+        return settings(await this.db.get(`SELECT ${columns} FROM hv_risk_settings WHERE agent_id=?`, agentId));
+    }
+    async save(agentId, value) {
+        const input = riskSettingsInput(value), now = Date.now();
+        const saved = settings(await this.db.transaction(async (tx) => {
+            const agent = await tx.get("SELECT state FROM hv_agents WHERE id=?", agentId);
+            if (!agent)
+                throw new AgentError("Agent not found", 404);
+            if (agent.state === "stopping" || agent.state === "stopped")
+                throw new AgentError("Agent is being deleted", 409);
+            await tx.run("INSERT INTO hv_risk_settings(agent_id,trading_enabled,allowed_instruments,max_order_notional,max_total_notional,updated_at) VALUES (?,?,?,?,?,?) ON CONFLICT(agent_id) DO UPDATE SET trading_enabled=excluded.trading_enabled,allowed_instruments=excluded.allowed_instruments,max_order_notional=excluded.max_order_notional,max_total_notional=excluded.max_total_notional,updated_at=excluded.updated_at", agentId, input.tradingEnabled ? 1 : 0, input.allowedInstruments && JSON.stringify(input.allowedInstruments), input.maxOrderNotional, input.maxTotalNotional, now);
+            return await tx.get(`SELECT ${columns} FROM hv_risk_settings WHERE agent_id=?`, agentId);
+        }));
+        this.changed?.(agentId);
+        return saved;
+    }
+}

package/dist/hyperliquid/orders/trade-admission.js

@@ -0,0 +1,117 @@
+import { assertActiveActor } from "../../memory/operations.js";
+import { HyperliquidError } from "../errors.js";
+import { RiskSettingsService } from "./risk-settings.js";
+import { compare, decimal, notional, notionalAtLeast, positionSize, sumDecimals } from "./order-math.js";
+/** Identity/tool permissions plus risk limits, never strategy or research policy. */
+export class TradeAdmissionService {
+    db;
+    execution;
+    handles = new WeakMap();
+    risk;
+    constructor(db, execution) {
+        this.db = db;
+        this.execution = execution;
+        this.risk = new RiskSettingsService(db);
+    }
+    async handle(agentId, api, context) {
+        const { actor, config } = await this.execution.resolve(agentId, api, context);
+        const handle = Object.freeze({});
+        this.handles.set(handle, { actor, tools: config.tools });
+        return handle;
+    }
+    authority(agentId, handle) {
+        const value = handle && this.handles.get(handle);
+        if (!value || value.actor.agentId !== agentId)
+            throw new HyperliquidError("A verified model execution handle is required for model order mutations", 403);
+        return value;
+    }
+    /** Only the trusted handle can supply request provenance, never model arguments. */
+    origin(agentId, handle, capability) {
+        const { actor, tools } = this.authority(agentId, handle);
+        if (!tools.includes(capability))
+            throw new HyperliquidError("Order mutation permission not selected", 403);
+        return actor;
+    }
+    /** Read-only planners need identity, not submit_orders permission. */
+    planning(agentId, handle) { this.authority(agentId, handle); }
+    /** Called under the existing per-Agent mutation lock, including before a retry sends. */
+    async validate(agentId, info, account, signal, actions, handle) {
+        const { actor, tools } = this.authority(agentId, handle);
+        if (!tools.includes("submit_orders"))
+            throw new HyperliquidError("Order mutation permission not selected", 403);
+        await this.db.transaction((tx) => assertActiveActor(tx, actor));
+        const entries = actions.flatMap((action) => action.items).filter((view) => !view.reduceOnly);
+        // Reduce-only orders cannot increase exposure. The exchange remains authoritative
+        // for position quantity/side; disabling entries never blocks protective management.
+        if (!entries.length)
+            return;
+        const settings = await this.risk.get(agentId);
+        if (!settings.tradingEnabled)
+            throw new HyperliquidError("Trading is disabled in this Agent's risk settings. Enable trading in the Agent's risk settings before opening exposure; enabling a worker does not bypass this shared gate.", 409);
+        const mids = settings.maxOrderNotional || settings.maxTotalNotional ? await info.allMids({ dex: "" }, signal) : {};
+        const quote = (coin) => {
+            const value = mids[coin];
+            if (typeof value !== "string")
+                throw new HyperliquidError(`Current market quote for ${coin} unavailable`, 503);
+            decimal(value);
+            return value;
+        };
+        for (const entry of entries) {
+            if (settings.allowedInstruments && !settings.allowedInstruments.includes(entry.symbol))
+                throw new HyperliquidError(`Instrument ${entry.symbol} is not in this Agent's allowed instruments`, 409);
+            if (!entry.size || !entry.price)
+                throw new HyperliquidError("Prepared entry size/price unavailable");
+            if (!notionalAtLeast(entry.size, entry.price, "10"))
+                throw new HyperliquidError("Opening notional is below the $10 venue minimum; never silently increase size");
+            if (settings.maxOrderNotional && compare(notional(entry.size, higher(quote(entry.symbol), entry.price)), settings.maxOrderNotional) > 0)
+                throw new HyperliquidError("Opening notional exceeds the configured maximum order notional", 409);
+        }
+        if (!settings.maxTotalNotional)
+            return;
+        const [state, live, local] = await Promise.all([
+            info.clearinghouseState({ user: account, dex: "" }, signal),
+            info.frontendOpenOrders({ user: account, dex: "" }, signal),
+            this.db.all(`SELECT i.view FROM hv_order_items i
+        JOIN hv_order_actions a ON a.id=i.action_id JOIN hv_order_requests r ON r.id=a.request_id
+        WHERE r.agent_id=? AND r.account=? AND i.id NOT IN (SELECT value FROM json_each(?)) AND r.kind='submit'
+        AND json_extract(i.view,'$.reduceOnly')=0 AND
+        (a.state IN ('prepared','submitting','unknown') OR i.active=1 OR
+          (json_extract(i.view,'$.orderStatus')='filled' AND i.updated_at>?)) LIMIT 1001`, agentId, account, JSON.stringify(actions.flatMap((action) => action.items.map((item) => item.id))), Date.now() - 30000),
+        ]);
+        if (!Array.isArray(state.assetPositions) || !Array.isArray(live))
+            throw new HyperliquidError("Current exposure data unavailable", 503);
+        if (local.length > 1000)
+            throw new HyperliquidError("Pending exposure exceeds the risk inspection budget", 409);
+        const amounts = state.assetPositions.flatMap(({ position }) => {
+            const exposure = positionSize(position.szi);
+            return exposure.side === "flat" ? [] : [notional(exposure.size, quote(position.coin))];
+        });
+        const pending = [...entries];
+        // Do not double-count an open order reported by both local storage and the venue.
+        const cloids = new Set(), oids = new Set();
+        for (const order of live) {
+            if (order.reduceOnly)
+                continue;
+            if (order.cloid)
+                cloids.add(order.cloid);
+            oids.add(String(order.oid));
+            amounts.push(notional(order.sz, higher(quote(order.coin), order.limitPx)));
+        }
+        for (const { view } of local) {
+            const order = JSON.parse(view);
+            if (order.cloid && cloids.has(order.cloid) || order.exchangeOid && oids.has(order.exchangeOid))
+                continue;
+            // Unknown/pending submissions and very recent fills reserve capacity while
+            // account snapshots catch up. Recent fills may briefly be counted twice.
+            pending.push(order);
+        }
+        for (const order of pending) {
+            if (!order.size || !order.price)
+                throw new HyperliquidError("Pending exposure size/price unavailable", 503);
+            amounts.push(notional(order.size, higher(quote(order.symbol), order.price)));
+        }
+        if (compare(sumDecimals(amounts), settings.maxTotalNotional) > 0)
+            throw new HyperliquidError("Projected total open notional (positions plus pending entries) exceeds the configured maximum total notional", 409);
+    }
+}
+function higher(a, b) { return compare(a, b) >= 0 ? a : b; }

package/dist/hyperliquid/orders/trade-planning.js

@@ -0,0 +1,60 @@
+import { HyperliquidError } from "../errors.js";
+import { compare, decimal, guardPrice, notionalAtLeast, positionSize, price, size } from "./order-math.js";
+import { instrument, instruments } from "./order-prepare.js";
+/** Run before schema validation as well, so callers see the allowed values. */
+export function assertEntryStyle(value) {
+    if (value !== "guarded_ioc" && value !== "limit")
+        throw new HyperliquidError(`entry_style must be "guarded_ioc" or "limit"; received ${JSON.stringify(value) ?? "missing"}. Use "guarded_ioc" for a market-like 0.5%-guarded IOC entry, not "market". Use "limit" with an explicit limit_price for GTC.`);
+}
+/**
+ * Read-only protected-entry planner. Strategy, sizing and protection levels
+ * are model/worker decisions from instructions and insights; this only
+ * enforces exact venue arithmetic and side sanity, never policy.
+ */
+export async function prepareProtectedEntry(info, input, signal) {
+    assertEntryStyle(input.entry_style);
+    if (!["buy", "sell"].includes(input.side))
+        throw new HyperliquidError('side must be "buy" or "sell"');
+    if (input.entry_style === "guarded_ioc" && input.limit_price !== undefined)
+        throw new HyperliquidError("Omit limit_price for guarded IOC planning");
+    if (input.entry_style === "limit" && input.limit_price === undefined)
+        throw new HyperliquidError("Explicit limit_price is required for limit planning");
+    const entry = instrument(await instruments(info, signal), input.instrument);
+    const observedAt = Date.now();
+    const quote = (await info.allMids({ dex: "" }, signal))[input.instrument];
+    if (typeof quote !== "string" || !quote)
+        throw new HyperliquidError("Current string-valued market quote unavailable", 503);
+    decimal(quote);
+    const buy = input.side === "buy";
+    const px = input.entry_style === "limit" ? price(input.limit_price, entry.szDecimals) : guardPrice(quote, buy, entry.szDecimals);
+    const qty = size(input.size, entry.szDecimals);
+    if (!notionalAtLeast(qty, px, "10"))
+        throw new HyperliquidError("Draft is below the $10 minimum entry notional; do not silently increase size");
+    const tp = price(input.take_profit_price, entry.szDecimals), sl = price(input.stop_loss_price, entry.szDecimals);
+    if (buy ? compare(tp, px) <= 0 || compare(sl, px) >= 0 : compare(tp, px) >= 0 || compare(sl, px) <= 0)
+        throw new HyperliquidError("TP/SL is on the wrong side of the guarded/explicit entry");
+    const order = { symbol: input.instrument, side: input.side, order_type: "limit", size: qty, price: px, time_in_force: input.entry_style === "guarded_ioc" ? "ioc" : "gtc", take_profits: [{ trigger_price: tp, size: qty }], stop_losses: [{ trigger_price: sl, size: qty }] };
+    return { orders: [order], quote, quoteSource: "Hyperliquid main-DEX allMids HTTP (host observation, not venue timestamp)", observedAt, validUntil: observedAt + 15000, calculationBasis: input.entry_style === "guarded_ioc" ? "0.5% guarded IOC limit" : "Explicit exact-decimal limit price", warning: "Draft only; no authority or protection guarantee. Submit revalidates prices and current state. Entry size and TP/SL levels are your strategy decisions within the Agent's risk settings; never silently increase size." };
+}
+/** Read-only planner for standalone reduce-only protection of an existing position. */
+export async function preparePositionProtection(info, input, account, signal) {
+    const observedAt = Date.now();
+    const [meta, state, mids] = await Promise.all([instruments(info, signal), info.clearinghouseState({ user: account, dex: "" }, signal), info.allMids({ dex: "" }, signal)]);
+    const asset = instrument(meta, input.instrument), position = state.assetPositions.find(({ position }) => position.coin === input.instrument)?.position;
+    const exposure = positionSize(position?.szi ?? "0");
+    if (exposure.side === "flat")
+        throw new HyperliquidError("No current position exists for protective planning");
+    const quote = mids[input.instrument];
+    if (typeof quote !== "string")
+        throw new HyperliquidError("Current string-valued quote unavailable", 503);
+    decimal(quote);
+    const long = exposure.side === "long", quantity = size(exposure.size, asset.szDecimals);
+    const tp = price(input.take_profit_price, asset.szDecimals), sl = price(input.stop_loss_price, asset.szDecimals);
+    if (long ? compare(tp, quote) <= 0 || compare(sl, quote) >= 0 : compare(tp, quote) >= 0 || compare(sl, quote) <= 0)
+        throw new HyperliquidError("Protection levels have crossed the current market; explicit review is required, not unapproved flattening or invented replacement prices");
+    const orders = [
+        { symbol: input.instrument, side: long ? "sell" : "buy", size: quantity, order_type: "take_profit", trigger_price: tp, reduce_only: true },
+        { symbol: input.instrument, side: long ? "sell" : "buy", size: quantity, order_type: "stop_loss", trigger_price: sl, reduce_only: true },
+    ];
+    return { orders, quote, quoteSource: "Hyperliquid main-DEX allMids and clearinghouseState HTTP (host observation, not venue timestamp)", observedAt, validUntil: observedAt + 15000, calculationBasis: "Actual current signed position quantity; no new exposure or sizing increase", warning: "Draft only. Inspect known protective orders first and submit ONLY missing/appropriate legs; never duplicate or cancel live protection blindly. No perpetual coverage guarantee." };
+}