@coinrithm/mcp-trading 0.7.7 → 0.7.8

package/CHANGELOG.md

@@ -5,6 +5,89 @@ ships two binaries — `coinrithm-mcp` (the MCP server) and `coinrithm-agent` (t
 self-host agent runner) — versioned together. The CoinRithm **API contract** is
 versioned separately (see `openapi.yaml` `info.version`, currently `1.7.0`).
 
+## 0.7.8
+
+Runner decision-quality, evidence and paper-capital release. Additive: no MCP
+tool was renamed or removed, and the API **contract stays 1.7.0**. This release
+contains all package changes since published 0.7.7 (`gitHead` `80d0cae`), not
+just the previously listed thesis work.
+
+**Thesis exits.** Every opening action (`futures_open`, `spot_order`,
+`pm_open`) now carries a `thesis`: a one-sentence summary plus an
+`invalidation` with at least one machine-checkable condition (`priceBelow` /
+`priceAbove` for coins, `probabilityBelow` / `probabilityAbove` for prediction
+markets, a `maxHoldMinutes` time stop, and a free-text `catalyst` the model
+re-judges itself). The runner binds the thesis to the position the server
+returns, sanitized side-aware (a rising price never invalidates a long; a
+wrong-side level is dropped rather than re-signed; the time stop is clamped to
+60 minutes .. 30 days), persists it in the run state (`RunState.theses`, the
+same state file / `agent_state` JSON as before, no schema change) and
+re-evaluates it every cycle. A futures position whose price level or time stop
+is breached is closed by the runner before the model is asked anything, logged
+as a `thesis_invalidated` exit with its own idempotency key, after the
+kill-switch and drawdown checks and never instead of them. Prediction-market
+positions have no close endpoint, so a broken PM thesis is surfaced to the
+model instead (do not add, let it settle). The parser is tolerant (a malformed
+thesis never fails the open; a thesis copied onto a close is ignored) and the
+structured-output schema requires it, so schema-enforced hosted models always
+emit one.
+
+**Fundamentals in the observation.** Each watch entry now carries
+`fundamentals` sourced only from calls the runner already makes: `categories`,
+`marketCapRank` and `marketCapUsd` from the market context; `volume24hUsd` from
+the candles the `indicators` capability already fetches (live-probed
+2026-09-02: each bar's `v` is a rolling 24h volume, so the latest bar is the
+24h figure, never the sum); and up to three `headlines` with `publishedAt`
+timestamps from the one `news` call, attributed through the curated coin-news
+graph. Discovered PM markets carry `endDate` and `liquidityUsd`; open PM
+positions carry their title, side, entry and current probability and
+`openedAt`; open futures positions carry `openedAt`. The system prompt states
+the thesis contract, the runner-enforced exit and how to grade a trade on the
+fundamentals. Not carried, because no agent endpoint serves them: an "about"
+text per coin, a 24h probability change and a cross-venue divergence per PM
+market.
+
+**Fix:** the public movers feed serializes `change24h` / `currentPrice` as
+decimal strings; the universe-scan context rows read them strictly as numbers
+and shipped `undefined` for every mover.
+
+**Opt-in equity-based paper sizing.** A runner can size entries from a
+conservative fraction of its independently attributed paper book instead of a
+fixed stake/margin. The book is accepted only when wallet identity, cash
+partitions, held-position attribution and spot-mark coverage reconcile. Quotes
+then enforce per-entry, per-symbol, deployed-capital and daily-entry limits;
+fee buffers and the API's fee-inclusive quote evidence are included. Any
+missing or inconsistent evidence fails closed. Legacy positions on a different
+book remain visible for management but never inflate the current book's buying
+power.
+
+**Prediction-market decisions use executable economics.** PM opens now reject
+an invalid raw probability and a model forecast that does not clear the quoted
+entry price. Forecast edge is measured against the actual fee/slippage-adjusted
+fill, not the headline market probability. Quote-expiry outcomes are recorded
+separately from risk/balance rejection, and futures risk/reward validation uses
+fee-inclusive entry and stop economics.
+
+**Decision evidence is structured and bounded.** Cycles can expose a sanitized,
+partial private decision-input record: configuration and observation
+fingerprints, daily budget and guard state, plus bounded observation rows with
+explicit omission counts. It is not a prompt, transcript, raw model output or
+hidden reasoning record. The runner also reports quote/validation evidence for
+abstained, forecast-only and quote-expired PM opportunities. Hosted persistence
+and retention remain the caller's responsibility.
+
+**Runtime controls are more faithful.** The model sees the remaining daily
+entry/add budget rather than only static maxima. Entry caps still block new
+risk, while closes and other risk-reducing actions remain available. Direct
+provider HTTP 429 responses are capacity skips rather than model failures, so
+BYO agents do not build a failure streak during ordinary quota pressure.
+Structured-tool decisions remain required where the provider supports that
+contract.
+
+**Scorecard fix.** Maximum drawdown now measures decline from starting equity,
+so an immediate loss is no longer hidden by treating the first post-trade point
+as the high-water mark.
+
 ## 0.7.7
 
 Reliability release. Every change here came from a live production failure, not

package/dist/agent/act.js

@@ -1,15 +1,11 @@
 // Act phase: fetch the quote evidence for an open (the runner does this, never
 // the model) and execute a validated action (futures / spot / PM) with an
 // idempotency key.
-import { asObj, asNum, asStr } from "./extract.js";
+import { asObj, asNum } from "./extract.js";
+import { freshnessOf } from "./pmContext.js";
 function coinIdFor(observation, symbol) {
     return (observation.watch.find((w) => w.symbol.toUpperCase() === symbol.toUpperCase())?.coinId ?? undefined);
 }
-function freshnessOf(block) {
-    const fr = asObj(block.freshness);
-    const status = asStr(fr.status);
-    return status ? { status, ageSeconds: asNum(fr.ageSeconds) } : undefined;
-}
 // Read-only quote BEFORE any open. Returns ineligible (never throws) on error.
 export async function fetchQuote(client, action, observation, trace) {
     let r;
@@ -50,7 +46,24 @@ export async function fetchQuote(client, action, observation, trace) {
         entryPrice: asNum(d.entryPrice), // futures
         liquidationPrice: asNum(d.liquidationPrice), // futures
         executionPrice: asNum(d.executionPrice), // spot live fill price
+        entryProbability: asNum(d.entryProbability), // pm raw probability POINTS
+        ...(action.type === "pm_open"
+            ? {
+                stakeMusd: asNum(d.stakeMusd),
+                sharesEstimate: asNum(d.sharesEstimate),
+            }
+            : {}),
         estimatedCostMusd: asNum(d.estimatedCostMusd), // spot gross notional
+        ...(action.type === "spot_order"
+            ? { estimatedFeeMusd: asNum(d.estimatedFeeMusd) }
+            : {}),
+        ...(action.type === "futures_open"
+            ? {
+                futuresFeeBps: asNum(asObj(d.executionModel).feeBps),
+                estimatedEntryFeeMusd: asNum(asObj(d.executionModel).estimatedEntryFeeMusd),
+                cashRequiredMusd: asNum(d.cashRequiredMusd),
+            }
+            : {}),
         // Freshness lives in the response's `observation` block (anti-look-ahead).
         freshness: freshnessOf(asObj(d.observation)),
         // PM open-time quality-gate preview (additive; older backends omit it → the

package/dist/agent/capitalSizing.d.ts

@@ -0,0 +1,32 @@
+import type { AgentSpec, CapitalBook, CapitalSizingAdjustment, Observation, ProposedAction, QuoteEvidence } from "./types.js";
+export declare const CAPITAL_VALUATION_BASIS = "wallet_assets_spot_marked_futures_pm_at_collateral";
+export declare const CAPITAL_FEE_BUFFER_BPS = 10;
+/** Reconcile the bounded open-position reads against the wallet's frozen
+ * buckets. A full page is not assumed complete: the collateral checksums must
+ * agree. No held mark, unknown status, missing bucket, or mismatched book can
+ * silently become zero exposure. Lists retain legacy positions on other books
+ * for management; only explicitly attributed current-book rows reconcile its
+ * cash and marks. Closed history never contributes unrealized. */
+export declare function deriveCapitalBook(portfolio: unknown, wallet: unknown, futures: unknown, pm: unknown): CapitalBook;
+export interface CapitalBudget {
+    cashAvailableMusd: number;
+    committedCapitalMusd: number;
+    openMarginMusd: number;
+}
+export declare const usesCapitalSizing: (spec: AgentSpec, mechanical?: boolean) => boolean;
+export declare function prepareCapitalAction(action: ProposedAction, spec: AgentSpec, observation: Observation, budget: CapitalBudget): {
+    action: ProposedAction;
+    adjustment?: CapitalSizingAdjustment;
+    rejection?: string;
+};
+/** Quote-bound monetary checks. Drift fails closed; never requote a resized
+ * ticket, silently widen a cap, or credit uncertain close/sell proceeds. */
+export declare function validateCapitalAction(action: ProposedAction, spec: AgentSpec, observation: Observation, budget: CapitalBudget, quote?: QuoteEvidence): string | undefined;
+/** Fee-inclusive opt-in reservation; the legacy gross helper stays unchanged.
+ * The API quotes a market fill even for a pending limit/stop order. Reserve at
+ * least that fee, scaled up if the proposed price requires more notional.
+ * This is conservative captured quote evidence, not a future fill guarantee. */
+export declare function capitalSpotBuyCost(action: Extract<ProposedAction, {
+    type: "spot_order";
+}>, quote?: QuoteEvidence): number | undefined;
+export declare function capitalCashCost(action: ProposedAction, quote?: QuoteEvidence): number;

package/dist/agent/capitalSizing.js

@@ -0,0 +1,257 @@
+// Opt-in, deterministic PAPER sizing. No provider, price or database reads.
+import { asNum, asObj } from "./extract.js";
+import { spotBuyCost } from "./types.js";
+import { validateCapitalSizingPolicy } from "./skillValidator.js";
+export const CAPITAL_VALUATION_BASIS = "wallet_assets_spot_marked_futures_pm_at_collateral";
+// Conservative pre-quote runner estimate: 10bp each way, with the exit fee
+// charged on stop notional. Actual API fee evidence is checked after ONE quote.
+// This is not an exchange-fill, funding or stop-execution guarantee.
+export const CAPITAL_FEE_BUFFER_BPS = 10;
+const CENT_TOLERANCE = 0.011;
+const centsDown = (n) => Math.floor(n * 100) / 100;
+const positive = (n) => asNum(n) !== undefined && n > 0;
+const nonnegative = (n) => asNum(n) !== undefined && n >= 0;
+/** Reconcile the bounded open-position reads against the wallet's frozen
+ * buckets. A full page is not assumed complete: the collateral checksums must
+ * agree. No held mark, unknown status, missing bucket, or mismatched book can
+ * silently become zero exposure. Lists retain legacy positions on other books
+ * for management; only explicitly attributed current-book rows reconcile its
+ * cash and marks. Closed history never contributes unrealized. */
+export function deriveCapitalBook(portfolio, wallet, futures, pm) {
+    const p = asObj(portfolio), w = asObj(wallet), eq = asObj(p.equity), cash = asObj(w.usdt);
+    const unavailable = (reason) => ({
+        status: "unavailable",
+        reason,
+    });
+    if (p.bookScope !== "api_key")
+        return unavailable("independent_agent_book_unproven");
+    if (!Number.isSafeInteger(p.walletId) ||
+        p.walletId <= 0 ||
+        p.walletId !== w.walletId)
+        return unavailable("portfolio_wallet_identity_mismatch");
+    if (eq.valuationBasis !== CAPITAL_VALUATION_BASIS || !positive(eq.totalUsd))
+        return unavailable("portfolio_valuation_unavailable");
+    if (eq.spotValuationComplete !== true)
+        return unavailable("held_spot_valuation_unproven");
+    const buckets = ["available", "frozen", "frozenPm", "frozenFutures"];
+    for (const key of buckets) {
+        if (!nonnegative(cash[key]) ||
+            !nonnegative(eq[key]) ||
+            Math.abs(cash[key] - eq[key]) > CENT_TOLERANCE)
+            return unavailable("cash_partitions_incomplete_or_changed");
+    }
+    const cashTotal = buckets.reduce((sum, k) => sum + cash[k], 0);
+    if (eq.totalUsd + CENT_TOLERANCE < cashTotal)
+        return unavailable("wallet_asset_value_incoherent");
+    let negativeMarks = 0;
+    for (const [raw, bucket, amountKey, markKeys] of [
+        [futures, "frozenFutures", "marginMusd", ["unrealizedPnlMusd"]],
+        [pm, "frozenPm", "stakeMusd", ["unrealizedPnl", "unrealizedPnlMusd"]],
+    ]) {
+        const rows = asObj(raw).positions;
+        if (!Array.isArray(rows)) {
+            // PM is not fetched for a futures-only legacy universe. Zero frozen PM
+            // proves no tied-up PM collateral; a nonzero bucket must have coverage.
+            if (bucket === "frozenPm" && raw === undefined && cash[bucket] === 0)
+                continue;
+            return unavailable("position_coverage_unavailable");
+        }
+        let held = 0;
+        for (const row of rows) {
+            const position = asObj(row);
+            if (typeof position.status !== "string")
+                return unavailable("position_status_unavailable");
+            if (position.status !== "open")
+                continue;
+            if (!Number.isSafeInteger(position.walletId) ||
+                position.walletId <= 0)
+                return unavailable("held_position_wallet_unavailable");
+            // The key-scoped API includes legacy/shared-book positions. Their
+            // liabilities settle to their originating wallet, not this active book.
+            // Do not filter the management observation or credit their close proceeds.
+            if (position.walletId !== p.walletId)
+                continue;
+            const amount = position[amountKey];
+            const mark = markKeys
+                .map((key) => asNum(position[key]))
+                .find((n) => n !== undefined);
+            if (!nonnegative(amount) || mark === undefined)
+                return unavailable("held_position_mark_unavailable");
+            held += amount;
+            negativeMarks += Math.min(0, mark);
+        }
+        if (Math.abs(held - cash[bucket]) > CENT_TOLERANCE)
+            return unavailable("held_collateral_coverage_mismatch");
+    }
+    const conservativeEquityMusd = eq.totalUsd + negativeMarks;
+    if (!positive(conservativeEquityMusd))
+        return unavailable("nonpositive_conservative_equity");
+    return {
+        status: "ready",
+        walletId: p.walletId,
+        conservativeEquityMusd,
+        cashAvailableMusd: Math.min(cash.available, eq.available),
+        committedCapitalMusd: Math.max(0, eq.totalUsd - cash.available),
+    };
+}
+export const usesCapitalSizing = (spec, mechanical = false) => spec.capitalSizing !== undefined &&
+    !mechanical &&
+    spec.model?.provider !== "mechanical";
+const increases = (a) => a.type === "futures_open" ||
+    a.type === "pm_open" ||
+    (a.type === "spot_order" && a.side === "buy");
+export function prepareCapitalAction(action, spec, observation, budget) {
+    if (!usesCapitalSizing(spec) || !increases(action))
+        return { action };
+    if (validateCapitalSizingPolicy(spec.capitalSizing).length > 0)
+        return { action, rejection: "capital_policy_invalid" };
+    const policy = spec.capitalSizing;
+    const adjustment = {
+        version: policy.version,
+        basis: "owned_collateral_spot_marked_negative_position_marks_only",
+    };
+    const reject = (rejection) => ({ action, adjustment, rejection });
+    const book = observation.capitalBook;
+    if (!book || book.status !== "ready")
+        return reject(book?.reason ?? "capital_book_unavailable");
+    const equity = book.conservativeEquityMusd;
+    if (!positive(equity) ||
+        !nonnegative(budget.cashAvailableMusd) ||
+        !nonnegative(budget.committedCapitalMusd) ||
+        !nonnegative(budget.openMarginMusd))
+        return reject("capital_budget_unavailable");
+    adjustment.conservativeEquityMusd = equity;
+    const ticket = Math.min(spec.risk.perTradeMarginMusd, (equity * policy.perTicketCapitalPct) / 100);
+    const room = Math.min(ticket, (equity * policy.totalCapitalPct) / 100 - budget.committedCapitalMusd, budget.cashAvailableMusd - (equity * policy.cashReservePct) / 100);
+    if (!positive(room))
+        return reject("capital_allocation_or_reserve_exhausted");
+    if (action.type === "spot_order")
+        return { action, adjustment }; // retain quantity; quote gate owns its cost
+    if (action.type === "pm_open") {
+        const stake = centsDown(Math.min(room, (equity * policy.pmMaxLossPct) / 100));
+        adjustment.proposedAmountMusd = action.stakeMusd;
+        adjustment.sizedAmountMusd = stake;
+        adjustment.riskBudgetMusd = (equity * policy.pmMaxLossPct) / 100;
+        if (stake < 10)
+            return reject("capital_ticket_below_minimum");
+        return { action: { ...action, stakeMusd: stake }, adjustment };
+    }
+    if (action.type !== "futures_open")
+        return { action };
+    const mark = observation.watch.find((w) => w.symbol.toUpperCase() === action.symbol.toUpperCase())?.priceUsd;
+    const stop = action.stopLossPrice;
+    if (!positive(mark) ||
+        !positive(stop) ||
+        !positive(action.leverage) ||
+        (action.side === "long" ? stop >= mark : stop <= mark))
+        return reject("capital_stop_or_mark_unavailable");
+    const distance = Math.abs(mark - stop) / mark;
+    const fee = CAPITAL_FEE_BUFFER_BPS / 10_000;
+    const riskPerMargin = action.leverage * (distance + fee * (1 + stop / mark));
+    const riskBudget = (equity * policy.futuresRiskPct) / 100;
+    const margin = centsDown(Math.min(ticket, riskBudget / riskPerMargin, spec.limits.maxOpenMarginMusd - budget.openMarginMusd, room / (1 + action.leverage * fee)));
+    Object.assign(adjustment, {
+        proposedAmountMusd: action.marginMusd,
+        sizedAmountMusd: margin,
+        riskBudgetMusd: riskBudget,
+        feeBufferBps: CAPITAL_FEE_BUFFER_BPS,
+    });
+    if (margin < 10)
+        return reject("capital_ticket_below_minimum");
+    return { action: { ...action, marginMusd: margin }, adjustment };
+}
+/** Quote-bound monetary checks. Drift fails closed; never requote a resized
+ * ticket, silently widen a cap, or credit uncertain close/sell proceeds. */
+export function validateCapitalAction(action, spec, observation, budget, quote) {
+    if (!usesCapitalSizing(spec) || !increases(action))
+        return undefined;
+    if (validateCapitalSizingPolicy(spec.capitalSizing).length > 0)
+        return "capital_policy_invalid";
+    if (observation.capitalBook?.status !== "ready")
+        return "capital_book_unavailable";
+    const p = spec.capitalSizing, equity = observation.capitalBook.conservativeEquityMusd;
+    if (!positive(equity) ||
+        !nonnegative(budget.cashAvailableMusd) ||
+        !nonnegative(budget.committedCapitalMusd) ||
+        !nonnegative(budget.openMarginMusd))
+        return "capital_budget_unavailable";
+    let cost, allocated;
+    if (action.type === "pm_open") {
+        cost = allocated = action.stakeMusd;
+        if (cost > (equity * p.pmMaxLossPct) / 100 + 1e-8)
+            return "capital_pm_max_loss_exceeded";
+    }
+    else if (action.type === "spot_order") {
+        cost = allocated = capitalSpotBuyCost(action, quote);
+        // Without a stop model, the entire spot buy is the capital at risk.
+        if (positive(cost) && cost > (equity * p.futuresRiskPct) / 100 + 1e-8)
+            return "capital_spot_risk_exceeded";
+    }
+    else if (action.type === "futures_open") {
+        const entry = quote?.entryPrice, stop = action.stopLossPrice, target = action.takeProfitPrice;
+        const bps = quote?.futuresFeeBps, entryFee = quote?.estimatedEntryFeeMusd;
+        cost = quote?.cashRequiredMusd;
+        allocated = action.marginMusd;
+        if (!positive(entry) ||
+            !positive(stop) ||
+            !positive(target) ||
+            !nonnegative(bps) ||
+            !nonnegative(entryFee) ||
+            !positive(cost))
+            return "capital_quote_cost_evidence_missing";
+        const notional = action.marginMusd * action.leverage;
+        const feeRate = bps / 10_000;
+        if (Math.abs(entryFee - notional * feeRate) > CENT_TOLERANCE ||
+            Math.abs(cost - action.marginMusd - entryFee) > CENT_TOLERANCE)
+            return "capital_quote_cost_mismatch";
+        const adverse = action.side === "long" ? entry - stop : stop - entry;
+        const favorable = action.side === "long" ? target - entry : entry - target;
+        if (!(adverse > 0) || !(favorable > 0))
+            return "capital_stop_target_wrong_side";
+        const risk = (notional * adverse) / entry +
+            entryFee +
+            ((notional * stop) / entry) * feeRate;
+        const reward = (notional * favorable) / entry -
+            entryFee -
+            ((notional * target) / entry) * feeRate;
+        if (risk > (equity * p.futuresRiskPct) / 100 + 1e-8)
+            return "capital_quote_stop_risk_exceeded";
+        if (reward / risk + 1e-8 < p.minRewardRisk)
+            return "capital_quote_reward_risk_too_low";
+    }
+    if (!positive(cost) || !positive(allocated))
+        return "capital_quote_cost_evidence_missing";
+    if (cost >
+        Math.min(spec.risk.perTradeMarginMusd, (equity * p.perTicketCapitalPct) / 100) +
+            1e-8)
+        return "capital_ticket_cap_exceeded";
+    if (budget.committedCapitalMusd + cost >
+        (equity * p.totalCapitalPct) / 100 + 1e-8)
+        return "capital_combined_allocation_exceeded";
+    if (budget.cashAvailableMusd - cost <
+        (equity * p.cashReservePct) / 100 - 1e-8)
+        return "capital_cash_reserve_exceeded";
+    return undefined;
+}
+/** Fee-inclusive opt-in reservation; the legacy gross helper stays unchanged.
+ * The API quotes a market fill even for a pending limit/stop order. Reserve at
+ * least that fee, scaled up if the proposed price requires more notional.
+ * This is conservative captured quote evidence, not a future fill guarantee. */
+export function capitalSpotBuyCost(action, quote) {
+    const gross = spotBuyCost(action, quote);
+    const quotedGross = quote?.estimatedCostMusd;
+    const fee = quote?.estimatedFeeMusd;
+    if (!positive(gross) || !positive(quotedGross) || !nonnegative(fee))
+        return undefined;
+    const cost = gross + fee * Math.max(1, gross / quotedGross);
+    return positive(cost) ? cost : undefined;
+}
+export function capitalCashCost(action, quote) {
+    if (action.type === "futures_open")
+        return quote?.cashRequiredMusd ?? action.marginMusd;
+    if (action.type === "pm_open")
+        return action.stakeMusd;
+    if (action.type === "spot_order" && action.side === "buy")
+        return capitalSpotBuyCost(action, quote) ?? Number.NaN;
+    return 0;
+}