@coinrithm/mcp-trading 0.7.2 → 0.7.4

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,
@@ -120,6 +172,391 @@ function present(result) {
         isError: !result.ok,
     };
 }
+function isJsonRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function pick(record, keys) {
+    return Object.fromEntries(keys
+        .filter((key) => record[key] !== undefined)
+        .map((key) => [key, record[key]]));
+}
+function probability(value) {
+    if (typeof value !== "number" && typeof value !== "string")
+        return null;
+    if (typeof value === "string" && value.trim() === "")
+        return null;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+const EVENT_SUMMARY_FIELDS = [
+    "id",
+    "slug",
+    "title",
+    "status",
+    "startDate",
+    "endDate",
+    "resolvedAt",
+    "freshness",
+    "volume",
+    "volume24h",
+    "liquidity",
+    "priceChange24h",
+    "priceChange7d",
+    "bestBid",
+    "bestAsk",
+    "spread",
+    "marketsCount",
+    "referenceProbability",
+    "crossPlatform",
+    "decisionSupport",
+    "quality",
+];
+const OUTCOME_SUMMARY_FIELDS = [
+    "externalMarketId",
+    "name",
+    "probability",
+    "priceChange24h",
+];
+const WHALE_TRADE_FIELDS = [
+    "source",
+    "sourceName",
+    "eventSlug",
+    "eventTitle",
+    "wallet",
+    "traderName",
+    "side",
+    "outcome",
+    "marketQuestion",
+    "usdValue",
+    "price",
+    "sourceMarketRef",
+    "nativeValue",
+    "nativeCurrency",
+    "valueBasis",
+    "evidenceType",
+    "evidenceRef",
+    "evidenceUrl",
+    "availability",
+    "observedAt",
+    "latencySeconds",
+    "tradedAt",
+];
+function boundedText(value, maxLength) {
+    if (typeof value !== "string" || value.length <= maxLength)
+        return value;
+    return `${value.slice(0, maxLength - 1)}…`;
+}
+function compactWhaleTrade(value) {
+    return isJsonRecord(value) ? pick(value, WHALE_TRADE_FIELDS) : value;
+}
+function eventSummary(value) {
+    if (!isJsonRecord(value))
+        return value;
+    const source = isJsonRecord(value.source)
+        ? pick(value.source, ["id", "name", "kind", "supportsTrading"])
+        : value.source;
+    const outcomes = Array.isArray(value.outcomes)
+        ? value.outcomes
+            .map((outcome, index) => ({ outcome, index }))
+            .sort((left, right) => {
+            const a = isJsonRecord(left.outcome)
+                ? probability(left.outcome.probability)
+                : null;
+            const b = isJsonRecord(right.outcome)
+                ? probability(right.outcome.probability)
+                : null;
+            const aValid = a !== null;
+            const bValid = b !== null;
+            if (aValid !== bValid)
+                return aValid ? -1 : 1;
+            return aValid && bValid && a !== b
+                ? b - a
+                : left.index - right.index;
+        })
+            .slice(0, 5)
+            .map(({ outcome }) => isJsonRecord(outcome)
+            ? pick(outcome, OUTCOME_SUMMARY_FIELDS)
+            : outcome)
+        : [];
+    return {
+        ...pick(value, EVENT_SUMMARY_FIELDS),
+        source,
+        outcomeCount: Array.isArray(value.outcomes) ? value.outcomes.length : 0,
+        outcomes,
+    };
+}
+/**
+ * Keep keyless discovery calls small enough for an agent context window.
+ * Full event evidence remains available from pm_data_event.
+ */
+export function compactPublicPmOverview(data) {
+    if (!isJsonRecord(data))
+        return data;
+    const highlights = isJsonRecord(data.highlights)
+        ? Object.fromEntries(Object.entries(data.highlights).map(([key, value]) => [
+            key,
+            Array.isArray(value) ? value.map(eventSummary) : value,
+        ]))
+        : data.highlights;
+    return {
+        ...pick(data, [
+            "stats",
+            "categories",
+            "bySource",
+            "byCategory",
+            "updatedAt",
+        ]),
+        highlights,
+    };
+}
+export function compactPublicPmEvents(data) {
+    if (!isJsonRecord(data))
+        return data;
+    return {
+        ...data,
+        data: Array.isArray(data.data) ? data.data.map(eventSummary) : data.data,
+    };
+}
+function compactSnapshot(value) {
+    if (!isJsonRecord(value))
+        return value;
+    return {
+        ...pick(value, [
+            "id",
+            "capturedAt",
+            "observedAt",
+            "timestamp",
+            "asOf",
+            "probability",
+            "volume",
+            "volume24h",
+            "liquidity",
+            "bestBid",
+            "bestAsk",
+            "spread",
+            "outcome",
+            "externalMarketId",
+        ]),
+        ...(Array.isArray(value.outcomes)
+            ? {
+                outcomeCount: value.outcomes.length,
+                outcomes: value.outcomes
+                    .slice(0, 10)
+                    .map((outcome) => isJsonRecord(outcome)
+                    ? pick(outcome, OUTCOME_SUMMARY_FIELDS)
+                    : outcome),
+            }
+            : {}),
+    };
+}
+function compactComparison(value) {
+    if (!isJsonRecord(value))
+        return value;
+    const outcomes = Array.isArray(value.outcomes) ? value.outcomes : [];
+    const shared = outcomes.filter((outcome) => isJsonRecord(outcome) &&
+        (outcome.isShared === true ||
+            (outcome.presentInA === true && outcome.presentInB === true)));
+    const candidates = shared.length > 0 ? shared : outcomes;
+    const ranked = candidates
+        .map((outcome, index) => ({ outcome, index }))
+        .sort((left, right) => {
+        const a = isJsonRecord(left.outcome)
+            ? Math.abs(probability(left.outcome.deltaPoints) ?? -1)
+            : -1;
+        const b = isJsonRecord(right.outcome)
+            ? Math.abs(probability(right.outcome.deltaPoints) ?? -1)
+            : -1;
+        return a !== b ? b - a : left.index - right.index;
+    })
+        .slice(0, 5)
+        .map(({ outcome }) => isJsonRecord(outcome)
+        ? pick(outcome, [
+            "key",
+            "label",
+            "eventAProbability",
+            "eventBProbability",
+            "deltaPoints",
+            "presentInA",
+            "presentInB",
+            "isShared",
+        ])
+        : outcome);
+    return {
+        summary: value.summary,
+        outcomeCount: outcomes.length,
+        outcomes: ranked,
+    };
+}
+function compactCrossSourceMatch(value) {
+    if (!isJsonRecord(value))
+        return value;
+    return {
+        ...pick(value, [
+            "matchId",
+            "confidence",
+            "matchMethod",
+            "recommendedSourceId",
+            "divergence",
+        ]),
+        comparison: compactComparison(value.comparison),
+        event: eventSummary(value.event),
+    };
+}
+/**
+ * Default event detail for agents: enough provenance and comparison evidence
+ * to reason safely without recursively spending an entire context window.
+ * Callers can explicitly request detail=full for the untouched API record.
+ */
+export function compactPublicPmEvent(data) {
+    if (!isJsonRecord(data))
+        return data;
+    const rawEvent = isJsonRecord(data.event) ? data.event : null;
+    const summary = rawEvent ? eventSummary(rawEvent) : data.event;
+    const event = isJsonRecord(summary)
+        ? {
+            ...summary,
+            ...(rawEvent
+                ? {
+                    image: rawEvent.image,
+                    externalUrl: rawEvent.externalUrl,
+                    description: boundedText(rawEvent.description, 1_200),
+                    resolutionCriteria: boundedText(rawEvent.resolutionCriteria, 2_000),
+                    forecasting: rawEvent.forecasting,
+                    topics: Array.isArray(rawEvent.topics)
+                        ? rawEvent.topics.slice(0, 20)
+                        : rawEvent.topics,
+                    directRelatedCoins: Array.isArray(rawEvent.directRelatedCoins)
+                        ? rawEvent.directRelatedCoins.slice(0, 20)
+                        : rawEvent.directRelatedCoins,
+                    indirectRelatedCoins: Array.isArray(rawEvent.indirectRelatedCoins)
+                        ? rawEvent.indirectRelatedCoins.slice(0, 20)
+                        : rawEvent.indirectRelatedCoins,
+                }
+                : {}),
+        }
+        : summary;
+    const relatedEvents = Array.isArray(data.relatedEvents)
+        ? data.relatedEvents.slice(0, 5).map(eventSummary)
+        : data.relatedEvents;
+    const crossSourceMatches = Array.isArray(data.crossSourceMatches)
+        ? data.crossSourceMatches
+            .map((match, index) => ({ match, index }))
+            .sort((left, right) => {
+            const a = isJsonRecord(left.match)
+                ? probability(left.match.confidence)
+                : null;
+            const b = isJsonRecord(right.match)
+                ? probability(right.match.confidence)
+                : null;
+            return a !== b && a !== null && b !== null
+                ? b - a
+                : left.index - right.index;
+        })
+            .slice(0, 5)
+            .map(({ match }) => compactCrossSourceMatch(match))
+        : data.crossSourceMatches;
+    return {
+        ...pick(data, ["resolution", "agentsTradingMarket"]),
+        event,
+        snapshotCount: Array.isArray(data.snapshots) ? data.snapshots.length : 0,
+        snapshots: Array.isArray(data.snapshots)
+            ? data.snapshots.slice(-20).map(compactSnapshot)
+            : data.snapshots,
+        relatedEventCount: Array.isArray(data.relatedEvents)
+            ? data.relatedEvents.length
+            : 0,
+        relatedEvents,
+        crossSourceMatchCount: Array.isArray(data.crossSourceMatches)
+            ? data.crossSourceMatches.length
+            : 0,
+        crossSourceMatches,
+        volumeHistory: Array.isArray(data.volumeHistory)
+            ? data.volumeHistory.slice(-90)
+            : data.volumeHistory,
+        relatedNews: Array.isArray(data.relatedNews)
+            ? data.relatedNews.slice(0, 5)
+            : data.relatedNews,
+        topicRelatedCoins: Array.isArray(data.topicRelatedCoins)
+            ? data.topicRelatedCoins.slice(0, 20)
+            : data.topicRelatedCoins,
+        recentWhaleTrades: Array.isArray(data.recentWhaleTrades)
+            ? data.recentWhaleTrades.slice(0, 5).map(compactWhaleTrade)
+            : data.recentWhaleTrades,
+    };
+}
+export function compactPublicPmWhales(data, limit) {
+    if (!isJsonRecord(data))
+        return data;
+    const trades = Array.isArray(data.trades)
+        ? data.trades.slice(0, limit).map(compactWhaleTrade)
+        : data.trades;
+    return { ...data, trades };
+}
+const MATCH_PAIR_FIELDS = [
+    "matchId",
+    "confidence",
+    "matchMethod",
+    "recommendedSourceId",
+    "divergence",
+];
+function compactMatchPair(value) {
+    if (!isJsonRecord(value))
+        return value;
+    return {
+        ...pick(value, MATCH_PAIR_FIELDS),
+        comparison: compactComparison(value.comparison),
+    };
+}
+function compactMatchCluster(value) {
+    if (!isJsonRecord(value))
+        return value;
+    const events = Array.isArray(value.events)
+        ? value.events.map(eventSummary)
+        : value.events;
+    const comparisons = Array.isArray(value.comparisons)
+        ? value.comparisons.map((comparison) => isJsonRecord(comparison)
+            ? {
+                eventId: comparison.eventId,
+                pair: compactMatchPair(comparison.pair),
+            }
+            : comparison)
+        : value.comparisons;
+    return {
+        ...pick(value, [
+            "clusterId",
+            "primaryEventId",
+            "title",
+            "referenceProbability",
+            "maxOverallGap",
+            "maxOutcomeGap",
+            "maxConfidence",
+        ]),
+        eventCount: Array.isArray(value.events) ? value.events.length : 0,
+        events,
+        comparisons,
+    };
+}
+/**
+ * Keep cross-venue disagreement clusters small enough for an agent context
+ * window: each event is reduced to eventSummary (drops descriptions, images,
+ * sparklines) and each pairwise comparison keeps only its top-5 highest-delta
+ * shared outcomes (compactComparison) — the same bounding pm_data_event
+ * applies to crossSourceMatches. Verified live: a 5-cluster page drops from
+ * ~466KB to ~48KB.
+ */
+export function compactPublicPmDisagreements(data) {
+    if (!isJsonRecord(data))
+        return data;
+    return {
+        ...pick(data, ["total", "hasMore", "pagination", "meta"]),
+        data: Array.isArray(data.data)
+            ? data.data.map(compactMatchCluster)
+            : data.data,
+    };
+}
+function mapSuccessfulBody(result, transform) {
+    return result.ok ? { ...result, data: transform(result.data) } : result;
+}
 export function registerTools(server, client) {
     // ---------------- identity ----------------
     server.registerTool("whoami", {
@@ -358,9 +795,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 +862,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 +891,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 +910,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 +1022,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 +1050,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 +1298,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,9 +1426,10 @@ 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 " +
-            "highlights. Freshness is SOURCE-AWARE — each venue ingests " +
+            "aggregated across all 11 venues (Polymarket, Kalshi, Rothera, " +
+            "Limitless, Smarkets, Manifold, Metaculus, PredictIt, Futuur, Myriad, ForecastEx), plus market " +
+            "highlights in a compact discovery shape. Use pm_data_event for full " +
+            "event evidence. 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 " +
             "reported on each venue's own basis (see the methodology at " +
@@ -876,26 +1444,31 @@ export function registerTools(server, client) {
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Cross-venue prediction-market statistics"),
-    }, async ({ fiat }) => present(await client.getPublicPmOverview({ fiat })));
+    }, async ({ fiat }) => present(mapSuccessfulBody(await client.getPublicPmOverview({ fiat }), compactPublicPmOverview)));
     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 " +
+            "the five highest-probability outcomes and the full outcome count. " +
+            "Use pm_data_event for all outcomes and full evidence. Also returns " +
             "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()
@@ -921,7 +1494,7 @@ export function registerTools(server, client) {
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Search prediction markets across all venues"),
-    }, async ({ q, source, status, sort, limit, offset, fiat }) => present(await client.listPublicPmEvents({
+    }, async ({ q, source, status, sort, limit, offset, fiat }) => present(mapSuccessfulBody(await client.listPublicPmEvents({
         q,
         source,
         status,
@@ -929,9 +1502,9 @@ export function registerTools(server, client) {
         limit,
         offset,
         fiat,
-    })));
+    }), compactPublicPmEvents)));
     server.registerTool("pm_data_event", {
-        title: "Get full prediction-market event detail",
+        title: "Get prediction-market event detail",
         description: "Free public detail for one prediction-market event by venue + slug: " +
             "outcomes with probabilities, price snapshots, resolution evidence, " +
             "crossSourceMatches (the SAME real-world question priced on other " +
@@ -943,32 +1516,216 @@ export function registerTools(server, client) {
             "recent whale trades on the event, related events, related news, and " +
             "volumeHistory when present (daily volume points captured since " +
             "2026-07-02 — read the event's volume trend directly from it). " +
+            "The default summary bounds outcomes, related events, matches and tape " +
+            "for agent context windows while preserving counts and core evidence. " +
+            "Set detail=full only when the untouched provider-rich record is needed. " +
             "This is the cross-venue research view; for tradability use pm_quote. " +
             "No API key required.",
         inputSchema: {
             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()
                 .optional()
                 .describe("Fiat currency code for monetary figures (default usd)."),
+            detail: z
+                .enum(["summary", "full"])
+                .optional()
+                .describe("Response detail: bounded summary (default) or untouched full record."),
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
-        annotations: readOnlyAnnotations("Get full prediction-market event detail"),
-    }, async ({ source, slug, fiat }) => present(await client.getPublicPmEvent(source, slug, { fiat })));
+        annotations: readOnlyAnnotations("Get prediction-market event detail"),
+    }, async ({ source, slug, fiat, detail }) => {
+        const result = await client.getPublicPmEvent(source, slug, { fiat });
+        return present(detail === "full"
+            ? result
+            : mapSuccessfulBody(result, compactPublicPmEvent));
+    });
     server.registerTool("pm_data_whales", {
         title: "Get latest prediction-market whale trades",
         description: "Free public tape of the latest large prediction-market trades " +
-            "(roughly $1k+ notional) across venues, newest first (top 50): side, " +
+            "(roughly $1k+ notional) across venues, newest first: side, " +
             "outcome, USD value, price, market question, and the event it printed " +
             "on. Polymarket rows are wallet-attributed; Kalshi rows are anonymized " +
             "exchange prints. A large print is information, not a recommendation. " +
             "No API key required.",
-        inputSchema: {},
+        inputSchema: {
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .describe("Max rows (1-50, default 10)."),
+        },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: readOnlyAnnotations("Get latest prediction-market whale trades"),
-    }, async () => present(await client.getPublicPmWhales()));
+    }, async ({ limit }) => present(mapSuccessfulBody(await client.getPublicPmWhales(), (data) => compactPublicPmWhales(data, limit ?? 10))));
+    server.registerTool("pm_data_disagreements", {
+        title: "Cross-venue disagreement clusters",
+        description: "Free public cross-venue disagreement clusters: prediction-market " +
+            "events CoinRithm has matched as the SAME real-world question across " +
+            "2+ venues (approved cross-source matches), graph-clustered so one row " +
+            "covers every venue tracking that question. Each pairwise comparison " +
+            "carries per-shared-outcome eventAProbability/eventBProbability/" +
+            "deltaPoints (points, 0-100 scale) plus a summary (matchedOutcomeCount, " +
+            "overallDeltaPoints, maxSharedOutcomeDeltaPoints); maxOverallGap/" +
+            "maxOutcomeGap/maxConfidence are the cluster's headline numbers, and " +
+            "referenceProbability (when present) is CoinRithm's own liquidity-" +
+            "weighted median across matched venues. Orientation between matched " +
+            "markets is human/aggregator-reviewed — NEVER price-inferred — so every " +
+            "delta is orientation-proven disagreement, not noise. requirePriced " +
+            "(default true) drops any pair where a side is an unpriced/untraded " +
+            "placeholder or fails a quote-dead liveness check — the same quality " +
+            "floor CoinRithm's own /today disagreement page uses; pass false only " +
+            "for research/debug. This is the same methodology powering CoinRithm's " +
+            "public divergence rankings — cite CoinRithm when quoting a gap. " +
+            "Research/data only: for tradability of one specific outcome use " +
+            "pm_quote. No API key required.",
+        inputSchema: {
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(25)
+                .optional()
+                .describe("Max clusters (1-25, default 10)."),
+            offset: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Pagination offset (default 0)."),
+            sort: z
+                .enum([
+                "confidence_desc",
+                "divergence_desc",
+                "max_outcome_delta_desc",
+            ])
+                .optional()
+                .describe("Ranking: confidence_desc (default) = strongest match first; " +
+                "divergence_desc = total cross-outcome gap; " +
+                "max_outcome_delta_desc = single largest shared-outcome gap " +
+                "(avoids multi-leg basket noise)."),
+            minDivergence: z
+                .number()
+                .min(0)
+                .optional()
+                .describe("Floor (points, 0-100) on whichever metric the active sort ranks by."),
+            sourceKind: z
+                .enum(["market"])
+                .optional()
+                .describe("Pass 'market' to restrict both sides of every pair to real-money " +
+                "market venues (excludes forecast/play-money venues like " +
+                "Metaculus/Manifold)."),
+            status: z
+                .enum(["open"])
+                .optional()
+                .describe("Pass 'open' to require BOTH matched events be currently open."),
+            maxSnapshotAgeMinutes: z
+                .number()
+                .min(0)
+                .optional()
+                .describe("Require both matched events' probability come from a price " +
+                "snapshot captured within this many minutes."),
+            requirePriced: z
+                .boolean()
+                .optional()
+                .describe("Default true: drops any pair where a side is an unpriced/untraded " +
+                "placeholder or fails a quote-dead liveness check. Set false only " +
+                "for research/debug."),
+            fiat: z
+                .string()
+                .optional()
+                .describe("Fiat currency code for monetary figures (default usd)."),
+        },
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Cross-venue disagreement clusters"),
+    }, async ({ limit, offset, sort, minDivergence, sourceKind, status, maxSnapshotAgeMinutes, requirePriced, fiat, }) => present(mapSuccessfulBody(await client.getPublicPmMatches({
+        limit,
+        offset,
+        sort,
+        minDivergence,
+        sourceKind,
+        status,
+        maxSnapshotAgeMinutes,
+        requirePriced,
+        fiat,
+    }), compactPublicPmDisagreements)));
+    server.registerTool("pm_data_calibration", {
+        title: "Per-venue forecast-accuracy calibration",
+        description: "Free public per-venue forecast-accuracy scorecard: for each venue, " +
+            "calibrationError (Expected Calibration Error, 0-1, lower is better — " +
+            "the fair cross-venue headline), sampleSize, meanWinnerConfidence, and " +
+            "a 10-bucket reliability curve (predictedMean vs realizedRate per " +
+            "probability bucket) computed from that venue's OWN probability ~24h " +
+            "before resolution against the outcome that actually happened, over " +
+            "resolved markets with >=24h of pre-resolution history. Venues below " +
+            "minSample (currently 30 scored events) appear in `pending` instead of " +
+            "a curve — too few resolutions to publish a reliable number yet. Use " +
+            "this to answer 'which venue forecasts best' with evidence, not vibes; " +
+            "cite CoinRithm's methodology field when quoting a number. No API key " +
+            "required.",
+        inputSchema: {},
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Per-venue forecast-accuracy calibration"),
+    }, async () => present(await client.getPublicPmCalibration()));
+    server.registerTool("pm_data_canonical", {
+        title: "Canonical cross-venue event identity",
+        description: "Free public canonical-event identity: CoinRithm's stable cross-venue " +
+            "identity for one real-world question, independent of any single " +
+            "venue's slug. Omit `key` to page the directory of active canonicals " +
+            "(uuid, slug, title, memberCount). Pass `key` (a canonical's uuid OR " +
+            "slug) for one canonical's full record: its venue members (each with " +
+            "orientation — same/inverted/unknown, NEVER price-inferred — plus " +
+            "confidence and provenance basis) and an append-only judgment lineage " +
+            "(created/member_added/member_removed/merged, newest first). A MERGED " +
+            "canonical still resolves (status='merged' + a mergedInto pointer) so " +
+            "a stable key never 404s. Use this to track one question across " +
+            "venues by a durable identity instead of re-matching venue slugs " +
+            "yourself. No API key required.",
+        inputSchema: {
+            key: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("UUID or slug of one canonical event. Omit to list active canonicals."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(200)
+                .optional()
+                .describe("List mode only: max rows (1-200, default 50)."),
+            cursor: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("List mode only: pagination cursor — pass the previous " +
+                "response's pagination.nextCursor."),
+        },
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Canonical cross-venue event identity"),
+    }, async ({ key, limit, cursor }) => present(key
+        ? await client.getPublicPmCanonicalDetail(key)
+        : await client.getPublicPmCanonicalList({ limit, cursor })));
+    server.registerTool("pm_data_volume_history", {
+        title: "Global prediction-market volume trend",
+        description: "Free public global daily prediction-market volume trend: one point " +
+            "per UTC calendar day (day-over-day delta of each event's cumulative " +
+            "volume, summed across REAL-MONEY venues only — play-money/forecast " +
+            "venues like Manifold and Metaculus are excluded), with a per-venue " +
+            "breakdown (bySource) each day. Captured forward since 2026-07-02, " +
+            "bounded to a rolling ~90-day window; a day or venue with no known " +
+            "value is a gap (null), never a zero bar — do not read a gap as zero " +
+            "activity. Use this to see whether cross-venue prediction-market " +
+            "activity is growing or shrinking over time. No API key required.",
+        inputSchema: {},
+        outputSchema: API_RESULT_OUTPUT_SCHEMA,
+        annotations: readOnlyAnnotations("Global prediction-market volume trend"),
+    }, async () => present(await client.getPublicPmVolumeHistory()));
 }