@coinrithm/mcp-trading 0.1.8 → 0.3.0

package/dist/agent/state.js

@@ -0,0 +1,96 @@
+// Local run state: the cursor, dedupe set, daily counters, and the kill-switch
+// inputs. Persisted to a JSON file so a re-run resumes where it left off.
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+import { dayKey } from "./util.js";
+import { asObj, asNum } from "./extract.js";
+// Disable after this many 429s in a session when killSwitch.onRateLimitPressure.
+const RATE_LIMIT_PRESSURE_THRESHOLD = 5;
+export function newState(runId) {
+    return {
+        runId,
+        cyclesRun: 0,
+        writesToday: 0,
+        realizedPnlMusd: 0,
+        peakRealizedMusd: 0,
+        consecutiveRejectCycles: 0,
+        consecutiveModelFailures: 0,
+        rateLimitHits: 0,
+        disabled: false,
+        dayKey: dayKey(),
+        cursor: null,
+        seen: [],
+        realizedPnlTodayMusd: 0,
+        consecutiveExecFailures: 0,
+        intentSeq: {},
+    };
+}
+// A corrupt EXISTING state file is FAIL-CLOSED: we refuse to run rather than
+// silently reset and (e.g.) re-enable a kill-switched agent or zero the daily
+// counters. A missing file is fine (fresh start).
+export function loadState(file, runId) {
+    if (file && existsSync(file)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch (e) {
+            throw new Error(`run state file is corrupt (${file}): ${e instanceof Error ? e.message : String(e)} — fix or delete it before running`);
+        }
+        const base = newState(parsed.runId ?? runId);
+        return rollDay({
+            ...base,
+            ...parsed,
+            seen: Array.isArray(parsed.seen) ? parsed.seen : [],
+            intentSeq: parsed.intentSeq && typeof parsed.intentSeq === "object" && !Array.isArray(parsed.intentSeq)
+                ? parsed.intentSeq
+                : {},
+        });
+    }
+    return newState(runId);
+}
+export function saveState(file, state) {
+    if (!file)
+        return;
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(state, null, 2), "utf8");
+}
+export function rollDay(state) {
+    const today = dayKey();
+    if (state.dayKey !== today) {
+        state.dayKey = today;
+        state.writesToday = 0;
+        state.realizedPnlTodayMusd = 0;
+    }
+    return state;
+}
+// Accrue realized PnL from newly-closed trades into both the session total (for
+// drawdown) and today's total (for the daily-loss cap). Dedupe by the caller.
+export function accrueRealized(state, closedTrades) {
+    for (const t of closedTrades) {
+        const pnl = asNum(asObj(t).realizedPnlMusd);
+        if (pnl != null) {
+            state.realizedPnlMusd += pnl;
+            state.realizedPnlTodayMusd += pnl;
+        }
+    }
+    if (state.realizedPnlMusd > state.peakRealizedMusd)
+        state.peakRealizedMusd = state.realizedPnlMusd;
+}
+// Returns a disable reason if any kill-switch condition is tripped, else null.
+export function checkKillSwitch(spec, state) {
+    const ks = spec.killSwitch;
+    if (ks.maxConsecutiveModelFailures > 0 && state.consecutiveModelFailures >= ks.maxConsecutiveModelFailures) {
+        return `consecutive model failures ${state.consecutiveModelFailures} >= ${ks.maxConsecutiveModelFailures}`;
+    }
+    if (ks.maxConsecutiveRejects > 0 && state.consecutiveRejectCycles >= ks.maxConsecutiveRejects) {
+        return `consecutive reject cycles ${state.consecutiveRejectCycles} >= ${ks.maxConsecutiveRejects}`;
+    }
+    if (ks.maxDrawdownMusd > 0 && state.peakRealizedMusd - state.realizedPnlMusd >= ks.maxDrawdownMusd) {
+        return `drawdown ${(state.peakRealizedMusd - state.realizedPnlMusd).toFixed(2)} >= ${ks.maxDrawdownMusd}`;
+    }
+    if (ks.onRateLimitPressure && state.rateLimitHits >= RATE_LIMIT_PRESSURE_THRESHOLD) {
+        return `rate-limit pressure: ${state.rateLimitHits} 429s this session`;
+    }
+    return null;
+}

package/dist/agent/strictLint.d.ts

@@ -0,0 +1,3 @@
+import { ResolveIssue } from "./types.js";
+export declare function levenshtein(a: string, b: string): number;
+export declare function strictLint(raw: Record<string, unknown>): ResolveIssue[];

package/dist/agent/strictLint.js

@@ -0,0 +1,165 @@
+// Strict key/enum lint over the RESOLVED frontmatter — the fix for the
+// "silently coerced to a default" footgun (Codex audit #9). A typo like
+// `maxLevrage: 3` must NOT silently become the default; it must be surfaced
+// (with a "did you mean" suggestion). The runner uses this in hosted mode to
+// fail closed; self-host can treat the issues as warnings.
+import { PROVIDERS, VENUES, ALLOWED_CAPABILITIES, OBJECTIVE_PRIMARIES, } from "./types.js";
+// Allowed keys per block. `null` = free-form (sizing is soft guidance; its
+// enforced-key ban is handled in the resolver, not here).
+const ALLOWED_KEYS = {
+    $root: [
+        "name",
+        "description",
+        "spec",
+        "mode",
+        "trigger",
+        "model",
+        "venues",
+        "risk",
+        "sizing",
+        "limits",
+        "abstention",
+        "sync",
+        "killSwitch",
+        "objective",
+        "capabilities",
+        "include",
+        "watchlist",
+    ],
+    trigger: ["cadence", "timezone", "events"],
+    model: ["provider", "name", "baseUrl"],
+    risk: [
+        "maxLeverage",
+        "perTradeMarginMusd",
+        "maxConcurrentPositions",
+        "requireStopLoss",
+        "watchlist",
+        "blocklist",
+    ],
+    sizing: null,
+    limits: [
+        "maxTradesPerDay",
+        "maxWritesPerCycle",
+        "maxDailyLossMusd",
+        "maxOpenMarginMusd",
+    ],
+    abstention: [
+        "onStaleData",
+        "onWeakSignal",
+        "onMissingQuote",
+        "onInsufficientBalance",
+        "minConfidence",
+    ],
+    sync: ["requirePollBeforeWrite"],
+    killSwitch: [
+        "maxDrawdownMusd",
+        "maxConsecutiveRejects",
+        "maxConsecutiveModelFailures",
+        "onRateLimitPressure",
+    ],
+    objective: ["primary", "secondary", "horizon"],
+};
+export function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const d = Array.from({ length: n + 1 }, (_, i) => i);
+    for (let i = 1; i <= m; i++) {
+        let prev = d[0];
+        d[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const tmp = d[j];
+            d[j] = Math.min(d[j] + 1, d[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = tmp;
+        }
+    }
+    return d[n];
+}
+function suggest(key, allowed) {
+    let best = null;
+    let bestDist = 3; // only suggest within edit distance 2
+    for (const cand of allowed) {
+        const dist = levenshtein(key.toLowerCase(), cand.toLowerCase());
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = cand;
+        }
+    }
+    return best;
+}
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function lintKeys(block, obj, issues) {
+    const allowed = ALLOWED_KEYS[block];
+    if (!allowed)
+        return; // free-form (null) or unknown block
+    for (const k of Object.keys(obj)) {
+        if (!allowed.includes(k)) {
+            const s = suggest(k, allowed);
+            issues.push({
+                code: "unknown_key",
+                path: block === "$root" ? k : `${block}.${k}`,
+                message: `unknown key "${k}"${s ? ` — did you mean "${s}"?` : ""}`,
+            });
+        }
+    }
+}
+export function strictLint(raw) {
+    const issues = [];
+    lintKeys("$root", raw, issues);
+    for (const block of [
+        "trigger",
+        "model",
+        "risk",
+        "limits",
+        "abstention",
+        "sync",
+        "killSwitch",
+        "objective",
+    ]) {
+        if (isObj(raw[block]))
+            lintKeys(block, raw[block], issues);
+    }
+    // Enum checks.
+    const model = raw.model;
+    if (isObj(model) &&
+        typeof model.provider === "string" &&
+        !PROVIDERS.includes(model.provider)) {
+        issues.push({
+            code: "bad_enum",
+            path: "model.provider",
+            message: `model.provider "${model.provider}" is not one of: ${PROVIDERS.join(", ")}`,
+        });
+    }
+    if (Array.isArray(raw.venues)) {
+        for (const v of raw.venues) {
+            if (!VENUES.includes(v)) {
+                issues.push({
+                    code: "bad_enum",
+                    path: "venues",
+                    message: `unknown venue "${String(v)}" (allowed: ${VENUES.join(", ")})`,
+                });
+            }
+        }
+    }
+    if (Array.isArray(raw.capabilities)) {
+        for (const c of raw.capabilities) {
+            if (!ALLOWED_CAPABILITIES.includes(c)) {
+                issues.push({
+                    code: "bad_enum",
+                    path: "capabilities",
+                    message: `unknown capability "${String(c)}" (allowed: ${ALLOWED_CAPABILITIES.join(", ")})`,
+                });
+            }
+        }
+    }
+    const objective = raw.objective;
+    if (isObj(objective) &&
+        typeof objective.primary === "string" &&
+        !OBJECTIVE_PRIMARIES.includes(objective.primary)) {
+        issues.push({
+            code: "bad_enum",
+            path: "objective.primary",
+            message: `objective.primary "${objective.primary}" is not one of: ${OBJECTIVE_PRIMARIES.join(", ")}`,
+        });
+    }
+    return issues;
+}

package/dist/agent/templates.d.ts

@@ -0,0 +1,14 @@
+export type PresetName = "conservative" | "balanced" | "bold";
+export declare const PRESET_NAMES: PresetName[];
+export interface AgentTemplate {
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+export declare function buildAgentObject(name: string, preset: PresetName): AgentTemplate;
+export declare function renderFolderOfOne(name: string, preset: PresetName): string;
+export declare function renderCoinrithmPin(): string;
+export declare function renderRuntime(model: unknown, trigger: unknown): string;
+export interface EjectResult {
+    files: Record<string, string>;
+}
+export declare function ejectFiles(fm: Record<string, unknown>, body: string): EjectResult;

package/dist/agent/templates.js

@@ -0,0 +1,192 @@
+// Agent templates + risk presets for the scaffolder.
+//
+// A `new` agent is a folder-of-one (a single agent.md) that ALWAYS emits the
+// hosted-required blocks (limits / abstention / sync / killSwitch) so it passes
+// `validate --hosted` out of the box. Presets differ only within safe ranges:
+// every preset is paper-only, keeps requireStopLoss=true, the kill-switch on,
+// and stays under the server caps (leverage <= 20). "bold" is faster + larger
+// but still safe.
+import { stringify as stringifyYaml } from "yaml";
+import { COINRITHM_API } from "./version.js";
+export const PRESET_NAMES = ["conservative", "balanced", "bold"];
+const PRESETS = {
+    conservative: {
+        leverage: 2,
+        margin: 50,
+        maxPos: 2,
+        tradesDay: 6,
+        writesCycle: 1,
+        dailyLoss: 300,
+        openMargin: 600,
+        minConf: 0.6,
+        cadence: "4h",
+        drawdown: 300,
+        modelFail: 3,
+    },
+    balanced: {
+        leverage: 3,
+        margin: 100,
+        maxPos: 3,
+        tradesDay: 12,
+        writesCycle: 2,
+        dailyLoss: 750,
+        openMargin: 2000,
+        minConf: 0.55,
+        cadence: "1h",
+        drawdown: 750,
+        modelFail: 4,
+    },
+    bold: {
+        leverage: 5,
+        margin: 250,
+        maxPos: 5,
+        tradesDay: 24,
+        writesCycle: 3,
+        dailyLoss: 2000,
+        openMargin: 5000,
+        minConf: 0.5,
+        cadence: "1h",
+        drawdown: 2000,
+        modelFail: 5,
+    },
+};
+const THESIS_BODY = `# Momentum Futures — strategy
+
+You operate a CoinRithm **paper-trading** futures account (50,000 virtual mUSD).
+Everything here is simulated; it is not financial advice and never touches real
+money. Edit this prose freely (any language) — it is your agent's borders.
+
+## Each cycle
+
+1. Ground yourself: read your portfolio and open positions first. Never assume
+   balances or what is already open.
+2. Scan the watchlist. A candidate is a coin whose short and medium momentum
+   agree (both up, or both down) and is not already an open position.
+3. Pick at most one strongest candidate. If nothing is clean, skip — a skipped
+   cycle is cheaper than a forced trade.
+4. Quote before you open. Read the liquidation price and confirm it is sane. If
+   the quote is not eligible, relay the reason and stop.
+5. Open small and protected: enter in the trend direction and set a stop-loss at
+   open. Place the take-profit a touch wider than the stop.
+6. Stay in sync: poll your trades for any stop / take-profit / liquidation that
+   fired while you were not looking, and react to what actually happened.
+
+The hard caps (leverage, margin, watchlist) live in the config blocks above and
+are enforced by the runner — change them there, not in this prose.`;
+const PERSONA_STUB = `# Persona
+
+Patient and selective. Prefers to skip rather than force a marginal trade.
+States its reasoning plainly and never frames paper results as real-money advice.
+`;
+export function buildAgentObject(name, preset) {
+    const p = PRESETS[preset];
+    const frontmatter = {
+        spec: "coinrithm.agent.v1",
+        name,
+        description: `Trend-following CoinRithm paper-trading agent (momentum-futures, ${preset}).`,
+        trigger: { cadence: p.cadence, timezone: "UTC" },
+        model: { provider: "anthropic", name: "claude-sonnet-4-6" },
+        venues: ["futures"],
+        risk: {
+            maxLeverage: p.leverage,
+            perTradeMarginMusd: p.margin,
+            maxConcurrentPositions: p.maxPos,
+            requireStopLoss: true,
+            watchlist: ["BTC", "ETH", "SOL"],
+        },
+        sizing: { riskRewardMin: 1.8, riskPerTradePct: 1, kellyFraction: 0.25 },
+        limits: {
+            maxTradesPerDay: p.tradesDay,
+            maxWritesPerCycle: p.writesCycle,
+            maxDailyLossMusd: p.dailyLoss,
+            maxOpenMarginMusd: p.openMargin,
+        },
+        abstention: {
+            onStaleData: true,
+            onWeakSignal: true,
+            onMissingQuote: true,
+            onInsufficientBalance: true,
+            minConfidence: p.minConf,
+        },
+        sync: { requirePollBeforeWrite: true },
+        killSwitch: {
+            maxDrawdownMusd: p.drawdown,
+            maxConsecutiveRejects: 0,
+            maxConsecutiveModelFailures: p.modelFail,
+            onRateLimitPressure: true,
+        },
+        objective: {
+            primary: "realized_pnl",
+            secondary: ["drawdown_control", "evidence_completeness"],
+            horizon: "7d",
+        },
+    };
+    return { frontmatter, body: THESIS_BODY };
+}
+export function renderFolderOfOne(name, preset) {
+    const { frontmatter, body } = buildAgentObject(name, preset);
+    return `---\n${stringifyYaml(frontmatter)}---\n\n${body}\n`;
+}
+export function renderCoinrithmPin() {
+    return stringifyYaml({
+        api: {
+            kind: COINRITHM_API.kind,
+            baseUrl: COINRITHM_API.baseUrl,
+            mcpUrl: COINRITHM_API.mcpUrl,
+            openapiVersion: COINRITHM_API.openapiVersion,
+            mcpPackage: COINRITHM_API.mcpPackage,
+            mcpVersion: COINRITHM_API.mcpVersion,
+        },
+        venues: ["spot", "futures", "pm"],
+        note: "Reference pin. The runner warns if this lags the live API; it does not block self-host.",
+    });
+}
+export function renderRuntime(model, trigger) {
+    return stringifyYaml({ mode: "self-host", model, trigger });
+}
+// Split a folder-of-one frontmatter+body into the decomposed layout. The
+// resolved AgentSpec must be unchanged (model/trigger via runtime.yaml extends;
+// risk/limits/abstention/killSwitch via $ref; venues/sync/sizing/objective stay
+// inline). Prose moves to character/thesis.md + persona.md.
+export function ejectFiles(fm, body) {
+    const files = {};
+    files["character/thesis.md"] = (body.trim() || THESIS_BODY) + "\n";
+    files["character/persona.md"] = PERSONA_STUB;
+    if (fm.risk)
+        files["character/risk.yaml"] = stringifyYaml(fm.risk);
+    if (fm.limits)
+        files["character/limits.yaml"] = stringifyYaml(fm.limits);
+    if (fm.abstention)
+        files["character/abstention.yaml"] = stringifyYaml(fm.abstention);
+    if (fm.killSwitch)
+        files["safety/killSwitch.yaml"] = stringifyYaml(fm.killSwitch);
+    files["runtime.yaml"] = renderRuntime(fm.model, fm.trigger);
+    files["functionality/coinrithm.yaml"] = renderCoinrithmPin();
+    const agentFm = {
+        spec: fm.spec,
+        name: fm.name,
+        description: fm.description,
+        extends: ["runtime.yaml"],
+        venues: fm.venues,
+        sync: fm.sync,
+    };
+    if (fm.sizing)
+        agentFm.sizing = fm.sizing;
+    if (fm.objective)
+        agentFm.objective = fm.objective;
+    if (fm.capabilities)
+        agentFm.capabilities = fm.capabilities;
+    if (fm.risk)
+        agentFm.risk = { $ref: "character/risk.yaml" };
+    if (fm.limits)
+        agentFm.limits = { $ref: "character/limits.yaml" };
+    if (fm.abstention)
+        agentFm.abstention = { $ref: "character/abstention.yaml" };
+    if (fm.killSwitch)
+        agentFm.killSwitch = { $ref: "safety/killSwitch.yaml" };
+    files["agent.md"] =
+        `---\n${stringifyYaml(agentFm)}---\n\n` +
+            `Strategy lives in [character/thesis.md](character/thesis.md); ` +
+            `persona in [character/persona.md](character/persona.md).\n`;
+    return { files };
+}