@coinrithm/mcp-trading 0.7.13 → 0.7.15

package/dist/agent/definitionSnapshot.js

@@ -0,0 +1,28 @@
+import { INDICATOR_VERSION } from "./indicators.js";
+import { COINRITHM_API, RESOLVER_VERSION } from "./version.js";
+import { sha256, stableStringify } from "./util.js";
+/**
+ * Binds the compiled definition and declared engine versions, not the original
+ * source folder alone. This is an integrity/comparison hash, not a signature,
+ * complete replay record, or attestation of a particular deployed binary.
+ */
+export function buildAgentDefinitionSnapshot(spec, mergedProse) {
+    const definition = {
+        schema: "coinrithm.agent-definition.v1",
+        engine: {
+            packageVersion: COINRITHM_API.mcpVersion,
+            resolverVersion: RESOLVER_VERSION,
+            indicatorVersion: INDICATOR_VERSION,
+            apiContractVersion: COINRITHM_API.openapiVersion,
+        },
+        spec,
+        mergedProse,
+    };
+    // Detach from caller-owned spec: later mutations must not invalidate a saved
+    // artifact while leaving its old hash attached to it.
+    const serialized = stableStringify(definition);
+    return {
+        ...JSON.parse(serialized),
+        definitionHash: sha256(serialized),
+    };
+}

package/dist/agent/engine.d.ts

@@ -1,4 +1,5 @@
 export { runCycle, type RunnerDeps } from "./runner.js";
+export { buildAgentDefinitionSnapshot, type AgentDefinitionSnapshot, } from "./definitionSnapshot.js";
 export { DECISION_INPUT_MAX_BYTES, sanitizeDecisionInputRecord, type DecisionInputRecord, } from "./decisionReceipt.js";
 export { selectProvider, providerForRoute, classifyProviderFailure, type ProviderEnv, type Provider, type DecideInput, type DecideResult, type DecideRouteAttempt, type DecideRouteMeta, } from "./providers.js";
 export { parseDecision } from "./decision.js";

package/dist/agent/engine.js

@@ -6,6 +6,7 @@
 // This barrel is the ONE import a host scheduler needs; it re-exports only the
 // stable engine pieces, never the CLI.
 export { runCycle } from "./runner.js";
+export { buildAgentDefinitionSnapshot, } from "./definitionSnapshot.js";
 export { DECISION_INPUT_MAX_BYTES, sanitizeDecisionInputRecord, } from "./decisionReceipt.js";
 export { selectProvider, providerForRoute, classifyProviderFailure, } from "./providers.js";
 export { parseDecision } from "./decision.js";

package/dist/agent/futuresEligibility.d.ts

@@ -0,0 +1,36 @@
+import type { Observation, ProposedAction } from "./types.js";
+export type FuturesEntryEligibilityStatus = "eligible" | "reference_stale" | "reference_unavailable";
+export interface FuturesEntryEligibility {
+    status: FuturesEntryEligibilityStatus;
+    /** Whether the server gate currently requires a reference for NEW opens. */
+    referenceRequired: boolean;
+    venue: string | null;
+    symbol: string | null;
+    referenceFetchedAt: string | null;
+    maxReferenceAgeHours: number;
+    evaluatedAt: string;
+}
+/**
+ * Strict parse of the market context field against its contract (backend-v2
+ * #106). Anything missing or malformed (an older API, a partial response, an
+ * unknown status, a non-boolean referenceRequired, a missing or invalid
+ * evaluatedAt, a non-positive or non-finite maxReferenceAgeHours, or a present
+ * but invalid referenceFetchedAt) is `undefined` = UNKNOWN. Unknown never
+ * blocks: the runner keeps today's behaviour and the server gate decides.
+ */
+export declare function futuresEntryEligibilityOf(marketContext: unknown): FuturesEntryEligibility | undefined;
+export interface FuturesEntryPreflightRejection {
+    code: "futures_reference_unavailable" | "futures_reference_stale";
+    reason: string;
+}
+/**
+ * Pre-quote check for a NEW futures open. Returns a rejection only when the
+ * observation EXPLICITLY reports that the server gate requires a reference and
+ * has none (or only a stale one) for this coin. Everything else passes:
+ * - non-futures_open actions (spot, PM, futures_close / futures_set_sltp);
+ * - any open futures position on the same coin (the open is an add or position
+ *   management, which the server never refuses for the reference);
+ * - unknown eligibility (field absent on an older API);
+ * - referenceRequired false.
+ */
+export declare function futuresEntryPreflight(action: ProposedAction, observation: Observation): FuturesEntryPreflightRejection | null;

package/dist/agent/futuresEligibility.js

@@ -0,0 +1,90 @@
+// Futures entry eligibility (API >= backend-v2 #106): GET /api/agent/market/{coinId}
+// carries `futuresEntryEligibility`, what the server entry gate's own
+// perpetual-reference rule says about a NEW futures open on the coin. Before it,
+// universe_scan surfaced coins with no supported perpetual reference (tokenized
+// ETFs such as SLVON/NAKA) and the runner spent a futures quote only to be
+// refused with perpetual_reference_unavailable (J-74). The server gate stays
+// authoritative: eligibility can change between observation and execution.
+import { asObj, asStr } from "./extract.js";
+import { baseSymbol } from "./setups.js";
+const STATUSES = [
+    "eligible",
+    "reference_stale",
+    "reference_unavailable",
+];
+// A zoned ISO 8601 date-time (the contract's `format: date-time`):
+// YYYY-MM-DDTHH:MM[:SS[.fraction]] with Z or a +/-HH:MM offset. Date-only,
+// zone-less and bare numbers ("0") are rejected even though Date.parse
+// accepts them.
+const ZONED_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/;
+const isIsoDate = (v) => typeof v === "string" &&
+    ZONED_DATE_TIME.test(v) &&
+    Number.isFinite(Date.parse(v));
+/**
+ * Strict parse of the market context field against its contract (backend-v2
+ * #106). Anything missing or malformed (an older API, a partial response, an
+ * unknown status, a non-boolean referenceRequired, a missing or invalid
+ * evaluatedAt, a non-positive or non-finite maxReferenceAgeHours, or a present
+ * but invalid referenceFetchedAt) is `undefined` = UNKNOWN. Unknown never
+ * blocks: the runner keeps today's behaviour and the server gate decides.
+ */
+export function futuresEntryEligibilityOf(marketContext) {
+    const raw = asObj(asObj(marketContext).futuresEntryEligibility);
+    const status = asStr(raw.status);
+    if (!status || !STATUSES.includes(status))
+        return undefined;
+    if (typeof raw.referenceRequired !== "boolean")
+        return undefined;
+    const hours = raw.maxReferenceAgeHours;
+    if (typeof hours !== "number" || !Number.isFinite(hours) || hours <= 0)
+        return undefined;
+    if (!isIsoDate(raw.evaluatedAt))
+        return undefined;
+    const fetchedAt = raw.referenceFetchedAt;
+    if (fetchedAt != null && !isIsoDate(fetchedAt))
+        return undefined;
+    return {
+        status,
+        referenceRequired: raw.referenceRequired,
+        venue: asStr(raw.venue) ?? null,
+        symbol: asStr(raw.symbol) ?? null,
+        referenceFetchedAt: fetchedAt ?? null,
+        maxReferenceAgeHours: hours,
+        evaluatedAt: raw.evaluatedAt,
+    };
+}
+/**
+ * Pre-quote check for a NEW futures open. Returns a rejection only when the
+ * observation EXPLICITLY reports that the server gate requires a reference and
+ * has none (or only a stale one) for this coin. Everything else passes:
+ * - non-futures_open actions (spot, PM, futures_close / futures_set_sltp);
+ * - any open futures position on the same coin (the open is an add or position
+ *   management, which the server never refuses for the reference);
+ * - unknown eligibility (field absent on an older API);
+ * - referenceRequired false.
+ */
+export function futuresEntryPreflight(action, observation) {
+    if (action.type !== "futures_open")
+        return null;
+    const base = baseSymbol(action.symbol);
+    const holdsCoin = (observation.openPositions ?? []).some((p) => p.venue === "futures" &&
+        (p.status ?? "open") === "open" &&
+        baseSymbol(p.symbol) === base);
+    if (holdsCoin)
+        return null;
+    const entry = observation.watch.find((w) => baseSymbol(w.symbol) === base);
+    const e = entry?.futuresEntryEligibility;
+    if (!e || !e.referenceRequired || e.status === "eligible")
+        return null;
+    const when = ` at ${e.evaluatedAt}`;
+    if (e.status === "reference_stale") {
+        return {
+            code: "futures_reference_stale",
+            reason: `${action.symbol}: the perpetual reference${e.venue ? ` (${e.venue})` : ""} is stale or unusable for a NEW futures open${when} (too old, or its refresh time is missing, invalid or in the future); the server would refuse it (perpetual_reference_stale). Trade another coin or wait for a fresh reference.`,
+        };
+    }
+    return {
+        code: "futures_reference_unavailable",
+        reason: `${action.symbol}: CoinRithm has no supported perpetual reference for this coin${when}, so the server refuses a NEW futures open (perpetual_reference_unavailable). Use spot for it, or another coin for futures.`,
+    };
+}

package/dist/agent/mergeRules.d.ts

@@ -1,5 +1,5 @@
 import { ResolveIssue } from "./types.js";
-export type CapDirection = "lower" | "higher" | "true";
+export type CapDirection = "lower" | "lower_zero_off" | "higher" | "true";
 export declare const RISK_CAPS: Record<string, CapDirection>;
 export declare const LIMIT_CAPS: Record<string, CapDirection>;
 export declare function isAtLeastAsRestrictive(dir: CapDirection, candidate: unknown, base: unknown): boolean;

package/dist/agent/mergeRules.js

@@ -8,6 +8,9 @@
 //
 // Normal (non-cap) config uses simple precedence (inline > $ref > defaults),
 // handled in the resolver; this module owns only the cap arithmetic.
+// 0 is "no cap" for lower_zero_off; every other value compares as itself.
+const zeroOffLimit = (n) => (n === 0 ? Infinity : n);
+const isZeroOffValue = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0;
 // risk.* hard caps a tactic module may tighten.
 export const RISK_CAPS = {
     maxLeverage: "lower",
@@ -17,9 +20,9 @@ export const RISK_CAPS = {
 };
 // limits.* throughput/spend caps a tactic module may tighten.
 export const LIMIT_CAPS = {
-    maxTradesPerDay: "lower",
+    maxTradesPerDay: "lower_zero_off",
     maxWritesPerCycle: "lower",
-    maxDailyLossMusd: "lower",
+    maxDailyLossMusd: "lower_zero_off",
     maxOpenMarginMusd: "lower",
 };
 // Is `candidate` at least as restrictive as `base` (i.e. a legal tightening)?
@@ -29,6 +32,11 @@ export function isAtLeastAsRestrictive(dir, candidate, base) {
         // legal: base=false→candidate any; base=true→candidate must be true.
         return base === true ? candidate === true : true;
     }
+    if (dir === "lower_zero_off") {
+        if (!isZeroOffValue(candidate) || !isZeroOffValue(base))
+            return false;
+        return zeroOffLimit(candidate) <= zeroOffLimit(base);
+    }
     if (typeof candidate !== "number" || typeof base !== "number") {
         // a non-numeric cap candidate where a number is expected is not a legal
         // tightening (caller will surface a type issue separately).
@@ -40,6 +48,13 @@ export function isAtLeastAsRestrictive(dir, candidate, base) {
 export function mostRestrictive(dir, a, b) {
     if (dir === "true")
         return a === true || b === true ? true : false;
+    if (dir === "lower_zero_off") {
+        if (!isZeroOffValue(a))
+            return b;
+        if (!isZeroOffValue(b))
+            return a;
+        return zeroOffLimit(a) <= zeroOffLimit(b) ? a : b;
+    }
     if (typeof a !== "number")
         return b;
     if (typeof b !== "number")

package/dist/agent/observe.d.ts

@@ -1,9 +1,17 @@
 import { CoinRithmClient } from "./client.js";
-import { AgentSpec, RunState, Observation, AgentTrace } from "./types.js";
+import { AgentSpec, RunState, Observation, AgentTrace, PmCalibration, WhaleContext } from "./types.js";
 export interface ObserveOutput {
     observation: Observation;
     skip?: string;
 }
+/**
+ * Add bounded public whale context after the deterministic gate. This is
+ * deliberately separate from observe(): a skipped or mechanical cycle never
+ * pays for the public reads, and this context cannot widen candidate selection.
+ */
+export declare function enrichWhaleContext(client: CoinRithmClient, observation: Observation): Promise<WhaleContext>;
+export declare function clearPmCalibrationCache(): void;
+export declare function readPmCalibration(client: CoinRithmClient, trace?: AgentTrace, nowMs?: number): Promise<PmCalibration | undefined>;
 export declare function isCalibrationChurnMarket(market: {
     slug?: string;
     title?: string;