@coinrithm/mcp-trading 0.1.7 → 0.2.0

package/dist/agent/strictLint.js

@@ -0,0 +1,164 @@
+// 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",
+    ],
+    sizing: null,
+    limits: [
+        "maxTradesPerDay",
+        "maxWritesPerCycle",
+        "maxDailyLossMusd",
+        "maxOpenMarginMusd",
+    ],
+    abstention: [
+        "onStaleData",
+        "onWeakSignal",
+        "onMissingQuote",
+        "onInsufficientBalance",
+        "minConfidence",
+    ],
+    sync: ["requirePollBeforeWrite"],
+    killSwitch: [
+        "maxDrawdownMusd",
+        "maxConsecutiveRejects",
+        "maxConsecutiveModelFailures",
+        "onRateLimitPressure",
+    ],
+    objective: ["primary", "secondary", "horizon"],
+};
+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.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 };
+}

package/dist/agent/types.js

@@ -0,0 +1,50 @@
+// Core types for the CoinRithm public agent runner.
+//
+// An "agent" is a single SKILL.md: machine-read frontmatter (the AgentSpec
+// types here) plus a plain-language strategy body. The runner reads the spec,
+// wakes on cadence, asks a model for proposed actions, validates them against
+// these caps, and acts via the CoinRithm paper API. Nothing here touches real
+// money.
+export const SPEC_VERSION = "coinrithm.agent.v1";
+export const VENUES = ["spot", "futures", "pm"];
+export const PROVIDERS = [
+    "anthropic",
+    "openai",
+    "groq",
+    "openai-compatible",
+];
+// What the agent declares it is optimizing for — so two similar-looking agents
+// are distinguishable and the scorecard/Arena can read intent.
+export const OBJECTIVE_PRIMARIES = [
+    "realized_pnl",
+    "risk_adjusted",
+    "drawdown_control",
+    "calibration",
+];
+// Opt-in capabilities beyond CoinRithm market reads + paper execution.
+// RESERVED in v1: declared + validated here, wired into the runner in a later
+// slice. `websearch` = external lookups (an injection surface + a cost — it can
+// inform reasoning but NEVER widen a cap, since caps live in the runner);
+// `indicators` = runner-computed RSI/MACD/etc. fed into the observation.
+export const ALLOWED_CAPABILITIES = ["websearch", "indicators"];
+export const ok = () => ({ valid: true });
+export const fail = (code, reason) => ({
+    valid: false,
+    code,
+    reason,
+});
+export function actionVenue(a) {
+    if (a.type.startsWith("futures"))
+        return "futures";
+    if (a.type.startsWith("spot"))
+        return "spot";
+    return "pm";
+}
+export function isWriteAction(a) {
+    // Every proposed action mutates state (set-sltp/cancel included). The model
+    // never proposes a read; reads are the runner's job during observe.
+    return true;
+}
+export function isOpenAction(a) {
+    return a.type === "futures_open" || a.type === "spot_order" || a.type === "pm_open";
+}

package/dist/agent/util.js

@@ -0,0 +1,112 @@
+// Small dependency-free helpers shared across the runner.
+import { createHash } from "node:crypto";
+import { resolve as resolvePath, relative as relativePath, isAbsolute } from "node:path";
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// Parse a cadence string ("30s", "15m", "1h", "4h", "1d") to milliseconds.
+// Returns null for anything unparseable so the skill validator can reject it.
+export function parseCadenceMs(cadence) {
+    if (typeof cadence !== "string")
+        return null;
+    const m = /^\s*(\d+)\s*(s|m|h|d)\s*$/i.exec(cadence);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    if (!Number.isFinite(n) || n <= 0)
+        return null;
+    const unit = m[2].toLowerCase();
+    const mult = unit === "s" ? 1000 : unit === "m" ? 60_000 : unit === "h" ? 3_600_000 : 86_400_000;
+    return n * mult;
+}
+// A UTC day key (YYYY-MM-DD) for resetting per-day counters.
+export function dayKey(d = new Date()) {
+    return d.toISOString().slice(0, 10);
+}
+// Deep-scan a parsed frontmatter object for anything that looks like a secret.
+// The skill file is meant to be committable and shareable; a real key must
+// NEVER live in it (keys are supplied at runtime via env / encrypted store).
+// Returns a list of human-readable findings (empty = clean).
+const SECRET_KEY_RE = /(^|[_.-])(api[_-]?key|secret|token|password|passwd|bearer|authorization|private[_-]?key)($|[_.-])/i;
+const SECRET_VALUE_RE = /(crk_live_[a-z0-9_]+|sk-[a-z0-9-]{16,}|sk_live_[a-z0-9]{16,}|ghp_[a-z0-9]{20,}|bearer\s+[a-z0-9._-]{12,}|AIza[a-z0-9_-]{20,})/i;
+export function scanForSecrets(value, pathPrefix = "", findings = []) {
+    if (value == null)
+        return findings;
+    if (typeof value === "string") {
+        if (SECRET_VALUE_RE.test(value)) {
+            findings.push(`value at "${pathPrefix || "(root)"}" looks like a secret/credential`);
+        }
+        return findings;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((v, i) => scanForSecrets(v, `${pathPrefix}[${i}]`, findings));
+        return findings;
+    }
+    if (typeof value === "object") {
+        for (const [k, v] of Object.entries(value)) {
+            const here = pathPrefix ? `${pathPrefix}.${k}` : k;
+            if (SECRET_KEY_RE.test(k)) {
+                findings.push(`field "${here}" must not appear in a skill file (secret-like key)`);
+            }
+            scanForSecrets(v, here, findings);
+        }
+    }
+    return findings;
+}
+// Short random id (for runId/decisionId/idempotencyKey suffixes).
+export function shortId() {
+    // randomUUID is available in Node 18+ (globalThis.crypto).
+    return crypto.randomUUID().slice(0, 8);
+}
+// ── Resolver helpers (cross-platform-deterministic) ──────────────────────────
+// Normalize file content for hashing: CRLF/CR -> LF, strip trailing whitespace,
+// so a Windows checkout and a Linux checkout of the same file hash identically.
+export function normalizeContent(text) {
+    return text
+        .replace(/^/, "") // strip UTF-8 BOM (Windows editors add it)
+        .replace(/\r\n/g, "\n")
+        .replace(/\r/g, "\n")
+        .replace(/\s+$/, "");
+}
+// SHA-256 of normalized content — the manifest lock's per-file contentHash.
+export function sha256(text) {
+    return ("sha256:" + createHash("sha256").update(normalizeContent(text), "utf8").digest("hex"));
+}
+// Canonical POSIX path (forward slashes) so the lock is byte-identical on
+// Windows and Linux.
+export function toPosix(p) {
+    return p.replace(/\\/g, "/");
+}
+// True iff `child` resolves to a location strictly inside `parent`
+// (path-traversal guard). A `$ref` that escapes the agent folder is rejected.
+export function isPathInside(parent, child) {
+    const rel = relativePath(resolvePath(parent), resolvePath(child));
+    return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+// Keep only the most-recent slice of a (possibly large) memory file so a growing
+// journal never blows the model context / the user's token budget.
+export function boundTail(text, maxLines, maxBytes) {
+    let lines = text.split("\n");
+    if (lines.length > maxLines)
+        lines = lines.slice(-maxLines);
+    let out = lines.join("\n");
+    if (Buffer.byteLength(out, "utf8") > maxBytes) {
+        out = Buffer.from(out, "utf8").subarray(-maxBytes).toString("utf8");
+    }
+    return out;
+}
+// Deterministic JSON: recursively sort object keys so two runs over the same
+// inputs produce a byte-identical manifest.lock.json.
+export function stableStringify(value) {
+    return JSON.stringify(sortDeep(value), null, 2);
+}
+export function sortDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortDeep);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const k of Object.keys(value).sort()) {
+            out[k] = sortDeep(value[k]);
+        }
+        return out;
+    }
+    return value;
+}

package/dist/agent/version.js

@@ -0,0 +1,16 @@
+// Versions stamped into manifest.lock.json so a resolved agent is reproducible
+// only against the exact compile that produced it.
+export const RUNNER_VERSION = "0.1.0";
+export const RESOLVER_VERSION = "1";
+export const MANIFEST_SCHEMA = "coinrithm.manifest.v1";
+// The CoinRithm execution surface a generated agent talks to. Written into
+// functionality/coinrithm.yaml as a version PIN; the CLI warns when an agent's
+// pin lags this, but never blocks self-host use.
+export const COINRITHM_API = {
+    kind: "coinrithm-agent-api",
+    baseUrl: "https://api.coinrithm.com",
+    mcpUrl: "https://mcp.coinrithm.com/mcp",
+    openapiVersion: "1.4.0",
+    mcpPackage: "@coinrithm/mcp-trading",
+    mcpVersion: "0.1.8",
+};

package/dist/tools.js

@@ -471,6 +471,20 @@ export function registerTools(server, client) {
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Export private agent ledger"),
     }, async ({ venue, eventType, runId, decisionId, status, from, to, agentTrace }, extra) => present(await client.exportLedger({ venue, eventType, runId, decisionId, status, from, to }, requestKey(extra), agentTrace)));
+    server.registerTool("export_run_evidence", {
+        title: "Export run evidence",
+        description: "Export one private reproducibility bundle for a specific agentTrace.runId. " +
+            "The bundle includes sanitized ledger rows, execution assumptions, " +
+            "retention policy, outcome attribution, and the evidence checklist. " +
+            "No public Arena user can see this data. " +
+            PAPER_NOTE,
+        inputSchema: {
+            runId: z.string().min(1).describe("Required run id to export."),
+            agentTrace: AGENT_TRACE_SCHEMA,
+        },
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Export run evidence"),
+    }, async ({ runId, agentTrace }, extra) => present(await client.exportLedger({ runId }, requestKey(extra), agentTrace)));
     server.registerTool("get_arena_leaderboard", {
         title: "Get Agent Arena leaderboard",
         description: "The public Agent Arena: opted-in agents ranked by total realized PnL " +