@coinrithm/mcp-trading 0.1.8 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to `@coinrithm/mcp-trading` are documented here. The package
+ships two binaries — `coinrithm-mcp` (the MCP server) and `coinrithm-agent` (the
+self-host agent runner) — versioned together. The CoinRithm **API contract** is
+versioned separately (see `openapi.yaml` `info.version`, currently `1.4.0`).
+
+## 0.3.0
+
+- **Agent risk config: coin deny-list (`blocklist`).** `risk.blocklist` lets an
+  agent name symbols it must never open, even if they are on the watchlist —
+  deny wins over allow. Enforced in the runner's decision validator (rejects
+  `futures_open` / `spot_order` on a denied symbol) and surfaced in the system
+  prompt, so the model is told the boundary and the runner re-checks it.
+- **Docs: Open Knowledge Format positioning.** Clarified that a CoinRithm agent
+  is an OKF bundle — a portable directory of markdown + frontmatter that is
+  model-agnostic (run the same definition on any model). Develop and prove it
+  free on paper, then run it anywhere.
+- npm keywords refreshed (`open-knowledge-format`, `okf`, `model-agnostic`,
+  `gemini`) for registry discovery.
+
+## 0.2.0
+
+- Added the **`coinrithm-agent`** self-host runner binary alongside the MCP
+  server: a folder-as-architecture (OKF) agent you bring your own model key to,
+  with caps enforced by the runner (not the model), dry-run by default,
+  paper-only.
+
+## 0.1.x
+
+- Initial `coinrithm-mcp` MCP server: reads, quotes, scoped spot/futures/PM
+  writes, ledger export, and Agent Arena integration over a user-minted API key.

package/README.md

@@ -1,7 +1,12 @@
 # @coinrithm/mcp-trading
 
-An MCP server that lets an AI agent paper-trade on CoinRithm (spot, futures,
-prediction markets) using a personal API key.
+CoinRithm paper-trading toolkit. Two binaries:
+
+- **`coinrithm-mcp`** — an MCP server that lets an AI agent paper-trade on
+  CoinRithm (spot, futures, prediction markets) using a personal API key.
+- **`coinrithm-agent`** — a self-host **agent runner**: author an agent as a
+  folder and run an observe→decide→validate→act loop with your own model key
+  (paper: spot, futures, prediction markets). See [Agent runner](#agent-runner-coinrithm-agent) below.
 
 > **Paper trading only** — virtual funds (50,000 mUSD). Not financial advice.
 
@@ -12,6 +17,25 @@ npm install
 npm run build
 ```
 
+## Agent runner (`coinrithm-agent`)
+
+This package also ships a **self-host agent runner**. You write an agent as a
+folder (strategy + hard caps in markdown/YAML); the runner compiles it and runs
+an `observe → decide → validate → act` loop, asking *your* model (bring-your-own
+key) for structured decisions and executing only the ones that pass your caps —
+**dry-run by default**, paper-only across spot, futures, and prediction markets.
+
+```bash
+coinrithm-agent new my-agent --preset conservative
+coinrithm-agent validate my-agent
+COINRITHM_API_KEY=crk_live_… ANTHROPIC_API_KEY=sk-ant-… \
+  coinrithm-agent run my-agent --once --dry-run
+```
+
+Full guide (env vars, fail-closed guarantees, folder layout):
+**[docs/agent-runner.md](../../docs/agent-runner.md)**. The CoinRithm hosted
+scheduler runs this same engine for you (later).
+
 ## Two ways to run
 
 | Mode | Entry | Auth | Who it's for |
@@ -59,11 +83,11 @@ key upstream. See [`DEPLOY.md`](./DEPLOY.md).
 | `get_market_context` (coinId) | read | `GET /api/agent/market/:coinId` |
 | `get_candles` (coinId, range) | read | `GET /api/agent/market/:coinId/candles` |
 | `discover_pm_markets` | read | `GET /api/agent/pm/discover` |
-| `get_performance` | read | `GET /api/agent/performance` |
-| `get_agent_ledger` | read | `GET /api/agent/ledger` |
-| `export_agent_ledger` | read | `GET /api/agent/ledger/export` |
-| `export_run_evidence` | read | `GET /api/agent/ledger/export?runId=...` |
-| `get_arena_leaderboard` | read | `GET /api/arena` |
+| `get_performance` | read | `GET /api/agent/performance` |
+| `get_agent_ledger` | read | `GET /api/agent/ledger` |
+| `export_agent_ledger` | read | `GET /api/agent/ledger/export` |
+| `export_run_evidence` | read | `GET /api/agent/ledger/export?runId=...` |
+| `get_arena_leaderboard` | read | `GET /api/arena` |
 | `get_arena_agent` (handle) | read | `GET /api/arena/:handle` |
 | `list_open_orders` | read | `GET /api/agent/orders/open` |
 | `get_positions` (venue) | read | `GET /api/agent/positions/{futures,pm}` |
@@ -125,18 +149,18 @@ account only, latest stored market/probability snapshots, no explicit
 commission/slippage in v1, no futures funding/fees, and worker-driven resting
 order / SL / TP / settlement timing. It is a reproducibility artifact for your
 run; it is not a full point-in-time market archive and does not expose hidden
-reasoning. Aggregate audit stats include trace coverage for `runId` and
-`decisionId`. Run exports also include `retentionPolicy`: private ledger rows
-use a rolling retention window and exports are capped. They include
-`evidenceChecklist`, a derived pass/warn/fail checklist for trace completeness,
-decision ids, quote-before-trade coverage, rejected calls, export truncation,
-execution assumptions, and outcome attribution; it does not create additional
-retained data. `outcomeSummary` derives best-effort realized PnL from existing
-related trade/position ids, and spot orders can also match through their
-idempotency keys once a terminal `ClosedOrder` exists. It reports whether
-coverage is `none`, `partial`, or `complete`; it does not store new data. Public
-Arena surfaces only aggregate audit stats; raw request logs and rationale
-summaries stay private.
+reasoning. Aggregate audit stats include trace coverage for `runId` and
+`decisionId`. Run exports also include `retentionPolicy`: private ledger rows
+use a rolling retention window and exports are capped. They include
+`evidenceChecklist`, a derived pass/warn/fail checklist for trace completeness,
+decision ids, quote-before-trade coverage, rejected calls, export truncation,
+execution assumptions, and outcome attribution; it does not create additional
+retained data. `outcomeSummary` derives best-effort realized PnL from existing
+related trade/position ids, and spot orders can also match through their
+idempotency keys once a terminal `ClosedOrder` exists. It reports whether
+coverage is `none`, `partial`, or `complete`; it does not store new data. Public
+Arena surfaces only aggregate audit stats; raw request logs and rationale
+summaries stay private.
 
 `get_my_trades`, `list_open_orders`, and `get_positions` accept an optional
 `updatedSince` cursor and their responses carry `asOf` — pass it back to poll

package/dist/agent/act.d.ts

@@ -0,0 +1,4 @@
+import { CoinRithmClient } from "./client.js";
+import { ProposedAction, AgentTrace, ApiResult, Observation, QuoteEvidence } from "./types.js";
+export declare function fetchQuote(client: CoinRithmClient, action: ProposedAction, observation: Observation, trace?: AgentTrace): Promise<QuoteEvidence | undefined>;
+export declare function executeAction(client: CoinRithmClient, action: ProposedAction, observation: Observation, trace: AgentTrace, idempotencyKey: string): Promise<ApiResult>;

package/dist/agent/act.js

@@ -0,0 +1,114 @@
+// Act phase: fetch the quote evidence for an open (the runner does this, never
+// the model) and execute a validated action (futures / spot / PM) with an
+// idempotency key.
+import { asObj, asNum, asStr } from "./extract.js";
+function coinIdFor(observation, symbol) {
+    return observation.watch.find((w) => w.symbol.toUpperCase() === symbol.toUpperCase())?.coinId ?? undefined;
+}
+function freshnessOf(block) {
+    const fr = asObj(block.freshness);
+    const status = asStr(fr.status);
+    return status ? { status, ageSeconds: asNum(fr.ageSeconds) } : undefined;
+}
+// Read-only quote BEFORE any open. Returns ineligible (never throws) on error.
+export async function fetchQuote(client, action, observation, trace) {
+    let r;
+    if (action.type === "futures_open") {
+        const coinId = coinIdFor(observation, action.symbol);
+        if (!coinId)
+            return { eligible: false, blockReasons: ["unresolved_symbol"] };
+        r = await client.futuresQuote({ coinId, side: action.side, leverage: action.leverage, marginMusd: action.marginMusd }, trace);
+    }
+    else if (action.type === "spot_order") {
+        const coinId = coinIdFor(observation, action.symbol);
+        if (!coinId)
+            return { eligible: false, blockReasons: ["unresolved_symbol"] };
+        r = await client.spotQuote({ coinId, side: action.side, quantity: action.quantity }, trace);
+    }
+    else if (action.type === "pm_open") {
+        r = await client.pmQuote({
+            source: action.source,
+            slug: action.slug,
+            outcomeExternalMarketId: action.outcomeExternalMarketId,
+            stakeMusd: action.stakeMusd,
+        }, trace);
+    }
+    else {
+        return undefined; // close / set-sltp / cancel need no quote
+    }
+    if (!r.ok)
+        return { eligible: false, blockReasons: [`quote_http_${r.status}`] };
+    const d = asObj(r.data);
+    return {
+        eligible: d.eligible === true,
+        blockReasons: d.blockReasons,
+        entryPrice: asNum(d.entryPrice), // futures
+        liquidationPrice: asNum(d.liquidationPrice), // futures
+        executionPrice: asNum(d.executionPrice), // spot live fill price
+        estimatedCostMusd: asNum(d.estimatedCostMusd), // spot gross notional
+        // Freshness lives in the response's `observation` block (anti-look-ahead).
+        freshness: freshnessOf(asObj(d.observation)),
+    };
+}
+export async function executeAction(client, action, observation, trace, idempotencyKey) {
+    if (action.type === "futures_open") {
+        const coinId = coinIdFor(observation, action.symbol);
+        if (!coinId)
+            return { ok: false, status: 0, data: { error: "unresolved_symbol" } };
+        return client.openFutures({
+            coinId,
+            side: action.side,
+            leverage: action.leverage,
+            marginMusd: action.marginMusd,
+            idempotencyKey,
+            stopLossPrice: action.stopLossPrice ?? null,
+            takeProfitPrice: action.takeProfitPrice ?? null,
+            agentTrace: trace,
+        });
+    }
+    if (action.type === "futures_close") {
+        return client.closeFutures({
+            positionId: action.positionId,
+            fraction: action.fraction,
+            idempotencyKey,
+            agentTrace: trace,
+        });
+    }
+    if (action.type === "futures_set_sltp") {
+        return client.setFuturesSlTp({
+            positionId: action.positionId,
+            stopLossPrice: action.stopLossPrice ?? undefined,
+            takeProfitPrice: action.takeProfitPrice ?? undefined,
+            agentTrace: trace,
+        });
+    }
+    if (action.type === "spot_order") {
+        const coinId = coinIdFor(observation, action.symbol);
+        if (!coinId)
+            return { ok: false, status: 0, data: { error: "unresolved_symbol" } };
+        return client.placeSpotOrder({
+            coinId,
+            side: action.side,
+            orderType: action.orderType,
+            quantity: action.quantity,
+            limitPrice: action.limitPrice,
+            stopPrice: action.stopPrice,
+            idempotencyKey,
+            agentTrace: trace,
+        });
+    }
+    if (action.type === "spot_cancel") {
+        return client.cancelSpotOrder(action.orderId, trace);
+    }
+    if (action.type === "pm_open") {
+        return client.openPmPosition({
+            source: action.source,
+            slug: action.slug,
+            outcomeExternalMarketId: action.outcomeExternalMarketId,
+            stakeMusd: action.stakeMusd,
+            idempotencyKey,
+            agentTrace: trace,
+        });
+    }
+    return { ok: false, status: 0, data: { error: "unsupported_action" } };
+}

package/dist/agent/capabilityGuard.d.ts

@@ -0,0 +1,2 @@
+import { AgentSpec, ResolvedAgent, ResolveIssue } from "./types.js";
+export declare function checkCapabilityDrift(resolved: ResolvedAgent, spec: AgentSpec): ResolveIssue[];

package/dist/agent/capabilityGuard.js

@@ -0,0 +1,131 @@
+// Capability drift guard.
+//
+// An agent's PROSE (thesis, persona, tactic skills) is authored separately from
+// the runner's code, so a skill can name a venue, an action, or a cap that the
+// runner does NOT support — and rot silently, exactly the way a stale doc drifts
+// from a live enum. (We watched this happen in a sibling system: a knowledge file
+// kept naming post types the live enum had dropped, and a test pinned the stale
+// names so the suite stayed green while the model was fed a wrong taxonomy.)
+//
+// This guard asserts that every capability IDENTIFIER referenced in authored
+// prose is in the runner's LIVE capability set AND — for actions/venues — in THIS
+// agent's enabled venues. It is deliberately deterministic and low-false-positive:
+// it inspects only identifier-shaped tokens (snake_case `<venue>_<verb>` actions
+// scanned anywhere; cap/venue identifiers scanned only inside markdown code
+// spans), never free English. Runtime memory (journal/notes.md) is excluded — it
+// records history, and may legitimately recall a venue later disabled.
+import { VENUES, ACTION_TYPES, } from "./types.js";
+import { levenshtein } from "./strictLint.js";
+import { RISK_CAPS, LIMIT_CAPS } from "./mergeRules.js";
+const KNOWN_ACTIONS = new Set(ACTION_TYPES);
+// Every enforced cap the runner knows: risk + limits + killSwitch + abstention.
+const LIVE_CAPS = [
+    ...Object.keys(RISK_CAPS),
+    ...Object.keys(LIMIT_CAPS),
+    "maxDrawdownMusd",
+    "maxConsecutiveRejects",
+    "maxConsecutiveModelFailures",
+    "onRateLimitPressure",
+    "onStaleData",
+    "onWeakSignal",
+    "onMissingQuote",
+    "onInsufficientBalance",
+    "minConfidence",
+];
+const LIVE_CAP_SET = new Set(LIVE_CAPS);
+// `<venue>_<verb>` action references. The verb is restricted to the runner's
+// real verbs, so descriptive tokens (spot_price, futures_curve) never match —
+// only action-shaped references (real OR plausibly-fake) do.
+const ACTION_RE = /\b(spot|futures|pm)_(open|close|order|cancel|set_sltp)\b/g;
+// camelCase cap-shaped identifiers (maxLeverage, minConfidence, requireStopLoss…).
+const CAP_RE = /\b(?:max|min|require|on|per)[A-Z][A-Za-z0-9]+\b/g;
+// markdown inline code spans — where authors put identifiers.
+const CODESPAN_RE = /`([^`\n]+)`/g;
+// Levenshtein threshold for "this is a typo/rename of a real cap" — matches the
+// strictLint "did you mean" threshold (< 3, i.e. edit distance <= 2).
+const CAP_NEARMISS_MAX = 3;
+function venueOf(action) {
+    return action.split("_")[0];
+}
+// Authored knowledge only: keystone + character/* + skills/*. journal/notes.md is
+// runtime memory and is intentionally NOT checked.
+function authoredProse(resolved) {
+    return resolved.proseParts.filter((p) => p.source !== "journal/notes.md");
+}
+// Returns one issue per (token, source) drift found. Empty = no drift.
+export function checkCapabilityDrift(resolved, spec) {
+    const issues = [];
+    const enabled = new Set(spec.venues);
+    const seen = new Set(); // dedupe "kind|token|source"
+    const once = (key) => {
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    };
+    for (const part of authoredProse(resolved)) {
+        const where = part.source;
+        // ── action references (anywhere in the body) ──
+        for (const m of part.text.matchAll(ACTION_RE)) {
+            const action = m[0];
+            if (!once(`a|${action}|${where}`))
+                continue;
+            if (!KNOWN_ACTIONS.has(action)) {
+                issues.push({
+                    code: "drift_unknown_action",
+                    path: where,
+                    message: `prose references action \`${action}\`, which the runner does not support (allowed: ${ACTION_TYPES.join(", ")})`,
+                });
+            }
+            else {
+                const venue = venueOf(action);
+                if (!enabled.has(venue)) {
+                    issues.push({
+                        code: "drift_venue_not_enabled",
+                        path: where,
+                        message: `prose references \`${action}\` but venue \`${venue}\` is not in this agent's venues [${spec.venues.join(", ")}]`,
+                    });
+                }
+            }
+        }
+        // ── venue + cap references inside code spans only ──
+        for (const span of part.text.matchAll(CODESPAN_RE)) {
+            const inner = span[1];
+            // An exact venue identifier in a code span (e.g. `pm`) that the agent has
+            // not enabled — a prose promise the runner cannot keep.
+            if (VENUES.includes(inner) &&
+                !enabled.has(inner) &&
+                once(`v|${inner}|${where}`)) {
+                issues.push({
+                    code: "drift_venue_not_enabled",
+                    path: where,
+                    message: `prose references venue \`${inner}\` but it is not in this agent's venues [${spec.venues.join(", ")}]`,
+                });
+            }
+            // cap-shaped identifiers — flag only a near-miss of a REAL cap (a typo or
+            // rename); unrelated identifiers are left alone to avoid false positives.
+            for (const cm of inner.matchAll(CAP_RE)) {
+                const token = cm[0];
+                if (LIVE_CAP_SET.has(token))
+                    continue;
+                let nearest = null;
+                let best = CAP_NEARMISS_MAX;
+                for (const cap of LIVE_CAPS) {
+                    const d = levenshtein(token.toLowerCase(), cap.toLowerCase());
+                    if (d < best) {
+                        best = d;
+                        nearest = cap;
+                    }
+                }
+                if (nearest && once(`c|${token}|${where}`)) {
+                    issues.push({
+                        code: "drift_unknown_cap",
+                        path: where,
+                        message: `prose references cap \`${token}\`, which is not a runner cap — did you mean \`${nearest}\`?`,
+                    });
+                }
+            }
+        }
+    }
+    return issues;
+}

package/dist/agent/cli.d.ts

@@ -0,0 +1,21 @@
+import { SkillValidationMode } from "./skillValidator.js";
+export interface CmdResult {
+    ok: boolean;
+    code: number;
+    lines: string[];
+    data?: unknown;
+}
+export declare function cmdNew(targetPath: string, opts?: {
+    template?: string;
+    preset?: string;
+}): CmdResult;
+export declare function cmdValidate(path: string, mode?: SkillValidationMode): CmdResult;
+export declare function cmdLock(path: string): CmdResult;
+export declare function cmdEject(path: string): CmdResult;
+export declare function cmdInspect(path: string, json?: boolean): CmdResult;
+export declare function cmdRun(path: string, opts?: {
+    once?: boolean;
+    live?: boolean;
+    stateFile?: string;
+}): Promise<CmdResult>;
+export declare function main(argv: string[]): Promise<number>;