@coinrithm/mcp-trading 0.7.14 → 0.7.16

package/dist/agent/bench/labels.js

@@ -0,0 +1,259 @@
+// Outcome labels for bench actions. Pure functions, no network.
+//
+// Labels are OPTIONAL in this slice. When `<corpus>/labels/<cassetteId>.json`
+// exists the bench scores accepted opens against it; otherwise every accepted
+// open is reported as "unlabelled" (counted, never dropped). This slice never
+// fetches labels: whoever builds the label file must take its data from AFTER
+// the cassette's asOf, and the scorer enforces that for price bars by ignoring
+// every bar at or before asOf (no look-ahead from the decision's own inputs).
+//
+// A futures outcome is a MODEL, not a fill record. It walks OHLC bars after
+// asOf with these assumptions (also listed in every report's `assumptions`):
+//   - entry at the recorded (synthesized) quote price with the paper fee model;
+//     entry latency is not modelled;
+//   - inside one bar the price path is unknown, so a bar that touches both the
+//     stop and the take-profit is resolved as the STOP (conservative) and is
+//     counted (sameBarStopAndTarget) so its share is visible;
+//   - a missing bar before the exit (or before the horizon end) makes the
+//     outcome "unlabelled_gap": counted, never filled or interpolated;
+//   - only bars that open after asOf AND close by the horizon end are
+//     walked, so no price after the horizon is ever seen; with a horizon
+//     that does not end on a bar boundary the walk stops at the last full
+//     bar before it (horizonFlooredToBar), a conservative cutoff;
+//   - funding is included only when the label file carries funding events for
+//     the symbol; otherwise the score says fundingIncluded: false.
+//
+// Label file shape:
+//   {
+//     "pm": { "<source>/<slug>/<outcomeExternalMarketId>": { "settled": 0 | 1 } },
+//     "prices": { "<SYMBOL>": [{ "t": <bar open, unix seconds>, "h": n, "l": n, "c": n }] },
+//     "barSeconds": <optional bar interval, default 300>,
+//     "funding": { "<SYMBOL>": [{ "t": <unix seconds>, "rate": <fraction of notional per event> }] },
+//     "horizonHours": <optional number: stop the walk at asOf + horizon>
+//   }
+// `settled: 1` means the outcome the agent BOUGHT won. A positive funding rate
+// is paid by longs and received by shorts.
+import { baseSymbol } from "../setups.js";
+import { FUTURES_SYNTHETIC_FEE_BPS } from "./costs.js";
+export const DEFAULT_BAR_SECONDS = 300;
+const isFiniteNumber = (v) => typeof v === "number" && Number.isFinite(v);
+const isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/** Parse and validate a label file. Throws on a malformed file (fail closed). */
+export function parseLabelFile(value, source) {
+    const bad = (why) => {
+        throw new Error(`label file ${source} is invalid: ${why}`);
+    };
+    if (!isObject(value))
+        return bad("not a JSON object");
+    const root = value;
+    const out = {};
+    if (root.pm !== undefined) {
+        if (!isObject(root.pm))
+            return bad("pm must be an object");
+        out.pm = {};
+        for (const [key, label] of Object.entries(root.pm)) {
+            const settled = isObject(label) ? label.settled : undefined;
+            if (settled !== 0 && settled !== 1)
+                return bad(`pm["${key}"].settled must be 0 or 1`);
+            if (key.split("/").length < 3)
+                return bad(`pm key "${key}" must be source/slug/outcomeExternalMarketId`);
+            out.pm[key] = { settled: settled };
+        }
+    }
+    const series = (field, keys) => {
+        const raw = root[field];
+        if (raw === undefined)
+            return undefined;
+        if (!isObject(raw))
+            return bad(`${field} must be an object`);
+        const result = {};
+        for (const [symbol, rows] of Object.entries(raw)) {
+            if (!Array.isArray(rows))
+                return bad(`${field}["${symbol}"] must be an array`);
+            result[symbol.toUpperCase()] = rows.map((row, i) => {
+                if (!isObject(row) || !keys.every((k) => isFiniteNumber(row[k])))
+                    return bad(`${field}["${symbol}"][${i}] needs numeric ${keys.join(", ")}`);
+                return Object.fromEntries(keys.map((k) => [k, row[k]]));
+            });
+        }
+        return result;
+    };
+    const prices = series("prices", ["t", "h", "l", "c"]);
+    if (prices)
+        out.prices = prices;
+    const funding = series("funding", ["t", "rate"]);
+    if (funding)
+        out.funding = funding;
+    for (const field of ["horizonHours", "barSeconds"]) {
+        const v = root[field];
+        if (v === undefined)
+            continue;
+        if (!isFiniteNumber(v) || v <= 0)
+            return bad(`${field} must be a positive number`);
+        out[field] = v;
+    }
+    return out;
+}
+function pmLabel(labels, action) {
+    const want = `${action.source.toLowerCase()}/${action.slug.toLowerCase()}/${action.outcomeExternalMarketId}`;
+    for (const [key, label] of Object.entries(labels.pm ?? {})) {
+        const [source, slug, ...rest] = key.split("/");
+        if (`${source.toLowerCase()}/${slug.toLowerCase()}/${rest.join("/")}` === want)
+            return label.settled;
+    }
+    return undefined;
+}
+function scorePm(action, quote, labels) {
+    const settled = pmLabel(labels, action);
+    if (settled === undefined)
+        return { status: "unlabelled", reason: "no_pm_settlement_label" };
+    const stake = quote?.stakeMusd;
+    const shares = quote?.sharesEstimate;
+    const market = quote?.entryProbability;
+    // Fee-inclusive cost first, the raw entry probability only as a fallback.
+    const cost = isFiniteNumber(stake) && isFiniteNumber(shares) && stake > 0 && shares > 0
+        ? stake / shares
+        : isFiniteNumber(market)
+            ? market / 100
+            : undefined;
+    if (cost === undefined || cost <= 0)
+        return { status: "unlabelled", reason: "no_entry_cost" };
+    const forecast = action.forecastProbability;
+    const returnOnStake = (settled - cost) / cost;
+    return {
+        status: "labelled",
+        venue: "pm",
+        settled,
+        cost,
+        pnlPerShare: settled - cost,
+        returnOnStake,
+        pnlMusd: returnOnStake * action.stakeMusd,
+        ...(isFiniteNumber(forecast)
+            ? { brier: (forecast / 100 - settled) ** 2 }
+            : {}),
+        ...(isFiniteNumber(market)
+            ? { marketBrier: (market / 100 - settled) ** 2 }
+            : {}),
+    };
+}
+const seconds = (t) => (t > 1e12 ? t / 1000 : t);
+function seriesFor(map, symbol) {
+    return map?.[symbol.toUpperCase()] ?? map?.[baseSymbol(symbol)];
+}
+function scoreFutures(action, quote, asOf, labels) {
+    const entry = quote?.entryPrice;
+    if (!isFiniteNumber(entry) || entry <= 0)
+        return { status: "unlabelled", reason: "no_entry_price" };
+    const asOfSec = Date.parse(asOf) / 1000;
+    if (!Number.isFinite(asOfSec))
+        return { status: "unlabelled", reason: "asof_unparseable" };
+    const series = seriesFor(labels.prices, action.symbol);
+    if (!series)
+        return { status: "unlabelled", reason: "no_price_series" };
+    const barSeconds = labels.barSeconds ?? DEFAULT_BAR_SECONDS;
+    const horizonEnd = labels.horizonHours !== undefined
+        ? asOfSec + labels.horizonHours * 3600
+        : Infinity;
+    // Only bars that open strictly AFTER the decision's asOf (no look-ahead)
+    // and CLOSE by the horizon end: a bar straddling the horizon could carry
+    // a stop or target after it, and a still-open bar is not final.
+    const bars = series
+        .map((b) => ({ ...b, t: seconds(b.t) }))
+        .filter((b) => b.t > asOfSec && b.t + barSeconds <= horizonEnd)
+        .sort((a, b) => a.t - b.t);
+    const gap = (why) => ({
+        status: "unlabelled_gap",
+        reason: why,
+    });
+    if (bars.length === 0)
+        return gap("no_bars_after_asof");
+    const long = action.side === "long";
+    const lev = action.leverage;
+    const liquidation = long ? entry * (1 - 1 / lev) : entry * (1 + 1 / lev);
+    const stop = isFiniteNumber(action.stopLossPrice)
+        ? action.stopLossPrice
+        : undefined;
+    const target = isFiniteNumber(action.takeProfitPrice)
+        ? action.takeProfitPrice
+        : undefined;
+    // The adverse trigger nearest to entry fires first.
+    const adverse = long
+        ? Math.max(stop ?? -Infinity, liquidation)
+        : Math.min(stop ?? Infinity, liquidation);
+    const adverseExit = adverse === liquidation ? "liquidation" : "stop";
+    let exit;
+    let sameBar = false;
+    let previousT = asOfSec;
+    for (const bar of bars) {
+        // A bar that opens more than one interval after the previous one (or,
+        // for the first bar, after asOf) leaves an unobserved stretch where the
+        // stop could have fired. Never fill it.
+        if (bar.t - previousT > barSeconds)
+            return gap("missing_bar_before_exit");
+        previousT = bar.t;
+        const hitAdverse = long ? bar.l <= adverse : bar.h >= adverse;
+        const hitTarget = target !== undefined && (long ? bar.h >= target : bar.l <= target);
+        if (hitAdverse) {
+            sameBar = hitTarget;
+            exit = { kind: adverseExit, price: adverse, t: bar.t };
+            break;
+        }
+        if (hitTarget && target !== undefined) {
+            exit = { kind: "take_profit", price: target, t: bar.t };
+            break;
+        }
+    }
+    if (!exit) {
+        // No trigger: mark at the last close, but only when the bars reach the
+        // last full bar before the horizon end (when one is set); a short series
+        // is a gap, not an exit.
+        if (Number.isFinite(horizonEnd) &&
+            horizonEnd - (previousT + barSeconds) >= barSeconds)
+            return gap("bars_end_before_horizon");
+        const last = bars[bars.length - 1];
+        // Priced at the final full bar's CLOSE, so funding settled inside that
+        // bar counts. Stop/target exits keep the bar OPEN as their time: inside
+        // one bar the trigger time is unknown (the stated same-bar ambiguity).
+        exit = { kind: "horizon", price: last.c, t: last.t + barSeconds };
+    }
+    const exitT = exit.t;
+    const fundingEvents = seriesFor(labels.funding, action.symbol);
+    const fundingCost = (fundingEvents ?? [])
+        .map((f) => ({ ...f, t: seconds(f.t) }))
+        .filter((f) => f.t > asOfSec && f.t <= exitT)
+        .reduce((s, f) => s + (long ? f.rate : -f.rate) * lev, 0);
+    const fees = (2 * FUTURES_SYNTHETIC_FEE_BPS * lev) / 10_000;
+    const gross = ((long ? 1 : -1) * (exit.price - entry) * lev) / entry;
+    // Liquidation forfeits the margin (openapi: no adverse fill cost on top).
+    const returnOnMargin = exit.kind === "liquidation" ? -1 : Math.max(-1, gross - fees - fundingCost);
+    return {
+        status: "labelled",
+        venue: "futures",
+        basis: "ohlc_walk_model",
+        exit: exit.kind,
+        exitPrice: exit.price,
+        sameBarStopAndTarget: sameBar,
+        // Candle times are epoch multiples of the bar size: a horizon end off
+        // that grid was cut back to the last full bar before it.
+        horizonFlooredToBar: Number.isFinite(horizonEnd) && horizonEnd % barSeconds !== 0,
+        fundingIncluded: fundingEvents !== undefined,
+        returnOnMargin,
+        pnlMusd: returnOnMargin * action.marginMusd,
+    };
+}
+/**
+ * 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 function scoreAction(input) {
+    const { action, quote, asOf, labels } = input;
+    if (action.type !== "pm_open" && action.type !== "futures_open")
+        return { status: "not_scored", reason: `${action.type}_not_scored` };
+    if (!labels)
+        return { status: "unlabelled", reason: "no_label_file" };
+    return action.type === "pm_open"
+        ? scorePm(action, quote, labels)
+        : scoreFutures(action, quote, asOf, labels);
+}

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

@@ -0,0 +1,51 @@
+import { ClientConfig, CoinRithmClient } from "../client.js";
+import { Provider } from "../providers.js";
+import { AgentSpec } from "../types.js";
+import { Cassette, RecordedResponse } from "./cassette.js";
+export declare const BENCH_RUN_ID = "bench";
+export declare const BENCH_WRITE_REFUSED = "bench_write_refused";
+export type FetchInput = Parameters<typeof fetch>[0];
+export type FetchInit = Parameters<typeof fetch>[1];
+export declare function urlOf(input: FetchInput): string;
+export declare function jsonResponse(status: number, body: unknown): Response;
+export declare function writeRefusedResponse(): Response;
+/** A brain that never calls a model: every cycle is a skip. */
+export declare const SKIP_PROVIDER: Provider;
+export declare class ResponseRecorder {
+    private readonly inner;
+    private readonly basePath;
+    private readonly entries;
+    private readonly frozen;
+    readonly refused: string[];
+    readonly fetch: typeof fetch;
+    constructor(inner: typeof fetch, basePath: string);
+    /**
+     * Keep every key recorded so far. Later reads can add new keys, but cannot
+     * replace these stored responses. Transport reads still run normally.
+     */
+    freeze(): void;
+    responses(): RecordedResponse[];
+    private keep;
+    private handle;
+}
+/** A production CoinRithmClient whose transport is a ResponseRecorder. */
+export declare class RecordingClient extends CoinRithmClient {
+    readonly recorder: ResponseRecorder;
+    constructor(cfg: ClientConfig);
+}
+export interface RecordCassetteOptions {
+    spec: AgentSpec;
+    mergedProse: string;
+    apiKey: string;
+    baseUrl?: string;
+    fetchFn?: typeof fetch;
+    log?: (line: string) => void;
+}
+/**
+ * Record one cassette: run the real runCycle in DRY-RUN through a
+ * RecordingClient with a brain that never calls a model, including the
+ * original PM board when the agent enables that venue.
+ * Baselines override the decision policy, not the recorded opportunity set,
+ * so no second pass or later market snapshot is needed.
+ */
+export declare function recordCassette(opts: RecordCassetteOptions): Promise<Cassette>;

package/dist/agent/bench/recordingClient.js

@@ -0,0 +1,193 @@
+// Recording side of the bench: a real CoinRithmClient whose transport records
+// every READ response into a cassette, and refuses every write.
+//
+// The recorder sits at the fetch layer (ClientConfig.fetchFn) rather than
+// wrapping client methods. That keeps the production client code in the path
+// (URL building, auth header, 429 handling, JSON parsing), records the public
+// whale reads too, and needs no knowledge of which client method made a call:
+// a new read added to observe() is recorded automatically.
+//
+// Write refusal is structural, not a convention: recording runs the cycle in
+// DRY-RUN (live=false) with a stub brain that always skips, so no write should
+// ever be attempted. If one is (a mechanical baseline asking for a quote, or a
+// future runner change), the recorder records nothing, never forwards it, and
+// answers 599 bench_write_refused. Only GET ever reaches the network.
+import { CoinRithmClient, DEFAULT_BASE_URL } from "../client.js";
+import { buildAgentDefinitionSnapshot } from "../definitionSnapshot.js";
+import { clearPmCalibrationCache } from "../observe.js";
+import { runCycle } from "../runner.js";
+import { newState } from "../state.js";
+import { asObj } from "../extract.js";
+import { basePathOf, canonicalJson, canonicalRequest, CASSETTE_SCHEMA, cassetteId, recordingSpec, sha256Hex, } from "./cassette.js";
+export const BENCH_RUN_ID = "bench";
+export const BENCH_WRITE_REFUSED = "bench_write_refused";
+// Statuses whose Response must carry a null body (the constructor throws
+// otherwise).
+const NULL_BODY_STATUS = new Set([204, 205, 304]);
+export function urlOf(input) {
+    if (typeof input === "string")
+        return input;
+    if (input instanceof URL)
+        return input.href;
+    return input.url;
+}
+export function jsonResponse(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json" },
+    });
+}
+export function writeRefusedResponse() {
+    return jsonResponse(599, {
+        error: BENCH_WRITE_REFUSED,
+        message: "the bench never forwards writes; recording and replay are dry-run",
+    });
+}
+/** A brain that never calls a model: every cycle is a skip. */
+export const SKIP_PROVIDER = {
+    label: "bench-skip",
+    decide: async () => ({
+        ok: true,
+        text: JSON.stringify({ decision: "skip", reason: "bench_no_model" }),
+    }),
+};
+export class ResponseRecorder {
+    inner;
+    basePath;
+    entries = new Map();
+    frozen = new Set();
+    refused = [];
+    fetch;
+    constructor(inner, basePath) {
+        this.inner = inner;
+        this.basePath = basePath;
+        this.fetch = ((input, init) => this.handle(input, init));
+    }
+    /**
+     * Keep every key recorded so far. Later reads can add new keys, but cannot
+     * replace these stored responses. Transport reads still run normally.
+     */
+    freeze() {
+        for (const key of this.entries.keys())
+            this.frozen.add(key);
+    }
+    responses() {
+        return [...this.entries.values()].sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+    }
+    keep(entry) {
+        // Last wins within a pass: after 429 retries the final answer is the one
+        // the client actually used.
+        if (!this.frozen.has(entry.key))
+            this.entries.set(entry.key, entry);
+    }
+    async handle(input, init) {
+        const req = canonicalRequest(init?.method ?? (input instanceof Request ? input.method : "GET"), urlOf(input), this.basePath);
+        if (req.method !== "GET") {
+            this.refused.push(req.key);
+            return writeRefusedResponse();
+        }
+        let res;
+        try {
+            res = await this.inner(input, init);
+        }
+        catch (error) {
+            this.keep({
+                ...req,
+                status: 0,
+                ok: false,
+                data: { error: "network_error" },
+                transportError: true,
+            });
+            throw error;
+        }
+        const text = await res.text();
+        let data = text;
+        if (text) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                /* leave as text, exactly as the client does */
+            }
+        }
+        this.keep({ ...req, status: res.status, ok: res.ok, data });
+        return new Response(NULL_BODY_STATUS.has(res.status) ? null : text, {
+            status: res.status,
+            statusText: res.statusText,
+            headers: res.headers,
+        });
+    }
+}
+/** A production CoinRithmClient whose transport is a ResponseRecorder. */
+export class RecordingClient extends CoinRithmClient {
+    recorder;
+    constructor(cfg) {
+        const recorder = new ResponseRecorder(cfg.fetchFn ?? fetch, basePathOf(cfg.baseUrl ?? DEFAULT_BASE_URL));
+        super({ ...cfg, fetchFn: recorder.fetch });
+        this.recorder = recorder;
+    }
+}
+/**
+ * Record one cassette: run the real runCycle in DRY-RUN through a
+ * RecordingClient with a brain that never calls a model, including the
+ * original PM board when the agent enables that venue.
+ * Baselines override the decision policy, not the recorded opportunity set,
+ * so no second pass or later market snapshot is needed.
+ */
+export async function recordCassette(opts) {
+    const client = new RecordingClient({
+        apiKey: opts.apiKey,
+        baseUrl: opts.baseUrl,
+        fetchFn: opts.fetchFn,
+    });
+    // The own-calibration read is cached per credential for 30 minutes. Clear
+    // it so every cassette records the read instead of inheriting a cache hit.
+    clearPmCalibrationCache();
+    const result = await runCycle({
+        client,
+        provider: SKIP_PROVIDER,
+        spec: recordingSpec(opts.spec),
+        mergedProse: opts.mergedProse,
+        state: newState(BENCH_RUN_ID),
+        live: false,
+        log: opts.log,
+    });
+    const responses = client.recorder.responses();
+    const pmDiscovery = responses.filter((r) => r.path === "/api/agent/pm/discover");
+    // Keep the legacy field name, but never confuse "pm enabled" with a
+    // recorded PM observation. An empty successful board is valid; missing or
+    // failed reads and pre-observation exits are not baseline-ready.
+    const marketBaselineRecorded = opts.spec.venues.includes("pm") &&
+        result.decisionInputRecord?.phase === "decision_input" &&
+        responses.some((r) => r.path === "/api/agent/positions/pm" &&
+            r.ok &&
+            Array.isArray(asObj(r.data).positions)) &&
+        pmDiscovery.length > 0 &&
+        pmDiscovery.every((r) => {
+            const body = asObj(r.data);
+            return r.ok && Array.isArray(body.data ?? body.markets ?? body.results);
+        });
+    // A trades cursor predates subsequent reads. Scoring from it would allow
+    // prices inside the input-collection window to count as future outcomes.
+    const clockMs = Date.now();
+    const recordedAt = new Date(clockMs).toISOString();
+    const asOf = recordedAt;
+    return {
+        schema: CASSETTE_SCHEMA,
+        id: cassetteId(asOf, sha256Hex(canonicalJson(responses))),
+        recordedAt,
+        clockMs,
+        asOf,
+        agentSpecHash: buildAgentDefinitionSnapshot(opts.spec, opts.mergedProse)
+            .definitionHash,
+        spec: opts.spec,
+        marketBaselineRecorded,
+        recordCycle: {
+            decision: result.decision,
+            ...(result.decisionType ? { decisionType: result.decisionType } : {}),
+            ...(result.skipReason ? { skipReason: result.skipReason } : {}),
+        },
+        refusedRequests: [...client.recorder.refused],
+        responses,
+    };
+}

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

@@ -0,0 +1,41 @@
+import { CoinRithmClient } from "../client.js";
+import { Cassette } from "./cassette.js";
+export declare const REPLAY_BASE_URL = "https://bench-replay.invalid";
+export declare const NOT_RECORDED_STATUS = 599;
+export interface SynthesizedQuote {
+    venue: "pm" | "futures" | "spot";
+    /** source/slug/outcome for PM, coinId for futures and spot. */
+    subject: string;
+    eligible: boolean;
+    /** What the price came from, or why the quote was ineligible. */
+    basis: string;
+}
+export interface ReplayStats {
+    served: number;
+    /** Canonical keys of reads the cassette did not contain (in call order). */
+    missing: string[];
+    synthesizedQuotes: SynthesizedQuote[];
+    refusedWrites: string[];
+}
+interface RecordedPmOutcome {
+    probability?: number;
+    freshness: string;
+    eligible: boolean;
+}
+/**
+ * The chosen PM outcome as the recording's discover reads reported it. Every
+ * recorded discover page is searched in key order (deterministic); the first
+ * match wins. Mirrors observe()'s expandPmMarkets field fallbacks.
+ */
+export declare function findRecordedPmOutcome(cassette: Cassette, source: string, slug: string, outcomeExternalMarketId: string): RecordedPmOutcome | undefined;
+/** The recorded /market price and freshness for a coin, if it was read. */
+export declare function findRecordedPrice(cassette: Cassette, coinId: string): {
+    priceUsd?: number;
+    freshness: string;
+} | undefined;
+/** A production CoinRithmClient that answers from one cassette. */
+export declare class ReplayClient extends CoinRithmClient {
+    readonly stats: ReplayStats;
+    constructor(cassette: Cassette);
+}
+export {};