@battlegrid/mcp-server 32.0.99 → 32.0.100

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.
@@ -191,6 +191,10 @@ Recipes — each one clause:
191
191
  came back under it. `dist_donchianHiPrior20 crossesBelow 0` is NOT "fell back into the channel": the rail
192
192
  rises to each breakout bar's high, so it fires once on the first bar of a breakout run that does not
193
193
  close above the raised rail — the run of new closing highs ended.
194
+ - **Near the all-time high** — `dist_ath gt -3`, over an `ATH × distance` column: the close is within 3% below the
195
+ coin's all-time high, or past it. `ATH` is the highest high before the bar since the coin listed on its venue
196
+ (Pine's `ta.max(high)[1]` over the venue's whole history), so the distance is negative below the level and
197
+ `dist_ath crossesAbove 0` is the first close above a new all-time high. It is absent on a coin's first bar.
194
198
  - **RSI crossed above 50 within the last 3 closes** — `RSI14_now crossesAbove 50` holding
195
199
  `{ "atLeast": 1, "of": 3 }`.
196
200
  - **Close crossed above a 100 EMA** (a length with no stored point) — `close_close_ema100_spread crossesAbove 0`,
@@ -262,17 +266,17 @@ FALSE, so `NOT [dist_donchianHiPrior20 gt -0.52]` reads TRUE on a coin with no c
262
266
  `CVD_state in ["bullish", "neutral"]` part the same way. Flip only a header that always carries a
263
267
  value, or choose deliberately which answer a missing value gives.
264
268
 
265
- A verdict carrier must read no DEVELOPING bar. A verdict is refused over any closure that reads a
266
- column selecting Developing above the strategy timeframe (`CONDITION_VERDICT_READ_ILLEGAL`). The
267
- closure is what the condition reads directly plus everything reached through `conditionRef`,
268
- transitively: a referenced condition contributes what IT reads, so moving the clause into a building
269
- block does not launder it. A closure whose candle columns all read Confirmed — or whose operands no
270
- bar moves at all, such as a published regime label or a funding rate — admits a verdict at every
271
- decision, because a decision reads the completed strategy bar and a level is compared against that
272
- bar's close. A change over a horizon above the strategy timeframe — `chg4h` or `chg24h` on a `1h`
273
- strategy, and `oiRegime`, which reads the `1h` change, below `1h` — is a developing read whatever its
274
- selector: its bar is still in progress at the close, so it carries no verdict. Read a horizon at or
275
- below the strategy timeframe instead, or a Confirmed `CLOSE_CHANGE` on the higher timeframe.
269
+ A verdict carrier may read a DEVELOPING bar. A verdict binds on the frame its decision reads,
270
+ whichever bar set its closure — what the condition reads directly plus everything reached through
271
+ `conditionRef`, transitively — reads. A closure that reads a column selecting Developing above the
272
+ strategy timeframe reads, on a decided bar, the higher-timeframe bar as it stood at the decided bar's
273
+ close, so the side is chosen by the value at the strategy close and never by the instant the
274
+ evaluation runs; the radar's close decision, the compose and the exit sweep read that one value. A
275
+ change over a horizon above the strategy timeframe — `chg4h` or `chg24h` on a `1h` strategy, and
276
+ `oiRegime`, which reads the `1h` change, below `1h` — is a developing read whatever its selector: its
277
+ bar is still in progress at the close, so it reads the change up to the decided close, renders
278
+ provisional, and may carry a verdict. What a developing read cannot do is count closes: a clause over
279
+ one holds Once and steps no sequence (`DEVELOPING`, below), whatever verdict its condition carries.
276
280
 
277
281
  Evaluation is three-valued: UNRESOLVED never collapses to FALSE; a developing read is provisional,
278
282
  and so is any reading taken on the display lane's forming bar.
@@ -312,9 +316,10 @@ a header admits only Once:
312
316
  `LIQUID_FLOOR` holds Once because `vol24hUsd` is a bundle scalar. A structure-zone column is not one of
313
317
  these: it holds on its own timeframe up to the window its `conditionHold` serves, each counted bar
314
318
  reading the zone set stored for that bar.
315
- - `DEVELOPING` — the column reads a bar still forming: a Developing candle column above the strategy
316
- timeframe, or a change over a horizon above it. **Developing columns cannot be held**; set a candle
317
- column Confirmed to count closes, or read a change at or below the strategy timeframe.
319
+ - `DEVELOPING` — the column reads a bar still in progress: a Developing candle column above the strategy
320
+ timeframe, or a change over a horizon above it. A decision reads that bar once, as it stood at the
321
+ decided close, so no earlier reading of it exists to count: **Developing columns cannot be held**; set
322
+ a candle column Confirmed to count closes, or read a change at or below the strategy timeframe.
318
323
  - `OFFSET` — the column already reads an earlier bar; remove the offset to count closes.
319
324
  - `BAR_STATE` — the header describes only the bar being decided.
320
325
  - `HISTORY` — not enough history is stored on that timeframe to count more than one close.
@@ -392,13 +397,17 @@ bar reads the reclaim column, `poolAboveRecl is "true"` (`## Market structure le
392
397
 
393
398
  **Confirmed / Developing, per candle column.** Every transform whose home is the coin's candle series
394
399
  carries `bars`: `"closed"` is Confirmed — the newest bar completed at the strategy close — and
395
- `"all"` is Developing, the higher-timeframe bar still in progress at that close, which REPAINTS until
396
- it completes. Left unset a column reads Confirmed at every timeframe; Developing applies only where
397
- you choose it. At or below the strategy timeframe a Developing choice sets only what the live lane
398
- shows — no bar is in progress at the anchor's own close — so there it is legal and changes no decision
399
- taken at that close. A condition reading a
400
- developing bar is single-frame: its clause holds Once (a Developing column cannot be held), it
401
- 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
400
+ `"all"` is Developing, the higher-timeframe bar still in progress, as it stands at each close of the
401
+ strategy bar; its value moves from one strategy bar to the next until that bar completes. Left unset a
402
+ column reads Confirmed at every timeframe; Developing applies only where you choose it. At or below the
403
+ strategy timeframe a Developing choice sets only what the live lane shows — no bar is in progress at the
404
+ anchor's own close — so there it is legal and changes no decision taken at that close. A condition
405
+ reading a developing bar holds one close: its clause holds Once (a Developing column cannot be held)
406
+ and steps no sequence. It may be required, carry a verdict or take the exit role: a decision reads the
407
+ bar as it stood at the decided bar's close, and a read with no decided bar (the arena's entry
408
+ admission, a live preview) reads the bar as it stands now. A Developing read of a spot-tape, market-breadth or
409
+ stablecoin-pair column reads no bar in progress at a decision, so a clause over one is UNRESOLVED there
410
+ — a required condition over it blocks. One exception overrides both the stored value and the default: a column reading a metric with
402
411
  no live value (itself, or a `spread` operand) reads completed bars at every rung, because the forming
403
412
  bar publishes nothing for it. A change (`chg5m` … `chg24h`, and `oiRegime`'s `1h` change) carries its
404
413
  horizon in the metric, so above the strategy timeframe it is Developing at every rung and under every
@@ -460,8 +469,10 @@ the side: an exit rule carries `verdict: null` and `required: false` (`CONDITION
460
469
  an exit rule may reference anything, so "exit when the entry setup stops holding" is an exit rule
461
470
  whose definition is `NOT` a `conditionRef` to the entry condition. An exit rule is legal only over a
462
471
  closure every operand of which a completed bar MOVES (`CONDITION_EXIT_READ_ILLEGAL`), which rules out
463
- a developing read — a bar in progress is the forming bar, and an exit fired on one is an intrabar
464
- exit — and rules out a frame-inert operand, which could never fire. A position stamps the exit rules
472
+ a frame-inert operand, which could never fire. A developing read is legal: the exit sweep reads the
473
+ higher-timeframe bar as it stood at the judged candle's close, so every completed strategy candle moves
474
+ it and the rule fires on the value at that close, never on an intrabar one; held over more than one
475
+ close it is refused (`DEVELOPING`). A position stamps the exit rules
465
476
  it opened under, with the report and timeframes they read: an exit-rule edit applies to positions
466
477
  opened after it, and an open position keeps the exit rules it opened with, so an open position never
467
478
  refuses a commit or a rebind.
@@ -563,7 +574,7 @@ where the CLOSE sits in the envelope — `pctB20 lt 0.05` closed in the bottom 5
563
574
  threshold, never a touch. `BB_UPPER × levelInteraction` says what the bar's RANGE did at the edge — touched it,
564
575
  or pierced it and closed back.
565
576
 
566
- **Candle patterns** — the bar's shape against the ten bars before it (TA-Lib's default settings). A
577
+ **Candle patterns** — the bar's shape against the ten bars before it (the default candle settings). A
567
578
  pattern carries no trend context: "a hammer in a downtrend" is `pin is "lower_wick"` plus a separate
568
579
  trend clause.
569
580
 
@@ -723,9 +734,9 @@ Recipes — the five structure reads are at the default pair; off it, read them
723
734
  and `upper_wick` at a swing high, and `engulf_o21` for an engulfing. The whole conditions are
724
735
  `references/recipes.md`, *Candle at a swing and liquidity-pool sweeps*.
725
736
 
726
- ## Market structure levels (LuxAlgo SMC)
737
+ ## Market structure levels (SMC)
727
738
 
728
- The levels LuxAlgo's Smart Money Concepts v7.0 draws, at its own defaults unless a column sets a knob:
739
+ The Smart Money Concepts levels, at their defaults unless a column sets a knob:
729
740
  swing length 50, internal length 5 (fixed), equal-pivot length 3 (`equalBars`), equal threshold 0.1 ×
730
741
  ATR(200) (`equalThreshold`), confluence filter off. A header carries only a knob off its default, so
731
742
  the default columns read `structHi`, `iStructLo`, `eqhLvl`. The server computes them over the column's
@@ -743,7 +754,7 @@ Every reading in this section is therefore a state.
743
754
 
744
755
  | Key | Header | Reads |
745
756
  |---|---|---|
746
- | `SWING_PENDING_HIGH` / `_LOW` | `structHi` / `structLo` | the swing high / low the next swing break is tested against — LuxAlgo's current level while no close has crossed it |
757
+ | `SWING_PENDING_HIGH` / `_LOW` | `structHi` / `structLo` | the swing high / low the next swing break is tested against — the current level while no close has crossed it |
747
758
  | `INTERNAL_PENDING_HIGH` / `_LOW` | `iStructHi` / `iStructLo` | the same on the internal structure (length 5) |
748
759
  | `EQH_LEVEL` / `EQL_LEVEL` | `eqhLvl` / `eqlLvl` | the newer pivot of the latest equal-high / equal-low pair, held until the next equal-length pivot on its side |
749
760
  | `SWING_STRUCTURE_LEVEL` | `structLvl` | the level the latest swing break crossed |
@@ -755,16 +766,16 @@ Every reading in this section is therefore a state.
755
766
 
756
767
  - **A pending level reads on the bar whose close crosses it**, and nothing from the next bar until a new
757
768
  pivot is recorded. So `dist_structHi gt 0` is true on that bar alone: every close through the pending swing
758
- high, the bar LuxAlgo marks BOS or CHoCH. The state is the crossing. It also reads the first, anchoring break,
769
+ high, the bar a break of structure (BOS) or change of character (CHoCH) is marked on. The state is the crossing. It also reads the first, anchoring break,
759
770
  which `structEvt` leaves untagged because its tag depends on a bias the column's bars have not yet proven.
760
- - **An internal crossing LuxAlgo does not count stays pending**: where the internal level is the swing
771
+ - **An internal crossing the structure does not count stays pending**: where the internal level is the swing
761
772
  level's own price, or the confluence filter refuses the bar, the close goes through and the internal
762
773
  level still reads, so `dist_iStructHi` reads above 0 while the close stays through it, and the internal
763
774
  event does not fire.
764
- - **No close retires an equal-pivot level** — LuxAlgo tests no break on equal highs. A sweep is its REJECT
775
+ - **No close retires an equal-pivot level** — no break is tested on equal highs. A sweep is its REJECT
765
776
  (`eqhLvl_lvl is "reject_from_below"`). A close through it is the state `dist_eqhLvl gt 0`, which holds while
766
777
  the close stays above, not the crossing bar alone.
767
- - **A close beyond a liquidity pool retires it** (LuxAlgo Liquidity Swings): the pool still reads on that
778
+ - **A close beyond a liquidity pool retires it**: the pool still reads on that
768
779
  bar, and from the next bar `poolAbove` reads the next pool out. A pool's sweep takes two forms: on one
769
780
  candle its REJECT, and over two candles the close beyond followed by a close back, which the next bar
770
781
  reads through the retired pool — `poolAboveRetired` (the pool the last close took, on that bar only)
@@ -797,7 +808,7 @@ Every reading in this section is therefore a state.
797
808
  `{ trigger, levelOffsetAtrMultiple, validForBars, levels }` — the axis's keys, and the trigger decides
798
809
  which of them you send. `ON_CANDLE_CLOSE` is sent ALONE, as `{ "trigger": "ON_CANDLE_CLOSE" }`: a
799
810
  `levelOffsetAtrMultiple`, `validForBars` or `levels` beside it is refused as an unrecognized key. A level
800
- trigger — `STOP_THROUGH_LEVEL` or `ON_RETEST` — sends all three, no defaults. The axis is staged
811
+ trigger — `STOP_THROUGH_LEVEL`, `ON_RETEST` or `EITHER_SIDE_OF_LEVEL` — sends all three, no defaults. The axis is staged
801
812
  WHOLE, so a level trigger missing one is refused rather than half-kept. It is not required on every
802
813
  CREATE: a CREATE that stages no entry takes the platform's seed entry, so stage it whenever the
803
814
  setup names one. There is no confirm-timeframe key: the bar whose close decides an entry is the
@@ -811,7 +822,7 @@ directions are authored separately and never mirrored, so an asymmetric strategy
811
822
  not yield is refused at save, naming `entry.levels.LONG` or `entry.levels.SHORT`; add a column that reads it, or choose
812
823
  one the report has.
813
824
 
814
- **Every trigger is decided at the close of the strategy's own bar — there are three, and the close
825
+ **Every trigger is decided at the close of the strategy's own bar — there are four, and the close
815
826
  is the only entry clock.** The newest completed bar is read on the closed basis — every one-close
816
827
  condition resolves on that bar and the gates read its close — and a reading that still qualifies
817
828
  fires at that close. A bar that does not qualify decides nothing and is not revisited. The fill lands
@@ -828,10 +839,29 @@ and is REFUSED on every stage and save; there is no live-reading entry to author
828
839
  for a return to it (a pullback: the broken 20-bar high `DONCHIAN_BROKEN_HI` for a long, the broken low
829
840
  `DONCHIAN_BROKEN_LO` for a short). The level must sit behind the mark. Not filling is a correct outcome, not a
830
841
  failure.
842
+ - `EITHER_SIDE_OF_LEVEL` — at the qualifying close the order rests at the same placed price (level ± offset × ATR)
843
+ and its type is chosen from the side of the mark that price sits on: a stop when it is beyond the mark in the
844
+ trade's direction, a limit when it is in front of it. A price exactly at the mark is no setup. Nothing is bought
845
+ past the level: the stop is the same order `STOP_THROUGH_LEVEL` rests and the limit the same `ON_RETEST` rests.
846
+ Choose it when the level should be traded from whichever side price reaches it.
847
+
848
+ **Each level has a side of price, by definition.** A resistance zone, the 20-bar high and a naked POC above sit above
849
+ price; a support zone, the 20-bar low and a naked POC below sit below it; moving averages, VWAPs, pivots and session
850
+ levels can sit on either side. A breakout stop needs a level beyond price in the trade's direction (above for a long),
851
+ a pullback limit one in front of it (below for a long). A level on the wrong side for its trigger still saves, and
852
+ the draft warns `ENTRY_LEVEL_USUALLY_SKIPPED`, because the entry will be skipped on most bars; `EITHER_SIDE_OF_LEVEL`
853
+ never warns.
831
854
 
832
855
  Either way a level with no reading on the decided bar, or on the wrong side of the mark, is no setup — refused with
833
- its stage, never substituted by another level. The entry price is fixed at the decision: a level that moves while the
834
- order waits does not move the order.
856
+ its stage, never substituted by another level.
857
+
858
+ **A resting entry follows its level.** On each closed strategy bar while the order waits, the platform reads the level
859
+ again and re-prices the order to the new level ± offset × ATR, with its stop, targets and size rebuilt from the same
860
+ setup. It never chases: no read happens between closes. If the level now sits on the wrong side of the mark, a
861
+ `STOP_THROUGH_LEVEL` or `ON_RETEST` entry is cancelled, and an `EITHER_SIDE_OF_LEVEL` entry switches between stop and
862
+ limit. The entry is also cancelled when the rebuilt setup fails its reward-to-risk floor or stop band, or its sizing or
863
+ budget. Once any part of the order has filled, the entry is frozen where it filled. Every re-price, switch and cancel is
864
+ in the position's audit history (`ENTRY_REPRICED`), and `validForBars` still counts from the decision.
835
865
 
836
866
  **A multi-bar hold belongs to the CLAUSE (or group) that needs it.** Declare that clause's own
837
867
  `hold` — "3 closes in a row", "within 5 closes" — the entry axis counts no bars, and there is no displacement band: the
@@ -43,7 +43,7 @@ default above the strategy timeframe); plus `includeCvd`. Conditions:
43
43
  `FADE_SHORT` verdict DOWN (ref + `RSI14 gte 65` + `closeChg_1d gte 5`); mirrored `SQUEEZED_SHORTS`
44
44
  / `SQUEEZE_LONG` verdict UP (`closeChg_1d lte -5`). The confirmation is the prior completed UTC day's
45
45
  move, not today's: today's (`chg24h`) is a 1d bar still in progress at every 1h close, a developing
46
- 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).
46
+ read that measures only the part of the day already traded and cannot be held. 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).
47
47
 
48
48
  ### 3 · Relative-Strength Rotation with a Benchmark Gate — 4h cross-sectional
49
49
 
@@ -53,7 +53,11 @@ Not "what were its returns" — whether it did *the thing it was told to do*.
53
53
  measurable trade's `tradeExcursion` reads in R: `mfeR` and `maeR` (the best and worst it reached),
54
54
  `exitR`, and `giveBackR` (what it surrendered between its peak and the close). `exitEfficiency` is
55
55
  a union — branch on its `state` before reading `efficiencyPercent`. All of them are gross of
56
- costs; `netPnl` is the after-fee figure.
56
+ costs; `netPnl` is the after-fee figure. A level entry's `entryDiscipline` names the order it rested as
57
+ (`restedOrderType`) and `repriceCount`, how many closed bars moved that order with its level; the
58
+ moves themselves, and a follow that cancelled the entry, are `ENTRY_REPRICED` events in
59
+ `get_position_audit_history`. An entry that expired `LEVEL_FOLLOW_REFUSED` was cancelled while
60
+ following its level, and its audit event's `refusalStage` names the step that refused it.
57
61
  - The record around the trades: `list_agent_market_grid_decisions` (an agent's arena decisions),
58
62
  `get_signal_log` (a trade's pipeline, its thesis as `thesisReasoning`), `list_my_market_grid_entries` / `get_my_market_grid_entry` (an
59
63
  arena entry's reasoning — `agentId` for one agent's entries, none for every entry),
@@ -49,11 +49,13 @@ close executes.
49
49
  - A refused scan (`RATE_LIMITED`) is a refusal: say the scan was refused and when it can be retried
50
50
  (`retryAfterSeconds`). Never say "nothing fits".
51
51
 
52
- ## 3. Confirm, then queue the request
52
+ ## 3. State the request, then queue it on the player's consent
53
53
 
54
- - **Confirm with the player before queueing.** Name the agent, the coin and the bar it will be
55
- decided on, and say that a qualifying close places the agent's entry at once, sized by the agent's
56
- own risk budget, with no further step. Ask, and queue only on their yes.
54
+ - **State the request before queueing.** Name the agent, the coin and the bar it will be decided on,
55
+ and say that a qualifying close places the agent's entry at once, sized by the agent's own risk
56
+ budget, with no further step. A client that prompts for tool approval collects the player's
57
+ approval on the queueing call itself — ask no separate question; a client that does not asks in its
58
+ reply and queues only on their yes.
57
59
  - **The player's own words can already be the consent.** "Trade SOL with Atlas at its next close" is
58
60
  consent: queue without asking again. So is a standing instruction the player gave you to trade for
59
61
  them. Interest is not consent — "what fits SOL right now?" is a question, so report the fit and ask