@battlegrid/mcp-server 31.2.24 → 31.2.26

package/README.md

@@ -24,6 +24,104 @@ 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 — v60
+
+One release train, four numbers, and two parts to read first: **`propose_entry_decision` no longer
+decides in the call**, and **a closed trade's `tradeStatus` now follows its net P&L**. v55 through v59 are not written up here; the canonical record for
+every contract move is `docs/architecture/MCP_CONTRACT_HISTORY.md` in `battlegrid-app`, and the
+served version is what the handshake announces.
+
+### Rejected input — something you author is no longer accepted
+
+- **The entry axis names no bar but the strategy's own, and three of its keys are gone** (60.0.0,
+  `decide-entry-on-strategy-close`). The authoring schemas are `.strict()`, so `compile_strategy_plan`,
+  `apply_strategy_plan`, `fork_strategy` and `restore_strategy` REFUSE a body carrying
+  `entry.confirmTf` (the deciding bar is the strategy's own timeframe, so a required input whose only
+  legal value was another field of the same strategy is absent rather than mirrored), `entry.closes`
+  and `entry.bandAtrMultiple` (a multi-bar hold is declared on the condition that needs it; the
+  displacement band is replaced by the platform's own entry-deviation gate, measured against the
+  decided close), and the whole `exit` object (the open-position exit lane judges one closed candle
+  of the position's strategy timeframe). Exactly one input hash moves, `compile_strategy_plan`'s.
+
+- **`entry.trigger: AT_SIGNAL` is retired for authoring** (60.0.0, `retire-at-signal-trigger`, riding
+  the same number). Refused on every authoring surface and on a RESTORE, which rebuilds a stored
+  revision through the same value object. The enum member stays READABLE on every strategy read and
+  on a fired decision's provenance, so a pre-retirement revision is still legible — it just cannot be
+  re-authored. The three that remain are `ON_CANDLE_CLOSE`, `STOP_THROUGH_LEVEL` and `ON_RETEST`.
+
+### Changed meaning, unchanged shape
+
+- **`tradeStatus` follows NET P&L on every closed trade** (60.3.0, `label-trade-outcome-by-pnl`).
+  No schema hash moves for this and the values you receive change anyway. It used to map the close
+  REASON onto a verdict — every `TAKE_PROFIT` was `WON`, every `STOP_LOSS` was `LOST`, and a
+  `MARKET_CLOSE` of either sign was the neutral `CLOSED` — so a stop that filled after a break-even
+  reprice was reported as a loss and a take-profit eaten by fees as a win. `LIQUIDATED` still
+  outranks the number, because a force-close is not a verdict about the trade; `CLOSED` now means
+  only that there is no outcome row to judge. A client that counted `WON` rows was counting
+  take-profits.
+
+- **A proposal is QUEUED, not decided** (60.2.0, `queue-manual-entry-for-close`). This is the entry in
+  this section to act on. `propose_entry_decision` registers a request against the agent's next
+  strategy-bar close and returns immediately: no model runs, nothing is spent, and the call carries
+  `type: "queued"` with `request` — `requestId`, the bar (`barStart`), when the answer is due
+  (`decidesBy`) and the last instant that bar may still be decided (`windowEndsAt`). The answer
+  arrives later, in the agent's conversation and, when it proposes a trade, in
+  `list_pending_approvals`. A close that does not qualify, a window that passes with no sweep, and a
+  bar the agent's own radar deployment decided first are each recorded in the conversation instead.
+
+  `recommendation` and `no_trade` REMAIN in the union: the idempotency registrar replays results
+  recorded before this release for their TTL, so a client that dropped those members would fail on
+  its own retry. **A client written against 60.2 handles `queued` and `error`**; one that must also
+  replay handles all four.
+
+### Reshaped output — the same call returns a different shape
+
+- **The four retired entry keys leave every strategy read** (60.0.0) — `get_strategy`,
+  `list_strategies`, `fork_strategy` and both plan envelopes — and `confirmTimeframesByMainCandle`
+  leaves `list_strategy_vocabulary`, because there is no confirm set left to publish.
+
+- **`entryDiscipline.closes` and `.bandAtrMultiple` go `number` → `number | null`** (60.0.0) on
+  `get_trade_outcome_by_decision` and `list_trade_outcomes`. Null on every decision fired after this
+  release, which authors neither; a non-null pair dates the row to the arming era.
+
+### Widened enum — new members your own copy rejects
+
+- **`TradeConvErrorCode` gains `REQUEST_PENDING`** (60.2.0), on the SURFACE arm of
+  `propose_entry_decision`'s error: one pending request per user and coin, so a second is refused. A
+  coin already carrying a pending or live position is refused before anything is queued, as an
+  ENGINE-origin `OPEN_POSITION_CONFLICT` — a member that was already published, reaching this surface
+  for the first time.
+
+### Additive in the same span
+
+- **The exit names the leg that filled** (60.3.0, `label-trade-outcome-by-pnl`). `TradeOutcomeDTO`
+  and the pipeline outcome summary gain `exitRepriceSource`: the reprice that placed the protection
+  leg which actually closed the position — `BREAK_EVEN`, `TRAILING`, `TIME_DECAY`,
+  `MANUAL_OVERRIDE`, `UPDATED` — or null on every close no protection leg filled and on a leg that
+  was never repriced. It is the mechanism behind the verdict above, so read it beside `closeReason`
+  before calling a stopped-out trade a failure. The enum is the one `get_position_audit_history`
+  already publishes. Four output hashes move; no input schema does.
+
+- **Two tools join the catalog for the request lifecycle** (60.2.0, `queue-manual-entry-for-close`).
+  `get_entry_request` (read scope) reads a request that is still pending and is `NOT_FOUND` once it
+  has been answered, cancelled or expired — the answer is in the conversation, not there.
+  `cancel_entry_request` (`mcp:wager`) withdraws one before its bar is decided. `toolCount` 115 → 117.
+
+- **Three radar reads publish the close decision** (60.1.0, `add-radar-close-decision-state`).
+  `get_radar_deployment`, `list_radar_deployments` and `preview_radar_resolution` carry one further
+  key on `resolvesNow`: `closeDecision`, non-null whenever an agent is on duty for the pair. It
+  carries the deciding `timeframe`, the `nextCloseAt` instant, a `state` of `WAITING` or `DEFERRED`
+  (a bar has closed and no sweep has decided it yet), and `last` — the bar, the instant, the outcome
+  (`FIRED` / `NOT_QUALIFIED` / `MISSED`), the gate and the closed reading's score against its
+  minimum — or null before the pair's first close decision.
+
+  **Read it first on a close-deciding pair.** The sibling `qualified` and `qualificationBlock` fields
+  are the per-minute DISPLAY reading there and decide nothing, so an agent ranking them reports
+  "qualified — watching for a setup" about a pair whose last three closes were each refused. Neither
+  field is removed or reshaped. A `NOT_QUALIFIED` outcome with a NULL gate beside a score at or above
+  the minimum is the consumed edge — the close qualified and the baseline was already spent — stated
+  by the server so no client compares the two numbers.
+
 ## Contract history — v37 → v54
 
 Eleven majors reached authors while this section stopped at v36. That gap is the mechanism, not an

package/dist/index.d.ts

@@ -49,7 +49,7 @@ import { type Implementation, type Prompt, type Resource } from '@modelcontextpr
  * 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 = "31.2.24";
+export declare const PACKAGE_VERSION = "31.2.26";
 export declare const DEFAULT_URL = "https://mcp.battlegrid.trade/mcp";
 export interface EnvConfig {
     apiKeys: string[];

package/dist/index.js

@@ -52,7 +52,7 @@ import { ListToolsRequestSchema, CallToolRequestSchema, ListPromptsRequestSchema
  * 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 = '31.2.24';
+export const PACKAGE_VERSION = '31.2.26';
 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": "31.2.24",
+  "version": "31.2.26",
   "description": "BattleGrid MCP server — play crypto prediction games from AI agents",
   "type": "module",
   "main": "dist/index.js",

package/skills/EXPORT.json

@@ -1,18 +1,18 @@
 {
   "generator": "battlegrid-app/server/scripts/export-mcp-skills.mjs",
-  "contractVersion": "59.0.0",
+  "contractVersion": "60.3.0",
   "files": {
     "battlegrid-agent-management/SKILL.md": "b6ea75b3d838c1dbaaf3984d7e99a11c81686de2c1a1910c35699ee7e70dafa5",
     "battlegrid-arena-play/SKILL.md": "03fa153bf82be18bf5ed01e3ba12e2cd9f99a81b08d903a77b52169e7519a182",
     "battlegrid-market-analysis/SKILL.md": "22fde9c4eac0261c89a8056ab8b20b66fcbe1fd58447fa0ac84fd410b4d134d7",
     "battlegrid-radar-deployment/SKILL.md": "d2a012b154e1e529db19529bd7c3d75d069f4e410d5804add51165f0f0902b2e",
-    "battlegrid-strategy-authoring/SKILL.md": "1f1bf1ecfbf1a20d585a53e8f1ba8e9fbdeaa329cad9ebdc16ce6cac2b213358",
+    "battlegrid-strategy-authoring/SKILL.md": "ea2593ea9d6d2feb9910e285e4b132eb36001164b9d6551cc206531afad3f552",
     "battlegrid-strategy-doctor/SKILL.md": "9ab3f79128ec81d3e90167c3f1ea4bd6f6b570290e5ebe2bf855195263c58239",
-    "battlegrid-strategy-examples/SKILL.md": "6f15da8b29a8aff15f6829d7ae87cbe74904bfe5372e37fe17d578cc0c289577",
+    "battlegrid-strategy-examples/SKILL.md": "263c3b865ea85e56ac420611a7070360d65be6f2faee071329880e49a6101eda",
     "battlegrid-strategy-examples/references/playbooks.md": "35c543c090d00ba19e4bcf0a80502afac7a4954643fc535de0b24381c91ecbf4",
     "battlegrid-strategy-examples/references/recipes.md": "53887daece17995543e7d3fe1bf2577fc41a6254c291acacde48d7de63853641",
     "battlegrid-strategy-examples/references/tradingview-ports.md": "2b13adbc137178955edcca31b6ab40c01c745a932a0750b91db8820c736700bb",
     "battlegrid-trade-analysis/SKILL.md": "32573a67e55d735e6ee4e36b3b48c815694102704bc453c4d1c13db39551b3da",
-    "battlegrid-trade-proposal/SKILL.md": "311af5a91576b095dcfcb3e3fc8b41e8a75d7af505222f975fde9733c633cb7e"
+    "battlegrid-trade-proposal/SKILL.md": "503ed705d4f9823e21846afe5a10f35d7d6e35933c4bdd1d5b4fd923eb9d674d"
   }
 }

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

@@ -100,11 +100,13 @@ question you would otherwise guess — and a refusal you would otherwise earn:
   yourself on a CREATE is refused with a hint telling you to omit `sectionKey` on CREATE; on an
   UPDATE, send back the key the compile returned. This is the one composition field whose right
   answer is "leave it out".
-- **The `entry` axis is required on every CREATE**, all six keys, no defaults — `trigger`,
-  `confirmTf`, `closes`, `bandAtrMultiple`, `levelOffsetAtrMultiple`, `validForBars`. It decides
-  when an entry is taken; for the level triggers the level itself is derived from the trigger and
-  the trade's direction, never named. The `strategy-examples` skill carries the vocabulary and the
-  one-directional legality matrix; a CREATE without it is refused outright.
+- **The `entry` axis is required on every CREATE**, all three keys, no defaults — `trigger`,
+  `levelOffsetAtrMultiple`, `validForBars`. Every trigger is decided at the close of the strategy's
+  OWN bar, so there is no confirm-timeframe key; for the level triggers the level itself is derived
+  from the trigger and the trade's direction, never named. A multi-bar hold belongs to the condition
+  that needs it (`clock: CLOSE` with its own `closes`), not to this axis. The `strategy-examples`
+  skill carries the vocabulary and the one-directional legality matrix; a CREATE without it is
+  refused outright.
 - `get_strategy_column_contract` → `outputs[].conditionOperators`. An empty array means that
   rendered header has no comparison semantics and cannot appear in a condition clause at all.
   Legality is per rendered header, not per column: a trajectory's slot header and its `_trend`

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

@@ -156,36 +156,34 @@ anchor, or the author gates on something that admits most bars.
 
 ## Entry
 
-`{ trigger, confirmTf, closes, bandAtrMultiple, levelOffsetAtrMultiple, validForBars }` — all six
-required on every CREATE, no defaults. This axis is replaced WHOLE on save, so an omitted key would
-silently revert an author's discipline rather than be refused. There is no level-source key: the
-level a level trigger rests at is DERIVED from the trigger and the trade's direction, never named.
-
-**The trigger decides WHEN, and for two of them WHERE, an entry is taken.**
-
-- `AT_SIGNAL` — fire the moment the radar observes the qualification flip, at whatever bar is on
-  the tape, keeping the platform's flat wall-clock entry window. Today's behaviour.
-- `ON_CANDLE_CLOSE` — the flip ARMS the pair; the entry is taken only after a close on
-  `confirmTf` that still reads the conditions true and has not displaced beyond the band.
-- `STOP_THROUGH_LEVEL` — a TRIGGER order rests past the Donchian channel's CURRENT edge in the
-  trade's direction (the 20-bar high for a long, the 20-bar low for a short) by the offset, and
-  the exchange book is the watcher; the entry is taken when price trades through, not when the
-  platform notices.
-- `ON_RETEST` — a LIMIT order rests in front of the edge a close most recently BROKE (the
-  channel's break memory: the broken high for a long, the broken low for a short) by the offset,
-  waiting for a return to it. Not filling is a correct outcome, not a failure; no unrecovered
-  break in memory means no setup, never a fallback level.
-
-`confirmTf` is the bar whose close confirms. Exactly two values are legal: the strategy's own
-timeframe and the rung below it — one only, when the strategy sits on the ladder floor. It is
-NOT the authorable main-candle set; a rung further down names a bar nothing else in the strategy
-observes and makes the radar sweep on every one of its closes.
-
-`closes` (1–5) is how many consecutive confirming closes are required, and `bandAtrMultiple` is
-the veto width: the entry is VOIDED when the confirming close has moved at or beyond that many
-ATR against the armed verdict. Strictly greater than zero — zero is not "no filter" but a filter
-that voids on any adverse move — and at or below the platform's own entry-deviation gate, since
-a wider band cannot refuse anything the platform will not refuse anyway.
+`{ trigger, levelOffsetAtrMultiple, validForBars }` — all three required on every CREATE, no
+defaults. This axis is replaced WHOLE on save, so an omitted key would silently revert an author's
+discipline rather than be refused. There is no level-source key: the level a level trigger rests at
+is DERIVED from the trigger and the trade's direction, never named. There is no confirm-timeframe
+key either: the bar whose close decides an entry is the strategy's OWN timeframe.
+
+**Every trigger is decided at the close of the strategy's own bar — there are three, and the close
+is the only entry clock.** The newest settled bar is read on the closed basis — every `LIVE`-clocked
+condition resolves on that bar and the scorecard reads its close — and a reading that still qualifies
+fires at that close. A bar that does not qualify decides nothing and is not revisited. The fill lands
+at the next tick, and the platform refuses it if the market has already run past its own drift budget
+from that close. A fourth value, `AT_SIGNAL`, is readable on strategies authored before this contract
+and is REFUSED on every save; there is no live-reading entry to author.
+
+- `ON_CANDLE_CLOSE` — the entry is taken AT the qualifying close, at market.
+- `STOP_THROUGH_LEVEL` — at the qualifying close a TRIGGER order rests past the Donchian channel's
+  CURRENT edge in the trade's direction (the 20-bar high for a long, the 20-bar low for a short) by
+  the offset, and the exchange book is the watcher; the entry is taken when price trades through,
+  not when the platform notices.
+- `ON_RETEST` — at the qualifying close a LIMIT order rests in front of the edge a close most
+  recently BROKE (the channel's break memory: the broken high for a long, the broken low for a
+  short) by the offset, waiting for a return to it. Not filling is a correct outcome, not a
+  failure; no unrecovered break in memory means no setup, never a fallback level.
+
+**A multi-bar hold belongs to the CONDITION that needs it.** Declare `clock: CLOSE` with that
+condition's own `closes` — the entry axis counts no bars, and there is no displacement band: the
+platform's entry-deviation gate measures the live mark against the decided close and refuses a fill
+that drifted past the budget in either direction.
 
 `levelOffsetAtrMultiple` (0–2) is an UNSIGNED distance from the derived edge in ATR multiples — a
 long adds it, a short subtracts it, so a breakout stop rests past its edge and a pullback limit
@@ -196,11 +194,10 @@ correct side of the mark when the order is placed — a buy stop above it, a buy
 mirror for a sell — or the entry is refused rather than filled at the market; there is no limit on
 how far from the mark a level may rest.
 
-**The legality matrix runs one way.** All six keys are always present, so the question is never
-"is it set" but "is it set to something that MEANS anything under this trigger". `closes` ≠ 1 is
-refused under any trigger but `ON_CANDLE_CLOSE`; `levelOffsetAtrMultiple` ≠ 0 and `validForBars`
-≠ 4 are refused under a non-level trigger. Leave a dial at its inert value rather than setting one
-the platform will ignore.
+**The legality matrix runs one way.** All three keys are always present, so the question is never
+"is it set" but "is it set to something that MEANS anything under this trigger".
+`levelOffsetAtrMultiple` ≠ 0 and `validForBars` ≠ 4 are refused under a non-level trigger. Leave a
+dial at its inert value rather than setting one the platform will ignore.
 
 ## Report sections
 

package/skills/battlegrid-trade-proposal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: battlegrid-trade-proposal
-description: Find and stage a trade for one of the player's agents, for the player to approve. Activate whenever the player asks which coins fit an agent right now, wants a trade found or proposed for an agent, asks the agent to evaluate a coin, or wants to approve or decline a proposal it made. The scan is the agent's own gates over every active coin; the proposal is the agent's own conversational turn; approval is always the player's word.
+description: Find and stage a trade for one of the player's agents, for the player to approve. Activate whenever the player asks which coins fit an agent right now, wants a trade found or proposed for an agent, asks the agent to evaluate a coin, or wants to approve or decline a proposal it made. The scan is the agent's own gates over every active coin; a proposal is QUEUED for the agent's next strategy-bar close and answered into the conversation when that bar is decided; approval is always the player's word.
 ---
 
 # Trade Proposal
@@ -29,33 +29,47 @@ re-sorts a list, re-derives a verdict, or approves on the player's behalf.
 - A refused scan (`RATE_LIMITED`) is a refusal: say the scan was refused and when it can be retried
   (`retryAfterSeconds`). Never say "nothing fits".
 
-## 2. Propose
+## 2. Queue the request
 
 - `propose_entry_decision` **only** on the coins the player named, or on the top qualifying row
   when they asked for the best fit. One coin per call.
+- **The call does not decide.** It registers a request against the agent's next strategy-bar close
+  and returns immediately; no model runs and nothing is spent. The agent reads that bar on its
+  settled close, through the same path its radar deployments use.
 - `userMessage` is the player's own words for the turn. Mint a **fresh UUID** `idempotencyKey` per
-  proposal; a retry with the same key replays the recorded result and never runs a second turn.
-- The call is synchronous and may take the turn's full LLM latency. Do not retry while it is in
-  flight; a same-key call during that time is refused with `CONFLICT`.
-
-## 3. Report the outcome in the player's terms
-
-- `type: "recommendation"` — the PROPOSED decision, awaiting approval. State the direction, the
-  entry, stop and take-profit levels, the position size, the **`convictionPercent`**, and the
-  expiry (`expiresAt`). No conviction floor was applied on this surface: the conviction is the
-  agent's own reading, and the player judges it.
-- `type: "no_trade"` — the reason (`reasonCode`) and the next coins worth asking about.
-- `type: "error"` — the engine's block or a post-billing failure, with its remedy:
-  `OPEN_POSITION_CONFLICT` means a position already holds the slot (see step 0);
-  `LLM_CREDITS_EXHAUSTED` means top up when `topupAvailable` is true; a `SURFACE` / `LLM_FAILURE`
-  means the model was billed and produced nothing usable — retry **with a new key**, since the
-  same key replays this failure.
-- A refused proposal (`RATE_LIMITED`) is a refusal with its retry-after. Never "nothing to do".
-
-## 4. Approve or decline — only on the player's word
-
-- Present the decision and **ask**. `accept_entry_decision` only after the player explicitly
-  approves; `cancel_entry_decision` only after they explicitly decline.
+  request; a retry with the same key replays the recorded result and never registers a second one.
+- **One pending request per coin.** A second is refused with `CONFLICT` / `REQUEST_PENDING` — read
+  the one that exists with `get_entry_request` rather than asking again.
+
+## 3. Tell the player what they are waiting for
+
+- `type: "queued"` is the normal answer. Read `request` back to them: the bar being decided
+  (`barStart`), when the answer is due (`decidesBy`), and the deadline past which that bar can no
+  longer be decided (`windowEndsAt`). `decidesBy` and `windowEndsAt` are different instants — a bar
+  that has already settled is decided at the next sweep, seconds away.
+- Say where the answer will appear: in the agent's conversation, and — if it proposes a trade — in
+  `list_pending_approvals`. Nothing further is needed from the player until then.
+- `get_entry_request` re-reads a request still pending; `cancel_entry_request` withdraws it. Both
+  are `NOT_FOUND` once it has been answered, cancelled or expired, and that is the honest record:
+  the answer is in the conversation.
+- `type: "error"` — the block, with its remedy: `OPEN_POSITION_CONFLICT` means a position already
+  holds the slot (see step 0) and nothing was queued; `LLM_CREDITS_EXHAUSTED` means top up when
+  `topupAvailable` is true. A refused request (`RATE_LIMITED`) is a refusal with its retry-after.
+  Never "nothing to do".
+- `type: "recommendation"` and `type: "no_trade"` arrive only as the **replay** of a request made
+  before the queued contract shipped. Report them as step 4 describes and do not expect them from a
+  fresh call.
+
+## 4. When the answer arrives — approve or decline only on the player's word
+
+- A decided close produces one of: a PROPOSED decision awaiting approval; a no-trade with the
+  reason and the next coins worth asking about; a close that did not qualify; a window that passed
+  with no sweep; or a bar the agent's own radar deployment decided first and traded in full.
+- On a proposal, state the direction, the entry, stop and take-profit levels, the position size,
+  the **`convictionPercent`**, and the expiry (`expiresAt`). No conviction floor is applied on this
+  surface: the conviction is the agent's own reading, and the player judges it.
+- Present it and **ask**. `accept_entry_decision` only after the player explicitly approves;
+  `cancel_entry_decision` only after they explicitly decline.
 - Never accept because the conviction reads high, because the scan ranked the coin first, or
   because the player asked you to "find a trade" — finding is not approving. `get_entry_decision`
   re-reads the row if the conversation moved on before they answered.