@battlegrid/mcp-server 32.0.1 → 32.0.3

package/README.md

@@ -38,6 +38,83 @@ Seeing package `31.x` alongside handshake `battlegrid@33.x` — the package **be
 
 **What this changes for you:** nothing about how you call anything. Upgrading the package no longer waits on a server deploy, and a server deploy no longer strands you on a package that names the wrong contract — reconnect and the announcement follows. **Contract breaking-change notes are no longer keyed to package versions**, since a contract move is no longer a release here; the v11-and-earlier notes below are kept as history, and the live vocabulary is always discovery.
 
+## Contract history — v118.1 (a server fault says whether repeating is safe)
+
+**Nothing you send is refused that v118 accepted.** v118.1 is the contract on top of v118. No input schema moves.
+Reconnect the proxy, or restart it, so discovery reads the new annotation below.
+
+### Added fields
+
+- **`details.correlationId`** is on every error envelope. The server mints it once per call and writes it on that
+  call's one log entry, so quote it when you report a failure.
+- **`details.retryable`** is on a server fault: `SERVICE_UNAVAILABLE` from an unavailable dependency, and every
+  `INTERNAL_ERROR`. It says whether repeating the same call unchanged is safe, never that it will succeed:
+  - `true` means a repeat has no additional effect. If the repeat is then refused, follow that refusal;
+  - `false` on `SERVICE_UNAVAILABLE` means the call may have taken effect, so read the current state before
+    repeating it;
+  - `false` on `INTERNAL_ERROR` means repeating fails the same way;
+  - absent, on any typed refusal, means its message and `nextAct` say whether repeating helps.
+
+### Reclassified
+
+- **A dependency the server could not use answers `SERVICE_UNAVAILABLE`**, where it answered `INTERNAL_ERROR`. That
+  covers a dropped database or Redis connection, a serialization failure or deadlock, a network timeout, and the
+  exchange budget declining to admit a call. `retryable` is `true` for a tool that declares `readOnlyHint` or
+  `idempotentHint`.
+- **`reset_agent_drawdown_baseline` declares `idempotentHint: false`.** Each call moves the drawdown baseline to now,
+  so a repeat forgives any loss realized in between.
+
+## Contract history — v118 (a refused argument is the house error envelope)
+
+**Breaking at v118: an argument refusal is JSON, and the scope check comes first.** v118 is the contract on top of
+v117. No schema moves, so nothing you send is refused that v117 accepted. Code that read the SDK's refusal sentence
+must read the envelope instead.
+
+### Reshaped output — something you read has a new shape
+
+- **A call whose arguments the tool's schema refuses** is an `isError` result whose text is the same JSON envelope
+  every other refusal uses: `{ "code": "VALIDATION_ERROR", "message", "details": { "issueCount", "issues" } }`. It
+  was the SDK's `Input validation error: …` sentence.
+
+### Refusal vocabulary
+
+- **`details.issues`** holds the first 20 issues in the order the parse found them. Each is `{ path, message }`:
+  - `path` is where the issue is, as segments within the arguments object, and `[]` is the arguments object itself;
+  - `message` is the schema's own text, so a remedy the schema appends to an issue reaches you unchanged.
+- **`details.issueCount`** is how many issues the parse found. It exceeds the length of `issues` when more than 20
+  were found.
+- **An unrecognised key** is reported at the path of the object it was sent on, by an issue whose message names the
+  key. A retired argument therefore shows up as an issue on its parent object, not as a path ending in its own name.
+- **`message`** is the first issue's message.
+- **The refusal carries no `details.nextAct`.** Recover by making the same call with corrected arguments. A refusal of
+  a draft's staged content still carries `nextAct: "stage"`, so the two are told apart by `details.issues`.
+
+### Behaviour behind unchanged schemas
+
+- **The required scope is checked before the arguments are parsed.** A credential without the tool's scope is refused
+  `FORBIDDEN` with `details.requiredScope` whatever it sends. Before, an argument object the schema refused was
+  answered by the parse first.
+
+## Contract history — v117 (decided changes read at their horizon bar)
+
+**Breaking at v117, behind unchanged schemas.** v117 is the contract on top of v116; no input or output schema moves.
+
+### Rejected input — something you send is no longer accepted
+
+- **A verdict carrier or hold that reads a change over a horizon above the strategy timeframe is refused.** That is
+  `chg4h` and `chg24h` on a `1h` strategy, and `oiRegime` (the `1h` change) below `1h`. Such a change is a developing
+  read whatever its selector.
+  - **Where it is refused:** a strategy save, draft stage or preview, refused `CONDITION_VERDICT_READ_ILLEGAL` or
+    `CONDITION_HOLD_ILLEGAL`. Restoring an archived strategy that holds one is refused the same way until it is
+    repaired.
+  - **What the refusal says:** it names the carrier and the column, with a remedy that reads a horizon at or below
+    the strategy timeframe.
+
+### Behaviour behind unchanged schemas
+
+- **A change is the frame's price against its horizon bar's open.** A decided frame reads it exactly where it read
+  UNRESOLVED, and a horizon whose bar was not read is UNRESOLVED where it read FALSE.
+
 ## Contract history — v116 (the server moves to MCP SDK v2 and protocol 2026-07-28)
 
 **Breaking at v116: `test_generate_deployment_grid` takes its payload at the top level.** v116 is the contract on top

package/SKILL.md

@@ -72,8 +72,9 @@ than about authoring:
   `expectedPolicyId` and `expectedRevision` a `COMMITTED` preview returned.
 - **The proxy forwards numbers and `null` unchanged.** It never fills in a version, never retries a
   refused call and never rebuilds a request. A `DRAFT_VERSION_MOVED` or `DRAFT_AXIS_CONTESTED` refusal
-  carries `details.nextAct` from every tool, and a revision `CONFLICT` or validation refusal carries it
-  from a stage or commit; the next act is the caller's.
+  carries `details.nextAct` from every tool, and a revision `CONFLICT` or a refusal of the staged content
+  carries it from a stage or commit. A refused argument (`VALIDATION_ERROR` with `details.issues`)
+  carries none: make the same call with the arguments corrected. The next act is the caller's.
 
 `fork_strategy` copies a revision into a new create draft and creates nothing until that draft is
 committed. An agent binds to a strategy through its draft's `STRATEGY_BINDING` axis, on a create or

package/dist/index.d.ts

@@ -47,7 +47,7 @@ import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/cli
  * being asked. Move it for a change to THIS package — a proxy fix, a dependency bump, a docs
  * correction. Never move it to track the server.
  */
-export declare const PACKAGE_VERSION = "32.0.1";
+export declare const PACKAGE_VERSION = "32.0.3";
 export declare const DEFAULT_URL = "https://mcp.battlegrid.trade/mcp";
 export interface EnvConfig {
     apiKeys: string[];

package/dist/index.js

@@ -49,7 +49,7 @@ import { Client, SdkHttpError, StreamableHTTPClientTransport } from '@modelconte
  * being asked. Move it for a change to THIS package — a proxy fix, a dependency bump, a docs
  * correction. Never move it to track the server.
  */
-export const PACKAGE_VERSION = '32.0.1';
+export const PACKAGE_VERSION = '32.0.3';
 export const DEFAULT_URL = 'https://mcp.battlegrid.trade/mcp';
 const MAX_RETRIES = 3;
 const RETRY_DELAYS_MS = [2000, 4000, 8000];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@battlegrid/mcp-server",
-  "version": "32.0.1",
+  "version": "32.0.3",
   "description": "BattleGrid MCP server — play crypto prediction games from AI agents",
   "type": "module",
   "main": "dist/index.js",

package/skills/EXPORT.json

@@ -1,6 +1,6 @@
 {
   "generator": "battlegrid-app/server/scripts/export-mcp-skills.mjs",
-  "contractVersion": "116.0.0",
+  "contractVersion": "116.1.0",
   "files": {
     "battlegrid-agent-management/SKILL.md": "9dc151c32c3578d06e8895c6752d7a64959bff6a6681a01d62ab65e1ea1590d1",
     "battlegrid-agent-management/references/agent-stage-examples.md": "dffcc353d61dfc7b5bb6a2b3077fc6bf8c760a34c287cafb3b59b99306f24195",
@@ -13,8 +13,8 @@
     "battlegrid-strategy-authoring/SKILL.md": "39cfa46b1f640e6800edb7e85a8f2c4b6b8786cddf71bb8244d172a44fc11d75",
     "battlegrid-strategy-authoring/references/strategy-stage-examples.md": "f10ecdc91f3660a708eee7a7bacefce2acbb46c9cf7e0ac1454bd54f839f39fd",
     "battlegrid-strategy-doctor/SKILL.md": "e34e055b0cc9b355bc1adeb5d49d464eaa0756ca3f48dc89ca2ccdda94e1311f",
-    "battlegrid-strategy-examples/SKILL.md": "597ddacdfc00955fcfd5a1afcc40b5ea72a0f658acbbebc8264afeecc46d2306",
-    "battlegrid-strategy-examples/references/playbooks.md": "2309eb7e8324f563c5b1b51e05da931b37c542484135a2be749eff6ef78aa40f",
+    "battlegrid-strategy-examples/SKILL.md": "82df6781b8dbb222407cc58f622f5fadb6f933aeb7efb855c26a9ae13620cca3",
+    "battlegrid-strategy-examples/references/playbooks.md": "275352be43652ca0fd36a35981ea7ffcfabdc4f9b33293826656ee500d3795e9",
     "battlegrid-strategy-examples/references/recipes.md": "635e03d163100f6de37cda1f6cc12928d5d36aa0ea883bf44fc72f17cbf3e98e",
     "battlegrid-strategy-examples/references/tradingview-ports.md": "9eaa926cbe8606c6a09f91007a0606042afbfdc50173a5b13ae9336d2e9e9b08",
     "battlegrid-trade-analysis/SKILL.md": "3f927b4f9796178526fa1673a2043c5f14358c39aa955de33192ea58641f18fb",

package/skills/battlegrid-strategy-examples/SKILL.md

@@ -228,9 +228,12 @@ column selecting Developing above the strategy timeframe (`CONDITION_VERDICT_REA
 closure is what the condition reads directly plus everything reached through `conditionRef`,
 transitively: a referenced condition contributes what IT reads, so moving the clause into a building
 block does not launder it. A closure whose candle columns all read Confirmed — or whose operands no
-bar moves at all, such as a published regime label, an open-interest regime or a published rolling
-change — admits a verdict at every decision, because a decision reads the completed strategy bar and
-a level is compared against that bar's close.
+bar moves at all, such as a published regime label or a funding rate — admits a verdict at every
+decision, because a decision reads the completed strategy bar and a level is compared against that
+bar's close. A change over a horizon above the strategy timeframe — `chg4h` or `chg24h` on a `1h`
+strategy, and `oiRegime`, which reads the `1h` change, below `1h` — is a developing read whatever its
+selector: its bar is still in progress at the close, so it carries no verdict. Read a horizon at or
+below the strategy timeframe instead, or a Confirmed `CLOSE_CHANGE` on the higher timeframe.
 
 Evaluation is three-valued: UNRESOLVED never collapses to FALSE; a developing read is provisional,
 and so is any reading taken on the display lane's forming bar.
@@ -266,10 +269,11 @@ the served domain is refused (`CONDITION_HOLD_ILLEGAL`, the domain in `allowedDo
 a header admits only Once:
 
 - `NOT_REWINDABLE` — the value is stored for the current bar only (session and universe scalars,
-  ranks, zone entities, enrichment metrics, published rolling changes). **Worked liquidity floor:**
+  ranks, zone entities, enrichment metrics, a change at or below the strategy timeframe). **Worked liquidity floor:**
   `LIQUID_FLOOR` holds Once because `vol24hUsd` is a bundle scalar.
-- `DEVELOPING` — the column reads the bar still forming. **Developing columns cannot be held**; set
-  the column Confirmed to count closes.
+- `DEVELOPING` — the column reads a bar still forming: a Developing candle column above the strategy
+  timeframe, or a change over a horizon above it. **Developing columns cannot be held**; set a candle
+  column Confirmed to count closes, or read a change at or below the strategy timeframe.
 - `OFFSET` — the column already reads an earlier bar; remove the offset to count closes.
 - `BAR_STATE` — the header describes only the bar being decided.
 - `HISTORY` — not enough history is stored on that timeframe to count more than one close.
@@ -300,8 +304,10 @@ anchor's own close — so Developing there is legal and changes no decision. A c
 developing bar is single-frame: its clause holds Once (a Developing column cannot be held), it
 carries no verdict and it cannot be an exit rule. One exception overrides both the stored value and the default: a column reading a metric with
 no live value (itself, or a `spread` operand) reads completed bars at every rung, because the forming
-bar publishes nothing for it. The resolved answer for a column is served on
-`effectiveParameters.bars`, and it states that exception.
+bar publishes nothing for it. A change (`chg5m` … `chg24h`, and `oiRegime`'s `1h` change) carries its
+horizon in the metric, so above the strategy timeframe it is Developing at every rung and under every
+selector. The resolved answer for a column is served on `effectiveParameters.bars`, and it states both
+exceptions.
 
 **A higher-timeframe level is measured from the current strategy-bar price.** The distance to a `4h`
 Donchian band, and every candle label classifier (`MA_ALIGN`, `PRICE_ZONE`, `BB_TOUCH`), compares

package/skills/battlegrid-strategy-examples/references/playbooks.md

@@ -36,11 +36,14 @@ anything failing {LIQUID_FLOOR}."
 Custom `Positioning`: `FUNDING_RATE value`→`rate`, `aggregate w24`→`rate_mean24`,
 `FUNDING_ANN value`→`ann`, `OI_CHG value`→`oiChg`, `OI_PX_REGIME value`→`oiRegime` (vocab:
 new longs / new shorts / short covering / long liquidation), `MARK spread ORACLE`→
-`mark_oracle_spread`, `RSI14 value`, `CHG_24H value`→`chg24h`; plus `includeCvd`. Conditions:
+`mark_oracle_spread`, `RSI14 value`, `CLOSE_CHANGE value @ {abs: 1d}`→`closeChg_1d` (Confirmed, the
+default above the strategy timeframe); plus `includeCvd`. Conditions:
 `NO_LIQUIDATION_TAPE` required NOT-veto (`NOT [oiRegime is "long liquidation"]`);
 `CROWDED_LONGS` building block (`ann gte 25` + `oiChg gte 3` + `oiRegime is "new longs"`);
-`FADE_SHORT` verdict DOWN (ref + `RSI14 gte 65` + `chg24h gte 5`); mirrored `SQUEEZED_SHORTS`
-/ `SQUEEZE_LONG` verdict UP. Levels 1.0–2.5 ATR, RR 1.5, ATR floor 0.5%. PM: BE 0.8R, no trail, timeDecay ON (120/60, 10→40, stale 25).
+`FADE_SHORT` verdict DOWN (ref + `RSI14 gte 65` + `closeChg_1d gte 5`); mirrored `SQUEEZED_SHORTS`
+/ `SQUEEZE_LONG` verdict UP (`closeChg_1d lte -5`). The confirmation is the prior completed UTC day's
+move, not today's: today's (`chg24h`) is a 1d bar still in progress at every 1h close, a developing
+read no verdict may carry. Levels 1.0–2.5 ATR, RR 1.5, ATR floor 0.5%. PM: BE 0.8R, no trail, timeDecay ON (120/60, 10→40, stale 25).
 
 ### 3 · Relative-Strength Rotation with a Benchmark Gate — 4h cross-sectional