@battlegrid/mcp-server 32.0.99 → 32.0.103

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -42,9 +42,10 @@ Explain a score, a payout or a captain choice from them, never from a remembered
42
42
  2. **A stale or superseded agent grid submitted.** *Cue: the agent generated a grid and then
43
43
  anything happened — a regeneration, a long pause, a change of mind.* The submit consumes
44
44
  whatever generation is cached, not the one the player looked at. → step 4.
45
- 3. **Restating a limit number.** *Cue: the urge to say "you have N entries left today" or "your cap
46
- is $X".* Daily wager caps are platform config with per-user overrides, and the pipeline is the
47
- only authority on them. → the negatives below.
45
+ 3. **A limit quoted from memory.** *Cue: the urge to say "you have N entries left today" or "your cap
46
+ is $X" without having just read it.* Daily wager caps are platform config with per-user overrides;
47
+ the account state serves today's values, and the pipeline is the authority on an attempt. → step 1
48
+ and the negatives below.
48
49
 
49
50
  ## Sequence
50
51
 
@@ -67,6 +68,20 @@ instead of `mcpWagerEnabled`.
67
68
  is still refused at the fee. The wager pipeline re-checks at the fee itself and its refusal is
68
69
  the authority in either direction.
69
70
 
71
+ **`dailyWagerCaps`** — today's MCP entries (`count`) and entry volume in USD (`volumeUsd`) against the
72
+ player's daily caps, each with `used`, `limit`, `remaining`, the server's `status` and `resetsAt`. The
73
+ caps bind every entry made through MCP — this conversation's included — for the player and their agents
74
+ alike; entries made in the web app are outside them.
75
+
76
+ - **`count.status` EXHAUSTED, or the session's entry fee above `volumeUsd.remaining`** ⇒ a **definite
77
+ refusal**, before any submission. Say which cap is spent and when it resets (`resetsAt`, a UTC
78
+ instant), and call no submission tool — a replacement of an agent's entry included.
79
+ - **LOW** ⇒ say how much remains — "this is your last entry today" — before the commit.
80
+ - **`null`** ⇒ the caps could not be read. Say so, quote no figure, and let the pipeline decide: it is
81
+ neither readiness nor a refusal.
82
+ - **Open** is never a promise. Another client can spend the last entry first; the pipeline's own
83
+ refusal is the authority for an attempt.
84
+
70
85
  **In a conversation a web Commander surface hosts, the switch renders beneath the account card just
71
86
  shown, or beneath the refusal — offer it there.** Say the arena needs Agent Wagers and point at the
72
87
  control rather than at a settings path they would have to leave the conversation for. Every other
@@ -120,7 +135,7 @@ ask. The commit requires a `RATIONALE` axis — `reasoning`, `confidenceScore`,
120
135
  - Each entry's reasoning cites **the market context you read in this conversation**, for that
121
136
  coin. Boilerplate reasoning attached to a real wager is worse than none — it looks like
122
137
  evidence.
123
- - `confidenceScore` is your honest read, and you state it to the player on the confirm form.
138
+ - `confidenceScore` is your honest read, and you state it to the player before the commit.
124
139
  - **The `RATIONALE` is public.** Once the session locks, every player sees it beside the grid — the summary,
125
140
  the confidence, the model and each pick's reasoning — as they see an agent's. Write it for that reader.
126
141
 
@@ -133,29 +148,35 @@ Present the generation as a card: the agent, its confidence against the threshol
133
148
  (`confidenceThreshold: null` means no deployment declares a bar here, so the grid is **ungated** —
134
149
  say that rather than inventing a bar), whether it meets the threshold, and the per-coin picks.
135
150
 
136
- ### 4. Read again, confirm, then commit promptly
151
+ ### 4. Read again, state it, then commit promptly on the player's approval
137
152
 
138
153
  `get_market_grid_entry_draft` again after staging: show the player the diff, any diagnostic, and the
139
- `impact` — `ENTER` with the `entryFee` the commit charges, or `REPLACE` for none. One confirmation
140
- naming **the session, that fee, and the confidence** — then commit on an explicit pick.
154
+ `impact` — `ENTER` with the `entryFee` the commit charges, or `REPLACE` for none. One statement
155
+ naming **the session, that fee, and the confidence** — then commit, **only on the player's
156
+ approval**. A client that prompts the player to approve tool calls collects it: call right after the
157
+ statement and ask no separate confirming question — the client asks the player, or applies the
158
+ standing setting they chose, and the call runs only if approved. A client that does not asks in its
159
+ reply and waits for the player's word. Words typed while an approval prompt is open are not
160
+ approval: that call does not run, so answer what they said and call again only when they ask.
141
161
 
142
162
  - Direct → `commit_market_grid_entry_draft({ sessionId, draftVersion, expectedRevision })`,
143
163
  naming exactly the `draftVersion` and `committedRevision` the last read returned (`null` with no
144
- entry). A refusal naming `get_draft` means the draft or the entry moved: read again and confirm
145
- again — never retry with a bumped number.
164
+ entry). A refusal naming `get_draft` means the draft or the entry moved: read again and state it
165
+ again before a fresh call — never retry with a bumped number.
146
166
  - Agent → `submit_agent_grid`, which consumes the cached generation for that (session, agent).
147
167
 
148
- **A regeneration voids any prior confirm.** The submit takes no generation token — it reads
149
- whatever is currently cached — so a grid regenerated after the player confirmed would be submitted
150
- under a confirmation given for different picks. Re-present the confirm for the new generation,
151
- every time, and submit promptly after the confirmed one.
168
+ **A regeneration voids any prior approval.** The submit takes no generation token — it reads
169
+ whatever is currently cached — so a grid regenerated after the player approved would be submitted
170
+ under an approval given for different picks. State the new generation, every time, and submit it
171
+ promptly, its call waiting on its own approval.
152
172
 
153
173
  **If the submit is refused with `CONFLICT`**, the player's entry changed after the grid was generated —
154
174
  replaced, cancelled, re-placed, or placed where there was none. No fee moved. The recovery is
155
- `generate_agent_grid` again, a fresh confirm of the new grid, then `submit_agent_grid`.
175
+ `generate_agent_grid` again, a fresh statement of the new grid, then `submit_agent_grid` on the
176
+ player's approval.
156
177
 
157
178
  **If the submit is refused for a missing pending generation**, the ten-minute window lapsed. The
158
- recovery is `generate_agent_grid` again and a fresh confirm. **Never** convert the stale picks into
179
+ recovery is `generate_agent_grid` again and a fresh statement. **Never** convert the stale picks into
159
180
  a hand-staged draft committed under the player's own name — that enters an agent's reasoning as the
160
181
  player's, and the attribution is part of what was scored.
161
182
 
@@ -188,7 +209,7 @@ arrives as the attached scope, and the session it names is the one in scope.
188
209
  - **Stage, do not enter.** When the player asks you to pick or fill in their grid, read the draft and
189
210
  stage the cells into it (step 3). Each staged pick appears in their builder at once, labelled as
190
211
  yours; nothing is entered and no fee or deposit is needed. Their own **PLACE ENTRY** places it;
191
- offer to place it for them only through step 4's confirmation and the draft commit.
212
+ offer to place it for them only through step 4's statement and the draft commit, on their approval.
192
213
  - **Their picks are in the draft.** A pick they make in the builder lands there as they make it, so
193
214
  read the draft before answering what they have picked or staging over it. A pick their builder
194
215
  rewrote after you staged it is their answer — stage it again only when they ask.
@@ -196,8 +217,8 @@ arrives as the attached scope, and the session it names is the one in scope.
196
217
  `generate_agent_grid` for the session in scope (the billed-inference warning in step 3 still
197
218
  applies). The result reaches them as a card with **LOAD INTO GRID**, which puts the picks into their
198
219
  builder as a starting point. A loaded grid they have not changed is the agent's: if they want it
199
- entered as it stands, run step 4, then `submit_agent_grid` on their explicit pick, never on free
200
- text. Once they change a pick, the grid is theirs.
220
+ entered as it stands, run step 4, then `submit_agent_grid` on their approval as step 4 describes.
221
+ Once they change a pick, the grid is theirs.
201
222
  - **A newer generation for the same agent replaces the older card.** The older one reads SUPERSEDED;
202
223
  only the newest is what `submit_agent_grid` would enter.
203
224
 
@@ -208,24 +229,25 @@ Each is typed and distinguishable. Read the code, do not paraphrase:
208
229
  - **No wallet consent** — the shared wager pipeline's own refusal, carrying its enablement copy.
209
230
  Surface that path verbatim. This is the same refusal an external MCP client gets; there is no
210
231
  chat-side difference and no chat-side override.
211
- - **A daily cap** — a typed rate-limit refusal. Say the cap is spent and that it resets on the UTC
212
- day. Distinguishable from the run's op budget and from consent — do not merge them into "you
213
- can't play right now".
232
+ - **A daily cap** — a typed rate-limit refusal. Say the cap is spent and when it resets — the
233
+ `resetsAt` of a fresh `get_account_state`. Distinguishable from the run's op budget and from
234
+ consent — do not merge them into "you can't play right now".
214
235
  - **Funds, session state, an already-submitted grid** — ordinary typed refusals. Report what the
215
236
  server said.
216
237
 
217
238
  ## Negatives
218
239
 
219
- - **Never restate a limit number** — not the daily count, not the volume cap. The pipeline holds
220
- the real value including per-user overrides, and a number repeated from anywhere else will
221
- eventually be wrong on a surface where being wrong costs money.
240
+ - **Never quote a limit from memory** — not the daily count, not the volume cap, not the reset.
241
+ Quote the served `dailyWagerCaps` of the read you just made: the server holds the real value
242
+ including per-user overrides, and a number repeated from anywhere else will eventually be wrong on
243
+ a surface where being wrong costs money.
222
244
  - **Never use `random_submit_market_grid`.** It shuffles the pool and wagers on the result with no
223
245
  reasoning at all. It exists for other clients; it is not something to offer a player who asked
224
246
  you to think.
225
- - **Your confirmation with the player is interaction, never authorization.** Do not describe it as
226
- a permission check, do not add a wager gate of your own, and do not treat free text typed while a
227
- confirmation is open as consent — in chat or in the form's own answer-in-your-own-words box. Only
228
- an explicit pick from the options you offered confirms.
247
+ - **The player's approval of the call is the client's, never authorization.** Do not describe it as
248
+ a permission check, do not add a wager gate of your own, and do not ask a separate confirming
249
+ question where the client already prompts for the call. Words typed while an approval prompt is
250
+ open never approve the call.
229
251
  - **Never re-commit over an unknown outcome.** An interrupted commit may have moved the fee. A retry
230
252
  of the same `draftVersion` returns the first commit's receipt; otherwise run
231
253
  `check_market_grid_submission` and `get_market_grid_entry_draft` first and report what actually
@@ -12,17 +12,18 @@ setting an officer up, running it, reading where it stands, and acting on what i
12
12
 
13
13
  Every officer run is billed to the player's LLM credit, and an applied proposal changes a live strategy, agent or
14
14
  Radar deployment. So a setup goes through its own draft, a run is started only on the player's word, and Apply is
15
- confirmed before it is called.
15
+ stated first and runs only on the player's approval.
16
16
 
17
17
  ## The four failures this flow exists to prevent
18
18
 
19
19
  1. **Writing a review yourself.** *Cue: "what would my officer say about…", wanting to record a finding.* You read
20
20
  an officer's reviews and give your own reading in the conversation; only the officer records a review. → §2.
21
- 2. **Applying without confirmation.** *Cue: "apply it", "make it live".* Apply publishes the proposal to a live
22
- target. Show the review, then confirm through `ask_user`. → §4.
21
+ 2. **Applying without approval.** *Cue: "apply it", "make it live".* Apply publishes the proposal to a live
22
+ target. Show the review and name what Apply publishes, then call it on the player's approval. → §4.
23
23
  3. **Computing what is served.** *Cue: working out the next run from the schedule, counting open reviews.* Every
24
24
  status figure is on the read. → §3.
25
- 4. **Committing a setup unasked.** *Cue: a staged officer that looks right.* The commit is the player's word. → §1.
25
+ 4. **Committing a setup unasked.** *Cue: a staged officer that looks right.* The commit runs on the player's
26
+ approval, never your judgement. → §1.
26
27
 
27
28
  ## 1. Set up and update an officer through its draft
28
29
 
@@ -43,15 +44,18 @@ confirmed before it is called.
43
44
  `list_intelligence_agents`) and `levers`; `MODEL` names a `modelId` from `list_approved_models`. `INSTRUCTIONS`
44
45
  are the player's brief in their own words: at most 2,000 characters, naming no tool and no id — the commit
45
46
  refuses either.
46
- - **Show, then commit on the player's word.** Read `get_officer_draft` and show the diff, the diagnostics and the
47
+ - **Show, then commit on the player's approval.** Read `get_officer_draft` and show the diff, the diagnostics and the
47
48
  impact — `nextRunAt` is when it first runs, and a create's `admission` says how many officers the player holds
48
49
  against their account plan's officer limit and how many more it admits (`officersRemaining`). Every unarchived
49
50
  officer counts, paused ones included; a create past the limit is refused as `PLAN_LIMIT_REACHED`, and archiving
50
- an officer frees its place. Commit with `commit_officer_draft` naming exactly the `draftVersion` and
51
- `committedRevision` the read returned, and only when the player says so. A cadence of `OFF` keeps the setup and
51
+ an officer frees its place. Then commit with `commit_officer_draft` naming exactly the `draftVersion` and
52
+ `committedRevision` the read returned, only on the player's approval: a client that prompts the player to
53
+ approve tool calls collects it, so call right after showing the read and ask no separate confirming question; a
54
+ client that does not asks in its reply and waits. Words typed while an approval prompt is open are not
55
+ approval: that call does not run, so answer what they said and call again only when they ask. A cadence of `OFF` keeps the setup and
52
56
  runs nothing on a schedule.
53
- - **Archive** with `archive_officer` only on the player's word: an archived officer runs no more, and its open
54
- reviews stay in the inbox.
57
+ - **Archive** with `archive_officer` only when the player asks, saying first that an archived officer runs no
58
+ more and its open reviews stay in the inbox; the call runs on their approval, as a commit's does.
55
59
  - In the app, the player sets an officer up in its own console, where this conversation may be docked beside the
56
60
  form — stage into the officer it is scoped to.
57
61
 
@@ -90,9 +94,10 @@ them as served, through their display names.
90
94
  served; `applyAvailable` says Apply is offered, `heldAxes` names every axis the target's draft holds and who wrote
91
95
  it, and `baseMoved` says the target was committed since the review. `awaitingOwner` says the review waits on the
92
96
  player; a review that proposes no change (lever `NONE`) is for their information and never waits.
93
- - **Apply** with `apply_officer_proposal` only after an `ask_user` confirmation naming the review, its target and
94
- its axis, and only on the confirming pick. A client with no `ask_user` asks in its reply and waits for the
95
- player's word. Apply publishes the proposal to the live target; it needs `mcp:wager`.
97
+ - **Apply** with `apply_officer_proposal` only after naming the review, its target and its axis, and only on the
98
+ player's approval of the call: a client that prompts for tool approval collects it, so ask no separate
99
+ confirming question; one that does not asks in its reply and waits. Apply publishes the proposal to the live
100
+ target; it needs `mcp:wager`.
96
101
  - **Push** with `push_officer_proposal` and **Dismiss** with `dismiss_officer_review` on the player's explicit word,
97
102
  naming the review. A push places the proposal in the target's draft for the player to save from the editor; a
98
103
  dismissal closes the review and touches no draft.
@@ -14,20 +14,22 @@ step the server says is next, and keep going until the account is battle-ready.
14
14
  Call `get_onboarding_requirements` before you say anything about setup, and again after every
15
15
  step you complete. Read its `status`, its `next` and the `remedy` on the step `next` names, as
16
16
  served. Never judge readiness from anything else — a deposit you saw, an agent you created, a
17
- policy you read — never name or count the steps, and never decide an order: the server already
17
+ policy you read — never list or count the steps, and never decide an order: the server already
18
18
  chose it, and the app's setup bar names the same step from the same read.
19
19
 
20
20
  ## Each turn
21
21
 
22
- 1. **Read the ladder.** If `status` is battle-ready, say the account is set up and stop.
23
- 2. **Take the step `next` names.** Say what it is in the step's own served sentence, then act on
24
- its `remedy` by who performs it (`actor`):
25
- - **`COMMANDER` — you do it, with the player's go-ahead.** Ask once, then turn to the skill
26
- that owns the act and follow that skill's own procedure to the end: the `strategy-authoring`
27
- skill builds a strategy; the `agent-management` skill creates an agent or resumes a paused
28
- one; the `radar-deployment` skill puts an agent on Radar or Arena duty. A resume is the act
29
- to try, not a promise: if the owning skill reports the stop is still breached, offer its
30
- exits and do not repeat the resume.
22
+ 1. **Read the ladder.** If `status` is battle-ready, say in one sentence that the account is set up
23
+ and end your turn. Ask nothing, and do not offer an optional step unless the player asks for one.
24
+ 2. **Take the step `next` names.** Name the step by its served `title`, then say what it gets the
25
+ player in the step's served sentence, and act on its `remedy` by who performs it (`actor`):
26
+ - **`COMMANDER` — you do it, with the player's go-ahead.** Offer it with `ask_user` and end your
27
+ turn on that question. Call nothing for the step, not even the owning skill's reads, until the
28
+ player says yes; then turn to the skill that owns the act and follow that skill's own
29
+ procedure to the end: the `strategy-authoring` skill builds a strategy; the `agent-management`
30
+ skill creates an agent or resumes a paused one; the `radar-deployment` skill puts an agent on
31
+ Radar or Arena duty. A resume is the act to try, not a promise: if the owning skill reports
32
+ the stop is still breached, offer its exits and do not repeat the resume.
31
33
  - **`PLAYER` — only the player can do it, in the app.** It is a deposit, a signature, a
32
34
  payment or an API key. Say what it is and why it is next. On the web, the control that does
33
35
  it sits directly under your reply; elsewhere, tell the player where in the app it lives.