@onride/agent 0.0.0-stage → 0.5.1-rc.0

package/dist/agent/ledger.js

@@ -0,0 +1,137 @@
+import { AgentError } from "./contracts.js";
+import { D, } from "./domain.js";
+function trade(l, q, px) {
+    const old = D(l.quantity), delta = D(q), price = D(px);
+    if (delta.isZero())
+        return;
+    const closes = !old.isZero() && old.isPositive() !== delta.isPositive();
+    const closed = closes ? D.min(old.abs(), delta.abs()) : D(0);
+    const avg = old.isZero() ? D(0) : D(l.cost).div(old);
+    l.realized = D(l.realized)
+        .plus(closed.times(price.minus(avg)).times(old.isPositive() ? 1 : -1))
+        .toString();
+    const next = old.plus(delta);
+    l.cost = (closes
+        ? next.isZero()
+            ? D(0)
+            : next.isPositive() === old.isPositive()
+                ? next.times(avg)
+                : next.times(price)
+        : D(l.cost).plus(delta.times(price))).toString();
+    l.quantity = next.toString();
+}
+function lot(p, sleeveId, key) {
+    const s = p.sleeves.find((x) => x.copy_id === sleeveId);
+    if (!s)
+        throw new AgentError("LEDGER_OWNER", "Unknown sleeve owner.");
+    const intent = s.intents[key], existing = s.lots[key];
+    if (existing)
+        return existing;
+    if (!intent)
+        throw new AgentError("LEDGER_OWNER", "An owned intent is required.");
+    return (s.lots[key] = {
+        key,
+        asset: intent.asset,
+        market: intent.market,
+        quantity: "0",
+        cost: "0",
+        realized: "0",
+        fees: "0",
+        funding: "0",
+    });
+}
+// Internal crosses settle virtual sleeve transfers at the same observed mark.
+// Their quantities sum to zero, and their combined PnL is conserved.
+export function internalCross(p, key, price) {
+    const deltas = p.sleeves.map((s) => ({
+        id: s.copy_id,
+        q: D(s.intents[key]?.quantity ?? 0).minus(s.lots[key]?.quantity ?? 0),
+    }));
+    const buys = deltas.filter((x) => x.q.gt(0)), sells = deltas.filter((x) => x.q.lt(0));
+    for (const buy of buys)
+        for (const sell of sells) {
+            const q = D.min(buy.q, sell.q.neg());
+            if (q.isZero())
+                continue;
+            trade(lot(p, buy.id, key), q.toString(), price);
+            trade(lot(p, sell.id, key), q.neg().toString(), price);
+            buy.q = buy.q.minus(q);
+            sell.q = sell.q.plus(q);
+        }
+    return Object.fromEntries(deltas.filter((x) => !x.q.isZero()).map((x) => [x.id, x.q.toString()]));
+}
+export function applyFill(p, fill) {
+    if (p.seen_fills.includes(fill.id))
+        return;
+    const e = p.executions.find((x) => x.task_id === fill.task_id && x.key === fill.key);
+    if (!e)
+        throw new AgentError("UNOWNED_FILL", "Exchange fill has no owned execution.");
+    const entries = Object.entries(e.allocations).filter(([, q]) => !D(q).isZero()), total = entries.reduce((n, [, q]) => n.plus(q), D(0));
+    const q = D(fill.quantity);
+    if (total.isZero() ||
+        q.isZero() ||
+        q.isPositive() !== total.isPositive() ||
+        entries.some(([, allocation]) => D(allocation).isPositive() !== q.isPositive()) ||
+        q.abs().gt(total.abs()))
+        throw new AgentError("FILL_MISMATCH", "Fill exceeds the unsettled owned execution.");
+    let remaining = q, feeRemaining = D(fill.fee_usdc);
+    // Keep virtual ownership on the venue's quantity grid. A repeating decimal
+    // share otherwise leaves the owned sum unequal to an exact exchange position.
+    const decimals = Math.max(p.snapshot?.quantity_decimals?.[fill.key] ?? 8, q.decimalPlaces(), ...entries.map(([, allocation]) => D(allocation).decimalPlaces()));
+    for (let i = 0; i < entries.length; i++) {
+        const [sid, remainingQ] = entries[i], last = i === entries.length - 1;
+        const laterCapacity = entries
+            .slice(i + 1)
+            .reduce((n, [, allocation]) => n.plus(D(allocation).abs()), D(0));
+        const proportional = q
+            .abs()
+            .times(D(remainingQ).abs())
+            .div(total.abs())
+            .toDecimalPlaces(decimals, 1);
+        const minimum = D.max(0, remaining.abs().minus(laterCapacity));
+        const part = last
+            ? remaining
+            : D.min(D(remainingQ).abs(), D.max(proportional, minimum)).times(q.isPositive() ? 1 : -1);
+        const fee = last ? feeRemaining : D(fill.fee_usdc).times(part.div(q));
+        const l = lot(p, sid, fill.key);
+        trade(l, part.toString(), fill.price);
+        l.fees = D(l.fees).plus(fee).toString();
+        e.allocations[sid] = D(remainingQ).minus(part).toString();
+        remaining = remaining.minus(part);
+        feeRemaining = feeRemaining.minus(fee);
+    }
+    p.seen_fills.push(fill.id);
+}
+export function applyFunding(p, event, holdings) {
+    if (p.seen_funding.includes(event.id))
+        return;
+    const total = Object.values(holdings).reduce((n, q) => n.plus(q), D(0));
+    if (total.isZero() && !D(event.amount_usdc).isZero())
+        throw new AgentError("FUNDING_MISMATCH", "Funding has no verified historical owned position.");
+    const entries = Object.entries(holdings).filter(([, q]) => !D(q).isZero());
+    let remaining = D(event.amount_usdc);
+    for (let i = 0; i < entries.length; i++) {
+        const [sid, q] = entries[i];
+        const share = i === entries.length - 1
+            ? remaining
+            : D(event.amount_usdc).times(D(q).div(total));
+        const l = lot(p, sid, event.key);
+        l.funding = D(l.funding).plus(share).toString();
+        remaining = remaining.minus(share);
+    }
+    p.seen_funding.push(event.id);
+}
+export function reconcileQuantities(p) {
+    if (!p.snapshot?.coverage_complete)
+        return false;
+    const keys = new Set([
+        ...Object.keys(p.snapshot.positions),
+        ...p.sleeves.flatMap((s) => Object.keys(s.lots)),
+    ]);
+    for (const key of keys) {
+        const actual = p.sleeves.reduce((n, s) => n.plus(s.lots[key]?.quantity ?? 0), D(0));
+        if (!actual.eq(p.snapshot.positions[key] ?? 0))
+            return false;
+    }
+    return true;
+}

package/dist/agent/mcp.js

@@ -0,0 +1,245 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { accountCopiesInput } from "../account_reads.js";
+import { claudeCardDomain } from "./card_hosts.js";
+import { AgentError, failure, inputs, mutationTools, stateTools, publicResult, output, TOOL_NAMES, } from "./contracts.js";
+export const RESOURCE_URI = "ui://ride/agent-v7-confirmation.html";
+export function registerAppAccountRead(server, invoke) {
+    server.registerTool("get_my_copies", {
+        title: "Your Ride App copies and positions",
+        description: "Read the signed-in account's existing Ride App Perps and prediction copies and current copied positions. Successful reads verify login, including empty accounts. App copies remain managed in Ride.",
+        inputSchema: accountCopiesInput,
+        outputSchema: output,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (args, extra) => {
+        try {
+            const value = publicResult(await invoke(args, extra));
+            return {
+                content: [{ type: "text", text: JSON.stringify(value) }],
+                structuredContent: value,
+                isError: !!value.error,
+            };
+        }
+        catch (e) {
+            const value = failure(e);
+            return {
+                content: [{ type: "text", text: JSON.stringify(value) }],
+                structuredContent: value,
+                isError: true,
+            };
+        }
+    });
+}
+export function registerAgentTools(server, invoke, readOnly = false, confirmation) {
+    const confirmationOrigin = confirmation
+        ? new URL(confirmation.base).origin
+        : undefined;
+    server.server.registerCapabilities({
+        extensions: {
+            "io.modelcontextprotocol/ui": {
+                mimeTypes: ["text/html;profile=mcp-app"],
+            },
+        },
+    });
+    for (const resourceUri of [
+        RESOURCE_URI,
+        "ui://ride/agent-v6-confirmation.html",
+        "ui://ride/agent-v5-confirmation.html",
+        "ui://ride/agent-v4-confirmation.html",
+        "ui://ride/agent-v3.html",
+    ])
+        server.registerResource("ride-agent-cards", resourceUri, {
+            mimeType: "text/html;profile=mcp-app",
+            _meta: { "openai/widgetPrefersBorder": true },
+        }, async () => ({
+            contents: [
+                {
+                    uri: resourceUri,
+                    mimeType: "text/html;profile=mcp-app",
+                    text: (await readFile(fileURLToPath(new URL("../../public/agent.html", import.meta.url)), "utf8")).replace("/*HOST_CONFIG*/{}", JSON.stringify({
+                        confirmation_origin: confirmationOrigin,
+                    }).replaceAll("<", "\\u003c")),
+                    _meta: {
+                        ui: {
+                            prefersBorder: true,
+                            ...(confirmationOrigin
+                                ? {
+                                    csp: { frameDomains: [confirmationOrigin] },
+                                    domain: claudeCardDomain(confirmation.base),
+                                }
+                                : {}),
+                        },
+                        ...(confirmationOrigin
+                            ? {
+                                "openai/widgetCSP": { frame_domains: [confirmationOrigin] },
+                            }
+                            : {}),
+                    },
+                },
+            ],
+        }));
+    if (confirmation && !readOnly)
+        server.registerTool("show_confirmation_card", {
+            title: "Ride confirmation card",
+            description: "Show an owned frozen proposal in a human confirmation card. mode:demo renders a 0-USDC interface test without account changes or any execution. This tool never confirms, signs or submits a proposal.",
+            inputSchema: z
+                .object({
+                mode: z.enum(["demo", "proposal"]),
+                proposal_id: z
+                    .string()
+                    .regex(/^proposal_[a-zA-Z0-9_-]{8,100}$/)
+                    .optional(),
+            })
+                .strict(),
+            outputSchema: output,
+            annotations: {
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+            _meta: {
+                ui: { resourceUri: RESOURCE_URI },
+                "openai/outputTemplate": RESOURCE_URI,
+            },
+        }, async ({ mode, proposal_id }, extra) => {
+            try {
+                if (!extra.authInfo?.scopes?.includes("ride:read"))
+                    throw new AgentError("SCOPE_REQUIRED", "Missing ride:read permission.", false, 403);
+                let value;
+                if (mode === "demo")
+                    value = {
+                        version: "3",
+                        status: "ok",
+                        data: {
+                            confirmation_demo: true,
+                            proposal: {
+                                id: "proposal_card_demo_00000000",
+                                action: "demo",
+                                status: "requires_confirmation",
+                                arguments: { amount_usdc: "0", execution: "disabled" },
+                                preview: {},
+                                expires_at: Date.now() + 300_000,
+                                confirmation_url: new URL("/agent/card-demo", confirmation.base).href,
+                            },
+                        },
+                        warnings: [],
+                        as_of: new Date().toISOString(),
+                    };
+                else {
+                    if (!proposal_id)
+                        throw new AgentError("NOT_FOUND", "Choose an owned proposal to display.", false, 400);
+                    value = publicResult(await confirmation.readProposal(proposal_id, extra));
+                    value.data.confirmation_card = true;
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify(value) }],
+                    structuredContent: value,
+                    isError: !!value.error,
+                };
+            }
+            catch (e) {
+                const value = failure(e);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(value) }],
+                    structuredContent: value,
+                    isError: true,
+                };
+            }
+        });
+    for (const name of TOOL_NAMES) {
+        if (readOnly &&
+            (mutationTools.has(name) ||
+                (stateTools.has(name) && name !== "recommend_traders")))
+            continue;
+        server.registerTool(name, {
+            title: name.replaceAll("_", " "),
+            description: description(name),
+            inputSchema: inputs[name],
+            outputSchema: output,
+            annotations: {
+                readOnlyHint: !mutationTools.has(name) && !stateTools.has(name),
+                destructiveHint: mutationTools.has(name),
+                idempotentHint: !stateTools.has(name) && !mutationTools.has(name),
+                openWorldHint: true,
+            },
+            ...(mutationTools.has(name) || name === "prepare_deposit"
+                ? {
+                    _meta: {
+                        ui: { resourceUri: RESOURCE_URI },
+                        "openai/outputTemplate": RESOURCE_URI,
+                    },
+                }
+                : {}),
+        }, async (args, extra) => {
+            try {
+                const value = publicResult(await invoke(name, args, extra));
+                return {
+                    content: [{ type: "text", text: JSON.stringify(value) }],
+                    structuredContent: value,
+                    isError: !!value.error,
+                };
+            }
+            catch (e) {
+                const value = failure(e);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(value) }],
+                    structuredContent: value,
+                    isError: true,
+                };
+            }
+        });
+    }
+}
+export async function invokeAgent(url, token, name, args) {
+    if (!token)
+        throw new AgentError("AUTH_REQUIRED", "Log in to Ride first.", false, 401);
+    const response = await fetch(new URL(`/agent/v1/${name}`, url), {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify(args),
+        signal: AbortSignal.timeout(25000),
+        redirect: "error",
+    });
+    const body = await response.json();
+    if (!response.ok && !body.error)
+        throw new AgentError("BACKEND_UNAVAILABLE", "Ride Agent request failed.", response.status >= 500, response.status);
+    return publicResult(body);
+}
+function description(name) {
+    const descriptions = {
+        get_preferences: "Read saved/partial answers. Start in chat with budget and risk preference only; ask only returned missing questions. Preserve earlier answers. Numeric risk presets are suggestions requiring final confirmation, not user consent.",
+        prepare_deposit: "Prepare an exact-amount deposit activation for an owned funding request. Returns a human Ride confirmation URL; no funds move until the user confirms and signs there.",
+        get_deposit_options: "Read currently supported funding routes. No funds are transferred.",
+        get_deposit_address: "Create an owned funding request and verified receiving address/QR for the chosen supported network. No transfer or signing is performed.",
+        check_deposit_status: "Read an account-owned deposit request. Wallet receipt, bridge settlement and copy-ready funds remain separate.",
+        get_daily_checkin: "Offer one portfolio performance review per local day and timezone; does not send a message or notification.",
+        update_portfolio: "Propose changing the owned portfolio loss threshold; requires Ride confirmation and cannot unlatch a triggered stop.",
+        set_preferences: "Save only supplied user answers, including partial budget/risk answers. Defaults and numeric risk suggestions are marked separately; do not ask for optional settings up front. Existing portfolios are unchanged.",
+        recalculate_plan: "Refresh a saved preview or validate edited trader allocations against fresh eligibility, budget and leverage limits. Returns a new frozen plan; no execution.",
+        get_performance: "Read persisted accounting snapshots for daily, weekly or inception performance. Historical sleeves remain after replacement; incomplete periods return null profit.",
+        diagnose_copy: "Read an owned copy's source fills, attributed follower receipts and event-time execution decisions for the same window (maximum 31 days). Missing evidence and counterfactual profit remain unavailable.",
+        get_notification_preferences: "Read daily Ride App digest preferences and actual push registration readiness. Server monitoring is independent of this chat.",
+        set_notification_preferences: "Save explicitly requested daily Ride App digest opt-in, local time and IANA timezone. Critical risk alerts remain enabled; this does not authorize trading.",
+        recommend_traders: "After get_preferences collect only missing budget/risk in conversation. Show recommended_portfolio and candidate_table as two compact chat tables. Assets default unrestricted, markets default both (either allowed); count is automatically feasible up to four unless user chooses 1–8 or trader_ids. Selections persist across edits; selection:system clears the pinned selection. Show candidates even if plan fails; no funding required. Defaults and risk parameters are suggestions for final Ride confirmation.",
+        browse_traders: "Page or sort the entire current verified candidate snapshot by score/drawdown/ROI; missing metrics sort last. Default five, request limit:10 for ten more, pass next_cursor with the same sort. compare_ids compares named public IDs. Does not replace the plan, allocations or selections. Disclose source pool limits, metric periods and incomparable/missing data. Refresh expired snapshots through recommend_traders.",
+        get_trader_profile: "Read verified source statistics and actual Copy Score components using a public trader ID.",
+        start_copy: "Create an expiring start proposal. Human confirmation in Ride is required unless bounded Ride authority applies.",
+        get_portfolio: "Read the signed-in account, per-market account balances, Agent portfolio and existing Ride App copies and positions. Account funds and copy allocation remaining are distinct; unavailable modules are null, not zero. An empty Agent portfolio still confirms login. App copies remain separately managed in Ride. Missing values are null.",
+        update_copy: "Propose amount, leverage cap, sleeve loss trigger or an explicit eligible replacement. Released funds must be verified.",
+        stop_copy: "Propose wind_down (default) or close_now. Removing a hedge can increase net exposure and is risk checked.",
+        review_portfolio: "Read factual portfolio observations and suggested changes. Suggestions do not execute.",
+        get_updates: "Read persisted monitoring and execution events using an opaque account-bound cursor. This call does not schedule monitoring.",
+        close_position: "Propose closing one owned aggregate position. All affected sleeves are included.",
+    };
+    return descriptions[name];
+}

package/dist/agent/order_rules.js

@@ -0,0 +1,61 @@
+import { D } from "./domain.js";
+// Hyperliquid's protocol opening-order floor, not a collateral allocation floor.
+// https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/error-responses
+export const HYPERLIQUID_MIN_OPEN_NOTIONAL_USDC = "10";
+/** Check the actual net opening leg, including a separate opening leg on flips.
+ * Hyperliquid reduce-only reductions/closes retain their dust-close exemption.
+ * Never round up an order or fall back to a trader's historical minimum.
+ */
+export function checkPerpsOrder(snapshot, key, targetQuantity) {
+    const unavailable = {
+        ok: false,
+        code: "VENUE_RULES_UNAVAILABLE",
+        message: "Verified per-asset venue price, quantity precision and opening-order minimum are required.",
+    };
+    try {
+        const price = D(snapshot.prices[key] ?? "NaN");
+        const decimals = snapshot.quantity_decimals?.[key];
+        const target = D(targetQuantity);
+        const current = D(snapshot.positions[key] ?? "0");
+        if (!price.isFinite() ||
+            price.lte(0) ||
+            decimals == null ||
+            !Number.isInteger(decimals) ||
+            decimals < 0 ||
+            decimals > 8 ||
+            !target.isFinite() ||
+            !current.isFinite())
+            return unavailable;
+        if (!target.eq(target.toDecimalPlaces(decimals)))
+            return {
+                ok: false,
+                code: "INVALID_ORDER_QUANTITY",
+                message: "Target quantity exceeds the venue's current size precision; it must not be rounded up.",
+            };
+        if (target.eq(current))
+            return { ok: true };
+        const flip = !current.isZero() &&
+            !target.isZero() &&
+            current.isPositive() !== target.isPositive();
+        const reduction = !flip && target.abs().lte(current.abs());
+        if (reduction)
+            return { ok: true };
+        const minimum = D(snapshot.min_notionals[key] ?? "NaN");
+        if (!minimum.isFinite() || minimum.lte(0))
+            return unavailable;
+        const size = flip ? target.abs() : target.minus(current).abs();
+        const notional = size.times(price);
+        if (notional.lt(minimum))
+            return {
+                ok: false,
+                code: "BELOW_MINIMUM_NOTIONAL",
+                message: "Sized Perps opening order is below the venue minimum; skipped without increasing quantity or leverage.",
+                order_notional_usdc: notional.toString(),
+                minimum_notional_usdc: minimum.toString(),
+            };
+        return { ok: true };
+    }
+    catch {
+        return unavailable;
+    }
+}

package/dist/agent/perps_account.js

@@ -0,0 +1,41 @@
+import { AgentError } from "./contracts.js";
+import { D, cash } from "./domain.js";
+export function perpsAccountMode(value) {
+    if (value && typeof value === "object") {
+        const row = value;
+        return perpsAccountMode(row.abstraction ?? row.userAbstraction ?? row.mode ?? row.response);
+    }
+    const mode = typeof value === "string"
+        ? value.replace(/[^a-z0-9]/gi, "").toLowerCase()
+        : "";
+    if (["disabled", "default"].includes(mode))
+        return "standard";
+    if (["unifiedaccount", "unified", "u"].includes(mode))
+        return "unified";
+    return "unsupported";
+}
+// Unified accounts report the single USDC balance and all holds in spot state.
+// Per-DEX equity must never be added to this balance.
+export function unifiedUsdc(state) {
+    try {
+        if (!Array.isArray(state?.balances))
+            throw Error();
+        const rows = state.balances.filter((row) => row.coin === "USDC");
+        if (rows.length !== 1 || rows[0].token !== 0)
+            throw Error();
+        const { total, hold } = rows[0];
+        if (typeof total !== "string" || typeof hold !== "string")
+            throw Error();
+        const equity = D(total), reserve = D(hold);
+        if (!equity.isFinite() ||
+            !reserve.isFinite() ||
+            equity.lt(0) ||
+            reserve.lt(0) ||
+            reserve.gt(equity))
+            throw Error();
+        return { equity: cash(equity), available: cash(equity.minus(reserve)) };
+    }
+    catch {
+        throw new AgentError("ACCOUNT_STALE", "Unified account USDC balance or holds could not be verified.", true);
+    }
+}