@coinrithm/mcp-trading 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -3,7 +3,60 @@
 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`).
+versioned separately (see `openapi.yaml` `info.version`, currently `1.5.0`).
+
+## 0.5.0
+
+Agent-runner quality + reliability release. `coinrithm-agent` got materially
+smarter and less noisy; `coinrithm-mcp` is unchanged in shape. Bundles the work
+since 0.4.0.
+
+- **Prediction markets are a first-class venue** in the decide prompt: a short
+  `pmN` ref so small models trade PM reliably, eligible-outcome filtering (only
+  backend-openable outcomes reach the model), and futures-capped agents steered
+  to PM (a separate budget) instead of re-rejecting.
+- **PM anti-churn — now actually effective.** The candidate list is pre-filtered
+  to exclude markets the agent already holds, and the runner + server both block
+  re-betting a held market+outcome (no more one-agent, 25-identical-bets churn).
+  An earlier version read the wrong `/positions/pm` fields and was silently dead;
+  fixed.
+- **Settlement-feedback learning loop.** The agent sees how its own recent bets
+  actually resolved (win/loss/void + realized PnL) as reflective context, so it
+  learns from outcomes across cycles.
+- **Per-trade reasoning stays honest about the market.** A multi-action decision
+  no longer stamps its primary rationale onto a secondary trade about a different
+  market — the trade's public Arena "why" always matches the market it's on.
+- **Futures reliability.** The model is unblinded to per-position mark /
+  liquidation / stop / take-profit prices; take-profit is auto-clamped to a valid
+  R:R target off the stop (kills the `take_profit_not_*_mark` reject waves); and a
+  marking-down PM book now trips the equity-drawdown kill-switch too.
+- **News capability.** Recent high-importance news for the watchlist coins is fed
+  into the decide context as a market-catalyst layer.
+- **Robustness + contract accuracy.** Scheduler/runner hardening, flat-state
+  prompt steers (weak models stop hallucinating closes), manage-enum
+  normalization, and the PM contract now documents real entry friction rather
+  than a disclose-only stance.
+- **Security.** `hono` bumped to 4.12.27 (high-severity advisories: serve-static
+  path traversal, CORS wildcard-with-credentials, body-limit bypass).
+- **Docs.** The npm README leads with value / free / OKF / Studio; stale
+  scheduler and `minDecidedTrades` claims corrected.
+
+## 0.4.0
+
+- **Deterministic scorecard engine (`computeScorecard`).** The reproducible-
+  evaluation engine for `coinrithm.agent.scorecard.v1` — pure math over an
+  agent's realized track record (no network, no model): realized PnL, win rate,
+  expectancy, profit factor, reward-to-risk, Sharpe, Sortino, deflated /
+  probabilistic Sharpe (Bailey & López de Prado — skill vs luck with a multiple-
+  testing penalty), max drawdown, and Brier + ECE calibration for probabilistic
+  calls. Same inputs → identical metrics **and** a sha256 `contentHash` of the
+  canonicalized result, so a scorecard whose hash doesn't reproduce isn't
+  trusted. Metrics are computed AFTER the run from immutable evidence (leakage-
+  separation), so tuning-to-the-metric is structurally impossible. Returns
+  `null` for thin records — never a fabricated number.
+- **Resolver: committable file metadata + functionality pin.** The OKF resolver
+  now carries per-file metadata and pins functionality through resolution, so a
+  bundle's behavior is reproducible from its committed files.
 
 ## 0.3.0
 

package/README.md

@@ -1,22 +1,45 @@
 # @coinrithm/mcp-trading
 
-CoinRithm paper-trading toolkit. Two binaries:
+**Deploy an AI trading agent with paper money — for free.** Give any model
+(Claude, GPT, Gemini, Llama…) a 50,000 mUSD virtual account and let it trade
+spot, futures, and prediction markets on
+[CoinRithm](https://coinrithm.com/agentic-trading). No real money, no exchange,
+no risk — a proving ground to show an agent works *before* anything is on the
+line, with a public **Agent Arena** leaderboard ranked by realized paper PnL.
+
+Agents are **OKF bundles** — an open, model-agnostic folder of markdown + YAML
+(strategy, persona, hard caps) that any runtime can read. Two ways to run the
+**same** bundle:
+
+- **Managed — nothing to install.** Build and deploy an agent in your browser
+  with the **Agent Studio** (CoinRithm → My Agents → Studio): fork a house agent
+  or write one from scratch, and CoinRithm runs it **free on Llama 3.1 8B**
+  (NVIDIA NIM) on an always-on scheduler. The fastest path to a live agent.
+- **Self-host — this package.** Bring your own model key and run the
+  `observe→decide→validate→act` loop on your machine, or wire the MCP server
+  into Claude Desktop / Cursor / Codex.
+
+This package ships 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.
+  folder and run an `observe→decide→validate→act` loop with your own model key,
+  **dry-run by default**. See [Agent runner](#agent-runner-coinrithm-agent) below.
 
 > **Paper trading only** — virtual funds (50,000 mUSD). Not financial advice.
 
-## Install / build
+## Quick start
 
 ```bash
-npm install
-npm run build
+# Run the MCP server with your CoinRithm key (no install needed):
+COINRITHM_API_KEY=crk_live_… npx -y @coinrithm/mcp-trading
 ```
 
+Get a `crk_live_…` key from CoinRithm → Profile → API Keys. To author and run a
+self-host agent instead, see [Agent runner](#agent-runner-coinrithm-agent).
+Building from source? `npm install && npm run build`.
+
 ## Agent runner (`coinrithm-agent`)
 
 This package also ships a **self-host agent runner**. You write an agent as a
@@ -33,8 +56,10 @@ COINRITHM_API_KEY=crk_live_… ANTHROPIC_API_KEY=sk-ant-… \
 ```
 
 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).
+**[docs/agent-runner.md](https://github.com/CoinRithm/coinrithm-agent-trading/blob/main/docs/agent-runner.md)**.
+The CoinRithm hosted scheduler runs this same engine for you — see the
+[scheduler README](../../packages/scheduler/README.md) for the built,
+DB-driven runtime.
 
 ## Two ways to run
 
@@ -176,7 +201,9 @@ least that long before retrying.
 
 ## Agent Arena
 
-Opted-in agents are publicly ranked by realized PnL (min 3 decided trades) at
+Opted-in agents are publicly ranked by realized PnL — every agent with any
+decided (win/loss) trade is listed (a small-sample asterisk flags thin records;
+the live gate is surfaced as `minDecidedTrades` in the response) at
 [coinrithm.com](https://coinrithm.com/agentic-trading) — set `agentName` /
 `agentPublic` / `agentModel` on your key to join, then check your standing
 with `get_arena_leaderboard` / `get_arena_agent`. Pass `window: "7d" | "30d"`

package/dist/agent/act.js

@@ -79,6 +79,10 @@ export async function executeAction(client, action, observation, trace, idempote
             positionId: action.positionId,
             stopLossPrice: action.stopLossPrice ?? undefined,
             takeProfitPrice: action.takeProfitPrice ?? undefined,
+            // Deterministic key (sltp:<posId>) so a retried cycle can't double-send,
+            // consistent with the open/close/place ops. Server-side this op is also
+            // idempotent (absolute-value set), so the key is belt-and-braces.
+            idempotencyKey,
             agentTrace: trace,
         });
     }
@@ -98,7 +102,10 @@ export async function executeAction(client, action, observation, trace, idempote
         });
     }
     if (action.type === "spot_cancel") {
-        return client.cancelSpotOrder(action.orderId, trace);
+        // Deterministic key (cancel:<orderId>) so a retried cycle can't double-send,
+        // consistent with the open/place ops. Server-side a re-cancel is a no-op, so
+        // the key is belt-and-braces.
+        return client.cancelSpotOrder(action.orderId, idempotencyKey, trace);
     }
     if (action.type === "pm_open") {
         return client.openPmPosition({

package/dist/agent/cli.d.ts

@@ -13,6 +13,7 @@ export declare function cmdValidate(path: string, mode?: SkillValidationMode): C
 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 acquireLock(stateFile: string): (() => void) | null;
 export declare function cmdRun(path: string, opts?: {
     once?: boolean;
     live?: boolean;

package/dist/agent/cli.js

@@ -192,17 +192,52 @@ export function cmdInspect(path, json = false) {
     ];
     return { ok: v.valid, code: 0, lines, data: output };
 }
+// Is a process still alive? signal 0 probes without sending — ESRCH means it's
+// gone, EPERM means it exists but we can't signal it (still alive). Unknown PIDs
+// (NaN / non-positive) are treated as alive so we never reclaim a malformed lock.
+function pidIsAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code !== "ESRCH";
+    }
+}
 // Acquire an exclusive per-agent run lock (O_EXCL). Returns a release fn, or
-// null if another runner already holds it — so two runners can't race one
-// state file and bypass the daily / write caps.
-function acquireLock(stateFile) {
+// null if another LIVE runner already holds it — so two runners can't race one
+// state file and bypass the daily / write caps. Stale-aware: if the existing
+// lock names a PID that is no longer alive (the prior runner was Ctrl-C'd /
+// killed without unwinding its finally), the orphaned lock is reclaimed instead
+// of trapping every subsequent `run` until a manual delete.
+export function acquireLock(stateFile) {
     const lock = `${stateFile}.lock`;
     let fd;
     try {
         fd = openSync(lock, "wx");
     }
     catch {
-        return null;
+        // Lock exists. Reclaim it only if its owner PID is provably dead.
+        let ownerAlive = true;
+        try {
+            const prior = JSON.parse(readFileSync(lock, "utf8"));
+            ownerAlive = pidIsAlive(Number(prior?.pid));
+        }
+        catch {
+            // Unreadable / unparseable lock — treat as held (conservative).
+            return null;
+        }
+        if (ownerAlive)
+            return null;
+        try {
+            unlinkSync(lock);
+            fd = openSync(lock, "wx"); // re-acquire; if we lose a race, bail out.
+        }
+        catch {
+            return null;
+        }
     }
     try {
         writeFileSync(fd, JSON.stringify({ pid: process.pid }));
@@ -210,7 +245,11 @@ function acquireLock(stateFile) {
     catch {
         /* best effort */
     }
+    let released = false;
     return () => {
+        if (released)
+            return;
+        released = true;
         try {
             closeSync(fd);
         }
@@ -253,6 +292,19 @@ export async function cmdRun(path, opts = {}) {
     if (!release) {
         return fail([`another runner holds ${stateFile}.lock — only one runner per agent at a time`]);
     }
+    // A self-host `run` is a cadence-paced loop users stop with Ctrl-C. Node exits
+    // on SIGINT/SIGTERM WITHOUT unwinding the finally across the awaited loop, so
+    // free the lock from a signal handler too (otherwise every later run is
+    // trapped on the orphaned .lock). Removed in the finally so repeated in-proc
+    // runs (tests) don't leak listeners; re-exit preserves normal Ctrl-C exit.
+    const onSignal = (sig) => {
+        release();
+        process.removeListener("SIGINT", onSignal);
+        process.removeListener("SIGTERM", onSignal);
+        process.kill(process.pid, sig);
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
     try {
         let state;
         try {
@@ -297,6 +349,8 @@ export async function cmdRun(path, opts = {}) {
         return { ok: true, code: 0, lines, data: results };
     }
     finally {
+        process.removeListener("SIGINT", onSignal);
+        process.removeListener("SIGTERM", onSignal);
         release();
     }
 }

package/dist/agent/client.d.ts

@@ -52,6 +52,12 @@ export declare class CoinRithmClient {
         source?: string;
         limit?: number;
     }, trace?: AgentTrace): Promise<ApiResult>;
+    agentNews(query: {
+        coins: string;
+        limit?: number;
+        hours?: number;
+        minImportance?: number;
+    }, trace?: AgentTrace): Promise<ApiResult>;
     pmPositions(query?: {
         updatedSince?: string;
     }, trace?: AgentTrace): Promise<ApiResult>;
@@ -81,6 +87,7 @@ export declare class CoinRithmClient {
         positionId: number;
         stopLossPrice?: number | null;
         takeProfitPrice?: number | null;
+        idempotencyKey?: string;
         agentTrace?: AgentTrace;
     }): Promise<ApiResult>;
     placeSpotOrder(body: {
@@ -93,7 +100,7 @@ export declare class CoinRithmClient {
         idempotencyKey: string;
         agentTrace?: AgentTrace;
     }): Promise<ApiResult>;
-    cancelSpotOrder(orderId: number, trace?: AgentTrace): Promise<ApiResult>;
+    cancelSpotOrder(orderId: number, idempotencyKey?: string, trace?: AgentTrace): Promise<ApiResult>;
     openPmPosition(body: {
         source: string;
         slug: string;

package/dist/agent/client.js

@@ -136,6 +136,15 @@ export class CoinRithmClient {
     discoverPmMarkets(query, trace) {
         return this.request("GET", "/api/agent/pm/discover", { query, trace });
     }
+    agentNews(query, trace) {
+        return this.request("GET", "/api/agent/news", { query, trace });
+    }
+    // GET /api/agent/positions/pm. Response (data: unknown — parsed defensively in
+    // observe): { positions: [...open + unrealized mark...], recentlyResolved: [...
+    // the caller's OWN bets that settled win/loss/void with realized pnl since the
+    // delta cursor; settlement-feedback loop...], updatedSince, asOf }. The
+    // `recentlyResolved` array is ADDITIVE (older backends omit it → observe degrades
+    // to []); the open `positions` shape is unchanged.
     pmPositions(query, trace) {
         return this.request("GET", "/api/agent/positions/pm", { query, trace });
     }
@@ -155,8 +164,11 @@ export class CoinRithmClient {
     placeSpotOrder(body) {
         return this.request("POST", "/api/agent/spot/order", { body });
     }
-    cancelSpotOrder(orderId, trace) {
-        return this.request("POST", `/api/agent/spot/order/${orderId}/cancel`, { trace });
+    cancelSpotOrder(orderId, idempotencyKey, trace) {
+        return this.request("POST", `/api/agent/spot/order/${orderId}/cancel`, {
+            body: idempotencyKey !== undefined ? { idempotencyKey } : undefined,
+            trace,
+        });
     }
     openPmPosition(body) {
         return this.request("POST", "/api/agent/pm/open", { body });

package/dist/agent/decision.d.ts

@@ -4,128 +4,131 @@ export declare const actionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<
     type: z.ZodLiteral<"futures_open">;
     symbol: z.ZodString;
     side: z.ZodEnum<["long", "short"]>;
-    leverage: z.ZodNumber;
-    marginMusd: z.ZodNumber;
-    stopLossPrice: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    takeProfitPrice: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    confidence: z.ZodOptional<z.ZodNumber>;
+    leverage: z.ZodEffects<z.ZodTypeAny, any, unknown>;
+    marginMusd: z.ZodEffects<z.ZodTypeAny, any, unknown>;
+    stopLossPrice: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodTypeAny, any, unknown>>>;
+    takeProfitPrice: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodTypeAny, any, unknown>>>;
+    confidence: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodTypeAny, any, unknown>>>, any, unknown>;
     rationaleSummary: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     symbol: string;
     side: "long" | "short";
-    leverage: number;
-    marginMusd: number;
     type: "futures_open";
-    stopLossPrice?: number | null | undefined;
-    takeProfitPrice?: number | null | undefined;
-    confidence?: number | undefined;
+    leverage?: any;
+    marginMusd?: any;
+    stopLossPrice?: any;
+    takeProfitPrice?: any;
+    confidence?: any;
     rationaleSummary?: string | undefined;
 }, {
     symbol: string;
     side: "long" | "short";
-    leverage: number;
-    marginMusd: number;
     type: "futures_open";
-    stopLossPrice?: number | null | undefined;
-    takeProfitPrice?: number | null | undefined;
-    confidence?: number | undefined;
+    leverage?: unknown;
+    marginMusd?: unknown;
+    stopLossPrice?: unknown;
+    takeProfitPrice?: unknown;
+    confidence?: unknown;
     rationaleSummary?: string | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"futures_close">;
-    positionId: z.ZodNumber;
-    fraction: z.ZodOptional<z.ZodNumber>;
-    confidence: z.ZodOptional<z.ZodNumber>;
+    positionId: z.ZodEffects<z.ZodTypeAny, any, unknown>;
+    fraction: z.ZodOptional<z.ZodEffects<z.ZodTypeAny, any, unknown>>;
+    confidence: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodTypeAny, any, unknown>>>, any, unknown>;
     rationaleSummary: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    positionId: number;
     type: "futures_close";
-    fraction?: number | undefined;
-    confidence?: number | undefined;
+    positionId?: any;
+    fraction?: any;
+    confidence?: any;
     rationaleSummary?: string | undefined;
 }, {
-    positionId: number;
     type: "futures_close";
-    fraction?: number | undefined;
-    confidence?: number | undefined;
+    positionId?: unknown;
+    fraction?: unknown;
+    confidence?: unknown;
     rationaleSummary?: string | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"futures_set_sltp">;
-    positionId: z.ZodNumber;
-    stopLossPrice: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    takeProfitPrice: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    positionId: z.ZodEffects<z.ZodTypeAny, any, unknown>;
+    stopLossPrice: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodTypeAny, any, unknown>>>;
+    takeProfitPrice: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodTypeAny, any, unknown>>>;
 }, "strict", z.ZodTypeAny, {
-    positionId: number;
     type: "futures_set_sltp";
-    stopLossPrice?: number | null | undefined;
-    takeProfitPrice?: number | null | undefined;
+    stopLossPrice?: any;
+    takeProfitPrice?: any;
+    positionId?: any;
 }, {
-    positionId: number;
     type: "futures_set_sltp";
-    stopLossPrice?: number | null | undefined;
-    takeProfitPrice?: number | null | undefined;
+    stopLossPrice?: unknown;
+    takeProfitPrice?: unknown;
+    positionId?: unknown;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"spot_order">;
     symbol: z.ZodString;
     side: z.ZodEnum<["buy", "sell"]>;
     orderType: z.ZodEnum<["market", "limit", "stop"]>;
-    quantity: z.ZodNumber;
-    limitPrice: z.ZodOptional<z.ZodNumber>;
-    stopPrice: z.ZodOptional<z.ZodNumber>;
-    confidence: z.ZodOptional<z.ZodNumber>;
+    quantity: z.ZodEffects<z.ZodTypeAny, any, unknown>;
+    limitPrice: z.ZodOptional<z.ZodEffects<z.ZodTypeAny, any, unknown>>;
+    stopPrice: z.ZodOptional<z.ZodEffects<z.ZodTypeAny, any, unknown>>;
+    confidence: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodTypeAny, any, unknown>>>, any, unknown>;
     rationaleSummary: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     symbol: string;
     side: "buy" | "sell";
     orderType: "limit" | "market" | "stop";
-    quantity: number;
     type: "spot_order";
-    limitPrice?: number | undefined;
-    stopPrice?: number | undefined;
-    confidence?: number | undefined;
+    quantity?: any;
+    limitPrice?: any;
+    stopPrice?: any;
+    confidence?: any;
     rationaleSummary?: string | undefined;
 }, {
     symbol: string;
     side: "buy" | "sell";
     orderType: "limit" | "market" | "stop";
-    quantity: number;
     type: "spot_order";
-    limitPrice?: number | undefined;
-    stopPrice?: number | undefined;
-    confidence?: number | undefined;
+    quantity?: unknown;
+    limitPrice?: unknown;
+    stopPrice?: unknown;
+    confidence?: unknown;
     rationaleSummary?: string | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"spot_cancel">;
-    orderId: z.ZodNumber;
+    orderId: z.ZodEffects<z.ZodTypeAny, any, unknown>;
 }, "strict", z.ZodTypeAny, {
     type: "spot_cancel";
-    orderId: number;
+    orderId?: any;
 }, {
     type: "spot_cancel";
-    orderId: number;
+    orderId?: unknown;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"pm_open">;
-    source: z.ZodString;
-    slug: z.ZodString;
-    outcomeExternalMarketId: z.ZodString;
-    stakeMusd: z.ZodNumber;
-    confidence: z.ZodOptional<z.ZodNumber>;
+    ref: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    outcomeExternalMarketId: z.ZodOptional<z.ZodString>;
+    stakeMusd: z.ZodEffects<z.ZodTypeAny, any, unknown>;
+    confidence: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodTypeAny, any, unknown>>>, any, unknown>;
     rationaleSummary: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    source: string;
-    slug: string;
-    outcomeExternalMarketId: string;
-    stakeMusd: number;
     type: "pm_open";
-    confidence?: number | undefined;
+    source?: string | undefined;
+    slug?: string | undefined;
+    outcomeExternalMarketId?: string | undefined;
+    stakeMusd?: any;
+    confidence?: any;
     rationaleSummary?: string | undefined;
+    ref?: string | undefined;
 }, {
-    source: string;
-    slug: string;
-    outcomeExternalMarketId: string;
-    stakeMusd: number;
     type: "pm_open";
-    confidence?: number | undefined;
+    source?: string | undefined;
+    slug?: string | undefined;
+    outcomeExternalMarketId?: string | undefined;
+    stakeMusd?: unknown;
+    confidence?: unknown;
     rationaleSummary?: string | undefined;
+    ref?: string | undefined;
 }>]>;
 export type ParseDecisionResult = {
     ok: true;