@coinrithm/mcp-trading 0.7.10 → 0.7.12

package/CHANGELOG.md

@@ -5,6 +5,37 @@ ships two binaries — `coinrithm-mcp` (the MCP server) and `coinrithm-agent` (t
 self-host agent runner) — versioned together. The CoinRithm **API contract** is
 versioned separately (see `openapi.yaml` `info.version`, currently `1.7.0`).
 
+## 0.7.12 — 2026-09-15
+
+Clarify `whoami`, `cancel_spot_order` and `report_pm_opportunity` descriptions,
+removing execution-cost prose unrelated to these operations. Document actual
+authentication, side effects, result fields and retry behavior.
+
+Spot cancellation now advertises its existing idempotent behavior. Opportunity
+reporting no longer advertises unconditional idempotency: duplicate protection
+requires `decisionId` (or `agentTrace.decisionId`) under the same API key; the
+first stored record wins. Reporting remains a write despite requiring only the
+`read` scope, and its evidence remains explicitly self-reported.
+
+Tool names, accepted inputs and execution behavior are unchanged. This source
+entry does not establish registry publication, deployment or a new Glama score.
+
+## 0.7.11 — 2026-09-15
+
+Fix opportunity reporting that previously treated resolved API failures as
+successful submissions. Only `ok: true` confirms a report. HTTP errors remain
+unconfirmed; transport failures and exceptions have an unknown delivery outcome.
+
+`CycleResult.opportunity` now contains confirmed reports only. The additive
+`opportunityReport` field preserves the attempted payload, outcome and status,
+without API error bodies or exception details. Existing consumers should use
+this field when they need attempted rather than confirmed evidence.
+
+The reporter retains its one-invocation-per-cycle latch and adds no retries.
+Focused regressions compare successful and failed reporting in skip/act cycles
+and verify unchanged trading results and runner state. SDK versions are unchanged.
+This source entry does not establish registry publication or hosted deployment.
+
 ## 0.7.10 — 2026-09-15
 
 Source changes following the published 0.7.9 release. The TypeScript SDK remains
@@ -26,8 +57,9 @@ Source changes following the published 0.7.9 release. The TypeScript SDK remains
 - Pin workflow actions and verify release-tool checksums. Add installed-package
   compatibility and restart smoke checks across operating systems and runtimes.
 
-Source/CI checks, registry publication and production deployment are separate.
-This entry does not claim that 0.7.10 is published or deployed.
+0.7.10 was published and deployed on 2026-09-15. Registry and GitHub downloads
+matched the CI-tested archive; hosted MCP and scheduler deployments finished.
+See the [release record](https://github.com/CoinRithm/coinrithm-agent-trading/releases/tag/mcp-trading-v0.7.10).
 
 ## 0.7.9 - 2026-09-15
 

package/README.md

@@ -42,14 +42,15 @@ This package ships two binaries:
 
 > **Paper trading only** — virtual funds (50,000 mUSD). Not financial advice.
 
-## Version 0.7.10
-
-This source version adds restart identity persistence, a supported engine
-import, opt-in entry predicates and configuration warnings. It also fixes
-runner startup on Node 18 by importing the Node crypto API explicitly. See
-[CHANGELOG.md](./CHANGELOG.md). Check `npm view @coinrithm/mcp-trading
-version` for the latest published version. Hosted deployments and npm releases
-are separate.
+## Version 0.7.12
+
+This patch clarifies `whoami`, `cancel_spot_order` and `report_pm_opportunity`
+for MCP clients. Cancellation is marked safe to repeat; opportunity reporting
+is a write whose duplicate protection requires a decision ID. Tool names,
+accepted inputs and execution behavior are unchanged. See [CHANGELOG.md](./CHANGELOG.md).
+This source entry does not establish publication. Check
+`npm view @coinrithm/mcp-trading version` for the latest published version;
+hosted deployments and npm releases are separate.
 
 Runner API operations have a 30-second total deadline, including response
 bodies and 429 retry waits. Timeout and cancellation results remain unconfirmed;

package/dist/agent/engine.d.ts

@@ -12,4 +12,4 @@ export { newState, rollDay, loadState, saveState } from "./state.js";
 export { makeRunId } from "./runEvidence.js";
 export { parseCadenceMs } from "./util.js";
 export { BENCHMARK_AGENTS, BENCHMARK_STRATEGIES, decideMechanical, isBenchmarkStrategy, type BenchmarkStrategy, type BenchmarkAgentDefinition, } from "./mechanical.js";
-export type { AgentSpec, RunState, CycleResult, PlannedAction, Venue, ProviderName, ModelConfig, } from "./types.js";
+export type { AgentSpec, RunState, CycleResult, OpportunityReport, PostedOpportunity, PlannedAction, Venue, ProviderName, ModelConfig, } from "./types.js";

package/dist/agent/opportunityReporter.d.ts

@@ -1,5 +1,5 @@
 import type { CoinRithmClient, ProvenanceReport } from "./client.js";
-import type { AgentSpec, AgentTrace, PostedOpportunity } from "./types.js";
+import type { AgentSpec, AgentTrace, OpportunityReport, PostedOpportunity } from "./types.js";
 export declare function createOpportunityReporter({ client, spec, live, enabled, runId, decisionId, provenance, baseTrace, log, }: {
     client: CoinRithmClient;
     spec: AgentSpec;
@@ -13,4 +13,5 @@ export declare function createOpportunityReporter({ client, spec, live, enabled,
 }): {
     post: (o: PostedOpportunity) => Promise<void>;
     readonly posted: PostedOpportunity | undefined;
+    readonly report: OpportunityReport | undefined;
 };

package/dist/agent/opportunityReporter.js

@@ -1,13 +1,12 @@
 export function createOpportunityReporter({ client, spec, live, enabled, runId, decisionId, provenance, baseTrace, log, }) {
-    let opportunityPosted = false;
-    let postedOpportunity;
+    let attempted = false;
+    let report;
     const post = async (o) => {
-        if (!enabled || !live || opportunityPosted)
+        if (!enabled || !live || attempted)
             return;
-        opportunityPosted = true;
-        postedOpportunity = o;
+        attempted = true;
         try {
-            await client.reportPmOpportunity({
+            const result = await client.reportPmOpportunity({
                 kind: o.kind,
                 source: o.source,
                 slug: o.slug,
@@ -23,16 +22,38 @@ export function createOpportunityReporter({ client, spec, live, enabled, runId,
                 runId,
                 provenance,
             }, baseTrace);
-            log(`reported ${o.kind} opportunity (universe ${o.universeSize ?? "?"})`);
+            report = {
+                opportunity: o,
+                outcome: result.ok
+                    ? "confirmed"
+                    : result.status === 0
+                        ? "unknown"
+                        : "http_error",
+                status: result.status,
+            };
+            if (result.ok) {
+                log(`reported ${o.kind} opportunity (universe ${o.universeSize ?? "?"})`);
+            }
+            else if (result.status === 0) {
+                log("opportunity report outcome unknown (transport failure)");
+            }
+            else {
+                log(`opportunity report received HTTP ${result.status}; delivery unconfirmed`);
+            }
         }
-        catch (err) {
-            log(`opportunity post failed: ${err instanceof Error ? err.message : String(err)}`);
+        catch {
+            report = { opportunity: o, outcome: "unknown", status: 0 };
+            // Exceptions and API error bodies may contain private request details.
+            log("opportunity report outcome unknown (exception)");
         }
     };
     return {
         post,
         get posted() {
-            return postedOpportunity;
+            return report?.outcome === "confirmed" ? report.opportunity : undefined;
+        },
+        get report() {
+            return report;
         },
     };
 }

package/dist/agent/runner.js

@@ -866,6 +866,9 @@ async function runCycleCore(deps, capture) {
             writeAttempted: decision.actions.length,
             writeAccepted: 0,
             ...(opportunities.posted ? { opportunity: opportunities.posted } : {}),
+            ...(opportunities.report
+                ? { opportunityReport: opportunities.report }
+                : {}),
             ...observationReceipt,
         };
     }
@@ -1276,6 +1279,9 @@ async function runCycleCore(deps, capture) {
         writeAttempted: decision.actions.length,
         writeAccepted: planned.filter((p) => p.accepted).length,
         ...(opportunities.posted ? { opportunity: opportunities.posted } : {}),
+        ...(opportunities.report
+            ? { opportunityReport: opportunities.report }
+            : {}),
         ...observationReceipt,
     };
 }

package/dist/agent/types.d.ts

@@ -504,6 +504,12 @@ export interface CycleResult {
     writeAttempted?: number;
     writeAccepted?: number;
     opportunity?: PostedOpportunity;
+    opportunityReport?: OpportunityReport;
+}
+export interface OpportunityReport {
+    opportunity: PostedOpportunity;
+    outcome: "confirmed" | "http_error" | "unknown";
+    status: number;
 }
 export interface PostedOpportunity {
     kind: "abstained" | "forecast_only" | "quote_expired";

package/dist/tools.js

@@ -604,12 +604,14 @@ export function registerTools(server, client) {
     // ---------------- identity ----------------
     server.registerTool("whoami", {
         title: "Who am I (CoinRithm)",
-        description: "Return the identity behind the configured API key: userId, keyId, " +
-            "granted scopes, plus the key's agentName and agentModel (both null " +
-            "until set in Profile -> API Keys; agentModel is the self-reported " +
-            "model/runtime label shown on the public Agent Arena when opted in). " +
-            "Use this first to confirm what the key is allowed to do. " +
-            PAPER_NOTE,
+        description: "Check the caller's CoinRithm API-key identity and permissions before " +
+            "using account or trading tools. Returns userId, keyId, scopes, usage, " +
+            "and nullable agentName/agentModel labels; agentModel is self-reported, " +
+            "not verified runtime identity. Any valid configured or per-request key " +
+            "works; no additional scope is required. Missing or invalid keys return " +
+            "401. Omit agentTrace for a simple check. Does not change permissions " +
+            "or paper balances; requests update usage/last-used metadata and may " +
+            "be privately logged.",
         inputSchema: {
             agentTrace: AGENT_TRACE_SCHEMA,
         },
@@ -1176,16 +1178,26 @@ export function registerTools(server, client) {
     }, requestKey(extra))));
     server.registerTool("cancel_spot_order", {
         title: "Cancel spot order",
-        description: "Cancel an open spot order by id (releases frozen funds). Requires the " +
-            "trade:spot scope. " +
-            PAPER_NOTE,
+        description: "Cancel the unfilled remainder of your paper spot order and release " +
+            "its reserved funds. Requires trade:spot scope; get orderId from " +
+            "list_open_orders. Does not reverse filled trades. Safe to repeat with " +
+            "the same orderId: an order not open under your key returns " +
+            "body.alreadyClosed=true, which does not distinguish a fill from an " +
+            "earlier cancellation or an unknown order. Use get_my_trades to check " +
+            "fills. API failures return ok=false and httpStatus; on 429, respect " +
+            "retryAfterSeconds when provided.",
         inputSchema: {
-            orderId: z.number().int().positive().describe("Open order id."),
+            orderId: z
+                .number()
+                .int()
+                .positive()
+                .describe("Your paper spot order id from list_open_orders."),
             agentTrace: AGENT_TRACE_SCHEMA,
         },
         outputSchema: API_RESULT_OUTPUT_SCHEMA,
         annotations: mutatingAnnotations("Cancel spot order", {
             destructive: true,
+            idempotent: true,
         }),
     }, async ({ orderId, agentTrace }, extra) => present(await client.cancelSpotOrder(orderId, requestKey(extra), agentTrace)));
     server.registerTool("open_futures_position", {
@@ -1375,21 +1387,19 @@ export function registerTools(server, client) {
     }, 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,
+        description: "Save a durable SELF-REPORT of a prediction-market evaluation for a " +
+            "decision that did not open a position. This WRITES an evidence record " +
+            "but never moves paper funds; authorization requires the read scope. " +
+            "It does not independently verify your evaluation. Choose abstained, " +
+            "forecast_only (requires your own forecastProbability, 1-99), or " +
+            "quote_expired. Report once per decision cycle; cohort.universeSize " +
+            "records its breadth. Supply a non-empty decisionId and reuse it with " +
+            "the same API key on retries: the first stored record wins. " +
+            "agentTrace.decisionId is a fallback; omitting both creates separate " +
+            "records. Success returns " +
+            "body.decisionUuid and, on replay, body.idempotentReplay=true. Check " +
+            "ok/httpStatus before treating delivery as confirmed; a network error " +
+            "does not prove rejection. Use open_pm_position to place a paper trade.",
         inputSchema: {
             kind: z
                 .enum(["abstained", "forecast_only", "quote_expired"])
@@ -1410,8 +1420,8 @@ export function registerTools(server, client) {
                 .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."),
+                .describe("Your OWN forecast probability (1-99). REQUIRED for forecast_only; " +
+                "optional for other kinds. Never echo the market price."),
             marketProbability: z
                 .number()
                 .min(0)
@@ -1442,15 +1452,17 @@ export function registerTools(server, client) {
             decisionId: z
                 .string()
                 .optional()
-                .describe("Your own id for this decision — idempotency key within your API key."),
+                .describe("Non-empty id for this decision, unique within your API key. " +
+                "Reuse for retries. Falls back to agentTrace.decisionId; " +
+                "omitting both creates a new record on each call."),
             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,
-        }),
+        // Idempotency is conditional on decisionId; it is not a safe default
+        // for the entire tool because the field remains optional.
+        annotations: mutatingAnnotations("Report a non-opened PM opportunity"),
     }, async ({ kind, source, slug, outcomeExternalMarketId, forecastProbability, marketProbability, reasonCode, cohort, decisionId, runId, provenance, agentTrace, }, extra) => present(await client.reportPmOpportunity({
         kind,
         source,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinrithm/mcp-trading",
-  "version": "0.7.10",
+  "version": "0.7.12",
   "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",