@coinrithm/mcp-trading 0.7.15 → 0.7.17

package/dist/agent/bench/costs.d.ts

@@ -0,0 +1,28 @@
+/** Fee fraction of the price paid at a 50% PM price (openapi.yaml: ~1.8%). */
+export declare const PM_SYNTHETIC_FEE_RATE_AT_MID = 0.018;
+/** Flat futures taker fee (bps of notional) used for synthesized quotes. */
+export declare const FUTURES_SYNTHETIC_FEE_BPS = 10;
+/** Flat spot taker fee (bps of notional) used for synthesized quotes. */
+export declare const SPOT_SYNTHETIC_FEE_BPS = 10;
+/**
+ * Synthetic PM fee in probability POINTS for an outcome priced at
+ * `probabilityPoints` (0..100). Zero at the extremes, largest at 50.
+ */
+export declare function pmSyntheticFeePoints(probabilityPoints: number): number;
+export interface SyntheticPmQuote {
+    /** Raw chosen-outcome probability in points: the value the floor checks. */
+    entryProbability: number;
+    feePoints: number;
+    /** Fee-inclusive break-even cost in points (entry + fee). */
+    costPoints: number;
+    stakeMusd: number;
+    /** Net shares: stake / (cost / 100). One share pays 1 mUSD on a win. */
+    sharesEstimate: number;
+}
+/**
+ * The PM quote the bench serves for a recorded outcome probability. Returns
+ * undefined for a probability the paper engine could not fill (0, 100, or not
+ * a finite number in range) or a non-positive stake, so the caller reports an
+ * ineligible quote instead of dividing by zero.
+ */
+export declare function synthesizePmQuote(probabilityPoints: number, stakeMusd: number): SyntheticPmQuote | undefined;

package/dist/agent/bench/costs.js

@@ -0,0 +1,60 @@
+// Synthetic execution costs for the bench's replayed quotes.
+//
+// A quote depends on the action the agent proposes (which outcome, which stake,
+// which leverage), so it can never be recorded ahead of time: a cassette only
+// holds the READ inputs of a cycle. On replay the bench therefore synthesizes
+// every quote from recorded evidence (the discover probability of the chosen PM
+// outcome, the recorded market price of a coin) plus the cost model below. Every
+// synthesized quote is counted in the report; it is a fidelity limit, not a
+// silent substitute for the paper engine.
+//
+// What the cost model covers and what it leaves out, stated plainly:
+//   - PM: the published fee SHAPE only. openapi.yaml ("Paper Execution Realism
+//     v1") documents a Polymarket-shaped taker fee of about 1.8% near a 50%
+//     price and about 0 at the extremes. That is modelled as
+//     PM_SYNTHETIC_FEE_RATE_AT_MID * 4p(1-p) of the price paid. The ask spread
+//     and the size-scaled slippage the paper engine adds are NOT modelled, so a
+//     synthesized PM cost is optimistic by an unmeasured amount.
+//   - Futures and spot: a flat taker fee on notional. The paper engine discloses
+//     its own feeBps per quote, which a cassette cannot contain, so the bench
+//     uses the runner's own conservative pre-quote estimate
+//     (CAPITAL_FEE_BUFFER_BPS). Funding, spread and slippage are not modelled.
+import { CAPITAL_FEE_BUFFER_BPS } from "../capitalSizing.js";
+/** Fee fraction of the price paid at a 50% PM price (openapi.yaml: ~1.8%). */
+export const PM_SYNTHETIC_FEE_RATE_AT_MID = 0.018;
+/** Flat futures taker fee (bps of notional) used for synthesized quotes. */
+export const FUTURES_SYNTHETIC_FEE_BPS = CAPITAL_FEE_BUFFER_BPS;
+/** Flat spot taker fee (bps of notional) used for synthesized quotes. */
+export const SPOT_SYNTHETIC_FEE_BPS = CAPITAL_FEE_BUFFER_BPS;
+/**
+ * Synthetic PM fee in probability POINTS for an outcome priced at
+ * `probabilityPoints` (0..100). Zero at the extremes, largest at 50.
+ */
+export function pmSyntheticFeePoints(probabilityPoints) {
+    const p = probabilityPoints / 100;
+    return probabilityPoints * PM_SYNTHETIC_FEE_RATE_AT_MID * 4 * p * (1 - p);
+}
+/**
+ * The PM quote the bench serves for a recorded outcome probability. Returns
+ * undefined for a probability the paper engine could not fill (0, 100, or not
+ * a finite number in range) or a non-positive stake, so the caller reports an
+ * ineligible quote instead of dividing by zero.
+ */
+export function synthesizePmQuote(probabilityPoints, stakeMusd) {
+    if (!Number.isFinite(probabilityPoints) ||
+        probabilityPoints <= 0 ||
+        probabilityPoints >= 100 ||
+        !Number.isFinite(stakeMusd) ||
+        stakeMusd <= 0) {
+        return undefined;
+    }
+    const feePoints = pmSyntheticFeePoints(probabilityPoints);
+    const costPoints = probabilityPoints + feePoints;
+    return {
+        entryProbability: probabilityPoints,
+        feePoints,
+        costPoints,
+        stakeMusd,
+        sharesEstimate: stakeMusd / (costPoints / 100),
+    };
+}

package/dist/agent/bench/labelBuilder.d.ts

@@ -0,0 +1,123 @@
+import { ApiResult } from "../types.js";
+import { Cassette } from "./cassette.js";
+import { LabelFile, PriceBar } from "./labels.js";
+export declare const LABEL_RANGES: readonly [{
+    readonly range: "1D";
+    readonly spanSeconds: 86400;
+    readonly barSeconds: 300;
+}, {
+    readonly range: "1W";
+    readonly spanSeconds: number;
+    readonly barSeconds: 900;
+}, {
+    readonly range: "1M";
+    readonly spanSeconds: number;
+    readonly barSeconds: 3600;
+}, {
+    readonly range: "3M";
+    readonly spanSeconds: number;
+    readonly barSeconds: 14400;
+}];
+export declare const DEFAULT_LABEL_HORIZON_HOURS = 24;
+export type PriceLabelPlan = {
+    status: "ready";
+    range: string;
+    barSeconds: number;
+    fromSec: number;
+    toSec: number;
+} | {
+    status: "not_yet";
+    labelableAfter: string;
+} | {
+    status: "too_old";
+};
+/**
+ * Which candle range can label [asOf, asOf + horizon] right now. The horizon
+ * must have fully elapsed, and the range window (ending now) must still hold
+ * the bar that contains asOf.
+ */
+export declare function planPriceLabels(asOf: string, horizonHours: number, nowMs: number): PriceLabelPlan;
+/** The coins a cassette observed: its recorded GET /api/agent/market/:id reads. */
+export declare function cassetteCoins(cassette: Pick<Cassette, "responses">): Array<{
+    coinId: string;
+    symbol: string;
+}>;
+/**
+ * Bars from a candles response that can matter for [fromSec, toSec]: the bar
+ * containing asOf onward (the scorer itself ignores every bar at or before
+ * asOf) through the last bar that CLOSES by toSec, finite OHLC only, oldest
+ * first. A bar straddling toSec (it may hold prices after the horizon) or
+ * still open when labelling runs is never stored.
+ */
+export declare function priceBarsFor(data: unknown, fromSec: number, toSec: number, barSeconds: number): PriceBar[];
+export type CassetteLabelResult = {
+    id: string;
+    status: "not_yet";
+    labelableAfter: string;
+} | {
+    id: string;
+    status: "too_old";
+} | {
+    id: string;
+    status: "kept";
+} | {
+    id: string;
+    status: "horizon_mismatch";
+    existingHorizonHours: number | null;
+} | {
+    id: string;
+    status: "no_coins";
+} | {
+    id: string;
+    status: "built";
+    file: LabelFile;
+    range: string;
+    symbols: string[];
+    missing: string[];
+};
+/**
+ * Price labels for each cassette. `fetchCandles` is the agent API candles
+ * read; one fetch per coin and range serves every cassette. An existing label
+ * file keeps its PM and funding labels; its prices are replaced only with
+ * `overwrite`. A symbol whose read fails or returns no bar in the window is
+ * reported missing and stays unlabelled.
+ */
+export declare function buildPriceLabels(cassettes: ReadonlyArray<Pick<Cassette, "id" | "asOf" | "responses">>, opts: {
+    fetchCandles: (coinId: string, range: string) => Promise<ApiResult>;
+    horizonHours?: number;
+    nowMs: number;
+    existing?: Record<string, LabelFile>;
+    overwrite?: boolean;
+}): Promise<CassetteLabelResult[]>;
+/** The PM events a cassette discovered (its recorded /pm/discover reads). */
+export declare function cassettePmEvents(cassette: Pick<Cassette, "responses">): Array<{
+    source: string;
+    slug: string;
+}>;
+/**
+ * Pure: settled labels from one public event-detail body, keyed
+ * `source/slug/outcomeExternalMarketId`. Empty unless the platform's own
+ * verdict says the event settles and the outcome has a provider result.
+ */
+export declare function pmVerdictLabels(source: string, slug: string, body: unknown): Record<string, {
+    settled: 0 | 1;
+}>;
+export type CassettePmResult = {
+    id: string;
+    events: number;
+    labelled: number;
+    failed: number;
+    pm: Record<string, {
+        settled: 0 | 1;
+    }>;
+};
+/**
+ * Settled PM labels per cassette from the public event verdict. One read per
+ * event serves every cassette; a failed or unusable read leaves that event
+ * unlabelled and is counted. Existing PM labels are kept unless `overwrite`.
+ */
+export declare function buildPmLabels(cassettes: ReadonlyArray<Pick<Cassette, "id" | "responses">>, opts: {
+    fetchEvent: (source: string, slug: string) => Promise<ApiResult>;
+    existing?: Record<string, LabelFile>;
+    overwrite?: boolean;
+}): Promise<CassettePmResult[]>;

package/dist/agent/bench/labelBuilder.js

@@ -0,0 +1,282 @@
+// Outcome labels for bench cassettes, built from data published AFTER each
+// cassette's asOf (C2 of the item-3 bench plan). Reads only; never writes to
+// the API.
+//
+// Prices: OHLC bars from GET /api/agent/market/:coinId/candles, the same
+// loader and shape as the public /api/coins/:slug/candles (probed live
+// 2026-10-07: range=1D -> 288 five-minute bars {t, o, h, l, c, v}, t = bar
+// open in unix seconds). Candle storage keeps fine bars only briefly (about
+// 24 h of 5-minute bars, 7 days of 15-minute, 30 days of hourly), so the bar
+// size follows the cassette's age: the finest range whose window still covers
+// asOf. A label file has one bar size (barSeconds).
+//
+// PM settlement comes from the platform's own public event verdict (see the
+// PM section below), never a rule rebuilt here; anything short of a settled
+// provider result stays "unlabelled".
+export const LABEL_RANGES = [
+    { range: "1D", spanSeconds: 86_400, barSeconds: 300 },
+    { range: "1W", spanSeconds: 7 * 86_400, barSeconds: 900 },
+    { range: "1M", spanSeconds: 30 * 86_400, barSeconds: 3_600 },
+    { range: "3M", spanSeconds: 90 * 86_400, barSeconds: 14_400 },
+];
+export const DEFAULT_LABEL_HORIZON_HOURS = 24;
+/**
+ * Which candle range can label [asOf, asOf + horizon] right now. The horizon
+ * must have fully elapsed, and the range window (ending now) must still hold
+ * the bar that contains asOf.
+ */
+export function planPriceLabels(asOf, horizonHours, nowMs) {
+    const asOfMs = Date.parse(asOf);
+    if (!Number.isFinite(asOfMs))
+        throw new Error(`invalid asOf "${asOf}"`);
+    if (!Number.isFinite(horizonHours) || horizonHours <= 0)
+        throw new Error("horizon hours must be a positive number");
+    const fromSec = Math.floor(asOfMs / 1000);
+    const toSec = fromSec + Math.round(horizonHours * 3600);
+    const nowSec = Math.floor(nowMs / 1000);
+    if (toSec > nowSec)
+        return {
+            status: "not_yet",
+            labelableAfter: new Date(toSec * 1000).toISOString(),
+        };
+    const age = nowSec - fromSec;
+    const pick = LABEL_RANGES.find((r) => age + r.barSeconds <= r.spanSeconds);
+    return pick
+        ? {
+            status: "ready",
+            range: pick.range,
+            barSeconds: pick.barSeconds,
+            fromSec,
+            toSec,
+        }
+        : { status: "too_old" };
+}
+const isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/** The coins a cassette observed: its recorded GET /api/agent/market/:id reads. */
+export function cassetteCoins(cassette) {
+    const out = new Map();
+    for (const r of cassette.responses) {
+        const m = /^\/api\/agent\/market\/([^/]+)$/.exec(r.path);
+        if (!m || r.method !== "GET" || !r.ok)
+            continue;
+        const coin = isObject(r.data) ? r.data.coin : undefined;
+        const symbol = isObject(coin) ? coin.symbol : undefined;
+        if (typeof symbol === "string" && symbol.trim())
+            out.set(decodeURIComponent(m[1]), symbol.trim().toUpperCase());
+    }
+    return [...out].map(([coinId, symbol]) => ({ coinId, symbol }));
+}
+/**
+ * Bars from a candles response that can matter for [fromSec, toSec]: the bar
+ * containing asOf onward (the scorer itself ignores every bar at or before
+ * asOf) through the last bar that CLOSES by toSec, finite OHLC only, oldest
+ * first. A bar straddling toSec (it may hold prices after the horizon) or
+ * still open when labelling runs is never stored.
+ */
+export function priceBarsFor(data, fromSec, toSec, barSeconds) {
+    const rows = isObject(data) && Array.isArray(data.candles) ? data.candles : [];
+    const bars = [];
+    for (const row of rows) {
+        if (!isObject(row))
+            continue;
+        const { t, h, l, c } = row;
+        if ([t, h, l, c].every((v) => typeof v === "number" && Number.isFinite(v)) &&
+            t > fromSec - barSeconds &&
+            t + barSeconds <= toSec)
+            bars.push({
+                t: t,
+                h: h,
+                l: l,
+                c: c,
+            });
+    }
+    return bars.sort((a, b) => a.t - b.t);
+}
+/**
+ * Price labels for each cassette. `fetchCandles` is the agent API candles
+ * read; one fetch per coin and range serves every cassette. An existing label
+ * file keeps its PM and funding labels; its prices are replaced only with
+ * `overwrite`. A symbol whose read fails or returns no bar in the window is
+ * reported missing and stays unlabelled.
+ */
+export async function buildPriceLabels(cassettes, opts) {
+    const horizonHours = opts.horizonHours ?? DEFAULT_LABEL_HORIZON_HOURS;
+    const cache = new Map();
+    const read = (coinId, range) => {
+        const key = `${coinId}|${range}`;
+        let hit = cache.get(key);
+        if (!hit) {
+            hit = opts
+                .fetchCandles(coinId, range)
+                .catch(() => ({ ok: false, status: 0, data: null }));
+            cache.set(key, hit);
+        }
+        return hit;
+    };
+    const results = [];
+    for (const cassette of cassettes) {
+        const existing = opts.existing?.[cassette.id];
+        if (existing?.prices && !opts.overwrite) {
+            // An existing file labelled for another horizon is never reported as
+            // done for this one: rebuilding it needs --overwrite.
+            results.push(existing.horizonHours === horizonHours
+                ? { id: cassette.id, status: "kept" }
+                : {
+                    id: cassette.id,
+                    status: "horizon_mismatch",
+                    existingHorizonHours: existing.horizonHours ?? null,
+                });
+            continue;
+        }
+        const plan = planPriceLabels(cassette.asOf, horizonHours, opts.nowMs);
+        if (plan.status !== "ready") {
+            results.push({ id: cassette.id, ...plan });
+            continue;
+        }
+        const coins = cassetteCoins(cassette);
+        if (coins.length === 0) {
+            results.push({ id: cassette.id, status: "no_coins" });
+            continue;
+        }
+        const prices = {};
+        const missing = [];
+        for (const { coinId, symbol } of coins) {
+            const res = await read(coinId, plan.range);
+            const bars = res.ok
+                ? priceBarsFor(res.data, plan.fromSec, plan.toSec, plan.barSeconds)
+                : [];
+            if (bars.length > 0)
+                prices[symbol] = bars;
+            else
+                missing.push(symbol);
+        }
+        const { prices: _old, barSeconds: _bar, horizonHours: _h, ...kept } = existing ?? {};
+        results.push({
+            id: cassette.id,
+            status: "built",
+            range: plan.range,
+            symbols: Object.keys(prices).sort(),
+            missing: missing.sort(),
+            file: {
+                ...kept,
+                prices,
+                barSeconds: plan.barSeconds,
+                horizonHours,
+            },
+        });
+    }
+    return results;
+}
+// ── PM settlement labels (root 57074) ──────────────────────────────────────
+// From the EXISTING public event read GET /api/prediction-markets/events/
+// :source/:slug, never an invented verdict: an outcome is labelled only when
+// the event's settlementTrust says settlementEligible AND limboVerdict
+// "settle", and the outcome's own lifecycle is a provider result (isResult,
+// basis "provider", result won|lost). Probed live 2026-10-07: a Kalshi ladder
+// (1 won / 74 lost, eligible, settle) and a ForecastEx event whose winner is
+// known but whose time is unverified (eligible false, limbo "void"), which
+// stays unlabelled. A pm_open buys its named outcome, so settled = won.
+/** The PM events a cassette discovered (its recorded /pm/discover reads). */
+export function cassettePmEvents(cassette) {
+    const out = new Map();
+    for (const r of cassette.responses) {
+        if (r.path !== "/api/agent/pm/discover" || r.method !== "GET" || !r.ok)
+            continue;
+        const rows = isObject(r.data) && Array.isArray(r.data.data) ? r.data.data : [];
+        for (const ev of rows) {
+            if (!isObject(ev))
+                continue;
+            const { source, slug } = ev;
+            if (typeof source !== "string" || typeof slug !== "string")
+                continue;
+            const s = source.trim().toLowerCase();
+            const g = slug.trim().toLowerCase();
+            if (s && g)
+                out.set(`${s}/${g}`, { source: s, slug: g });
+        }
+    }
+    return [...out.values()];
+}
+/**
+ * Pure: settled labels from one public event-detail body, keyed
+ * `source/slug/outcomeExternalMarketId`. Empty unless the platform's own
+ * verdict says the event settles and the outcome has a provider result.
+ */
+export function pmVerdictLabels(source, slug, body) {
+    const out = {};
+    if (!isObject(body))
+        return out;
+    const resolution = isObject(body.resolution) ? body.resolution : undefined;
+    const trust = resolution && isObject(resolution.settlementTrust)
+        ? resolution.settlementTrust
+        : undefined;
+    if (!trust ||
+        trust.settlementEligible !== true ||
+        trust.limboVerdict !== "settle")
+        return out;
+    const event = isObject(body.event) ? body.event : undefined;
+    const outcomes = event && Array.isArray(event.outcomes) ? event.outcomes : [];
+    for (const o of outcomes) {
+        if (!isObject(o) || typeof o.externalMarketId !== "string")
+            continue;
+        const lc = isObject(o.lifecycle) ? o.lifecycle : undefined;
+        if (!lc ||
+            lc.isResult !== true ||
+            lc.basis !== "provider" ||
+            (lc.result !== "won" && lc.result !== "lost"))
+            continue;
+        out[`${source}/${slug}/${o.externalMarketId}`] = {
+            settled: lc.result === "won" ? 1 : 0,
+        };
+    }
+    return out;
+}
+/**
+ * Settled PM labels per cassette from the public event verdict. One read per
+ * event serves every cassette; a failed or unusable read leaves that event
+ * unlabelled and is counted. Existing PM labels are kept unless `overwrite`.
+ */
+export async function buildPmLabels(cassettes, opts) {
+    const cache = new Map();
+    const read = (source, slug) => {
+        const key = `${source}/${slug}`;
+        let hit = cache.get(key);
+        if (!hit) {
+            hit = opts
+                .fetchEvent(source, slug)
+                .catch(() => ({ ok: false, status: 0, data: null }));
+            cache.set(key, hit);
+        }
+        return hit;
+    };
+    const results = [];
+    for (const cassette of cassettes) {
+        const events = cassettePmEvents(cassette);
+        const pm = opts.overwrite
+            ? {}
+            : { ...(opts.existing?.[cassette.id]?.pm ?? {}) };
+        let failed = 0;
+        let labelled = 0;
+        for (const { source, slug } of events) {
+            const res = await read(source, slug);
+            if (!res.ok) {
+                failed += 1;
+                continue;
+            }
+            for (const [key, label] of Object.entries(pmVerdictLabels(source, slug, res.data))) {
+                if (!opts.overwrite && pm[key] !== undefined)
+                    continue;
+                pm[key] = label;
+                labelled += 1;
+            }
+        }
+        results.push({
+            id: cassette.id,
+            events: events.length,
+            labelled,
+            failed,
+            pm,
+        });
+    }
+    return results;
+}

package/dist/agent/bench/labels.d.ts

@@ -0,0 +1,75 @@
+import { ProposedAction, QuoteEvidence } from "../types.js";
+export declare const DEFAULT_BAR_SECONDS = 300;
+export interface PriceBar {
+    t: number;
+    h: number;
+    l: number;
+    c: number;
+}
+export interface FundingEvent {
+    t: number;
+    rate: number;
+}
+export interface LabelFile {
+    pm?: Record<string, {
+        settled: 0 | 1;
+    }>;
+    prices?: Record<string, PriceBar[]>;
+    barSeconds?: number;
+    funding?: Record<string, FundingEvent[]>;
+    horizonHours?: number;
+}
+export type ActionScore = {
+    status: "not_scored";
+    reason: string;
+} | {
+    status: "unlabelled";
+    reason: string;
+} | {
+    status: "unlabelled_gap";
+    reason: string;
+} | {
+    status: "labelled";
+    venue: "pm";
+    settled: 0 | 1;
+    /** Fee-inclusive cost per share, 0..1 (stake / net shares). */
+    cost: number;
+    /** settled - cost: P&L per share bought. */
+    pnlPerShare: number;
+    /** (settled - cost) / cost: P&L per 1 mUSD staked. */
+    returnOnStake: number;
+    pnlMusd: number;
+    /** Brier of the agent's own forecast; absent when it sent none. */
+    brier?: number;
+    /** Brier of the market's raw entry probability on the same outcome. */
+    marketBrier?: number;
+} | {
+    status: "labelled";
+    venue: "futures";
+    basis: "ohlc_walk_model";
+    exit: "stop" | "take_profit" | "liquidation" | "horizon";
+    exitPrice: number;
+    /** One bar touched both stop and target; resolved as the stop. */
+    sameBarStopAndTarget: boolean;
+    /** The horizon was not on a bar boundary: the walk ended at the last
+     *  full bar before it (never at a close after the horizon). */
+    horizonFlooredToBar: boolean;
+    fundingIncluded: boolean;
+    /** After fees (and funding when included), fraction of margin, >= -1. */
+    returnOnMargin: number;
+    pnlMusd: number;
+};
+/** Parse and validate a label file. Throws on a malformed file (fail closed). */
+export declare function parseLabelFile(value: unknown, source: string): LabelFile;
+/**
+ * Score one ACCEPTED action. Only risk-increasing PM and futures opens are
+ * scored in this slice; closes, protection updates, cancels and spot orders
+ * are "not_scored". An open with no matching label is "unlabelled"; a futures
+ * open whose bar path has holes is "unlabelled_gap".
+ */
+export declare function scoreAction(input: {
+    action: ProposedAction;
+    quote?: QuoteEvidence;
+    asOf: string;
+    labels?: LabelFile;
+}): ActionScore;