# AGENTS.md

## Role
TRADER-MCP is a strategy runtime.

It executes multiple independent trading strategies and converts their outputs into execution intents for exec-mcp.

---

## Architecture

TRADER-MCP is structured in three layers:

1. Strategy Layer
   - runs pluggable strategies (grid, mean reversion, etc.)
   - produces trade intents

2. Runtime Layer
   - manages lifecycle of strategies (start/stop/configure)
   - isolates strategies from each other

3. Execution Layer
   - translates intents into exec-mcp commands
   - ensures format correctness

---

## Control Authority

- hermes-mcp controls:
  - which strategies are active
  - strategy parameters
  - global risk posture

- trader-mcp must obey all hermes control signals
- trader-mcp must NOT override or reinterpret them

---

## Core Invariants

- strategies are independent units
- no strategy may access others’ internal state
- trader-mcp does not define market stance
- execution is derived only from strategy outputs + Hermes constraints

---

## Boundary Rules

- NO strategy selection logic (belongs to Hermes)
- NO direct exchange access
- NO market-data-driven decision making outside strategies
- NO cross-strategy coupling

## Strategy Notes

- See `strategies/AGENTS.md` for shared strategy-folder rules and strategy-specific notes such as `grid_trader` shape and rebuild behavior.

---

## Failure Model

- strategy failures must be isolated
- system must continue running unaffected strategies
- invalid outputs must be rejected, not corrected silently

---

## Local Environment

- before claiming a Python dependency is missing, source the repo-local `.venv`
- prefer running Python, pytest, and helper scripts through the activated `.venv`

## Runtime Trace Inspection

- `grid_trader` does not write reseed events into a separate database table.
- The strategy appends trace lines to `state["debug_log"]` in `strategies/grid_trader.py::_log()`, and `src/trader_mcp/strategy_engine.py::tick_strategy()` persists that state into `data/trader_mcp.sqlite3` via `strategy_instances.state_json`.
- To inspect a running instance's trace from the DB, read `strategy_instances.state_json` for the target strategy id and extract `debug_log`.
- The live file log is `logs/trader_mcp.log`; `src/trader_mcp/logging_utils.py::log_event()` writes the same `grid ...` messages there.

---

## Interface Stability

Changes affecting:
- Hermes control signals
- execution intent format

are breaking and must be coordinated across MCPs.