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

package/dist/agent/prediction_history.js

@@ -0,0 +1,336 @@
+import { unzipSync, strFromU8 } from "fflate";
+import { D, now } from "./domain.js";
+import { Gate, } from "./prediction_equity_history.js";
+const DAY = 86_400_000;
+const BASIS = "polymarket_economic_nav_1m_daily_cashflow_adjusted_v1";
+const validNumber = (x) => typeof x === "number" && Number.isFinite(x);
+function requireData(ok, reason) {
+    if (!ok)
+        throw new Error(reason);
+}
+function sameWallet(a, b) {
+    return typeof a === "string" && a.toLowerCase() === b.toLowerCase();
+}
+export function accountingEquity(zip) {
+    const files = unzipSync(zip, {
+        filter: (f) => {
+            if (f.name !== "equity.csv")
+                return false;
+            requireData(f.originalSize > 0 && f.originalSize <= 4096, "invalid_equity_snapshot");
+            return true;
+        },
+    });
+    requireData(files["equity.csv"], "invalid_equity_snapshot");
+    const lines = strFromU8(files["equity.csv"]).trim().split(/\r?\n/);
+    requireData(lines.length === 2 &&
+        lines[0] === "cashBalance,positionsValue,equity,valuationTime", "invalid_equity_snapshot");
+    const fields = lines[1].split(",");
+    requireData(fields.length === 4 &&
+        fields.slice(0, 3).every((x) => /^\d+(\.\d+)?$/.test(x)), "invalid_equity_snapshot");
+    const [cash, positions, equity] = fields.slice(0, 3).map((x) => D(x));
+    const at = Date.parse(fields[3]);
+    requireData(Number.isFinite(at) &&
+        equity.gt(0) &&
+        cash.plus(positions).minus(equity).abs().lte("0.000002"), "invalid_equity_snapshot");
+    return { equity, at };
+}
+// The PnL endpoint currently leaves cumulative funding null. Its separately
+// paginated DEPOSIT/WITHDRAWAL ledger supplies the missing capital, from genesis.
+// PnL alone (or PnL / current balance) is never treated as an equity return.
+export function predictionMetrics(wallet, series, flows, snapshot, at) {
+    requireData(sameWallet(series?.proxy_wallet, wallet) &&
+        series.interval === "1m" &&
+        series.fidelity === "1d" &&
+        series.source_fidelity === "1d", "invalid_history_identity");
+    const points = series.points;
+    requireData(Array.isArray(points) && points.length >= 29 && points.length <= 33, "insufficient_history");
+    requireData(snapshot.at <= at + 60_000 && at - snapshot.at <= 5 * 60_000, "stale_equity_snapshot");
+    let priorTime = 0, priorBlock = 0;
+    for (const p of points) {
+        requireData(Number.isSafeInteger(p.timestamp) &&
+            p.timestamp > priorTime &&
+            Number.isSafeInteger(p.source_block) &&
+            p.source_block > priorBlock &&
+            p.source_block > 0, "invalid_or_carried_history_observation");
+        requireData(!priorTime || (p.timestamp - priorTime) * 1000 <= 26 * 3_600_000, "history_gap");
+        requireData(validNumber(p.economic_pnl), "missing_economic_pnl");
+        // Cross-check the source composition; do not substitute zero for an atom.
+        requireData(validNumber(p.position_pnl) &&
+            validNumber(p.wallet_income) &&
+            D(p.position_pnl)
+                .plus(p.wallet_income)
+                .minus(p.economic_pnl)
+                .abs()
+                .lte("0.000002"), "invalid_pnl_composition");
+        priorTime = p.timestamp;
+        priorBlock = p.source_block;
+    }
+    const first = points[0], last = points.at(-1);
+    requireData(snapshot.at >= last.timestamp * 1000, "equity_snapshot_precedes_history");
+    requireData(last.timestamp * 1000 <= at + 60_000 &&
+        at - last.timestamp * 1000 <= 36 * 3_600_000 &&
+        (last.timestamp - first.timestamp) * 1000 >= 28 * DAY &&
+        at - first.timestamp * 1000 <= 32 * DAY, "stale_or_short_history");
+    const ordered = [...flows].sort((a, b) => a.timestamp - b.timestamp);
+    requireData(ordered.length > 0 &&
+        ordered.some((f) => f.type === "DEPOSIT" &&
+            f.timestamp <= first.timestamp &&
+            f.usdc_size > 0), "missing_initial_capital");
+    for (const f of ordered) {
+        requireData(sameWallet(f.proxy_wallet, wallet) &&
+            (f.type === "DEPOSIT" || f.type === "WITHDRAWAL") &&
+            Number.isSafeInteger(f.timestamp) &&
+            f.timestamp > 0 &&
+            f.timestamp * 1000 <= at + 60_000 &&
+            validNumber(f.usdc_size) &&
+            f.usdc_size >= 0, "invalid_funding_ledger");
+    }
+    let index = 0, deposits = D(0), withdrawals = D(0), nav = D(1), peak = D(1), drawdown = D(0);
+    let previous = null;
+    for (const p of points) {
+        while (index < ordered.length && ordered[index].timestamp <= p.timestamp) {
+            const f = ordered[index++];
+            if (f.type === "DEPOSIT")
+                deposits = deposits.plus(f.usdc_size);
+            else
+                withdrawals = withdrawals.plus(f.usdc_size);
+        }
+        for (const [field, computed] of [
+            ["deposits", deposits],
+            ["withdrawals", withdrawals],
+            ["cashflow_net", deposits.minus(withdrawals)],
+        ]) {
+            requireData(p[field] == null ||
+                (validNumber(p[field]) &&
+                    D(p[field]).minus(computed).abs().lte("0.01")), "conflicting_funding_sources");
+        }
+        const equity = deposits.minus(withdrawals).plus(p.economic_pnl);
+        requireData(equity.gt(0), "nonpositive_historical_equity");
+        if (previous) {
+            // Daily source observations cannot place returns around intraday flows.
+            // Gross deposits go at the start and withdrawals at the end of the day;
+            // retain this timing estimate explicitly in the metric provenance.
+            nav = nav
+                .times(equity.plus(withdrawals.minus(previous.withdrawals)))
+                .div(previous.equity.plus(deposits.minus(previous.deposits)));
+            peak = D.max(peak, nav);
+            drawdown = D.max(drawdown, D(1).minus(nav.div(peak)));
+        }
+        previous = { equity, deposits, withdrawals };
+    }
+    // Independent current equity catches absent/partial ledgers and unaccounted
+    // transfers. Daily marks can move since the last PnL point: allow at most 1%
+    // reconciliation difference, disclose it, and reject larger discrepancies.
+    let expectedCurrent = previous.equity;
+    for (const f of ordered
+        .slice(index)
+        .filter((f) => f.timestamp * 1000 <= snapshot.at))
+        expectedCurrent = expectedCurrent.plus(f.type === "DEPOSIT" ? f.usdc_size : -f.usdc_size);
+    const difference = expectedCurrent
+        .minus(snapshot.equity)
+        .abs()
+        .div(snapshot.equity)
+        .times(100);
+    requireData(difference.lte(1), "equity_reconciliation_failed");
+    return {
+        source_roi_pct: nav.minus(1).times(100).toNumber(),
+        source_drawdown_pct: drawdown.times(100).toNumber(),
+        metric_window: {
+            start_at: first.timestamp * 1000,
+            end_at: last.timestamp * 1000,
+            basis: BASIS,
+        },
+        metric_provenance: {
+            source: "polymarket_data_v2_and_accounting_snapshot",
+            sampling: "daily",
+            estimated: true,
+            cashflow_adjusted: true,
+            flow_timing: "deposits_at_start_withdrawals_at_end",
+            reconciliation_difference_pct: difference.toNumber(),
+        },
+    };
+}
+export class PredictionHistory {
+    equity;
+    cache = new Map();
+    pending = new Map();
+    reconstructed = new Map();
+    hydrated = new Map();
+    reconstructing = new Map();
+    retries = new Map();
+    jobs = new Gate(2);
+    constructor(equity) {
+        this.equity = equity;
+    }
+    async metrics(wallet) {
+        if (!this.equity)
+            return this.nativeMetrics(wallet);
+        const key = this.equity.key(wallet);
+        let hydration = this.hydrated.get(key);
+        if (!hydration) {
+            hydration = this.equity
+                .read(key)
+                .then((record) => {
+                if (record && this.validRecord(record))
+                    this.reconstructed.set(key, record);
+            })
+                .catch(() => { });
+            this.hydrated.set(key, hydration);
+        }
+        await hydration;
+        let record = this.reconstructed.get(key);
+        if (record && !this.validRecord(record)) {
+            this.reconstructed.delete(key);
+            record = undefined;
+        }
+        if (record && record.refresh_at > now())
+            return record.metrics;
+        const retry = this.retries.get(key);
+        if (!this.reconstructing.has(key) && (!retry || retry.at <= now())) {
+            const job = this.jobs
+                .run(async () => {
+                try {
+                    const result = await this.equity.loader.load(wallet);
+                    const record = {
+                        version: 2,
+                        computed_at: now(),
+                        refresh_at: now() + 3600_000,
+                        ...result,
+                    };
+                    if (!this.validRecord(record))
+                        throw new Error("invalid_reconstructed_metrics");
+                    this.reconstructed.set(key, record);
+                    await this.equity.write(key, record);
+                    this.retries.delete(key);
+                }
+                catch (e) {
+                    this.retries.set(key, {
+                        at: now() + 5 * 60_000,
+                        reason: e instanceof Error && /^[a-z_]+$/.test(e.message)
+                            ? e.message
+                            : "equity_reconstruction_unavailable",
+                    });
+                }
+            })
+                .finally(() => this.reconstructing.delete(key));
+            this.reconstructing.set(key, job);
+        }
+        if (record)
+            return record.metrics;
+        // Keep the existing verified path available while bounded reconstruction
+        // warms. Missing risk data never becomes zero or a smaller risk threshold.
+        const fallback = await this.nativeMetrics(wallet);
+        const completed = this.reconstructed.get(key);
+        if (completed && this.validRecord(completed))
+            return completed.metrics;
+        if (fallback.metric_window)
+            return fallback;
+        return {
+            ...fallback,
+            metric_unavailable_reason: this.retries.get(key)?.reason ??
+                "equity_history_reconstruction_pending",
+        };
+    }
+    validRecord(r) {
+        const m = r.metrics, window = m?.metric_window;
+        return (r.version === 2 &&
+            Number.isFinite(r.computed_at) &&
+            r.computed_at <= now() + 60_000 &&
+            Number.isFinite(r.refresh_at) &&
+            window?.basis === "polygon_inventory_nav_1m_daily_v2" &&
+            window.end_at <= now() + 60_000 &&
+            now() - window.end_at < 36 * 3600_000 &&
+            window.end_at - window.start_at >= 28 * DAY &&
+            validNumber(m.source_drawdown_pct) &&
+            m.source_drawdown_pct >= 0 &&
+            m.source_drawdown_pct <= 100 &&
+            validNumber(m.source_roi_pct) &&
+            m.source_roi_pct >= -100 &&
+            m.metric_provenance?.source ===
+                "polygon_transfers_and_polymarket_historical_marks");
+    }
+    async nativeMetrics(wallet) {
+        const key = wallet.toLowerCase(), cached = this.cache.get(key);
+        if (cached && cached.until > now())
+            return cached.value;
+        const existing = this.pending.get(key);
+        if (existing)
+            return existing;
+        const promise = this.load(key)
+            .catch((e) => ({
+            source_roi_pct: null,
+            source_drawdown_pct: null,
+            metric_unavailable_reason: e instanceof Error && /^[a-z_]+$/.test(e.message)
+                ? e.message
+                : "history_source_unavailable",
+        }))
+            .then((value) => {
+            this.cache.set(key, {
+                until: value.metric_window
+                    ? Math.min(now() + 10 * 60_000, value.metric_window.end_at + 36 * 3_600_000)
+                    : now() + 60_000,
+                value,
+            });
+            // This is a bounded display cache, never an execution source snapshot.
+            if (this.cache.size > 100)
+                this.cache.delete(this.cache.keys().next().value);
+            return value;
+        })
+            .finally(() => this.pending.delete(key));
+        this.pending.set(key, promise);
+        return promise;
+    }
+    async load(wallet) {
+        const signal = AbortSignal.timeout(6000);
+        const read = async (path, params, zip = false) => {
+            const url = new URL(path, "https://data-api.polymarket.com");
+            for (const [k, v] of Object.entries(params))
+                url.searchParams.set(k, v);
+            const r = await fetch(url, { signal, redirect: "error" });
+            requireData(r.ok && r.body, "history_source_unavailable");
+            let size = 0;
+            const chunks = [];
+            for await (const chunk of r.body) {
+                size += chunk.length;
+                requireData(size <= 4 * 1024 * 1024, "history_response_too_large");
+                chunks.push(chunk);
+            }
+            const body = Buffer.concat(chunks);
+            return zip ? accountingEquity(body) : JSON.parse(body.toString("utf8"));
+        };
+        const [pnl, snapshot] = await Promise.all([
+            read("/v2/user-pnl", { user: wallet, interval: "1m", fidelity: "1d" }),
+            read("/v1/accounting/snapshot", { user: wallet }, true),
+        ]);
+        const flows = [], seen = new Set();
+        let cursor = null;
+        for (let page = 0; page < 10; page++) {
+            const response = await read("/v2/activity", {
+                user: wallet,
+                start: "1",
+                end: String(Math.ceil(snapshot.at / 1000)),
+                type: "DEPOSIT,WITHDRAWAL",
+                exclude_deposits_withdrawals: "false",
+                limit: "1000",
+                sort_direction: "ASC",
+                ...(cursor ? { cursor } : {}),
+            });
+            requireData(Array.isArray(response.data) &&
+                response.data.length <= 1000 &&
+                typeof response.pagination?.has_more === "boolean", "incomplete_funding_ledger");
+            flows.push(...response.data);
+            const next = response.pagination.next_cursor;
+            if (!response.pagination.has_more) {
+                requireData(next === null, "incomplete_funding_ledger");
+                return predictionMetrics(wallet, pnl.data, flows, snapshot, now());
+            }
+            requireData(typeof next === "string" &&
+                next.length > 0 &&
+                !seen.has(next) &&
+                response.data.length > 0, "incomplete_funding_ledger");
+            seen.add(next);
+            cursor = next;
+        }
+        throw new Error("funding_ledger_page_limit");
+    }
+}

package/dist/agent/preferences.js

@@ -0,0 +1,114 @@
+import { preferences } from "./contracts.js";
+// Product planning presets, not inferred user consent or guaranteed loss caps.
+export const suggestedLoss = { low: 10, medium: 20, high: 30 };
+const questions = {
+    budget_usdc: { question: "这次计划投入多少 USDC？", unit: "USDC" },
+    risk_tolerance: {
+        question: "风险偏好是稳健、平衡，还是进取？",
+        options: ["low", "medium", "high"],
+    },
+    fixed_margin_usdc: {
+        question: "你选择了固定保证金模式，每次新开仓使用多少 USDC？",
+        unit: "USDC",
+    },
+};
+// Never reinterpret an already approved legacy portfolio's asset semantics.
+export function normalizedAssetPreferences(value, version = 2) {
+    return version !== 2 && ["any", "rwa"].includes(value.asset_category ?? "")
+        ? { ...value, assets: [], allow_altcoins: true }
+        : value;
+}
+export function preferenceCollection(s, answers = {}) {
+    const previous = s.preferences ??
+        s.plans.at(-1)?.preferences ??
+        s.portfolios.find((p) => p.state !== "closed")?.preferences ??
+        {};
+    const previousVersion = s.preferences
+        ? s.preference_asset_filter_version
+        : (s.plans.at(-1)?.asset_filter_version ??
+            s.portfolios.find((p) => p.state !== "closed")?.asset_filter_version);
+    const defaults = {
+        market: "both",
+        assets: [],
+        allow_altcoins: true,
+        asset_category: "any",
+        copy_mode: "ride_recommends",
+    };
+    const saved = {
+        ...defaults,
+        ...normalizedAssetPreferences(previous, previousVersion ?? 1),
+        ...(s.preference_draft ?? {}),
+        ...answers,
+    };
+    const sources = {
+        market: "default",
+        assets: "default",
+        allow_altcoins: "default",
+        asset_category: "default",
+        copy_mode: "default",
+    };
+    // Existing explicit numeric risk settings remain explicit, including old plans.
+    for (const key of Object.keys(previous))
+        if (previous[key] != null)
+            sources[key] = "user";
+    Object.assign(sources, s.preference_sources);
+    for (const key of Object.keys(answers))
+        if (answers[key] != null)
+            sources[key] = "user";
+    if (saved.risk_tolerance &&
+        (saved.loss_trigger_pct == null ||
+            sources.loss_trigger_pct === "recommended")) {
+        saved.loss_trigger_pct = suggestedLoss[saved.risk_tolerance];
+        sources.loss_trigger_pct = "recommended";
+    }
+    const missing = [];
+    if (saved.budget_usdc == null)
+        missing.push("budget_usdc");
+    // An existing user-supplied numerical loss constraint is a custom risk answer.
+    if (!saved.risk_tolerance &&
+        !(saved.loss_trigger_pct != null && sources.loss_trigger_pct === "user"))
+        missing.push("risk_tolerance");
+    if (!missing.length &&
+        saved.copy_mode === "fixed" &&
+        saved.fixed_margin_usdc == null)
+        missing.push("fixed_margin_usdc");
+    return {
+        ready: missing.length === 0,
+        answers: saved,
+        sources,
+        missing_fields: missing,
+        questions: missing.map((field) => ({ field, ...questions[field] })),
+        defaults,
+        suggestions: sources.loss_trigger_pct === "recommended"
+            ? {
+                loss_trigger_pct: saved.loss_trigger_pct,
+                source: "Ride planning preset v1",
+                requires_final_confirmation: true,
+                explanation: "建议的组合亏损退出触发值，可修改；是尽力执行的退出触发条件，不是最大亏损保证。",
+            }
+            : null,
+        optional_choices: {
+            market: ["perps", "prediction", "both"],
+            risk_tolerance: ["low", "medium", "high"],
+            asset_category: ["crypto", "rwa", "any"],
+            copy_mode: ["ride_recommends", "fixed", "proportional"],
+        },
+        instruction: missing.length
+            ? "Ask only the returned missing questions in conversation. Save partial user answers. Do not open a full form, ask for trader count or funding, or invent budget or risk preference."
+            : "Recommend now. Disclose defaults and label numeric risk parameters as suggestions for final Ride confirmation. Preserve explicit choices; a budget or preview never authorizes funds or trades.",
+    };
+}
+export function savePreferenceCollection(s, collection) {
+    s.preference_sources = collection.sources;
+    if (collection.ready) {
+        s.preferences = preferences.parse(collection.answers);
+        s.preference_asset_filter_version = 2;
+        s.preference_draft = undefined;
+    }
+    else
+        s.preference_draft = collection.answers;
+}
+export function completePreferences(s, answers = {}) {
+    const collection = preferenceCollection(s, answers);
+    return collection.ready ? preferences.parse(collection.answers) : null;
+}

package/dist/agent/repository.js

@@ -0,0 +1,106 @@
+import pg from "pg";
+import { randomBytes, timingSafeEqual, createHmac } from "node:crypto";
+import { AgentError } from "./contracts.js";
+export const emptyState = () => ({
+    preferences: null,
+    plans: [],
+    portfolios: [],
+    proposals: [],
+    delegation: null,
+    updates: [],
+    checkpoints: [],
+});
+export class PgRepository {
+    pool;
+    constructor(url) {
+        this.pool = new pg.Pool({
+            connectionString: url,
+            max: 10,
+            connectionTimeoutMillis: 5000,
+        });
+    }
+    async migrate() {
+        await this.pool.query(`CREATE TABLE IF NOT EXISTS ride_agent_state (user_id TEXT PRIMARY KEY, state JSONB NOT NULL, updated_at TIMESTAMPTZ NOT NULL DEFAULT now());`);
+    }
+    async transact(user, fn) {
+        const c = await this.pool.connect();
+        try {
+            await c.query("BEGIN");
+            await c.query("SET LOCAL lock_timeout = '5s'");
+            await c.query("SET LOCAL idle_in_transaction_session_timeout = '90s'");
+            await c.query("INSERT INTO ride_agent_state(user_id,state) VALUES($1,$2) ON CONFLICT DO NOTHING", [user, emptyState()]);
+            const r = await c.query("SELECT state FROM ride_agent_state WHERE user_id=$1 FOR UPDATE", [user]);
+            const s = r.rows[0].state;
+            const out = await fn(s);
+            await c.query("UPDATE ride_agent_state SET state=$2, updated_at=now() WHERE user_id=$1", [user, s]);
+            await c.query("COMMIT");
+            return out;
+        }
+        catch (e) {
+            await c.query("ROLLBACK");
+            throw e;
+        }
+        finally {
+            c.release();
+        }
+    }
+    async users() {
+        return (await this.pool.query("SELECT user_id FROM ride_agent_state WHERE EXISTS (SELECT 1 FROM jsonb_array_elements(state->'portfolios') p WHERE p->>'state' <> 'closed') OR EXISTS (SELECT 1 FROM jsonb_array_elements(state->'updates') u WHERE u->>'notification' = 'pending') OR state->'notification_preferences'->>'daily_digest' = 'true'")).rows.map((x) => x.user_id);
+    }
+    async close() {
+        await this.pool.end();
+    }
+}
+// Test-only adapter; production startup requires PostgreSQL.
+export class MemoryRepository {
+    states = new Map();
+    tails = new Map();
+    async transact(user, fn) {
+        const prior = this.tails.get(user) ?? Promise.resolve();
+        const work = prior
+            .catch(() => { })
+            .then(async () => {
+            const s = structuredClone(this.states.get(user) ?? emptyState());
+            const out = await fn(s);
+            this.states.set(user, s);
+            return out;
+        });
+        this.tails.set(user, work);
+        return work;
+    }
+    async users() {
+        return [...this.states.keys()];
+    }
+    async close() { }
+}
+export class Cursor {
+    key;
+    constructor(key) {
+        this.key = key;
+        if (Buffer.byteLength(key) < 32)
+            throw new Error("Cursor signing key requires 32 bytes");
+    }
+    encode(user, at, id) {
+        const data = Buffer.from(JSON.stringify({ u: user, a: at, i: id })).toString("base64url");
+        return `${data}.${this.mac(data)}`;
+    }
+    decode(user, token) {
+        try {
+            const [data, sig] = token.split(".");
+            const a = Buffer.from(sig ?? ""), b = Buffer.from(this.mac(data));
+            if (a.length !== b.length || !timingSafeEqual(a, b))
+                throw 0;
+            const v = JSON.parse(Buffer.from(data, "base64url").toString());
+            if (v.u !== user || !Number.isSafeInteger(v.a) || typeof v.i !== "string")
+                throw 0;
+            return { at: v.a, id: v.i };
+        }
+        catch {
+            throw new AgentError("INVALID_CURSOR", "Cursor is invalid for this account.", false, 400);
+        }
+    }
+    mac(data) {
+        return createHmac("sha256", this.key).update(data).digest("base64url");
+    }
+}
+export const nonce = () => randomBytes(32).toString("base64url");