hypervibes 0.0.0-stage → 0.4.0

package/dist/hyperliquid/orders/order-service.js

@@ -0,0 +1,432 @@
+import { ApiRequestError, ExchangeClient, InfoClient } from "@nktkas/hyperliquid";
+import { TradeAdmissionService } from "./trade-admission.js";
+import { preparePositionProtection, prepareProtectedEntry } from "./trade-planning.js";
+import { verifyProtection } from "./protection.js";
+import { compare, positionSize } from "./order-math.js";
+import { assertAgentExecutable } from "../../agents/agent-enablement.js";
+import { privateKeyToAccount } from "viem/accounts";
+import { HyperliquidError } from "../errors.js";
+import { assertStringAmounts, exchangeOid, instruments, instrument, isPerpetual, liveView, newView, prepareSubmit } from "./order-prepare.js";
+import { OrderStore, active } from "./order-store.js";
+import { reconciledView, responseViews, unknownViews } from "./order-outcomes.js";
+/** Application-owned intent/outcome gateway. Reconciliation NEVER submits orders. */
+export class OrderService {
+    database;
+    transport;
+    bindings;
+    log;
+    store;
+    info;
+    locks = new Map();
+    tasks = new Set();
+    agentTasks = new Map();
+    stoppedAgents = new Set();
+    shutdown = new AbortController();
+    timer;
+    started = false;
+    stopping = false;
+    admission;
+    constructor(database, transport, bindings, log) {
+        this.database = database;
+        this.transport = transport;
+        this.bindings = bindings;
+        this.log = log;
+        this.store = new OrderStore(database);
+        this.info = new InfoClient({ transport });
+    }
+    installAdmission(execution) { this.admission = new TradeAdmissionService(this.database, execution); }
+    executionHandle(agentId, api, context) {
+        if (!this.admission)
+            throw new HyperliquidError("Execution identity is not initialized; model orders are unavailable", 503);
+        return this.admission.handle(agentId, api, context);
+    }
+    async plan(userId, agentId, input, handle, cancellation) {
+        await this.account(userId, agentId);
+        if (!this.admission)
+            throw new HyperliquidError("Trade planning is not initialized", 503);
+        this.admission.planning(agentId, handle);
+        return prepareProtectedEntry(this.info, input, this.signal(cancellation));
+    }
+    async planProtection(userId, agentId, input, handle, cancellation) {
+        const account = await this.account(userId, agentId);
+        if (!this.admission)
+            throw new HyperliquidError("Trade planning is not initialized", 503);
+        this.admission.planning(agentId, handle);
+        return preparePositionProtection(this.info, input, account, this.signal(cancellation));
+    }
+    async protection(userId, agentId, cancellation) {
+        const account = await this.account(userId, agentId), signal = this.signal(cancellation);
+        const [state, orders, mids] = await Promise.all([this.info.clearinghouseState({ user: account, dex: "" }, signal), this.info.frontendOpenOrders({ user: account, dex: "" }, signal), this.info.allMids({ dex: "" }, signal)]);
+        if (orders.length > 100 || state.assetPositions.length > 100)
+            throw new HyperliquidError("More than 100 open orders/positions; protection coverage is over budget and must be reviewed manually", 409);
+        const positions = await verifyProtection(this.info, account, state.assetPositions.map(({ position }) => ({ coin: position.coin, size: position.szi })), orders, mids, signal);
+        return { observedAt: Date.now(), positions, warning: "Snapshot verification only. Native children waitingForFill do not protect partial positions. Scheduled model repair cannot guarantee zero unprotected time. Preserve known orders; do not flatten or cancel-all without authorization." };
+    }
+    recover() { return this.store.recover(); }
+    start() {
+        if (this.started || this.stopping)
+            return;
+        this.started = true;
+        this.log?.info("Starting order reconciliation loop");
+        const tick = async () => {
+            try {
+                for (const request of await this.store.pendingRequests()) {
+                    if (this.stopping)
+                        break;
+                    if (this.stoppedAgents.has(request.agentId))
+                        continue;
+                    const agent = await this.database.get("SELECT state FROM hv_agents WHERE id=?", request.agentId);
+                    if (!agent || agent.state === "stopping" || agent.state === "stopped" || this.stoppedAgents.has(request.agentId))
+                        continue;
+                    await this.trackAgent(request.agentId, () => this.lock(request.id, () => this.reconcile(request, this.signal())));
+                }
+            }
+            catch (error) {
+                this.log?.warn(error, "Order reconciliation pass failed; retrying on the next pass");
+            }
+            finally {
+                if (!this.stopping) {
+                    this.timer = setTimeout(() => { void this.track(tick()); }, 15_000);
+                    this.timer.unref();
+                }
+            }
+        };
+        void this.track(tick());
+    }
+    async close() {
+        this.stopping = true;
+        clearTimeout(this.timer);
+        this.shutdown.abort();
+        await Promise.allSettled([...this.tasks]);
+    }
+    /** Join the per-agent mutation queue without sealing operator exits or reconciliation. */
+    quiesce(agentId) { return this.lock(agentId, async () => { }); }
+    /** Seal this agent only; join submissions and reconciliation before cascading its records. */
+    async stopAgent(agentId) {
+        this.stoppedAgents.add(agentId);
+        await Promise.allSettled([...(this.agentTasks.get(agentId) ?? [])]);
+    }
+    trackAgent(agentId, run) {
+        if (this.stoppedAgents.has(agentId))
+            return Promise.reject(new HyperliquidError("Agent is being deleted", 409));
+        const tasks = this.agentTasks.get(agentId) ?? new Set();
+        this.agentTasks.set(agentId, tasks);
+        const task = this.track(run());
+        tasks.add(task);
+        void task.finally(() => {
+            tasks.delete(task);
+            if (!tasks.size)
+                this.agentTasks.delete(agentId);
+        }).catch(() => { });
+        return task;
+    }
+    signal(signal) { return AbortSignal.any([this.shutdown.signal, AbortSignal.timeout(15_000), ...(signal ? [signal] : [])]); }
+    track(task) {
+        this.tasks.add(task);
+        void task.finally(() => this.tasks.delete(task)).catch(() => { });
+        return task;
+    }
+    admit() { if (this.stopping)
+        throw new HyperliquidError("Order service is closed", 503); }
+    lock(key, run) {
+        const task = (this.locks.get(key) ?? Promise.resolve()).catch(() => { }).then(run);
+        this.locks.set(key, task);
+        void task.finally(() => { if (this.locks.get(key) === task)
+            this.locks.delete(key); }).catch(() => { });
+        return task;
+    }
+    async account(userId, agentId) {
+        this.admit();
+        if (this.stoppedAgents.has(agentId))
+            throw new HyperliquidError("Agent is being deleted", 409);
+        const address = await this.bindings.account(userId, agentId);
+        if (!address || !/^0x[0-9a-fA-F]{40}$/.test(address))
+            throw new HyperliquidError("This Agent has no valid assigned trading account.", 409);
+        return address.toLowerCase();
+    }
+    requestKey(key) { if (typeof key !== "string" || !/^[a-zA-Z0-9_-]{1,120}$/.test(key))
+        throw new HyperliquidError("Use a stable request_id of 1–120 letters, digits, underscores or hyphens."); }
+    submit(userId, agentId, input, signal, execution) {
+        assertStringAmounts(input);
+        if (!Array.isArray(input.orders) || input.orders.length < 1 || input.orders.length > 20)
+            throw new HyperliquidError("Submit 1–20 entry orders per request.");
+        return this.mutate(userId, agentId, input.request_id, "submit", input, signal, (authority, abort) => prepareSubmit(this.info, input.request_id, input.orders, authority.builder, abort), execution);
+    }
+    cancel(userId, agentId, input, signal, execution) {
+        assertStringAmounts(input);
+        if (!Array.isArray(input.orders) || input.orders.length < 1 || input.orders.length > 100)
+            throw new HyperliquidError("Cancel 1–100 orders per request.");
+        return this.mutate(userId, agentId, input.request_id, "cancel", input, signal, (authority, abort) => this.prepareCancel(authority.account, input.request_id, input.orders, abort), execution);
+    }
+    cancelAll(userId, agentId, input, signal, execution) {
+        return this.mutate(userId, agentId, input.request_id, "cancel_all", input, signal, async (authority, abort) => {
+            const orders = (await this.info.frontendOpenOrders({ user: authority.account, dex: "" }, abort))
+                .filter((order) => isPerpetual(order.coin) && (!input.symbol || order.coin === input.symbol));
+            if (orders.length > 100)
+                throw new HyperliquidError("More than 100 open orders; cancel explicit bounded batches instead.");
+            if (!orders.length)
+                return [];
+            return this.prepareCancel(authority.account, input.request_id, orders.map((order) => ({ symbol: order.coin, oid: String(order.oid) })), abort);
+        }, execution);
+    }
+    /** Operator-only single-order cancellation; mutate owns the per-agent lock and replay. */
+    cancelOrder(userId, agentId, symbol, oid, key) {
+        const input = { request_id: key, orders: [{ symbol, oid }] };
+        return this.mutate(userId, agentId, key, "cancel", input, undefined, (authority, signal) => this.prepareCancel(authority.account, key, input.orders, signal), undefined, { operator: true });
+    }
+    /** Operator-only exit. Browser/model input never supplies side, size, or signing authority. */
+    closePosition(userId, agentId, symbol, key) {
+        this.admit();
+        this.requestKey(key);
+        if (key.length > 100)
+            throw new HyperliquidError("Close request ID must be at most 100 characters");
+        return this.trackAgent(agentId, () => this.lock(agentId, async () => {
+            const account = await this.account(userId, agentId);
+            instrument(await instruments(this.info, this.signal()), symbol);
+            const unresolved = await this.database.get(`SELECT r.request_key FROM hv_order_requests r JOIN hv_order_actions a ON a.request_id=r.id WHERE r.account=? AND r.kind='close_position' AND json_extract(r.input,'$.symbol')=? AND a.state IN ('submitting','unknown') AND r.request_key!=? LIMIT 1`, account, symbol, `${key}-close`);
+            if (unresolved)
+                throw new HyperliquidError(`An earlier position close has an unknown outcome. Reconcile request ${unresolved.request_key} before issuing another close.`, 409);
+            const cancel = await this.mutate(userId, agentId, `${key}-cancel`, "cancel_all", { symbol }, undefined, async (authority, signal) => {
+                const orders = (await this.info.frontendOpenOrders({ user: authority.account, dex: "" }, signal)).filter((order) => order.coin === symbol);
+                if (orders.length > 100)
+                    throw new HyperliquidError("More than 100 orders in this market; review manually", 409);
+                return orders.length ? this.prepareCancel(account, `${key}-cancel`, orders.map((order) => ({ symbol, oid: String(order.oid) })), signal) : [];
+            }, undefined, { operator: true, locked: true });
+            const close = await this.mutate(userId, agentId, `${key}-close`, "close_position", { symbol }, undefined, async (authority, signal) => {
+                const state = await this.info.clearinghouseState({ user: account, dex: "" }, signal);
+                const current = state.assetPositions.find(({ position }) => position.coin === symbol)?.position;
+                if (!current)
+                    return [];
+                const position = positionSize(current.szi);
+                if (position.side === "flat")
+                    return [];
+                return prepareSubmit(this.info, `${key}-close`, [{ symbol, side: position.side === "long" ? "sell" : "buy", size: position.size, order_type: "market", reduce_only: true }], authority.builder, signal);
+            }, undefined, { operator: true, locked: true });
+            const warnings = [...close.warnings];
+            if (cancel.uncertain)
+                warnings.push("Cancellation outcome is unknown. Check the original operation instead of retrying with a new ID.");
+            if (cancel.results.some((order) => order.commandStatus === "rejected" || order.commandStatus === "unknown" || order.commandStatus === "not_sent"))
+                warnings.push("Some market orders were not confirmed canceled; inspect remaining orders.");
+            let remainingSize = null, remainingOrders = null;
+            try {
+                const [state, orders] = await Promise.all([
+                    this.info.clearinghouseState({ user: account, dex: "" }, this.signal()),
+                    this.info.frontendOpenOrders({ user: account, dex: "" }, this.signal()),
+                ]);
+                remainingSize = state.assetPositions.find(({ position }) => position.coin === symbol)?.position.szi ?? "0";
+                remainingOrders = orders.filter((order) => order.coin === symbol).length;
+            }
+            catch {
+                warnings.push("Could not verify remaining position/orders. Inspect the account before retrying.");
+            }
+            return { requestId: key, cancel, close, remainingSize, remainingOrders, warnings,
+                complete: remainingSize !== null && positionSize(remainingSize).side === "flat" && remainingOrders === 0 && !cancel.uncertain && !close.uncertain };
+        }));
+    }
+    async prepareCancel(account, key, inputs, signal) {
+        const meta = await instruments(this.info, signal);
+        const seen = new Set();
+        const items = [], cancels = [];
+        for (const input of inputs) {
+            const asset = instrument(meta, input.symbol).asset;
+            const oid = exchangeOid(input.oid);
+            if (seen.has(input.oid))
+                throw new HyperliquidError("Duplicate cancellation target.");
+            seen.add(input.oid);
+            // OIDs alone confer no authority. Check the assigned account and symbol,
+            // including orders this account placed outside HyperVibes.
+            const status = await this.info.orderStatus({ user: account, oid }, signal);
+            if (status.status !== "order" || status.order.order.coin !== input.symbol || status.order.order.oid !== oid)
+                throw new HyperliquidError("Cancellation target was not found on this Agent's account/symbol.", 409);
+            const view = liveView(status.order.order, status.order.status, status.order.statusTimestamp);
+            items.push({ ...view, id: newView(key, input.symbol, "cancel").id, requestId: key, kind: "cancel", cloid: null, commandStatus: "not_sent", source: "intent" });
+            cancels.push({ a: asset, o: oid });
+        }
+        return [{ payload: { kind: "cancel", cancels }, items }];
+    }
+    mutate(userId, agentId, key, kind, input, cancellation, prepare, execution, options = {}) {
+        this.admit();
+        this.requestKey(key);
+        const operator = options.operator === true;
+        if (!this.started)
+            return Promise.reject(new HyperliquidError("Order execution is not started", 503));
+        const run = async () => {
+            const account = await this.account(userId, agentId);
+            if (!operator)
+                await assertAgentExecutable(this.database, agentId);
+            const submission = kind === "submit" || kind === "close_position";
+            const signal = this.signal(cancellation);
+            signal.throwIfAborted();
+            let request = await this.store.request(agentId, key);
+            let authority;
+            if (request) {
+                this.store.matches(request, account, kind, input);
+                const existing = request;
+                if (operator)
+                    await this.lock(existing.id, () => this.reconcile(existing, signal));
+            }
+            else {
+                if (kind === "submit" && input.orders.some((order) => !order.reduce_only && ["limit", "market"].includes(order.order_type)) && await this.store.hasUncertain(account)) {
+                    throw new HyperliquidError("An earlier command has an unknown outcome on this account. Reconcile it before adding exposure; do not retry with a new request_id.", 409);
+                }
+                authority = await this.bindings.authority(userId, agentId, signal, submission);
+                if (authority.account !== account)
+                    throw new HyperliquidError("Account assignment changed", 409);
+                const prepared = await prepare(authority, signal);
+                if (kind === "submit" && this.admission)
+                    await this.admission.validate(agentId, this.info, account, signal, prepared, execution);
+                const capability = kind === "submit" ? "submit_orders" : kind === "cancel" ? "cancel_orders" : "cancel_all_orders";
+                const origin = operator ? undefined : this.admission?.origin(agentId, execution, capability);
+                request = await this.store.prepare(agentId, account, key, kind, input, prepared, origin);
+            }
+            // The same request lock is also used by background reconciliation.
+            const captured = request;
+            return this.lock(captured.id, async () => {
+                const actions = await this.store.actions(captured.id);
+                let stop = actions.some((action) => action.state === "unknown" || action.state === "submitting")
+                    || (await this.store.allItems(captured.id)).some(({ view }) => JSON.parse(view).commandStatus === "rejected");
+                for (const action of actions) {
+                    if (action.state !== "prepared")
+                        continue;
+                    const views = (await this.store.items(action.id)).map(({ view }) => JSON.parse(view));
+                    if (stop || signal.aborted || Date.now() >= action.expiresAt) {
+                        await this.store.outcome(action.id, "not_sent", views.map((view) => ({ ...view, commandStatus: "not_sent", orderStatus: "not_sent", updatedAt: Date.now(), error: "Not sent: previous action uncertain/rejected, request expired, or execution aborted." })), "not_sent");
+                        continue;
+                    }
+                    if (!operator)
+                        await assertAgentExecutable(this.database, agentId);
+                    authority ??= await this.bindings.authority(userId, agentId, signal, submission);
+                    if (authority.account !== captured.account)
+                        throw new HyperliquidError("Account assignment changed", 409);
+                    if (kind === "submit" && this.admission) {
+                        if (views.some((view) => !view.reduceOnly) && await this.store.hasUncertain(account))
+                            throw new HyperliquidError("An earlier command has an unknown outcome on this account. Reconcile it before adding exposure.", 409);
+                        await this.admission.validate(agentId, this.info, account, signal, [{ payload: JSON.parse(action.payload), items: views }], execution);
+                    }
+                    if (operator && submission && views.some((view) => !view.reduceOnly))
+                        throw new HyperliquidError("Operator exits must be reduce-only", 403);
+                    if (!operator)
+                        await assertAgentExecutable(this.database, agentId);
+                    if (!(await this.store.begin(action, operator ? undefined : agentId)))
+                        continue;
+                    const payload = JSON.parse(action.payload);
+                    let response;
+                    let uncertain = false;
+                    try {
+                        const client = new ExchangeClient({ transport: this.transport, wallet: privateKeyToAccount(authority.privateKey),
+                            nonceManager: (signer) => this.store.nonce(signer, action.id) });
+                        const options = { signal, vaultAddress: authority.vaultAddress, expiresAfter: action.expiresAt };
+                        response = payload.kind === "submit" ? await client.order({ orders: payload.orders, grouping: payload.grouping, builder: payload.builder }, options)
+                            : await client.cancel({ cancels: payload.cancels }, options);
+                    }
+                    catch (error) {
+                        if (error instanceof ApiRequestError)
+                            response = error.response;
+                        else
+                            uncertain = true;
+                    }
+                    const outcomes = uncertain ? unknownViews(views, "Submission outcome is unknown after transport/signing interruption. Do not resubmit; reconcile this request_id.") : responseViews(payload.kind, response, views);
+                    const unknown = outcomes.some((view) => view.commandStatus === "unknown");
+                    await this.store.outcome(action.id, unknown ? "unknown" : "done", outcomes, "exchange_response");
+                    stop = unknown || outcomes.some((view) => view.commandStatus === "rejected");
+                }
+                return this.result(captured);
+            });
+        };
+        return this.trackAgent(agentId, () => options.locked ? run() : this.lock(agentId, run));
+    }
+    async result(request) {
+        const results = (await this.store.allItems(request.id)).map(({ view }) => JSON.parse(view));
+        const warnings = [];
+        if (request.kind === "cancel_all")
+            warnings.push("Cancel-all targets only the original captured main-DEX perpetual orders, including any protective TP/SL. It does not sweep new orders or close positions.");
+        if (results.some((view) => view.kind === "take_profit" || view.kind === "stop_loss"))
+            warnings.push("TP/SL uses fixed-size reduce-only triggers. Native attached TP/SL activates on full parent fill; manually canceling a partially filled parent also cancels its attached protection. Inspect every leg; a rejected leg can leave exposure unprotected.");
+        if (results.some((view) => view.filledSize && view.size && compare(view.filledSize, view.size) < 0))
+            warnings.push("Only part of the requested size was filled. filledSize is the executed quantity; a filled receipt does not imply the whole requested size traded. IOC remainders do not rest.");
+        if (results.some((view) => view.commandStatus === "unknown"))
+            warnings.push("Unknown is not failure. Reconcile using get_order_request/get_order; never retry with a new request_id.");
+        return { operationId: request.id, requestId: request.requestKey, kind: request.kind, results, uncertain: results.some((view) => view.commandStatus === "unknown"), warnings };
+    }
+    async reconcile(request, signal) {
+        for (const action of await this.store.actions(request.id)) {
+            if (action.state === "prepared" || action.state === "not_sent")
+                continue;
+            const items = await this.store.items(action.id);
+            const views = [];
+            for (const item of items) {
+                const view = JSON.parse(item.view);
+                if (!active(view)) {
+                    views.push(view);
+                    continue;
+                }
+                try {
+                    const oid = view.exchangeOid ? exchangeOid(view.exchangeOid) : view.cloid;
+                    if (!oid) {
+                        views.push(view);
+                        continue;
+                    }
+                    views.push(reconciledView(view, await this.info.orderStatus({ user: request.account, oid }, signal)));
+                }
+                catch {
+                    views.push({ ...view, updatedAt: Date.now(), error: "Order reconciliation unavailable; previous state retained." });
+                }
+            }
+            await this.store.outcome(action.id, views.some((view) => view.commandStatus === "unknown") ? "unknown" : "done", views, "reconciliation");
+        }
+    }
+    request(userId, agentId, key, cancellation) {
+        this.admit();
+        this.requestKey(key);
+        return this.trackAgent(agentId, async () => {
+            const account = await this.account(userId, agentId);
+            const request = await this.store.request(agentId, key);
+            if (!request || request.account !== account)
+                throw new HyperliquidError("Order request not found", 404);
+            return this.lock(request.id, async () => { await this.reconcile(request, this.signal(cancellation)); return this.result(request); });
+        });
+    }
+    list(userId, agentId, input, cancellation) {
+        this.admit();
+        return this.track((async () => {
+            const account = await this.account(userId, agentId);
+            const source = input.source ?? "open", limit = input.limit ?? 50, offset = input.offset ?? 0;
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100 || !Number.isInteger(offset) || offset < 0 || offset > 100000)
+                throw new HyperliquidError("Invalid pagination.");
+            let items;
+            if (source === "local") {
+                items = (await this.store.local(agentId, account)).map(({ view }) => JSON.parse(view));
+            }
+            else if (source === "open")
+                items = (await this.info.frontendOpenOrders({ user: account, dex: "" }, this.signal(cancellation))).filter((order) => isPerpetual(order.coin)).map((order) => liveView(order));
+            else
+                throw new HyperliquidError("Invalid order source.");
+            items = items.filter((item) => (!input.symbol || item.symbol === input.symbol) && (!input.status || item.orderStatus === input.status));
+            return { items: items.slice(offset, offset + limit), nextOffset: offset + limit < items.length ? offset + limit : null, source, observedAt: Date.now(),
+                coverage: source === "open" ? "Current main-DEX perpetual open orders, including externally placed orders. Pagination is over a changing live snapshot." : "Locally recorded submissions from the latest 500 requests only; not full exchange history. States may lag; get_order refreshes a selected order." };
+        })());
+    }
+    get(userId, agentId, id, includeEvents = false, cancellation) {
+        this.admit();
+        return this.trackAgent(agentId, async () => {
+            const account = await this.account(userId, agentId);
+            const found = await this.store.find(agentId, account, id);
+            if (found && found.request.account !== account)
+                throw new HyperliquidError("Order not found", 404);
+            if (found) {
+                return this.lock(found.request.id, async () => {
+                    await this.reconcile(found.request, this.signal(cancellation));
+                    const updated = await this.store.find(agentId, account, found.item.id);
+                    return { order: updated ? JSON.parse(updated.item.view) : null, events: includeEvents ? await this.store.events(found.item.id) : [], error: null, observedAt: Date.now() };
+                });
+            }
+            const oid = /^0x[0-9a-fA-F]{32}$/.test(id) ? id : exchangeOid(id);
+            const response = await this.info.orderStatus({ user: account, oid }, this.signal(cancellation));
+            if (response.status !== "order")
+                return { order: null, events: [], error: "Order not found; absence is not proof of rejection, fill, or cancellation.", observedAt: Date.now() };
+            if (!isPerpetual(response.order.order.coin))
+                throw new HyperliquidError("Only main-DEX perpetual orders are supported.");
+            return { order: liveView(response.order.order, response.order.status, response.order.statusTimestamp), events: [], error: null, observedAt: Date.now() };
+        });
+    }
+}

package/dist/hyperliquid/orders/order-store.js

@@ -0,0 +1,134 @@
+import { and, asc, desc, eq, inArray, or } from "drizzle-orm";
+import { randomUUID } from "node:crypto";
+import { assertAgentExecutable } from "../../agents/agent-enablement.js";
+import { hvExchangeNonces, hvOrderActions, hvOrderEvents, hvOrderItems, hvOrderRequests } from "../../db/order-schema.js";
+import { applicationDatabase } from "../../db/shared-database.js";
+import { HyperliquidError } from "../errors.js";
+import { canonical } from "../../canonical.js";
+import { hvOrderRequestProvenance } from "../../db/order-provenance-schema.js";
+import { assertActiveActor } from "../../memory/operations.js";
+export { canonical } from "../../canonical.js";
+export function active(view) {
+    return view.commandStatus === "unknown" || ["open", "waitingForFill", "waitingForTrigger", "triggered"].includes(view.orderStatus);
+}
+export class OrderStore {
+    database;
+    notifications;
+    db;
+    constructor(database) {
+        this.database = database;
+        this.db = applicationDatabase(database);
+    }
+    request(agentId, key) { return this.db.select().from(hvOrderRequests).where(and(eq(hvOrderRequests.agentId, agentId), eq(hvOrderRequests.requestKey, key))).get(); }
+    actions(id) { return this.db.select().from(hvOrderActions).where(eq(hvOrderActions.requestId, id)).orderBy(asc(hvOrderActions.ordinal)).all(); }
+    items(actionId) { return this.db.select().from(hvOrderItems).where(eq(hvOrderItems.actionId, actionId)).orderBy(asc(hvOrderItems.ordinal)).all(); }
+    async allItems(requestId) { return (await Promise.all((await this.actions(requestId)).map((action) => this.items(action.id)))).flat(); }
+    async prepare(agentId, account, key, kind, input, actions, origin) {
+        return this.database.appTransaction(async (db, tx) => {
+            const existing = await db.select().from(hvOrderRequests).where(and(eq(hvOrderRequests.agentId, agentId), eq(hvOrderRequests.requestKey, key))).get();
+            if (existing) {
+                this.matches(existing, account, kind, input);
+                return existing;
+            }
+            const now = Date.now();
+            const row = { id: randomUUID(), agentId, account, requestKey: key, kind, input: canonical(input), createdAt: now };
+            await db.insert(hvOrderRequests).values(row).run();
+            if (origin) {
+                if (origin.agentId !== agentId || !origin.subagentId || origin.conversationId === null || origin.toolTaskId === null)
+                    throw new HyperliquidError("Invalid execution provenance", 403);
+                await assertActiveActor(tx, origin);
+                await db.insert(hvOrderRequestProvenance).values({ requestId: row.id, agentId, producerSubagentId: origin.subagentId, sourceRunId: origin.runId, conversationId: origin.conversationId, toolTaskId: origin.toolTaskId }).run();
+            }
+            for (const [ordinal, action] of actions.entries()) {
+                const actionId = randomUUID();
+                await db.insert(hvOrderActions).values({ id: actionId, requestId: row.id, ordinal, payload: JSON.stringify(action.payload), state: "prepared", expiresAt: now + 60_000, updatedAt: now }).run();
+                for (const [index, view] of action.items.entries()) {
+                    await db.insert(hvOrderItems).values({ id: view.id, actionId, ordinal: index, symbol: view.symbol, cloid: view.cloid, oid: view.exchangeOid, active: 0, view: JSON.stringify(view), updatedAt: now }).run();
+                    await db.insert(hvOrderEvents).values({ itemId: view.id, source: "intent", time: now, data: JSON.stringify(view) }).run();
+                }
+            }
+            return row;
+        });
+    }
+    matches(row, account, kind, input) {
+        if (row.account !== account || row.kind !== kind || row.input !== canonical(input))
+            throw new HyperliquidError("This request_id was already used with different arguments or an account assignment.", 409);
+    }
+    async begin(action, modelAgentId) {
+        return this.database.appTransaction(async (db, tx) => {
+            if (modelAgentId)
+                await assertAgentExecutable(tx, modelAgentId);
+            const now = Date.now();
+            const rows = await db.update(hvOrderActions).set({ state: "submitting", updatedAt: now })
+                .where(and(eq(hvOrderActions.id, action.id), eq(hvOrderActions.state, "prepared"))).returning().all();
+            if (!rows.length)
+                return false;
+            for (const item of await db.select().from(hvOrderItems).where(eq(hvOrderItems.actionId, action.id)).all()) {
+                const view = { ...JSON.parse(item.view), commandStatus: "unknown", orderStatus: "unknown", updatedAt: now, error: "Submission started; venue outcome not yet committed." };
+                await db.update(hvOrderItems).set({ active: 1, view: JSON.stringify(view), updatedAt: now }).where(eq(hvOrderItems.id, item.id)).run();
+                await db.insert(hvOrderEvents).values({ itemId: item.id, source: "submission_intent", time: now, data: JSON.stringify(view) }).run();
+            }
+            return true;
+        });
+    }
+    async hasUncertain(account) {
+        const row = await this.db.select({ id: hvOrderActions.id }).from(hvOrderActions).innerJoin(hvOrderRequests, eq(hvOrderRequests.id, hvOrderActions.requestId))
+            .where(and(eq(hvOrderRequests.account, account), or(eq(hvOrderActions.state, "unknown"), eq(hvOrderActions.state, "submitting")))).get();
+        return Boolean(row);
+    }
+    async outcome(actionId, state, views, source) {
+        const agentId = await this.database.appTransaction(async (db, tx) => {
+            await db.update(hvOrderActions).set({ state, updatedAt: Date.now() }).where(eq(hvOrderActions.id, actionId)).run();
+            for (const view of views) {
+                const previous = await db.select().from(hvOrderItems).where(eq(hvOrderItems.id, view.id)).get();
+                if (!previous || previous.actionId !== actionId)
+                    throw new Error("Order item identity changed");
+                const old = JSON.parse(previous.view);
+                await db.update(hvOrderItems).set({ oid: view.exchangeOid, view: JSON.stringify(view), active: active(view) ? 1 : 0, updatedAt: view.updatedAt }).where(eq(hvOrderItems.id, view.id)).run();
+                // Polling timestamps do not produce an unbounded event log of identical states.
+                const comparable = (v) => ({ ...v, updatedAt: 0, source: "", venueTimestamp: null });
+                if (canonical(comparable(old)) !== canonical(comparable(view)))
+                    await db.insert(hvOrderEvents).values({ itemId: view.id, source, time: Date.now(), data: JSON.stringify(view) }).run();
+            }
+            return this.notifications?.orderOutcomeTx(tx, actionId);
+        });
+        if (agentId)
+            this.notifications?.changed(agentId);
+    }
+    async nonce(signer, actionId) {
+        return this.database.appTransaction(async (db) => {
+            signer = signer.toLowerCase();
+            const previous = await db.select().from(hvExchangeNonces).where(eq(hvExchangeNonces.signer, signer)).get();
+            const nonce = Math.max(Date.now(), (previous?.nonce ?? 0) + 1);
+            await db.insert(hvExchangeNonces).values({ signer, nonce }).onConflictDoUpdate({ target: hvExchangeNonces.signer, set: { nonce } }).run();
+            if (actionId)
+                await db.update(hvOrderActions).set({ nonce }).where(eq(hvOrderActions.id, actionId)).run();
+            return nonce;
+        });
+    }
+    async recover() {
+        for (const action of await this.db.select().from(hvOrderActions).where(eq(hvOrderActions.state, "submitting")).all()) {
+            const views = (await this.items(action.id)).map(({ view }) => ({ ...JSON.parse(view), commandStatus: "unknown", orderStatus: "unknown", source: "restart", updatedAt: Date.now(), error: "Process stopped during submission. Reconciliation required; do not resubmit." }));
+            await this.outcome(action.id, "unknown", views, "restart");
+        }
+    }
+    async pendingRequests(limit = 20) {
+        const rows = await this.db.select({ request: hvOrderRequests }).from(hvOrderRequests)
+            .innerJoin(hvOrderActions, eq(hvOrderActions.requestId, hvOrderRequests.id))
+            .innerJoin(hvOrderItems, eq(hvOrderItems.actionId, hvOrderActions.id))
+            .where(eq(hvOrderItems.active, 1)).orderBy(asc(hvOrderItems.updatedAt)).limit(limit).all();
+        return [...new Map(rows.map(({ request }) => [request.id, request])).values()];
+    }
+    async local(agentId, account) {
+        // Bounded local history scan. Live open orders are queried separately.
+        const requests = await this.db.select().from(hvOrderRequests).where(and(eq(hvOrderRequests.agentId, agentId), eq(hvOrderRequests.account, account), inArray(hvOrderRequests.kind, ["submit", "close_position"]))).orderBy(desc(hvOrderRequests.createdAt)).limit(500).all();
+        return (await Promise.all(requests.map((request) => this.allItems(request.id)))).flat();
+    }
+    async find(agentId, account, id) {
+        const rows = await this.db.select({ item: hvOrderItems, request: hvOrderRequests }).from(hvOrderItems)
+            .innerJoin(hvOrderActions, eq(hvOrderActions.id, hvOrderItems.actionId)).innerJoin(hvOrderRequests, eq(hvOrderRequests.id, hvOrderActions.requestId))
+            .where(and(eq(hvOrderRequests.agentId, agentId), eq(hvOrderRequests.account, account), or(eq(hvOrderItems.id, id), eq(hvOrderItems.cloid, id), eq(hvOrderItems.oid, id)))).orderBy(desc(hvOrderRequests.createdAt)).get();
+        return rows;
+    }
+    events(id) { return this.db.select({ id: hvOrderEvents.id, source: hvOrderEvents.source, time: hvOrderEvents.time, data: hvOrderEvents.data }).from(hvOrderEvents).where(eq(hvOrderEvents.itemId, id)).orderBy(desc(hvOrderEvents.id)).limit(100).all(); }
+}

package/dist/hyperliquid/orders/order-tools.js

@@ -0,0 +1,40 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-durable";
+import { OrderInputSchema, OrderSize, OrderPrice, Decimal, CancelAllSchema, CancelSchema, GetResultSchema, GetSchema, ListResultSchema, ListSchema, OperationSchema, RequestId, SubmitSchema } from "./order-contracts.js";
+import { assertStringAmounts } from "./order-prepare.js";
+import { assertEntryStyle } from "./trade-planning.js";
+/** Both model and nested/code-mode callers get the same typed, bounded value. */
+export function toolResult(value) {
+    return { output: [{ type: "text", text: JSON.stringify(value) }], structuredOutput: value };
+}
+export function createOrderTools(service, userId, agentId) {
+    return [
+        defineTool({ name: "prepare_protected_entry", description: "Read-only exact protected-entry planner for your own size and TP/SL levels, using a current string-valued quote and exchange precision. Read list_instruments size/price rules before calculating amounts. entry_style must be \"guarded_ioc\" (market-like entry with a 0.5% guarded IOC limit; omit limit_price) or \"limit\" (GTC with an explicit limit_price), never \"market\". Returns a short-lived draft of submit_orders.orders, NOT authority, an order, or confirmation that trading is enabled. TP/SL must be explicit prices on the correct side of the entry. Sizing and protection levels are your strategy decisions within this Agent's risk settings; never silently increase size to meet the venue minimum.", parameters: Type.Object({ instrument: Type.String({ maxLength: 32 }), side: Type.Union([Type.Literal("buy"), Type.Literal("sell")]), entry_style: Type.Union([Type.Literal("guarded_ioc"), Type.Literal("limit")], { description: 'Exactly "guarded_ioc" (market-like, 0.5% guarded IOC; omit limit_price) or "limit" (GTC; require limit_price). "market" is NOT a valid planner entry_style.' }), size: OrderSize, limit_price: Type.Optional(OrderPrice), take_profit_price: OrderPrice, stop_loss_price: OrderPrice }, { additionalProperties: false }), structuredOutputSchema: Type.Object({ orders: Type.Array(OrderInputSchema, { maxItems: 1 }), quote: Decimal, quoteSource: Type.String(), observedAt: Type.Integer(), validUntil: Type.Integer(), calculationBasis: Type.String(), warning: Type.String() }), replay: "safe", prepareArguments(args) { assertStringAmounts(args); assertEntryStyle(args && typeof args === "object" ? Reflect.get(args, "entry_style") : undefined); return args; }, execute: async (args, api, context) => toolResult(await service.plan(userId, agentId, args, await service.executionHandle(agentId, api, context), context.abortSignal)) }),
+        defineTool({ name: "prepare_position_protection", description: "Read-only repair planner for an ACTUAL current position, including partial/external exposure. Derives signed size and closing side from this account; you supply explicit exact TP and SL trigger prices on the correct side of the market. No entry, authority or mutation. Inspect get_protection_status first and submit ONLY missing appropriate legs; never duplicate/cancel known live protection blindly. Crossed/unknown levels require review, not automatic flattening.", parameters: Type.Object({ instrument: Type.String({ maxLength: 32 }), take_profit_price: OrderPrice, stop_loss_price: OrderPrice }, { additionalProperties: false }), structuredOutputSchema: Type.Object({ orders: Type.Array(OrderInputSchema, { maxItems: 2 }), quote: Decimal, quoteSource: Type.String(), observedAt: Type.Integer(), validUntil: Type.Integer(), calculationBasis: Type.String(), warning: Type.String() }), replay: "safe", prepareArguments(args) { assertStringAmounts(args); return args; }, execute: async (args, api, context) => toolResult(await service.planProtection(userId, agentId, args, await service.executionHandle(agentId, api, context), context.abortSignal)) }),
+        defineTool({ name: "get_protection_status", description: "Inspect current main-DEX positions and top-level reduce-only TP/SL triggers with individual venue statuses. waitingForFill/native children do not count as active partial-position protection. Snapshot only, no continuous guarantee; missing coverage calls for deliberate repair, not blind duplicate orders, cancel-all or unapproved flattening.", parameters: Type.Object({}, { additionalProperties: false }), structuredOutputSchema: Type.Object({ observedAt: Type.Integer(), positions: Type.Array(Type.Object({ instrument: Type.String(), side: Type.String(), size: Decimal, takeProfitOids: Type.Array(Type.String()), stopLossOids: Type.Array(Type.String()), covered: Type.Boolean(), warning: Type.String() }), { maxItems: 100 }), warning: Type.String() }), replay: "safe", execute: async (_args, _api, context) => toolResult(await service.protection(userId, agentId, context.abortSignal)) }),
+        defineTool({ name: "submit_orders", description: "Place real main-DEX perpetual orders on this Agent's assigned account. The only host-enforced rules are this Agent's risk settings (trading enabled, allowed instruments, order/total notional caps); strategy, protection and sizing are yours within them. Always pair new entries with TP and SL protection (attached native TP/SL, or standalone reduce-only triggers). A direct/manual operator request does not require consulting memories or creating a decision publication; omit decision_ref when no decision memory actually motivates the order. For memory-based decisions, record_trade_decision and decision_ref are optional rationale/audit aids, never execution prerequisites or authority. Do not attach unrelated or previously blocked/skipped decisions merely to populate decision_ref. Host-recorded Agent/worker provenance does not depend on a memory ref. Exact decimal-string size/prices; size is base-asset quantity. Read list_instruments sizeDecimals/sizeStep and price precision rules before calculating amounts. Hyperliquid main-DEX perps have a $10 minimum order notional (size × price), plus symbol-specific size/tick precision. Do not silently increase size to meet the minimum or bypass reduce-only constraints; report exchange rejections/exceptions. Limit GTC/IOC/ALO, market entries (0.5% guarded IOC), attached native TP/SL (one each), and standalone reduce-only TP/SL. Attached SL is market-on-trigger; triggers without a limit use a 10% guard. Persisted request_id deduplicates retries; never use a new ID to retry unknown outcomes. Inspect every result/leg; accepted does not mean filled or protected.",
+            parameters: SubmitSchema, structuredOutputSchema: OperationSchema, replay: "safe", executionMode: "sequential",
+            prepareArguments(args) { assertStringAmounts(args); return args; },
+            execute: async (args, api, context) => toolResult(await service.submit(userId, agentId, args, context.abortSignal, await service.executionHandle(agentId, api, context))), }),
+        defineTool({ name: "cancel_orders", description: "Cancel explicit exchange OIDs on this Agent's own main-DEX perpetual account. Each item requires symbol and oid (decimal string). May remove protective TP/SL; does not close positions. Use the same request_id for retries; inspect per-item results and unknown outcomes.",
+            parameters: CancelSchema, structuredOutputSchema: OperationSchema, replay: "safe", executionMode: "sequential",
+            prepareArguments(args) { assertStringAmounts(args); return args; },
+            execute: async (args, api, context) => toolResult(await service.cancel(userId, agentId, args, context.abortSignal, await service.executionHandle(agentId, api, context))), }),
+        defineTool({ name: "cancel_all_orders", description: "Cancel one captured set of current main-DEX perpetual orders, optionally for one symbol. Includes protective stops/TP; does not close positions. Replaying the same request_id never captures newly created orders. Maximum 100 targets; use explicit batches beyond that.",
+            parameters: CancelAllSchema, structuredOutputSchema: OperationSchema, replay: "safe", executionMode: "sequential",
+            execute: async (args, api, context) => toolResult(await service.cancelAll(userId, agentId, args, context.abortSignal, await service.executionHandle(agentId, api, context))),
+        }),
+        defineTool({ name: "list_orders", description: "List this Agent's main-DEX perpetual orders. source=open (default) reads live exchange orders, including external orders. source=local reads the latest 500 recorded submission requests, not full exchange history; states can lag. Optional symbol/status and bounded limit/offset. Use get_order for fresh status of a selected local order.",
+            parameters: ListSchema, structuredOutputSchema: ListResultSchema, replay: "safe",
+            execute: async (args, _api, context) => toolResult(await service.list(userId, agentId, args, context.abortSignal)),
+        }),
+        defineTool({ name: "get_order", description: "Query this Agent's main-DEX perpetual order by local ID, decimal-string exchange OID, or 128-bit hex CLOID. Reconciles local requests before returning. Optional include_events returns up to 100 latest local events, newest first. Not-found does not prove rejection, fill, or cancellation.",
+            parameters: GetSchema, structuredOutputSchema: GetResultSchema, replay: "safe",
+            execute: async (args, _api, context) => toolResult(await service.get(userId, agentId, args.order_id, args.include_events, context.abortSignal)),
+        }),
+        defineTool({ name: "get_order_request", description: "Read and reconcile one existing exchange submit/cancel request, including per-leg outcomes and uncertainty. Supply the original request_id used with submit_orders, cancel_orders or cancel_all_orders (returned as requestId in their results or local list_orders items). Worker inbox request IDs, assignment/run IDs and exchange order OIDs are NOT order request IDs. To discover local submissions, use list_orders with source=local; do not guess an ID or query this tool just because an assignment contains a request ID. Never sends/retries exchange actions. Use after timeouts/restarts instead of issuing a new request_id. Not-found does not prove rejection, cancellation or absence of exchange orders.",
+            parameters: Type.Object({ request_id: { ...RequestId, description: "Original request_id of a submit_orders, cancel_orders or cancel_all_orders call; returned as requestId. Never a worker inbox request ID, assignment/run ID or exchange order OID." } }, { additionalProperties: false }), structuredOutputSchema: OperationSchema, replay: "safe",
+            execute: async (args, _api, context) => toolResult(await service.request(userId, agentId, args.request_id, context.abortSignal)),
+        }),
+    ];
+}