@coinrithm/mcp-trading 0.7.7 → 0.7.9

package/dist/agent/capitalSizing.js

@@ -0,0 +1,270 @@
+// 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;
+// Paper settlement writers use EPS=1e-8 on floating-point frozen balances.
+// Thawing the final position can leave negative dust (observed: -6.82e-13).
+// Normalize only that bounded frozen residue, never spendable cash or debt.
+// This is much tighter than reconciliation tolerance and does not edit balances.
+const FROZEN_RESIDUE_TOLERANCE = 1e-8;
+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), rawCash = asObj(w.usdt);
+    const cash = { ...rawCash };
+    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) {
+        const walletValue = asNum(rawCash[key]);
+        const portfolioValue = asNum(eq[key]);
+        const minimum = key === "available" ? 0 : -FROZEN_RESIDUE_TOLERANCE;
+        if (walletValue === undefined ||
+            portfolioValue === undefined ||
+            walletValue < minimum ||
+            portfolioValue < minimum ||
+            // Compare raw reads first: normalization must not hide snapshot drift.
+            Math.abs(walletValue - portfolioValue) > CENT_TOLERANCE)
+            return unavailable("cash_partitions_incomplete_or_changed");
+        cash[key] = Math.max(0, walletValue);
+    }
+    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;
+}

package/dist/agent/client.d.ts

@@ -1,5 +1,6 @@
 import { AgentTrace, ApiResult } from "./types.js";
 export declare const DEFAULT_BASE_URL = "https://api.coinrithm.com";
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 export type ProvenanceReport = {
     runtimeKind?: "hosted_scheduler" | "self_host_runner" | "byo_api" | "mcp_tool";
     packageVersion?: string;
@@ -21,14 +22,20 @@ export interface ClientConfig {
     fetchFn?: typeof fetch;
     sleepFn?: (ms: number) => Promise<void>;
     maxRetries?: number;
+    /** Total deadline, including response bodies and all 429 retry waits. */
+    requestTimeoutMs?: number;
+    /** Optional caller cancellation, applied to each request from this client. */
+    signal?: AbortSignal;
     extraHeaders?: Record<string, string>;
 }
 export declare class CoinRithmClient {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly fetchFn;
-    private readonly sleepFn;
+    private readonly sleepFn?;
     private readonly maxRetries;
+    private readonly requestTimeoutMs;
+    private readonly signal?;
     private readonly extraHeaders?;
     rateLimitHits: number;
     constructor(cfg: ClientConfig);

package/dist/agent/client.js

@@ -4,8 +4,10 @@
 // from an agent file). 429 backs off on Retry-After; 401/403/409/422 are
 // FAIL-CLOSED cycle outcomes (returned, not retried). fetch + sleep are
 // injectable so tests run with no network and no real waits.
-import { sleep as realSleep } from "./util.js";
+import { setTimeout as sleep } from "node:timers/promises";
+import { retryAfterSeconds } from "../retryAfter.js";
 export const DEFAULT_BASE_URL = "https://api.coinrithm.com";
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 function traceHeaders(trace) {
     const h = {};
     if (!trace)
@@ -30,6 +32,8 @@ export class CoinRithmClient {
     fetchFn;
     sleepFn;
     maxRetries;
+    requestTimeoutMs;
+    signal;
     extraHeaders;
     // Every 429 seen this session (read or write, retried or not) — feeds the
     // rate-limit-pressure kill-switch, which a write-only counter would miss.
@@ -38,8 +42,15 @@ export class CoinRithmClient {
         this.apiKey = cfg.apiKey;
         this.baseUrl = (cfg.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
         this.fetchFn = cfg.fetchFn ?? fetch;
-        this.sleepFn = cfg.sleepFn ?? realSleep;
+        this.sleepFn = cfg.sleepFn;
         this.maxRetries = cfg.maxRetries ?? 3;
+        this.requestTimeoutMs = cfg.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        if (!Number.isSafeInteger(this.requestTimeoutMs) ||
+            this.requestTimeoutMs < 1 ||
+            this.requestTimeoutMs > 2_147_483_647) {
+            throw new Error("requestTimeoutMs must be an integer between 1 and 2147483647");
+        }
+        this.signal = cfg.signal;
         this.extraHeaders = cfg.extraHeaders;
     }
     async request(method, path, opts = {}) {
@@ -59,53 +70,101 @@ export class CoinRithmClient {
         };
         if (opts.body !== undefined)
             headers["Content-Type"] = "application/json";
-        for (let attempt = 0;; attempt++) {
-            let res;
-            try {
-                res = await this.fetchFn(url.toString(), {
+        const controller = new AbortController();
+        let timedOut = false;
+        const cancel = () => controller.abort(new Error("API request cancelled"));
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort(new Error("API request deadline exceeded"));
+        }, this.requestTimeoutMs);
+        this.signal?.addEventListener("abort", cancel, { once: true });
+        if (this.signal?.aborted)
+            cancel();
+        let rejectAborted;
+        const aborted = new Promise((_, reject) => {
+            rejectAborted = () => reject(controller.signal.reason);
+            controller.signal.addEventListener("abort", rejectAborted, {
+                once: true,
+            });
+            if (controller.signal.aborted)
+                rejectAborted();
+        });
+        const perform = async () => {
+            for (let attempt = 0;; attempt++) {
+                controller.signal.throwIfAborted();
+                const res = await this.fetchFn(url.toString(), {
                     method,
                     headers,
                     body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+                    signal: controller.signal,
                 });
-            }
-            catch (err) {
-                return {
-                    ok: false,
-                    status: 0,
-                    data: {
-                        error: "network_error",
-                        message: err instanceof Error ? err.message : String(err),
-                    },
-                };
-            }
-            const retryAfter = Number(res.headers.get("retry-after"));
-            if (res.status === 429)
-                this.rateLimitHits += 1;
-            if (res.status === 429 && attempt < this.maxRetries) {
-                await this.sleepFn((Number.isFinite(retryAfter) ? retryAfter : 5) * 1000);
-                continue;
-            }
-            const text = await res.text();
-            let data = text;
-            if (text) {
-                try {
-                    data = JSON.parse(text);
+                controller.signal.throwIfAborted();
+                const retryAfter = retryAfterSeconds(res.headers.get("retry-after"));
+                if (res.status === 429)
+                    this.rateLimitHits += 1;
+                if (res.status === 429 && attempt < this.maxRetries) {
+                    // Release this response before waiting so retries do not retain sockets.
+                    void res.body?.cancel().catch(() => { });
+                    const delayMs = (retryAfter ?? 5) * 1000;
+                    // Never shorten a provider's Retry-After or overflow a Node timer.
+                    if (delayMs >= this.requestTimeoutMs)
+                        await aborted;
+                    else if (this.sleepFn)
+                        await this.sleepFn(delayMs);
+                    else
+                        await sleep(delayMs, undefined, { signal: controller.signal });
+                    continue;
                 }
-                catch {
-                    /* leave as text */
+                const text = await res.text();
+                controller.signal.throwIfAborted();
+                let data = text;
+                if (text) {
+                    try {
+                        data = JSON.parse(text);
+                    }
+                    catch {
+                        /* leave as text */
+                    }
                 }
+                return {
+                    ok: res.ok,
+                    status: res.status,
+                    data,
+                    retryAfterSeconds: res.status === 429 ? retryAfter : undefined,
+                    rateLimitRemaining: Number(res.headers.get("ratelimit-remaining")) || undefined,
+                    ledgerEventId: res.headers.get("x-coinrithm-ledger-event-id"),
+                };
             }
+        };
+        try {
+            // The race also bounds injected transports that do not honor AbortSignal.
+            return await Promise.race([perform(), aborted]);
+        }
+        catch (err) {
             return {
-                ok: res.ok,
-                status: res.status,
-                data,
-                retryAfterSeconds: res.status === 429 && Number.isFinite(retryAfter)
-                    ? retryAfter
-                    : undefined,
-                rateLimitRemaining: Number(res.headers.get("ratelimit-remaining")) || undefined,
-                ledgerEventId: res.headers.get("x-coinrithm-ledger-event-id"),
+                ok: false,
+                status: 0,
+                data: {
+                    error: timedOut
+                        ? "request_timeout"
+                        : controller.signal.aborted
+                            ? "request_aborted"
+                            : "network_error",
+                    message: timedOut
+                        ? `API request exceeded ${this.requestTimeoutMs}ms deadline`
+                        : controller.signal.aborted
+                            ? "API request cancelled"
+                            : err instanceof Error
+                                ? err.message
+                                : String(err),
+                },
             };
         }
+        finally {
+            clearTimeout(timer);
+            this.signal?.removeEventListener("abort", cancel);
+            controller.signal.removeEventListener("abort", rejectAborted);
+        }
     }
     // ── reads ──────────────────────────────────────────────────────────────────
     me(trace) {