@coinrithm/mcp-trading 0.7.2 → 0.7.3

package/dist/tools.js

@@ -6,8 +6,12 @@
 // isError results rather than thrown so the model can react.
 import { z } from "zod";
 import { bearerFromHeader } from "./client.js";
-const PAPER_NOTE = "Paper trading only — virtual funds (50,000 mUSD). Not financial advice. " +
-    "Paper fills apply a disclosed execution cost folded into realized PnL: " +
+import { PAPER_EXECUTION_VERSION } from "./executionPolicy.js";
+// Served on tool descriptions. Names the versioned execution policy and never
+// claims costless execution (drift-tested in executionPolicy.test.ts).
+export const PAPER_NOTE = "Paper trading only — virtual funds (50,000 mUSD). Not financial advice. " +
+    `Paper fills run under the versioned ${PAPER_EXECUTION_VERSION} policy and ` +
+    "apply a disclosed execution cost folded into realized PnL: " +
     "spot/futures pay a taker fee (spot market orders also pay half-spread + " +
     "slippage); PM fills at the ask with size-based slippage and a Polymarket-" +
     "shaped taker fee, with entryProbability kept at the mid for calibration. " +
@@ -64,6 +68,54 @@ const AGENT_TRACE_SCHEMA = z
 })
     .optional()
     .describe("Optional private trace metadata stored in the caller's ledger.");
+// Optional SELF-REPORTED provenance a caller attaches to a PM open/opportunity so the
+// durable artifact records WHAT RAN. Every field carries NO trust: the server always
+// stamps the execution/evaluation policy versions AND providerVerified itself
+// (providerVerified can NEVER be raised by a caller), validates/caps each value, and
+// hex-checks the hashes. Sending ANY block (even {}) makes the artifact schemaVersion 2.
+const PROVENANCE_REPORT_SCHEMA = z
+    .object({
+    runtimeKind: z
+        .enum(["hosted_scheduler", "self_host_runner", "byo_api", "mcp_tool"])
+        .optional()
+        .describe("The runtime surface you ran on (self-reported; no trust)."),
+    packageVersion: z.string().max(40).optional(),
+    bundleId: z.string().max(120).optional(),
+    bundleVersion: z.string().max(40).optional(),
+    skillVersions: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe("{skillId: version}. Capped: 50 keys, key<=120 / value<=40."),
+    promptHash: z
+        .string()
+        .regex(/^[0-9a-fA-F]{64}$/)
+        .optional()
+        .describe("sha256 hex of your exact prompt strings. HASH ONLY — never raw text."),
+    configHash: z
+        .string()
+        .regex(/^[0-9a-fA-F]{64}$/)
+        .optional()
+        .describe("sha256 hex of your resolved config/spec. HASH ONLY — never raw text."),
+    modelProvider: z.string().max(80).optional(),
+    modelName: z.string().max(80).optional(),
+    evidenceRef: z
+        .object({
+        snapshotIds: z
+            .array(z.string().max(200))
+            .optional()
+            .describe("Opaque snapshot ids (capped at 100)."),
+        sourceCapturedAt: z
+            .string()
+            .optional()
+            .describe("Source capture time (ISO 8601)."),
+    })
+        .optional()
+        .describe("Pointers to the observation evidence (never the evidence itself)."),
+})
+    .optional()
+    .describe("Optional self-reported provenance (WHAT RAN). No trust: the server stamps " +
+    "policy versions + providerVerified itself. Any block (even {}) makes the " +
+    "artifact schemaVersion 2.");
 function readOnlyAnnotations(title) {
     return {
         title,
@@ -358,9 +410,12 @@ export function registerTools(server, client) {
         description: "Find active-open, quote-ready-first prediction markets on the mock-PM " +
             "sources (Kalshi + Polymarket by default). Returns source, slug, " +
             "quoteable outcome externalMarketIds, freshness, volume/liquidity/spread, " +
-            "and decisionSupport. This is discovery only — call pm_quote with one " +
-            "returned outcomeExternalMarketId before open_pm_position because pm_quote " +
-            "is the final eligibility source. " +
+            "decisionSupport, and quality (the truth engine's persisted verdict: " +
+            "decisionEligible plus stable warning/block reason codes; " +
+            "decisionEligible=false means opens are blocked and alerts suppressed " +
+            "while the market stays visible). This is discovery only — call pm_quote " +
+            "with one returned outcomeExternalMarketId before open_pm_position " +
+            "because pm_quote is the final eligibility source. " +
             PAPER_NOTE,
         inputSchema: {
             q: z
@@ -422,16 +477,16 @@ export function registerTools(server, client) {
             PAPER_NOTE,
         inputSchema: {
             venue: z.string().optional().describe("Optional venue filter."),
-            eventType: z.string().optional().describe("Optional event type filter."),
+            eventType: z
+                .string()
+                .optional()
+                .describe("Optional event type filter."),
             runId: z.string().optional().describe("Optional run id filter."),
             decisionId: z
                 .string()
                 .optional()
                 .describe("Optional decision id filter."),
-            status: z
-                .string()
-                .optional()
-                .describe("Optional ledgerStatus filter."),
+            status: z.string().optional().describe("Optional ledgerStatus filter."),
             from: z.string().optional().describe("Optional ISO start timestamp."),
             to: z.string().optional().describe("Optional ISO end timestamp."),
             limit: z
@@ -451,7 +506,17 @@ export function registerTools(server, client) {
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Get private agent ledger"),
-    }, async ({ venue, eventType, runId, decisionId, status, from, to, limit, offset, agentTrace, }, extra) => present(await client.getLedger({ venue, eventType, runId, decisionId, status, from, to, limit, offset }, requestKey(extra), agentTrace)));
+    }, async ({ venue, eventType, runId, decisionId, status, from, to, limit, offset, agentTrace, }, extra) => present(await client.getLedger({
+        venue,
+        eventType,
+        runId,
+        decisionId,
+        status,
+        from,
+        to,
+        limit,
+        offset,
+    }, requestKey(extra), agentTrace)));
     server.registerTool("export_agent_ledger", {
         title: "Export private agent ledger",
         description: "Export up to 1,000 private ledger rows for the calling API key as JSON. " +
@@ -460,16 +525,16 @@ export function registerTools(server, client) {
             PAPER_NOTE,
         inputSchema: {
             venue: z.string().optional().describe("Optional venue filter."),
-            eventType: z.string().optional().describe("Optional event type filter."),
+            eventType: z
+                .string()
+                .optional()
+                .describe("Optional event type filter."),
             runId: z.string().optional().describe("Optional run id filter."),
             decisionId: z
                 .string()
                 .optional()
                 .describe("Optional decision id filter."),
-            status: z
-                .string()
-                .optional()
-                .describe("Optional ledgerStatus filter."),
+            status: z.string().optional().describe("Optional ledgerStatus filter."),
             from: z.string().optional().describe("Optional ISO start timestamp."),
             to: z.string().optional().describe("Optional ISO end timestamp."),
             agentTrace: AGENT_TRACE_SCHEMA,
@@ -572,9 +637,13 @@ export function registerTools(server, client) {
     server.registerTool("pm_quote", {
         title: "Prediction-market quote",
         description: "Read-only PM quote for a binary outcome: entry probability, share " +
-            "estimate, max payout, eligibility, freshness, and decisionSupport " +
-            "(market quality/liquidity/volume/spread tiers + flags) so you can " +
-            "quote and gauge tradability in one call. Never mutates state. " +
+            "estimate, max payout, eligibility, freshness, decisionSupport " +
+            "(market quality/liquidity/volume/spread tiers + flags), quality (the " +
+            "persisted truth-engine verdict), and openBlocked/openBlockReasons — " +
+            "a preview of the open-time quality gate: when openBlocked is true, " +
+            "open_pm_position would be rejected 422 with those stored reason codes " +
+            "(quality_state_missing, quality_state_stale, quote_dead, " +
+            "stale_freshness, ...). Never mutates state. " +
             "stakeMusd must be > 0 (min to open is 10). Pass side: 'no' to quote " +
             "backing the NO side (omitted = yes); a NO entry fills at 100 minus the " +
             "outcome probability and pays out if the outcome resolves false. " +
@@ -596,7 +665,14 @@ export function registerTools(server, client) {
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Prediction-market quote"),
-    }, async ({ source, slug, outcomeExternalMarketId, side, stakeMusd, agentTrace }, extra) => present(await client.pmQuote({ source, slug, outcomeExternalMarketId, side, stakeMusd, agentTrace }, requestKey(extra))));
+    }, async ({ source, slug, outcomeExternalMarketId, side, stakeMusd, agentTrace }, extra) => present(await client.pmQuote({
+        source,
+        slug,
+        outcomeExternalMarketId,
+        side,
+        stakeMusd,
+        agentTrace,
+    }, requestKey(extra))));
     server.registerTool("spot_quote", {
         title: "Spot quote",
         description: "Read-only spot MARKET quote: live execution price, estimated cost " +
@@ -837,19 +913,125 @@ export function registerTools(server, client) {
                 .string()
                 .min(1)
                 .describe("Unique per PM-open intent; reuse replays the original result."),
+            forecastProbability: z
+                .number()
+                .gt(0)
+                .lt(100)
+                .optional()
+                .describe("OPTIONAL. Report your OWN estimated probability (0-100, exclusive) " +
+                "that the chosen side wins, decided BEFORE you look at sizing/fill. " +
+                "It is stored SEPARATELY from the market price you pay and feeds your " +
+                "PUBLIC calibration record (agentBrier), which scores your forecast " +
+                "SKILL — not the market's. Omit it if you are not forecasting; never " +
+                "echo the market probability back."),
+            provenance: PROVENANCE_REPORT_SCHEMA,
             agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: mutatingAnnotations("Open prediction-market position", {
             idempotent: true,
         }),
-    }, async ({ source, slug, outcomeExternalMarketId, side, stakeMusd, idempotencyKey, agentTrace, }, extra) => present(await client.openPmPosition({
+    }, async ({ source, slug, outcomeExternalMarketId, side, stakeMusd, idempotencyKey, forecastProbability, provenance, agentTrace, }, extra) => present(await client.openPmPosition({
         source,
         slug,
         outcomeExternalMarketId,
         side,
         stakeMusd,
         idempotencyKey,
+        forecastProbability,
+        provenance,
+        agentTrace,
+    }, requestKey(extra))));
+    server.registerTool("report_pm_opportunity", {
+        title: "Report a non-opened PM opportunity",
+        description: "Report a prediction-market opportunity you evaluated but did NOT open, so " +
+            "your PUBLIC evaluation reflects the FULL opportunity universe — not only " +
+            "the trades you took (otherwise an agent can look skilled by exposure " +
+            "choice alone). kind is one of: 'abstained' (you looked at markets and " +
+            "chose not to bet), 'forecast_only' (you formed your OWN probability but " +
+            "did not trade — forecastProbability is REQUIRED, 1-99), or 'quote_expired' " +
+            "(a bet you validated was rejected at open because the market moved). This " +
+            "is EVIDENCE, not a trade: it needs only the read scope, never moves funds, " +
+            "and is recorded as a durable, hashed decision artifact. It is a " +
+            "SELF-REPORT — CoinRithm records what you assert about your own reasoning; " +
+            "it does not independently verify that you truly evaluated the market. Put " +
+            "the breadth of what you weighed in cohort.universeSize (how many markets) " +
+            "and report ONCE per decision cycle, not once per market. Reuse decisionId " +
+            "to make a retry idempotent. " +
+            PAPER_NOTE,
+        inputSchema: {
+            kind: z
+                .enum(["abstained", "forecast_only", "quote_expired"])
+                .describe("abstained = evaluated but did not bet; forecast_only = formed your " +
+                "own probability without trading (forecastProbability required); " +
+                "quote_expired = a validated open the server rejected at act time."),
+            source: z
+                .string()
+                .optional()
+                .describe("Optional subject market source slug (e.g. kalshi)."),
+            slug: z.string().optional().describe("Optional subject event slug."),
+            outcomeExternalMarketId: z
+                .string()
+                .optional()
+                .describe("Optional case-sensitive outcome/market id of the subject."),
+            forecastProbability: z
+                .number()
+                .min(1)
+                .max(99)
+                .optional()
+                .describe("Your OWN probability (1-99) the chosen side wins. REQUIRED for " +
+                "forecast_only; omit for the other kinds. Never echo the market price."),
+            marketProbability: z
+                .number()
+                .min(0)
+                .max(100)
+                .optional()
+                .describe("The market price (0-100) you observed at the time."),
+            reasonCode: z
+                .string()
+                .max(500)
+                .optional()
+                .describe("Short structured reason (e.g. 'no_edge', 'stale_data')."),
+            cohort: z
+                .object({
+                universeSize: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .optional()
+                    .describe("How many markets you were choosing from this cycle."),
+                horizon: z
+                    .string()
+                    .max(64)
+                    .optional()
+                    .describe("Your forecast/decision horizon label (e.g. '7d')."),
+            })
+                .optional()
+                .describe("Opportunity-cohort breadth (frozen into the artifact)."),
+            decisionId: z
+                .string()
+                .optional()
+                .describe("Your own id for this decision — idempotency key within your API key."),
+            runId: z.string().optional().describe("Your own run id for grouping."),
+            provenance: PROVENANCE_REPORT_SCHEMA,
+            agentTrace: AGENT_TRACE_SCHEMA,
+        },
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: mutatingAnnotations("Report a non-opened PM opportunity", {
+            idempotent: true,
+        }),
+    }, async ({ kind, source, slug, outcomeExternalMarketId, forecastProbability, marketProbability, reasonCode, cohort, decisionId, runId, provenance, agentTrace, }, extra) => present(await client.reportPmOpportunity({
+        kind,
+        source,
+        slug,
+        outcomeExternalMarketId,
+        forecastProbability,
+        marketProbability,
+        reasonCode,
+        cohort,
+        decisionId,
+        runId,
+        provenance,
         agentTrace,
     }, requestKey(extra))));
     // ---- Public cross-venue PM data (no API key required) ----
@@ -859,8 +1041,8 @@ export function registerTools(server, client) {
         title: "Cross-venue prediction-market statistics",
         description: "Free public cross-venue prediction-market statistics: total/open/" +
             "closed market counts, total volume, 24h volume, and liquidity " +
-            "aggregated across all ten venues (Polymarket, Kalshi, Rothera, " +
-            "Limitless, Smarkets, Manifold, Metaculus, PredictIt, Futuur, Myriad), plus market " +
+            "aggregated across all 11 venues (Polymarket, Kalshi, Rothera, " +
+            "Limitless, Smarkets, Manifold, Metaculus, PredictIt, Futuur, Myriad, ForecastEx), plus market " +
             "highlights. Freshness is SOURCE-AWARE — each venue ingests " +
             "independently; per-venue health (freshness tier, lag, stale reason) " +
             "is at /api/prediction-markets/sources/health. Volume is " +
@@ -879,23 +1061,26 @@ export function registerTools(server, client) {
     }, async ({ fiat }) => present(await client.getPublicPmOverview({ fiat })));
     server.registerTool("pm_data_events", {
         title: "Search prediction markets across all venues",
-        description: "Free public search over prediction-market events across ALL ten " +
+        description: "Free public search over prediction-market events across ALL 11 " +
             "venues (Polymarket, Kalshi, Rothera, Limitless, Smarkets, " +
-            "Manifold, Metaculus, PredictIt, Futuur, Myriad) — broader than discover_pm_markets, which is " +
+            "Manifold, Metaculus, PredictIt, Futuur, Myriad, ForecastEx) — broader than discover_pm_markets, which is " +
             "scoped to the paper-tradeable venues. Returns titles, probabilities, " +
             "volume/liquidity, status, and source per event, plus " +
             "referenceProbability when present (CoinRithm's canonical cross-venue " +
             "number for open events matched across venues — probability, " +
             "venueCount, spreadPoints, and outcomeName for multi-outcome " +
-            "leaders). Research/data only: to trade, use discover_pm_markets + " +
-            "pm_quote instead. No API key required.",
+            "leaders), quality (persisted truth-engine verdict: decisionEligible " +
+            "+ warning/block reason codes — blocked markets stay visible but " +
+            "cannot drive paper opens or alerts), and crossPlatform (sibling " +
+            "venues pricing the same question). Research/data only: to trade, " +
+            "use discover_pm_markets + pm_quote instead. No API key required.",
         inputSchema: {
             q: z.string().optional().describe("Optional search text."),
             source: z
                 .string()
                 .optional()
                 .describe("Optional venue filter: polymarket, kalshi, rothera, limitless, " +
-                "smarkets, manifold, metaculus, predictit, futuur, or myriad."),
+                "smarkets, manifold, metaculus, predictit, futuur, myriad, or forecastex."),
             status: z
                 .string()
                 .optional()
@@ -949,7 +1134,7 @@ export function registerTools(server, client) {
             source: z
                 .string()
                 .describe("Venue slug: polymarket, kalshi, rothera, limitless, smarkets, " +
-                "manifold, metaculus, predictit, futuur, or myriad."),
+                "manifold, metaculus, predictit, futuur, myriad, or forecastex."),
             slug: z.string().describe("Event slug on that venue."),
             fiat: z
                 .string()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinrithm/mcp-trading",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "mcpName": "io.github.CoinRithm/mcp-trading",
   "description": "CoinRithm paper-trading toolkit: an MCP server (coinrithm-mcp) AND a self-host agent runner (coinrithm-agent) for spot, futures, and prediction markets with a user-minted API key.",
   "type": "module",
@@ -31,6 +31,10 @@
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
     "start": "node dist/index.js",
     "start:http": "node dist/http.js",
     "smoke:agent": "npm run build && node scripts/agent-smoke.mjs",
@@ -70,9 +74,13 @@
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@eslint/js": "^9.13.0",
     "@types/express": "^4.17.21",
     "@types/node": "^20.14.0",
+    "eslint": "^9.13.0",
+    "prettier": "^3.3.3",
     "typescript": "^5.5.0",
+    "typescript-eslint": "^8.11.0",
     "vitest": "^2.1.0"
   }
 }