@coinrithm/mcp-trading 0.3.0 → 0.5.0

package/dist/agent/decision.js

@@ -3,34 +3,45 @@
 // JSON, an unknown action type, a free-form endpoint/tool name, extra unknown
 // fields, or a missing required field — fails closed (the runner skips).
 import { z } from "zod";
+// Small models (especially Llama 3.1 8B) frequently emit numbers as JSON strings
+// ("12345", "0.8", "62000"). Coerce a *clean* numeric string to a number before
+// validating; leave anything else untouched so genuine garbage ("abc", "pos#5")
+// still fails closed. This is why actions were being rejected with
+// "actions.0.positionId: Expected number, received string".
+const num = (inner) => z.preprocess((v) => (typeof v === "string" && v.trim() !== "" && Number.isFinite(Number(v)) ? Number(v) : v), inner);
+// Optional 0..1 confidence, tolerant of stringified/null input.
+const confidence = num(z.number().min(0).max(1))
+    .nullable()
+    .optional()
+    .transform((v) => v ?? undefined);
 const futuresOpen = z
     .object({
     type: z.literal("futures_open"),
     symbol: z.string().min(1),
     side: z.enum(["long", "short"]),
-    leverage: z.number().positive(),
-    marginMusd: z.number().positive(),
-    stopLossPrice: z.number().nullable().optional(),
-    takeProfitPrice: z.number().nullable().optional(),
-    confidence: z.number().min(0).max(1).optional(),
+    leverage: num(z.number().positive()),
+    marginMusd: num(z.number().positive()),
+    stopLossPrice: num(z.number()).nullable().optional(),
+    takeProfitPrice: num(z.number()).nullable().optional(),
+    confidence,
     rationaleSummary: z.string().optional(),
 })
     .strict();
 const futuresClose = z
     .object({
     type: z.literal("futures_close"),
-    positionId: z.number(),
-    fraction: z.number().positive().max(1).optional(),
-    confidence: z.number().min(0).max(1).optional(),
+    positionId: num(z.number()),
+    fraction: num(z.number().positive().max(1)).optional(),
+    confidence,
     rationaleSummary: z.string().optional(),
 })
     .strict();
 const futuresSetSltp = z
     .object({
     type: z.literal("futures_set_sltp"),
-    positionId: z.number(),
-    stopLossPrice: z.number().nullable().optional(),
-    takeProfitPrice: z.number().nullable().optional(),
+    positionId: num(z.number()),
+    stopLossPrice: num(z.number()).nullable().optional(),
+    takeProfitPrice: num(z.number()).nullable().optional(),
 })
     .strict();
 const spotOrder = z
@@ -39,27 +50,34 @@ const spotOrder = z
     symbol: z.string().min(1),
     side: z.enum(["buy", "sell"]),
     orderType: z.enum(["market", "limit", "stop"]),
-    quantity: z.number().positive(),
-    limitPrice: z.number().positive().optional(),
-    stopPrice: z.number().positive().optional(),
-    confidence: z.number().min(0).max(1).optional(),
+    quantity: num(z.number().positive()),
+    limitPrice: num(z.number().positive()).optional(),
+    stopPrice: num(z.number().positive()).optional(),
+    confidence,
     rationaleSummary: z.string().optional(),
 })
     .strict();
 const spotCancel = z
     .object({
     type: z.literal("spot_cancel"),
-    orderId: z.number(),
+    orderId: num(z.number()),
 })
     .strict();
+// pm_open accepts EITHER a short ref (pm1…pmN, what the prompt now asks for) OR
+// the full {source,slug,outcomeExternalMarketId} triple (back-compat for models
+// that copy ids correctly). The id fields are optional here; the runner's
+// resolvePmRef() fills them from the ref (or rejects a bad/missing ref) BEFORE
+// the validator/act phase, which require the triple. Kept a plain `.strict()`
+// object (not refined) so it stays valid inside the discriminatedUnion.
 const pmOpen = z
     .object({
     type: z.literal("pm_open"),
-    source: z.string().min(1),
-    slug: z.string().min(1),
-    outcomeExternalMarketId: z.string().min(1),
-    stakeMusd: z.number().positive(),
-    confidence: z.number().min(0).max(1).optional(),
+    ref: z.string().min(1).optional(),
+    source: z.string().min(1).optional(),
+    slug: z.string().min(1).optional(),
+    outcomeExternalMarketId: z.string().min(1).optional(),
+    stakeMusd: num(z.number().positive()),
+    confidence,
     rationaleSummary: z.string().optional(),
 })
     .strict();
@@ -74,11 +92,58 @@ export const actionSchema = z.discriminatedUnion("type", [
 const decisionSchema = z
     .object({
     decision: z.enum(["skip", "act"]),
-    confidence: z.number().min(0).max(1).optional(),
+    confidence,
     reason: z.string().optional(),
+    // The model's short analysis for this cycle. Allowed here so a model that
+    // explains its thinking isn't fail-closed by .strict(); capped so a runaway
+    // generation can't bloat the cycle record. Surfaced in the Arena terminal.
+    rationale: z.string().max(1200).optional(),
     actions: z.array(actionSchema).default([]),
 })
     .strict();
+// Weak/instruct models routinely answer the decision verb with a natural-language
+// synonym ("manage", "trade", "hold", "wait") instead of the strict skip|act enum
+// — which fail-closed the ENTIRE cycle on a zod enum error (observed live: Carl /
+// Nemotron 49B returning "manage" repeatedly, burning whole cycles). Normalize the
+// common synonyms to the canonical enum before validation; anything unrecognised
+// still falls through to the enum error. ("act" with no actions is already treated
+// as a skip downstream, so mapping a manage-with-no-action to "act" is harmless.)
+const DECISION_ALIASES = {
+    act: "act",
+    manage: "act",
+    trade: "act",
+    open: "act",
+    close: "act",
+    adjust: "act",
+    add: "act",
+    reduce: "act",
+    execute: "act",
+    enter: "act",
+    exit: "act",
+    rebalance: "act",
+    skip: "skip",
+    hold: "skip",
+    wait: "skip",
+    none: "skip",
+    nothing: "skip",
+    noop: "skip",
+    no_action: "skip",
+    pass: "skip",
+    monitor: "skip",
+    observe: "skip",
+    stay: "skip",
+};
+function normalizeDecisionVerb(obj) {
+    if (obj && typeof obj === "object" && !Array.isArray(obj)) {
+        const o = obj;
+        if (typeof o.decision === "string") {
+            const mapped = DECISION_ALIASES[o.decision.trim().toLowerCase()];
+            if (mapped)
+                o.decision = mapped;
+        }
+    }
+    return obj;
+}
 // Pull a JSON object out of a model response that may be fenced or wrapped.
 function coerceJson(text) {
     let s = text.trim();
@@ -96,7 +161,7 @@ function coerceJson(text) {
 export function parseDecision(text) {
     let obj;
     try {
-        obj = coerceJson(text);
+        obj = normalizeDecisionVerb(coerceJson(text));
     }
     catch (err) {
         return { ok: false, error: `model output is not valid JSON: ${err instanceof Error ? err.message : String(err)}` };
@@ -113,6 +178,12 @@ export function parseDecision(text) {
     const actions = d.decision === "act" ? d.actions : [];
     return {
         ok: true,
-        decision: { decision: d.decision, confidence: d.confidence, reason: d.reason, actions },
+        decision: {
+            decision: d.decision,
+            confidence: d.confidence,
+            reason: d.reason,
+            rationale: d.rationale,
+            actions,
+        },
     };
 }

package/dist/agent/decisionValidator.js

@@ -17,7 +17,11 @@ export function validateAction(action, ctx) {
     if (ctx.writesThisCycle >= spec.limits.maxWritesPerCycle) {
         return fail("write_budget_exceeded", `maxWritesPerCycle ${spec.limits.maxWritesPerCycle} reached`);
     }
-    if (ctx.writesToday >= spec.limits.maxTradesPerDay) {
+    // maxTradesPerDay <= 0 means UNLIMITED daily trade count — house agents are never
+    // throttled (we want an active Arena), and hosted agents only when the customer sets a
+    // positive cap. The risk caps below (daily loss, open margin, leverage, stops) are the
+    // real guardrails and always apply regardless of the trade-count cap.
+    if (spec.limits.maxTradesPerDay > 0 && ctx.writesToday >= spec.limits.maxTradesPerDay) {
         return fail("daily_trade_cap", `maxTradesPerDay ${spec.limits.maxTradesPerDay} reached`);
     }
     // Deny-list: an open on a blocked symbol is rejected up front (deny wins over
@@ -42,6 +46,20 @@ export function validateAction(action, ctx) {
             return fail("unknown_symbol", `${action.symbol} is not on the watchlist`);
         if (!entry.coinId)
             return fail("unresolved_symbol", `${action.symbol} did not resolve to a coin`);
+        // A futures_open on a symbol you ALREADY hold is treated as an ADD by the
+        // server, which REJECTS any SL/TP on an add (sl_tp_not_supported_on_add) and
+        // fails the whole open — the single biggest rejection class (e.g. Sam 61/61).
+        // Catch it here with an actionable reason: manage triggers on the held
+        // position via futures_set_sltp instead of re-opening with SL/TP. (Relies on
+        // the observation now carrying a populated `symbol` per position.)
+        if (action.stopLossPrice != null || action.takeProfitPrice != null) {
+            const heldSame = (observation.openPositions ?? []).find((p) => p.venue === "futures" &&
+                (p.status ?? "open") === "open" &&
+                (p.symbol ?? "").toUpperCase() === action.symbol.toUpperCase());
+            if (heldSame) {
+                return fail("add_cannot_carry_sltp", `already hold a ${action.symbol} futures position (#${heldSame.id}); the server rejects SL/TP on an add — manage triggers with futures_set_sltp on positionId ${heldSame.id}`);
+            }
+        }
         if (action.leverage > spec.risk.maxLeverage) {
             return fail("leverage_exceeds_cap", `leverage ${action.leverage} > cap ${spec.risk.maxLeverage}`);
         }
@@ -88,6 +106,28 @@ export function validateAction(action, ctx) {
                 }
             }
         }
+        // Take-profit must sit on the PROFIT side of entry, mirroring the server rule
+        // (long: TP above mark; short: below). A wrong-side TP makes the server reject
+        // the ENTIRE open (take_profit_not_above_mark / take_profit_not_below_mark) so
+        // NO trade is placed at all — the biggest silent missed-trade failure after
+        // the add case. Catch it here so the model gets a clear, self-correctable
+        // reason (and, with markPrice now in the observation, stops producing it).
+        {
+            const tp = action.takeProfitPrice;
+            const e = ctx.quote?.entryPrice;
+            if (tp != null &&
+                Number.isFinite(tp) &&
+                tp > 0 &&
+                typeof e === "number" &&
+                Number.isFinite(e)) {
+                if (action.side === "long" && tp <= e) {
+                    return fail("take_profit_wrong_side", `long take-profit ${tp} must be above entry ${e}`);
+                }
+                if (action.side === "short" && tp >= e) {
+                    return fail("take_profit_wrong_side", `short take-profit ${tp} must be below entry ${e}`);
+                }
+            }
+        }
         if (!ctx.quote)
             return fail("missing_quote", "no quote evidence was fetched for this open");
         if (!ctx.quote.eligible) {

package/dist/agent/deploymentOverlay.d.ts

@@ -0,0 +1,22 @@
+import { TriggerPolicy } from "./types.js";
+export type Tier = "free_demo" | "builder" | "pro" | "byok" | "house";
+export interface TierLimits {
+    maxLlmCallsPerHour: number;
+    minCadenceSeconds: number;
+    maxConcurrentAgents: number;
+}
+export declare const TIER_LIMITS: Record<Tier, TierLimits>;
+export declare function applyDeploymentOverlay(requested: TriggerPolicy, tier: Tier): TriggerPolicy;
+export declare function effectiveCadenceSeconds(requestedSeconds: number, tier: Tier): number;
+export interface EffectivePolicyView {
+    tier: Tier;
+    requested: {
+        maxLlmCallsPerHour: number;
+        cadenceSeconds: number;
+    };
+    effective: {
+        maxLlmCallsPerHour: number;
+        cadenceSeconds: number;
+    };
+}
+export declare function effectivePolicyView(requested: TriggerPolicy, requestedCadenceSeconds: number, tier: Tier): EffectivePolicyView;

package/dist/agent/deploymentOverlay.js

@@ -0,0 +1,55 @@
+// The deployment overlay — CoinRithm's server-side AUTHORITY over an agent's
+// runtime capacity. The OKF declares INTENT (its TriggerPolicy + cadence); the
+// platform caps it to the agent's effective TIER here. It only ever TIGHTENS,
+// never widens — so a forked OKF that sets `tier: pro` or `maxLlmCallsPerHour: 999`
+// can't self-grant capacity. This is where "the OKF asks, CoinRithm decides" lives,
+// and it's the prerequisite the monetization rule names: no paid tier without the
+// overlay. (Billing/Stripe wires a real tier onto the agent later; until then every
+// agent runs on a default tier and this still enforces it.)
+// Effective caps per tier. Tightenable later from config; these are the defaults.
+export const TIER_LIMITS = {
+    free_demo: { maxLlmCallsPerHour: 4, minCadenceSeconds: 3600, maxConcurrentAgents: 1 },
+    builder: { maxLlmCallsPerHour: 20, minCadenceSeconds: 900, maxConcurrentAgents: 3 },
+    pro: { maxLlmCallsPerHour: 120, minCadenceSeconds: 60, maxConcurrentAgents: 10 },
+    // BYO key = the user's own model quota, so we don't cap their calls; we still
+    // host + meter + verify (that's what they pay the infra fee for).
+    byok: { maxLlmCallsPerHour: 0, minCadenceSeconds: 60, maxConcurrentAgents: 5 },
+    // The house showcase fleet — uncapped, runs on our pooled keys.
+    house: { maxLlmCallsPerHour: 0, minCadenceSeconds: 60, maxConcurrentAgents: 0 },
+};
+// Tighten one numeric cap: 0 means "unlimited" on either side. The tier always wins
+// where it imposes a finite cap; it can never raise a request.
+function tighten(requested, tierCap) {
+    if (tierCap === 0)
+        return requested; // tier unlimited -> honor the request
+    if (requested === 0)
+        return tierCap; // request unlimited -> tier caps it
+    return Math.min(requested, tierCap); // both finite -> the tighter wins
+}
+// Cap the OKF's requested TriggerPolicy by the tier. NEVER widens.
+export function applyDeploymentOverlay(requested, tier) {
+    const lim = TIER_LIMITS[tier];
+    return {
+        ...requested,
+        maxLlmCallsPerHour: tighten(requested.maxLlmCallsPerHour, lim.maxLlmCallsPerHour),
+    };
+}
+// Effective cadence (seconds): the agent's requested cadence floored by the tier
+// (a free agent can't run every minute even if its OKF asks to).
+export function effectiveCadenceSeconds(requestedSeconds, tier) {
+    return Math.max(requestedSeconds, TIER_LIMITS[tier].minCadenceSeconds);
+}
+export function effectivePolicyView(requested, requestedCadenceSeconds, tier) {
+    const eff = applyDeploymentOverlay(requested, tier);
+    return {
+        tier,
+        requested: {
+            maxLlmCallsPerHour: requested.maxLlmCallsPerHour,
+            cadenceSeconds: requestedCadenceSeconds,
+        },
+        effective: {
+            maxLlmCallsPerHour: eff.maxLlmCallsPerHour,
+            cadenceSeconds: effectiveCadenceSeconds(requestedCadenceSeconds, tier),
+        },
+    };
+}

package/dist/agent/gate.d.ts

@@ -0,0 +1,9 @@
+import { Observation, RunState, TriggerPolicy } from "./types.js";
+export interface GateResult {
+    fire: boolean;
+    codes: string[];
+    reason: string;
+}
+export declare function evaluateGate(observation: Observation, state: RunState, policy: TriggerPolicy, nowMs: number): GateResult;
+export declare function noteLlmCall(state: RunState, codes: string[], nowMs: number): void;
+export declare function estimateCostUsd(provider: string, tokensIn: number, tokensOut: number): number;

package/dist/agent/gate.js

@@ -0,0 +1,114 @@
+// Slice-2 preflight gate: decides whether a cycle SPENDS an LLM call.
+//
+// content-engine's lesson made load-bearing: don't pay the model to stare at a
+// flat tape. A cycle only "fires" (calls the LLM) when a deterministic trigger is
+// present — a flagged entry setup, or an open position to manage. No trigger => a
+// cheap heartbeat skip, zero tokens. This is the cost/scale win (a free pool hosts
+// far more agents), the agentic feel (waits, then strikes), AND the metering
+// substrate (every cycle records what fired).
+//
+// Pure + deterministic: the caller injects nowMs so debounce/budget are testable
+// without timers. The gate NEVER widens a hard cap — it only decides whether to
+// think; the runner still validates every action against the caps.
+// Abs unrealized PnL (mUSD) on a single open position that counts as a swing worth
+// a fresh look even if no entry trigger fired.
+const BIG_SWING_MUSD = 150;
+// Map a flagged setup to its entry trigger code.
+function entryCode(s) {
+    switch (s.kind) {
+        case "breakout":
+            return "PRICE_BREAKOUT";
+        case "breakdown":
+            return "PRICE_BREAKDOWN";
+        case "uptrend":
+        case "downtrend":
+            return "MOMENTUM_TREND";
+        case "stretched":
+            return "RSI_EXTREME";
+    }
+}
+export function evaluateGate(observation, state, policy, nowMs) {
+    const codes = new Set();
+    // ENTRY triggers: a flagged setup we do NOT already hold is a fresh entry signal.
+    for (const s of observation.setups) {
+        if (!s.held)
+            codes.add(entryCode(s));
+    }
+    // MANAGE triggers: an open position is always evaluated through the manage path.
+    const hasPosition = observation.openPositions.length > 0;
+    if (hasPosition && policy.alwaysManageOpenPositions) {
+        codes.add("POSITION_OPEN");
+        for (const p of observation.openPositions) {
+            if (Math.abs(p.unrealizedPnlMusd ?? 0) >= BIG_SWING_MUSD) {
+                codes.add("POSITION_BIG_PNL_SWING");
+                break;
+            }
+        }
+    }
+    const codeList = [...codes];
+    // Legacy / explicit always-on: never gate (call every cycle).
+    if (policy.mode === "always" || !policy.skipLlmWhenNoTrigger) {
+        return {
+            fire: true,
+            codes: codeList,
+            reason: codeList.length ? `triggers: ${codeList.join(",")}` : "always-on",
+        };
+    }
+    // No price setup and no open position. Before skipping, periodically wake to
+    // evaluate PREDICTION MARKETS — they carry edge even when crypto prices are flat,
+    // so an agent on a quiet tape shouldn't go dark on PM. At most once per cooldown
+    // (gated on the last LLM call, which any fire resets), so it's not every cycle.
+    if (codeList.length === 0) {
+        const pmAvailable = observation.pmMarkets.length > 0;
+        const sinceLastCall = state.lastLlmCallAt == null ? Infinity : nowMs - state.lastLlmCallAt;
+        if (pmAvailable &&
+            policy.pmEvalCooldownMinutes > 0 &&
+            sinceLastCall >= policy.pmEvalCooldownMinutes * 60_000) {
+            return { fire: true, codes: ["PM_PERIODIC"], reason: "PM periodic eval (quiet price tape)" };
+        }
+        return { fire: false, codes: [], reason: "no trigger (flat tape, no open position)" };
+    }
+    // A real trigger exists. Open positions are NEVER starved by budget/debounce
+    // (managing a live position is always allowed); the caps below only throttle
+    // fresh entry-only cycles so a chop-storm of entry setups can't burn the budget.
+    if (!hasPosition) {
+        if (policy.maxLlmCallsPerHour > 0) {
+            const recent = (state.llmCallTimestamps ?? []).filter((t) => nowMs - t < 3_600_000);
+            if (recent.length >= policy.maxLlmCallsPerHour) {
+                return { fire: false, codes: codeList, reason: `hourly LLM budget ${policy.maxLlmCallsPerHour} reached` };
+            }
+        }
+        if (policy.debounceMinutes > 0) {
+            const fp = [...codeList].sort().join(",");
+            if (state.lastTriggerFingerprint === fp &&
+                state.lastLlmCallAt != null &&
+                nowMs - state.lastLlmCallAt < policy.debounceMinutes * 60_000) {
+                return { fire: false, codes: codeList, reason: `debounced (same triggers within ${policy.debounceMinutes}m)` };
+            }
+        }
+    }
+    return { fire: true, codes: codeList, reason: `triggers: ${codeList.join(",")}` };
+}
+// Record that this cycle spent an LLM call — feeds the budget + debounce next
+// cycle. Mutates state; the caller persists it.
+export function noteLlmCall(state, codes, nowMs) {
+    state.llmCallTimestamps = [...(state.llmCallTimestamps ?? []), nowMs]
+        .filter((t) => nowMs - t < 3_600_000)
+        .slice(-200);
+    state.lastLlmCallAt = nowMs;
+    state.lastTriggerFingerprint = [...codes].sort().join(",");
+}
+// Notional cost from a coarse per-provider blended rate ($/1M tokens). Free tiers
+// are ~$0; the number exists so tier pricing has real usage data to model from.
+const RATE_PER_MTOK = {
+    anthropic: 6,
+    openai: 2.5,
+    gemini: 0.3,
+    groq: 0.1,
+    nvidia: 0, // free hosted tier
+    "openai-compatible": 0.5,
+};
+export function estimateCostUsd(provider, tokensIn, tokensOut) {
+    const rate = RATE_PER_MTOK[provider] ?? 0;
+    return Math.round(((tokensIn + tokensOut) / 1_000_000) * rate * 1e6) / 1e6;
+}

package/dist/agent/indicators.js

@@ -119,14 +119,29 @@ export function computeIndicators(candles, opts = {}) {
     const ema50 = ema(closes, emaSlow);
     // Breakout vs the window BEFORE the latest candle (exclude the current bar).
     const prior = recentHighLow(candles.slice(0, -1), breakoutLookback);
+    const atr14 = atr(candles, atrPeriod);
+    const bb = bollinger(closes, bbPeriod);
+    const r20 = recentHighLow(candles, breakoutLookback);
+    const rsi14 = rsi(closes, rsiPeriod);
+    // Round numbers the model sees/echoes to clean significant figures, so reasoning
+    // reads "recent20 low 6.29216" not "6.292164535198927" — and stays clean for both
+    // $62k coins and sub-cent ones. The booleans below use the RAW locals, so the
+    // trend/breakout reads are unaffected.
+    const sig = (n, figs = 6) => {
+        if (!Number.isFinite(n) || n === 0)
+            return n;
+        const f = Math.pow(10, figs - Math.ceil(Math.log10(Math.abs(n))));
+        return Math.round(n * f) / f;
+    };
+    const sigN = (n, figs = 6) => (n == null ? null : sig(n, figs));
     return {
-        asOfClose: close,
-        rsi14: rsi(closes, rsiPeriod),
-        ema20,
-        ema50,
-        atr14: atr(candles, atrPeriod),
-        bollinger: bollinger(closes, bbPeriod),
-        recent20: recentHighLow(candles, breakoutLookback),
+        asOfClose: sig(close),
+        rsi14: rsi14 == null ? null : Math.round(rsi14 * 10) / 10,
+        ema20: sigN(ema20),
+        ema50: sigN(ema50),
+        atr14: sigN(atr14),
+        bollinger: bb == null ? null : { upper: sig(bb.upper), mid: sig(bb.mid), lower: sig(bb.lower) },
+        recent20: r20 == null ? null : { high: sig(r20.high), low: sig(r20.low) },
         aboveEma20: ema20 == null ? null : close > ema20,
         ema20AboveEma50: ema20 == null || ema50 == null ? null : ema20 > ema50,
         brokeRecentHigh: prior == null ? null : close >= prior.high,