Trader-MCP Hermes Compatibility TODO

This file is the structured upgrade plan for preparing trader-mcp for hermes-mcp supervision.

Guiding rule

Trader-MCP concerns strategy behavior and the surfaces strategies must expose. Hermes decides the market story and the active control stance.

1. Contract first

Freeze the Hermes ⇄ Trader read contract before adding new strategy behavior.
Freeze the Hermes → Trader action contract before adding new control paths.
Keep every request and response machine readable.
Require decision_id, reason, and confidence for Hermes control decisions.
Require Trader to return a structured applied-result record.
Keep one canonical Hermes write tool: apply_control_decision.
Do not send keep actions to Trader; Hermes records keep on its own side.

2. Canonical strategy taxonomy

Reduce the strategy set to a small, orthogonal registry. Treat parameter variants as modes inside a strategy, not separate strategies.

Canonical set:

idle
defensive
trend_following
mean_reversion
grid
breakout
event_driven

Rules:

Remove or fold redundant strategy names that differ only by tuning.
Keep names human-readable and stable.
Preserve a single conceptual strategy per regime.

3. Strategy metadata

Every strategy must declare:

expects
avoids
risk_profile
capabilities

The natural habitat fields should cover:

trend
volatility
event risk
liquidity

Example capability declaration:

{
  "name": "mean_reversion",
  "capabilities": ["fade_extremes", "range_entry", "range_exit"],
  "expects": {
    "trend": "none",
    "volatility": "low",
    "event_risk": "low",
    "liquidity": "normal"
  },
  "avoids": {
    "trend": "strong",
    "volatility": "expanding",
    "event_risk": "high",
    "liquidity": "thin"
  },
  "risk_profile": "medium"
}

4. Strategy surface

Expose clean strategy state. Each strategy should provide:

status
recent_changes
decision_history
render_state
risk_state
execution_state

Preferred additions:

confidence
uncertainty
last_transition
last_error

5. Trader surface for Hermes

Refactor the MCP tools toward Hermes usefulness, but keep the surface narrow.

Canonical read tools:

list_strategies
get_strategy

Canonical write tool:

apply_control_decision

Internal or operator helpers may still exist:

switch_strategy
set_risk_mode
pause_strategy
resume_strategy
reconcile_state

Rules:

Hermes should not need multiple Trader tool calls to express one decision.
Avoid adding extra Hermes-facing read tools unless get_strategy().report proves insufficient.

6. Switching policy

Prevent flip-flopping.

Add:

confidence threshold
minimum hold time
hysteresis
explicit emergency override path
degraded execution fallback

7. Ownership boundaries

Strategy owns

local logic
local state
local config
own render output
own explanation string

Trader runtime owns

lifecycle
persistence
snapshots
reconciliation
dashboard presentation
execution plumbing

Human observer owns

inspection
approval where configured
operational overrides where explicitly allowed
debugging and review

Hermes owns

enable / disable / switch decisions
risk-mode changes
uncertainty and confidence weighting
regime interpretation
execution-degradation-driven downranking

8. First strategies to implement

Implement in this order:

idle
defensive
trend_following
mean_reversion
grid
breakout
event_driven

Notes:

idle and defensive are safety exits.
trend_following and mean_reversion are the first core alpha strategies.
grid is structure-based, not signal-based.
breakout is separate from trend-following.
event_driven should remain explicit and temporary in behavior.

9. Stepwise upgrade path toward Hermes compatibility

Phase 0, document the contract

write Hermes_Trader_Contract_v0.1.md
agree the control verbs
agree the request/response schemas

Phase 1, normalize the registry

fold redundant strategy names
mark parameter variants as modes
add metadata to current strategies

Phase 2, harden the Hermes read path

make get_strategy().report the canonical structured read shape
ensure list_strategies() and get_strategy() cover Hermes inspection needs
ensure dashboard and API agree

Phase 3, add the action layer

add apply_control_decision
validate every transition
log the reason for every decision
keep legacy helper verbs behind the single write entry point where possible

Phase 4, implement switching safety

confidence threshold
hold time
hysteresis
emergency override
degraded execution fallback

Phase 5, implement the initial strategy set

idle
defensive
trend_following
mean_reversion

Phase 6, add structure strategies

grid
breakout

Phase 7, add event-aware behavior

event_driven
event-risk metadata
event-pressure aware selection

Phase 8, feed back execution quality

fills
slippage
latency
rejected orders
venue stress
partial fill patterns
degraded connectivity

Phase 9, tighten dashboards and audit trails

current strategy view
why-active view
recent changes timeline
Hermes decision trace
execution state panel

10. Tests to add

Contract tests

strategy metadata validation
Hermes request schema validation
Trader response schema validation
control verb validation

Runtime tests

load / unload / switch transitions
state snapshot and restore
minimum hold enforcement
hysteresis enforcement
defensive fallback on degraded execution

Strategy tests

expected regime matching
avoided regime rejection
deterministic state transitions
readable explanation output

Integration tests

Hermes decision to Trader control path
Trader response parsing
execution feedback influencing future selection

11. Cleanup and simplification

Separate signal-based strategies from structure-based ones, especially mean_reversion vs grid.
Avoid adding micro-strategies until the minimal taxonomy is stable.
Keep strategy names human-readable and stable.

12. Current implementation order

lock the contract paper
canonicalize the strategy registry
add metadata to current strategies
add validation tests
implement the inspection tools
implement the control tools
add switching safety
implement idle and defensive
implement trend_following and mean_reversion
add grid, breakout, and event_driven
wire execution feedback into selection
polish dashboard and traceability

TODO.md 6.8 KB Cronologia Originale