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

package/dist/agent/contracts.js

@@ -0,0 +1,276 @@
+import { z } from "zod";
+// JSON-safe decimals: six-place USDC precision; no floating point accounting.
+export const money = z.union([
+    z.string().regex(/^(0|[1-9]\d{0,11})(\.\d{1,6})?$/),
+    z
+        .number()
+        .finite()
+        .nonnegative()
+        .max(999999999999)
+        .refine((v) => /^\d+(\.\d{1,6})?$/.test(String(v))),
+]);
+export const positiveMoney = money.refine((v) => Number(v) > 0, "Amount must be positive");
+export const id = z.string().regex(/^[a-zA-Z0-9_-]{8,100}$/);
+export const market = z.enum(["perps", "prediction", "both"]);
+export const copySettings = {
+    copy_mode: z.enum(["ride_recommends", "fixed", "proportional"]).optional(),
+    fixed_margin_usdc: positiveMoney.optional(),
+    proportional_multiplier: z.number().positive().max(10).optional(),
+    loss_policy: z.enum(["exit", "pause_then_exit"]).optional(),
+    emergency_exit_pct: z.number().min(1).max(100).optional(),
+};
+export const preferences = z
+    .object({
+    budget_usdc: positiveMoney,
+    loss_trigger_pct: z.number().min(1).max(100),
+    market: market.default("perps"),
+    assets: z
+        .array(z.string().regex(/^[A-Za-z][A-Za-z0-9:_-]{0,30}$/))
+        .max(20)
+        .default([]),
+    allow_altcoins: z.boolean().default(true),
+    portfolio_kind: z.enum(["single", "basket"]).optional(),
+    basket_size: z.number().int().min(1).max(8).optional(),
+    risk_tolerance: z.enum(["low", "medium", "high"]).optional(),
+    asset_category: z.enum(["crypto", "rwa", "any"]).optional(),
+    ...copySettings,
+})
+    .strict();
+const portfolioInput = z.object({ portfolio_id: id.optional() }).strict();
+// Partial answers must not silently acquire defaults before the user chooses.
+export const preferenceAnswers = z
+    .object({
+    ...preferences.shape,
+    market: market,
+    assets: preferences.shape.assets.unwrap(),
+    allow_altcoins: z.boolean(),
+})
+    .partial()
+    .strict();
+export const inputs = {
+    get_preferences: z.object({}).strict(),
+    prepare_deposit: z
+        .object({ deposit_id: id, amount_usdc: positiveMoney })
+        .strict(),
+    get_deposit_options: z.object({}).strict(),
+    get_deposit_address: z
+        .object({
+        market: z.enum(["perps", "prediction"]),
+        asset: z.enum(["USDC", "USDT"]),
+        network: z.enum(["Arbitrum", "Base", "Ethereum", "Polygon"]),
+        amount_usdc: positiveMoney.optional(),
+    })
+        .strict(),
+    check_deposit_status: z.object({ deposit_id: id }).strict(),
+    get_daily_checkin: z
+        .object({ timezone: z.string().max(80).optional() })
+        .strict(),
+    update_portfolio: z
+        .object({ portfolio_id: id, loss_trigger_pct: z.number().min(1).max(100) })
+        .strict(),
+    set_preferences: preferenceAnswers,
+    recommend_traders: z
+        .object({
+        preferences: preferenceAnswers.optional(),
+        batch_action: z.enum(["first", "next", "saved"]).optional(),
+        batch_index: z.number().int().min(0).max(1).optional(),
+        trader_ids: z
+            .array(id)
+            .min(1)
+            .max(8)
+            .refine((v) => new Set(v).size === v.length, "Select each trader only once")
+            .optional(),
+        selection: z.enum(["system"]).optional(),
+    })
+        .strict(),
+    browse_traders: z
+        .object({
+        sort_by: z.enum(["score", "drawdown", "roi"]).default("score"),
+        direction: z.enum(["asc", "desc"]).optional(),
+        limit: z.number().int().min(1).max(20).default(5),
+        cursor: z.string().max(1024).optional(),
+        compare_ids: z.array(id).min(1).max(8).optional(),
+    })
+        .strict(),
+    get_trader_profile: z
+        .object({
+        trader_id: id,
+        market: z.enum(["perps", "prediction"]).optional(),
+    })
+        .strict(),
+    start_copy: z
+        .object({
+        plan_id: id,
+        compatibility_ack: z.string().length(64).optional(),
+    })
+        .strict(),
+    recalculate_plan: z
+        .object({
+        plan_id: id,
+        preferences: preferenceAnswers.optional(),
+        allocations: z
+            .array(z
+            .object({
+            trader_id: id,
+            amount_usdc: positiveMoney,
+            leverage_cap: z.number().int().min(1).max(40).nullable().optional(),
+            stop_loss_pct: z.number().min(1).max(100).optional(),
+            ...copySettings,
+        })
+            .strict())
+            .min(1)
+            .max(8)
+            .optional(),
+    })
+        .strict(),
+    get_performance: z
+        .object({
+        portfolio_id: id.optional(),
+        period: z.enum(["daily", "weekly", "inception"]).default("weekly"),
+    })
+        .strict(),
+    diagnose_copy: z
+        .object({
+        copy_id: id,
+        start_at: z.number().int().positive(),
+        end_at: z.number().int().positive(),
+    })
+        .strict()
+        .refine((v) => v.end_at > v.start_at && v.end_at - v.start_at <= 31 * 86400_000, "Use a time window of at most 31 days"),
+    get_notification_preferences: z.object({}).strict(),
+    set_notification_preferences: z
+        .object({
+        daily_digest: z.boolean(),
+        local_time: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/),
+        timezone: z
+            .string()
+            .max(80)
+            .refine((v) => {
+            try {
+                new Intl.DateTimeFormat("en", { timeZone: v });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }, "Use an IANA timezone"),
+    })
+        .strict(),
+    get_portfolio: portfolioInput,
+    update_copy: z
+        .object({
+        copy_id: id,
+        amount_usdc: positiveMoney.optional(),
+        leverage_cap: z.number().int().min(1).max(40).nullable().optional(),
+        stop_loss_pct: z.number().min(1).max(100).optional(),
+        replacement_trader_id: id.optional(),
+        resume_new_trades: z.boolean().optional(),
+        ...copySettings,
+    })
+        .strict()
+        .refine((v) => Object.keys(v).length > 1, "Specify a change"),
+    stop_copy: z
+        .object({
+        copy_id: id,
+        mode: z.enum(["wind_down", "close_now"]).default("wind_down"),
+    })
+        .strict(),
+    review_portfolio: portfolioInput,
+    get_updates: z
+        .object({
+        cursor: z.string().max(256).optional(),
+        limit: z.number().int().min(1).max(100).default(20),
+    })
+        .strict(),
+    close_position: z.object({ position_id: id }).strict(),
+};
+export const mutationTools = new Set([
+    "start_copy",
+    "update_portfolio",
+    "update_copy",
+    "stop_copy",
+    "close_position",
+]);
+// State edits are distinct from proposals that can move funds.
+export const stateTools = new Set([
+    "prepare_deposit",
+    "set_preferences",
+    "recalculate_plan",
+    "recommend_traders",
+    "set_notification_preferences",
+    "get_deposit_address",
+    "get_daily_checkin",
+]);
+export const TOOL_NAMES = Object.keys(inputs);
+export const output = z
+    .object({
+    version: z.literal("3"),
+    status: z.enum([
+        "ok",
+        "requires_preferences",
+        "empty",
+        "requires_confirmation",
+        "queued",
+        "executing",
+        "partially_filled",
+        "settling",
+        "completed",
+        "failed",
+        "uncertain",
+        "stale",
+    ]),
+    data: z.record(z.string(), z.unknown()),
+    warnings: z.array(z.string()),
+    as_of: z.string(),
+    error: z
+        .object({ code: z.string(), message: z.string(), retryable: z.boolean() })
+        .strict()
+        .optional(),
+})
+    .strict();
+export class AgentError extends Error {
+    code;
+    retryable;
+    httpStatus;
+    constructor(code, message, retryable = false, httpStatus = 409) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.httpStatus = httpStatus;
+    }
+}
+export function result(data, status = "ok", warnings = []) {
+    return {
+        version: "3",
+        status,
+        data,
+        warnings,
+        as_of: new Date().toISOString(),
+    };
+}
+export function failure(error) {
+    const e = error instanceof AgentError
+        ? error
+        : error instanceof z.ZodError
+            ? new AgentError("INVALID_INPUT", "Input does not match the Ride tool contract.", false, 400)
+            : new AgentError("INTERNAL_ERROR", "Ride could not complete this request.", true, 500);
+    return {
+        ...result({}, "failed"),
+        error: { code: e.code, message: e.message, retryable: e.retryable },
+    };
+}
+// No raw upstream objects cross the MCP boundary. Reject accidental addresses
+// anywhere, including explanations and nested arrays, instead of leaking them.
+export function publicResult(value) {
+    const checked = output.parse(value);
+    const scan = structuredClone(checked);
+    const own = scan.data.deposit;
+    if (own &&
+        /^deposit_[a-f0-9]{32}$/.test(own.id) &&
+        ["wallet", "polymarket_bridge"].includes(own.provider) &&
+        /^0x[a-fA-F0-9]{40}$/.test(own.address))
+        own.address = "owned deposit address";
+    if (/0x[a-fA-F0-9]{40}\b/.test(JSON.stringify(scan)))
+        throw new AgentError("PRIVATE_DATA", "Response contained a private trading identity.", false, 502);
+    return checked;
+}

package/dist/agent/conversational.js

@@ -0,0 +1,86 @@
+import { AgentError } from "./contracts.js";
+import { D, cash, fingerprint, } from "./domain.js";
+export function validateCopySettings(a) {
+    if (a.copy_mode === "fixed" &&
+        (!a.fixed_margin_usdc || D(a.fixed_margin_usdc).gt(a.amount_usdc)))
+        throw new AgentError("INVALID_COPY_MODE", "Fixed margin must be positive and within the trader allocation.", false, 400);
+    if (a.loss_policy === "pause_then_exit" &&
+        (a.emergency_exit_pct ?? 70) <= a.stop_loss_pct)
+        throw new AgentError("INVALID_LOSS_POLICY", "Emergency exit must be above the pause threshold.", false, 400);
+    if (a.trader.market === "prediction" && a.copy_mode === "fixed")
+        throw new AgentError("INVALID_COPY_MODE", "Fixed margin is a Perps mode; prediction copies use proportional exposure.", false, 400);
+}
+export function compatibility(plan) {
+    const allocations = plan.allocations, total = allocations.reduce((n, a) => n.plus(a.amount_usdc), D(0));
+    const pairs = [];
+    for (let i = 0; i < allocations.length; i++)
+        for (let j = i + 1; j < allocations.length; j++) {
+            const a = allocations[i].trader, b = allocations[j].trader;
+            const assets = a.assets.filter((x) => b.assets.includes(x));
+            const sameDirection = a.direction !== "mixed" && a.direction === b.direction;
+            const holdingOverlap = a.median_hold_hours == null || b.median_hold_hours == null
+                ? null
+                : Math.max(a.median_hold_hours, b.median_hold_hours) /
+                    Math.max(1, Math.min(a.median_hold_hours, b.median_hold_hours)) <
+                    2;
+            const flags = [
+                assets.length && sameDirection ? "same_asset_and_direction" : null,
+                holdingOverlap && a.style === b.style
+                    ? "similar_holding_and_style"
+                    : null,
+            ].filter(Boolean);
+            pairs.push({
+                traders: [a.id, b.id],
+                shared_assets: assets,
+                same_direction: sameDirection,
+                similar_holding_period: holdingOverlap,
+                flags,
+            });
+        }
+    const warnings = pairs.reduce((n, p) => n + p.flags.length, 0);
+    return {
+        fingerprint: fingerprint(allocations),
+        warnings,
+        pairs,
+        capital_weights: allocations.map((a) => ({
+            trader_id: a.trader.id,
+            weight_pct: total.isZero()
+                ? null
+                : cash(D(a.amount_usdc).div(total).times(100)),
+        })),
+        portfolio_historical_drawdown_pct: null,
+        historical_loss_correlation: null,
+        missing_evidence: "Historical overlap of losses is unavailable. Shared assets and current direction do not prove future correlation.",
+    };
+}
+export function alternatives(plan, candidates) {
+    const current = compatibility(plan).warnings;
+    const suggestions = [];
+    for (const out of plan.allocations)
+        for (const candidate of candidates) {
+            if (plan.allocations.some((a) => a.trader.id === candidate.id))
+                continue;
+            const trial = {
+                ...plan,
+                allocations: plan.allocations.map((a) => a === out ? { ...a, trader: candidate } : a),
+            };
+            const improvement = current - compatibility(trial).warnings;
+            if (improvement > 0)
+                suggestions.push({
+                    outgoing_trader_id: out.trader.id,
+                    incoming_trader: candidate,
+                    fewer_flags: improvement,
+                });
+        }
+    return suggestions
+        .sort((a, b) => b.fewer_flags - a.fewer_flags ||
+        b.incoming_trader.score - a.incoming_trader.score)
+        .slice(0, 4);
+}
+export function basketLimits(p) {
+    return p.portfolio_kind === "single"
+        ? [1, 1]
+        : p.portfolio_kind === "basket"
+            ? [2, 8]
+            : [3, 6];
+}