@battlegrid/mcp-server 31.2.42 → 31.2.45

package/README.md

@@ -24,6 +24,71 @@ 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 — v66
+
+**Breaking: one tool retired and one input reshaped.** Radar content now commits only as a draft the
+player was shown a live preview of. The player's radar builder and every conversation share one
+unsaved draft per coin.
+
+### Removed tool — something you call no longer exists
+
+- **`upsert_radar_deployment` is retired**, with no alias. Calling it is an unknown-tool error. To
+  deploy or change a coin's Radar policy:
+  1. `stage_radar_deployment_draft` the axes you are changing;
+  2. `preview_radar_resolution` with `request: { kind: "DRAFT", draftVersion }` at the version staging
+     returned;
+  3. show the player the resolution, and on their word call `commit_radar_deployment_draft` with the
+     `previewToken` that preview returned and `confirm: true`.
+
+  Pausing is no longer a flag on the write: use `pause_radar_deployment`.
+
+### Rejected input — something you send is no longer accepted
+
+- **`preview_radar_resolution`'s `request` needs a `kind`.** `{ kind: "SLOTS", deploymentTimeframe,
+  slots, simulatedRegime? }` is the old request. `{ kind: "DRAFT", draftVersion }` previews the
+  player's draft of the coin at that version, composed over the deployed policy exactly as the commit
+  writes it. `{ kind: "COMMITTED" }` previews the deployed policy a resume would arm. A request
+  without `kind` is refused.
+
+### Wider surface — seven tools added
+
+- **`stage_radar_deployment_draft`**, **`get_radar_deployment_draft`**,
+  **`list_radar_deployment_drafts`** and **`discard_radar_deployment_draft`** (`mcp:read`). The draft
+  axes are `DEPLOYMENT_TIMEFRAME`, `RULES` (the complete ordered rule list, first = highest priority)
+  and `DEFAULT_SLOT`, each written whole. None of them commits or arms anything.
+- **`commit_radar_deployment_draft`** (`coinId`, `previewToken`, `confirm: true`; `mcp:wager`) — the
+  only MCP committer of radar content.
+- **`pause_radar_deployment`** (`coinId`; `mcp:wager`) — no revision and no certificate: a disarm never
+  waits on a read.
+- **`resume_radar_deployment`** (`coinId`, `previewToken`, `confirm: true`; `mcp:wager`) — needs the
+  certificate a live `COMMITTED` preview returned.
+
+### Reshaped output — `preview_radar_resolution`
+
+- Gains **`previewToken`**, the certificate a LIVE preview (no `simulatedRegime`) of `DRAFT` or
+  `COMMITTED` earns — null otherwise, and good for five minutes. It also gains
+  **`enabledAfterCommit`**: whether the policy trades once the previewed write lands. A paused
+  policy's draft stays paused.
+
+### Refusals worth knowing before you commit or resume
+
+- **The certificate is bound to what you previewed**: your credential, the player, the coin, the
+  subject, the deployment and its revision, the draft version and the composed content. If the
+  player edits the draft, another commit lands, the coin is redeployed, or an agent in it is deleted,
+  the commit or resume is a `CONFLICT` and nothing is written. Preview again; never reuse the old
+  certificate.
+- **`commit_radar_deployment_draft` takes only a draft certificate**, and `resume_radar_deployment`
+  only a committed-policy one.
+- **`discard_radar_deployment_draft` with `confirm: true` requires `expectedVersion`**: the version the
+  unconfirmed call named and the player was shown. A draft that moved since is answered again, and
+  nothing is removed.
+- **`delete_radar_deployment` also ends the player's radar draft of the coin.**
+
+### Vocabulary
+
+`toolCount` goes 126 → 132. `preview_radar_resolution`'s input and output schemas move, and
+`upsert_radar_deployment`'s are removed.
+
 ## Contract history — v65
 
 **Breaking on one input, and four refusals behind unchanged schemas.** Agent staging now names the

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.42";
+export declare const PACKAGE_VERSION = "31.2.45";
 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.42';
+export const PACKAGE_VERSION = '31.2.45';
 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.42",
+  "version": "31.2.45",
   "description": "BattleGrid MCP server — play crypto prediction games from AI agents",
   "type": "module",
   "main": "dist/index.js",

package/skills/EXPORT.json

@@ -1,12 +1,12 @@
 {
   "generator": "battlegrid-app/server/scripts/export-mcp-skills.mjs",
-  "contractVersion": "64.1.0",
+  "contractVersion": "66.1.0",
   "files": {
-    "battlegrid-agent-management/SKILL.md": "f43f3ac852e032c320d43f599d3e683203c68daf42637a9dbf292b380f17c635",
+    "battlegrid-agent-management/SKILL.md": "fbc602e9445d0f72353bfba23c30a364b478bd04a9cc6248418cfeec66717eb1",
     "battlegrid-arena-play/SKILL.md": "4cfaa92a8d0dcaf477b227abd774e7aa8642c185d72108dfd401be0cf8aecd7f",
     "battlegrid-market-analysis/SKILL.md": "22fde9c4eac0261c89a8056ab8b20b66fcbe1fd58447fa0ac84fd410b4d134d7",
-    "battlegrid-radar-deployment/SKILL.md": "d2a012b154e1e529db19529bd7c3d75d069f4e410d5804add51165f0f0902b2e",
-    "battlegrid-strategy-authoring/SKILL.md": "2ad66540d406fdf447118396821aa2aeb3510045a79d397846b83c7c797f33a1",
+    "battlegrid-radar-deployment/SKILL.md": "40cff6a1f5beac8a9f7d6e7a0805af6209613691170eddc19f9a7bc301cdeded",
+    "battlegrid-strategy-authoring/SKILL.md": "95e91dd1ff36922b7ed0f5eb92c98def98fa39cce37c3d7447269aea1b5a017f",
     "battlegrid-strategy-doctor/SKILL.md": "d0b9e9e07648246d5a23b0c17183278b70b5bcbb5f472ac7da13d03e42a6c6c6",
     "battlegrid-strategy-examples/SKILL.md": "17e8cf8040813622bd5b82165c7af82e03287fee1f6aac974e0b6c584580dd27",
     "battlegrid-strategy-examples/references/playbooks.md": "35c543c090d00ba19e4bcf0a80502afac7a4954643fc535de0b24381c91ecbf4",

package/skills/battlegrid-agent-management/SKILL.md

@@ -79,7 +79,8 @@ budget posture** — the capital ceiling and stops the trading configuration wil
 will take platform defaults.
 
 **Build it in a create draft.** As the picks come back, stage them with `stage_agent_draft` —
-omit `agentId` on the first call and reuse the id it returns — each axis WHOLE: IDENTITY
+omit `agentId` and send `draftVersion: 0` on the first call, then reuse the id and the `version` it
+returns — each axis WHOLE: IDENTITY
 `{ displayName }`, BEHAVIOR `{ behavior: { risk, outlook, conviction } }`, MODEL `{ modelId }`,
 TRADING_CONFIG with every agent-owned field, and STRATEGY_BINDING `{ strategyId }`. The build then
 survives a refresh, lists in the Agents Hub as *not yet created*, and opens on the create screen,
@@ -104,12 +105,15 @@ and not readiness — the pipeline's own refusal at the fee is the authority.
 Before proposing any change to an existing agent, `get_agent_draft`. **A draft means the player is
 mid-edit in their form.** Then:
 
-- **Stage** the change with `stage_agent_draft`: it lands in their open form, labelled as yours, and
-  **their Save commits it** together with their own edits. `update_intelligence_agent` and
-  `rebind_intelligence_agent` are REFUSED while the draft exists — that refusal is the server's, so
-  do not retry them.
-- A staging call **refused naming an axis** means the player changed it after you read the draft:
-  read again and propose against what they now have — never re-send the same values.
+- **Stage** the change with `stage_agent_draft`, naming as `draftVersion` the `version` the read you
+  proposed against returned (0 when `get_agent_draft` returned null): it lands in their open form,
+  labelled as yours, and **their Save commits it** together with their own edits.
+  `update_intelligence_agent` and `rebind_intelligence_agent` are REFUSED while the draft exists —
+  that refusal is the server's, so do not retry them.
+- A staging call **refused naming an axis** means the player changed it after the version you name:
+  read again and propose against what they now have — never re-send the same values. A call refused
+  because that version is one the draft never reached means the draft you read is gone: read again.
+  Never raise the number to get past either refusal.
 - **Rebinding is never staged.** While a draft is open, ask the player to save or discard it first.
 - `discard_agent_draft` only on the player's word: call it with `confirm:false` first, tell them
   when the draft was last written and from which surface, ask, then confirm.

package/skills/battlegrid-radar-deployment/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: battlegrid-radar-deployment
-description: Deploy the player's agents to standing duty — per-coin Radar policies that fire real trades on confirmed regime flips, and per-preset Arena deployment policies that enter sessions automatically. Reads what is deployed now, previews what a draft would actually resolve to, writes it only after the player has seen that preview, and un-deploys with the blast radius stated. Activate whenever the player wants an agent put on duty, wants to change or pause a deployment, asks what would fire right now or why nothing is firing, or wants to stop a coin or a preset being traded automatically.
+description: Deploy the player's agents to standing duty — per-coin Radar policies that fire real trades on confirmed regime flips, and per-preset Arena deployment policies that enter sessions automatically. Reads what is deployed now, stages a Radar change into the player's draft, previews what it would actually resolve to, commits it only after the player has seen that preview, and un-deploys with the blast radius stated. Activate whenever the player wants an agent put on duty, wants to change or pause a deployment, asks what would fire right now or why nothing is firing, or wants to stop a coin or a preset being traded automatically.
 ---
 
 # Radar & Deployment
@@ -16,17 +16,17 @@ and never describe them as one thing with two modes.
 
 ## The five failures this flow exists to prevent
 
-1. **A write with no fresh preview.** *Cue: any `upsert_radar_deployment` or
-   `upsert_deployment_policy`.* The preview is the only place the player sees which agent actually
-   goes on duty and why. → steps 2–3.
-2. **A blind CAS retry.** *Cue: a CONFLICT on a write.* The revision moved because the stored
-   policy changed. Bumping the number and retrying overwrites an edit you never read. → step 3.
-3. **Previewing one thing and writing another.** *Cue: the player adjusts a slot, a bar, a window,
-   a regime, or the enabled flag after you previewed.* A preview vouches only for the parameters it
-   was given. → step 2.
-4. **A replacement that silently drops slots.** *Cue: any upsert on a coin or preset that already
-   has a policy.* `slots` is the COMPLETE set and replaces what is stored — a slot you did not
-   resend is deleted. → step 3.
+1. **A write with no fresh preview.** *Cue: any `commit_radar_deployment_draft`,
+   `resume_radar_deployment` or `upsert_deployment_policy`.* The preview is the only place the
+   player sees which agent actually goes on duty and why. → steps 2–3.
+2. **A blind retry.** *Cue: a CONFLICT on a write.* Something moved under you — the stored policy,
+   or for Radar the player's draft. Retrying overwrites an edit you never read. → step 3.
+3. **Previewing one thing and writing another.** *Cue: the player adjusts a slot, a bar, a window
+   or a regime after you previewed.* A preview vouches only for what it resolved. → step 2.
+4. **A replacement that silently drops slots.** *Cue: a Radar `RULES` axis staged over a deployed
+   coin, or any Arena upsert on a preset that already has a policy.* Radar's `RULES` is the COMPLETE
+   ordered rule list and Arena's `slots` the complete slot set: a rule or slot you did not resend is
+   deleted. → step 3.
 5. **Answering "why isn't it firing?" by paging the journal.** *Cue: any question about why a
    deployed agent has been quiet — "is it working?", "it hasn't traded all day", "what's blocking
    it?".* `get_radar_activity_summary` now answers the whole question in one small call — which
@@ -51,69 +51,106 @@ Then read what exists:
 - `get_radar_deployment` (one coin) or `list_radar_deployments` (the fleet, plus the platform
   `radarPaused` kill-switch — if that is set, say so up front: nothing will fire whatever you
   write).
-- `get_deployment_policy` / `list_deployment_policies` for Arena.
-
-The read is what supplies `expectedRevision` for the write. **`null` only for a first deploy** —
-a coin or preset with no policy at all. Anything else carries the revision you just read.
+- **For Radar, also read the player's draft of the coin** with `get_radar_deployment_draft` — or
+  `list_radar_deployment_drafts` when no coin is named yet. The player may be part-way through a
+  change in their radar builder. **If a draft exists, say so** — what it holds, and when and from
+  where it was last written — and propose against it rather than starting over beside it.
+- `get_deployment_policy` / `list_deployment_policies` for Arena. The read supplies
+  `expectedRevision` for the Arena write: **`null` only for a first deploy** — a preset with no
+  policy at all.
 
 `get_regime_snapshot` / `get_regime_history` when the policy turns on regime conditions.
 
 If the question is *why did my radar agent not fire*, do not start from the journal — **go to step
 5**, which reads state first and pattern second.
 
-### 2. Preview the exact parameters under discussion
+### 2. Stage the change, then preview exactly what would be written
+
+**Radar** — the change goes into the player's draft of the coin, never straight to the policy:
+
+1. `stage_radar_deployment_draft` with `draftVersion` = the `version` you read (0 when there was
+   no draft) and only the axes you are changing, each WHOLE: `DEPLOYMENT_TIMEFRAME`, `RULES` (the
+   complete ordered rule list — first is highest priority) and `DEFAULT_SLOT` (the catch-all, or
+   null for none). Staging writes nothing live and shows the change in the player's builder as a
+   proposal. A refusal naming axes means the player changed them after your read: read again and
+   propose against what they now have.
+2. `preview_radar_resolution` with `request: { kind: "DRAFT", draftVersion }` at the version staging
+   returned. It composes the draft over the deployed policy **exactly as the commit will write it**.
 
-- **Radar** → `preview_radar_resolution` with the draft slots.
-- **Arena** → `preview_deployment_resolution` with the draft slots.
+To try a slot set without touching the draft, preview `{ kind: "SLOTS", deploymentTimeframe, slots }` —
+it certifies nothing and cannot be committed.
 
-Both run the **same resolver the live sweep runs**, so the preview is the real outcome, not an
-estimate. Neither writes anything, neither needs a revision, and neither costs the player an LLM
-call — so previewing repeatedly while iterating is free and correct.
+**Arena** → `preview_deployment_resolution` with the draft slots.
+
+Both previews run the **same resolver the live sweep runs**, so the preview is the real outcome, not
+an estimate. Neither writes anything and neither costs the player an LLM call — so previewing
+repeatedly while iterating is free and correct.
 
 Render the preview as a card and read it out: which agent goes on duty, which slot matched and at
 what priority, the regime and conviction used, the qualification verdict, and any typed idle or
 blocked reason. **Render `section` as the server sends it — never re-derive it.** A non-null reason
 does not mean idle (`ON_DUTY_BUT_POSITION_BLOCKED` carries a reason and is not idle), so deciding
-the headline yourself gets it wrong.
+the headline yourself gets it wrong. For Radar, `enabledAfterCommit` says whether the policy will
+trade once committed — a paused policy stays paused.
 
-**If any parameter changes after a preview, re-preview.** A preview never vouches for parameters
-it did not see. That includes a changed conviction bar, an added or removed slot, an edited time
-window or regime set, and flipping `enabled`.
+**If anything changes after a preview, re-preview.** A preview never vouches for what it did not
+resolve.
 
-### 3. Confirm against the preview, then write
+### 3. Confirm against the preview, then commit
 
 One confirmation whose question **references what the preview showed** — the agent it put on duty and
-the reason — and **names what the replacement changes about the stored policy**, read from step 1:
-
-- every slot the replacement **removes** (by agent and priority), because `slots` is the whole set;
-- a bar, window or regime that **changes** on a slot that survives;
-- `enabled` going false (**paused, slots kept — nothing fires**) or true (**resumed — it can fire
-  again from the next confirmed flip**).
-
-Then `upsert_radar_deployment` / `upsert_deployment_policy` with the revision from step 1.
-
-**On a typed CONFLICT: re-read, re-preview, re-confirm.** In that order, and all three. The policy
-changed under you, so the state your preview resolved and the radius you stated are both stale.
-Never retry with a bumped revision.
-
-### 4. Deletes: read, state what stops, confirm
-
-`delete_radar_deployment` / `delete_deployment_policy` remove the **entire** policy — every slot and
-condition — and revoke the standing authority. There is no preview here, and correctly so: there is
-no resolution to preview once the policy is gone. The evidence is **the deployment's own read**.
+the reason — and **names what the change does to the stored policy**, read from step 1:
+
+- every rule or slot the change **removes** (by agent and priority), because `RULES` and `slots` are
+  the whole set;
+- a bar, window or regime that **changes** on a rule or slot that survives;
+- for Arena, `enabled` going false (**paused, slots kept — nothing fires**) or true (**resumed — it can
+  fire again from the next confirmed flip**).
+
+Then:
+
+- **Radar** → `commit_radar_deployment_draft({ coinId, previewToken, confirm: true })`, with the
+  `previewToken` the **live** DRAFT preview returned — no `simulatedRegime`, within five minutes. The
+  draft ends when it commits.
+- **Arena** → `upsert_deployment_policy` with the revision from step 1.
+
+**On a typed CONFLICT: re-read, re-preview, re-confirm.** In that order, and all three. The draft or
+the policy changed under you, so the state your preview resolved and the radius you stated are both
+stale. A Radar certificate is bound to the draft version, the deployment and its content, so a
+retry with the old one is refused again — only a fresh preview earns a new one.
+
+### 4. Pause, resume, discard, delete
+
+**Pause a coin's Radar** → `pause_radar_deployment({ coinId })`. No preview and no revision: stopping
+never waits on a read. The player's draft is kept. **Resume** → preview the deployed policy with
+`request: { kind: "COMMITTED" }`, tell the player what will go on duty again, and on their word
+`resume_radar_deployment({ coinId, previewToken, confirm: true })` with the token that preview
+returned.
+
+**Discard a Radar draft** only on the player's word. Call `discard_radar_deployment_draft` with
+`confirm: false` first: the answer names what the draft holds, its version, and when and from where
+it was last written. Tell the player, ask, and call with `confirm: true` and `expectedVersion` set to
+**the version you were shown**. If the draft moved since, nothing is removed and the answer names what
+it now holds — show them again.
+
+**Deletes** — `delete_radar_deployment` / `delete_deployment_policy` remove the **entire** policy —
+every slot and condition — and revoke the standing authority. Un-deploying a Radar coin **also ends
+the player's draft of it**. There is no preview here, and correctly so: there is no resolution to
+preview once the policy is gone. The evidence is **the deployment's own read**, which supplies the
+`expectedRevision` the delete carries.
 
 State what stops, from that read: which agents were on duty or eligible, what the policy was
 firing on, and that the slots are not recoverable. Both tools carry a schema-level `confirm: true`.
 
-**If the player wants to stop trading without losing the slots, that is not a delete** — it is an
-upsert with `enabled: false`. Offer that whenever the ask sounds like "pause", "stop for now", or
-"take it off duty for a while".
+**If the player wants to stop trading without losing the slots, that is not a delete** — it is
+`pause_radar_deployment` for Radar, and an upsert with `enabled: false` for Arena. Offer that
+whenever the ask sounds like "pause", "stop for now", or "take it off duty for a while".
 
 ### 5. "Why isn't it firing?" — state, then pattern, then rows
 
 Three reads, cheapest first. Stop as soon as the player's question is answered.
 
-1. **`preview_radar_resolution` → `resolvesNow`** for what is true **right now**: the section, the
+1. **`get_radar_deployment` → `resolvesNow`** for what is true **right now**: the section, the
    blocked reason and since when, the qualification block, the cooldown, the last fire, and which
    agent is on duty. Most "is it working?" questions end here.
 2. **`get_radar_activity_summary`** for everything else about "why is it quiet", in ONE call. It
@@ -150,19 +187,26 @@ Two negatives, both checkable:
   rollup's counts span every matching row inside `windowStartAt`–`windowEndAt` — quote them with
   that window ("41 times in the last 7 days"), never as a total.
 
-## Preview-before-commit is a rule of this flow, and only that
+## Preview-before-commit: enforced for Radar, this flow's rule for Arena
+
+**Radar** arms only with a certificate. `commit_radar_deployment_draft` takes the certificate a live
+preview of that draft returned, and `resume_radar_deployment` one from a live preview of the deployed
+policy. Each is bound to your credential, the player, the coin, the subject previewed, the deployment
+and its revision, the draft version and the content the preview resolved, and expires after five
+minutes. A simulated preview returns none. So a commit of anything the player was not shown is
+refused by the server — but the player's confirmation is still yours to ask for, against the preview.
 
-There is no server-side preview receipt: the upsert takes no token proving a preview happened, and
-the CAS revision is the only cross-call state. So the sequence above is what holds the invariant —
-not a mechanism that could refuse you. Treat it as binding anyway. A write that reaches the player's
-confirm with no preview in the conversation is a failure of this skill even if the server accepts it.
+**Arena** has no server-side preview receipt: the upsert takes no token proving a preview happened,
+and the CAS revision is the only cross-call state. There the sequence above is what holds the
+invariant. Treat it as binding anyway: an Arena write that reaches the player's confirm with no
+preview in the conversation is a failure of this skill even if the server accepts it.
 
 ## When a write's outcome is unknown
 
-An interrupted or timed-out upsert or delete may have landed. **Read the deployment first**
-(`get_radar_deployment` / `get_deployment_policy`) and report what is actually stored. A committed
-change is a success to report, not a call to repeat. Never blind-retry a write whose outcome you
-did not see.
+An interrupted or timed-out commit, pause, resume, upsert or delete may have landed. **Read the
+deployment first** (`get_radar_deployment` / `get_deployment_policy`) and report what is actually
+stored. A committed change is a success to report, not a call to repeat. Never blind-retry a write
+whose outcome you did not see.
 
 ## `test_generate_deployment_grid`
 

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

@@ -215,7 +215,8 @@ confirmation as the plan's own: the player is approving all of it, not only what
 
 If a staging call is refused as contested, it names the axes the player's own hand changed after
 your compile. Do not retry it and do not work around it — compile again so the new plan absorbs
-those edits, then stage that one.
+those edits, then stage that one. The same holds when it is refused because the strategy committed
+a newer revision after your compile: compile again against what is committed now.
 
 **Offer to discard a draft only on the player's explicit word**, never on your own judgement that
 it looks stale, and never batched into another act. State when it was last touched and which
@@ -272,6 +273,12 @@ with the player:
 - **Tuning a single rule** — how many agents are bound, and that the change reaches every one of
   them immediately.
 
+**Never tune or restore around a draft.** `update_strategy_signal_rule` and `restore_strategy` are
+REFUSED while the player holds a draft of the strategy — check `get_strategy_draft` first. For a
+tune, compile the one-rule change and `stage_strategy_plan` it, so it lands in their form; for a
+restore, ask them to save or discard their draft first. The refusal is the server's, so do not
+retry the call.
+
 **Your `ask_user` is the explanation, not the mechanism.** For single-rule tuning the server
 independently requires `confirm:true` whenever the strategy has bound agents, so stating the radius
 and calling anyway is refused, not committed. Send `confirm:true` only on a turn where the player