tradelab 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.1] - 2026-06-28
+
+### Changed
+
+- Documentation refresh: the README now leads with the agent-native MCP story, and the reference docs cover `summarize`, `createResearchStore` and the agent research loop, `attachNotifier`, multi-symbol sessions, exposure caps, and `tradelab run`.
+
 ## [1.3.0] - 2026-06-27
 
 ### Added

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <img src="https://i.imgur.com/HGvvQbq.png" width="420" alt="tradelab logo" />
 
-  <p><strong>A Node.js backtesting toolkit for serious trading strategy research.</strong></p>
+  <p><strong>An agent-native Node.js trading engine: research, backtest, and trade live through one signal contract.</strong></p>
 
 [![npm version](https://img.shields.io/npm/v/tradelab?color=0f172a&label=npm&logo=npm)](https://www.npmjs.com/package/tradelab)
 [![GitHub](https://img.shields.io/badge/github-ishsharm0/tradelab-0f172a?logo=github)](https://github.com/ishsharm0/tradelab)
@@ -13,17 +13,18 @@
 
 ---
 
-A Node.js toolkit for testing, validating, and operating trading strategies.
+A Node.js toolkit for testing, validating, and operating trading strategies, built so humans and AI agents work from the same primitives.
 
-tradelab gives you one `signal()` contract across research and execution:
+One `signal()` contract runs across research and execution:
 
 - run candle or tick backtests
 - model slippage, commissions, borrow, carry, and funding
 - validate parameters with walk-forward tests and research statistics
 - combine multiple systems into a shared-capital portfolio
-- move the same strategy into paper or live execution
+- move the same strategy into paper or live execution, single or multi-symbol
 - export reports, metrics, and trade ledgers
-- expose research tools through an MCP server
+
+**Agent-native.** The `tradelab-mcp` server exposes 25 tools over stdio, so an AI agent can run the whole loop itself: pull data, run and score backtests, track hypotheses across runs with built-in overfitting guards, then open a paper or live session and place risk-sized bracket orders behind a kill-switch. Agents get the same depth a quant does, not a thin read-only wrapper. See [docs/mcp.md](docs/mcp.md).
 
 ```bash
 npm install tradelab
@@ -270,7 +271,7 @@ Add `--dashboard --dashboardPort 4317` to open a local Server-Sent Events dashbo
 
 ## MCP Server
 
-`tradelab-mcp` exposes research and live-trading tools over stdio to any MCP-capable agent (Claude Desktop, Cursor, etc.). See [docs/mcp.md](docs/mcp.md) for the full tool reference and agent trading guide.
+`tradelab-mcp` exposes 25 tools over stdio to any MCP-capable agent (Claude Desktop, Cursor, and similar). They cover the full loop an agent needs to work a strategy end to end: research it, validate it, track the search, then trade it. See [docs/mcp.md](docs/mcp.md) for the full tool reference and agent trading guide.
 
 **Research tools:** `list_strategies`, `fetch_candles`, `run_backtest`, `walk_forward`, `analyze_robustness`, `optimize_strategy`, `compare_strategies`, `candle_stats`
 

package/bin/tradelab.js

@@ -271,7 +271,7 @@ async function loadWalkForwardStrategy(strategyArg, args) {
 }
 
 function printHelp() {
-  console.log(`tradelab — backtesting toolkit for Node.js
+  console.log(`tradelab: agent-native trading engine for Node.js
 
 Usage: tradelab <command> [options]
 

package/dist/cjs/live.cjs

@@ -3666,7 +3666,7 @@ var TradingSession = class _TradingSession {
     }
     return order;
   }
-  // Sync event handler — fire-and-forget async OCO work via a stored promise
+  // Sync event handler; fire-and-forget async OCO work via a stored promise
   _onBrokerFillSync(order) {
     this._record("order:filled", this._withMeta(order));
     for (const [sym, staged] of this._pendingBrackets) {

package/docs/README.md

@@ -11,8 +11,8 @@ Use this page to choose the right guide. If you are new to tradelab, read the fi
 ## Reference
 
 - [API reference](api-reference.md) - public exports by module.
-- [Research tools](research.md) - Monte Carlo, deflated Sharpe, PBO, and CPCV.
-- [MCP server](mcp.md) - `tradelab-mcp` setup and tool list.
+- [Research tools](research.md) - Monte Carlo, deflated Sharpe, PBO, CPCV, and the agent research loop.
+- [MCP server](mcp.md) - `tradelab-mcp` setup and the 25-tool reference for AI agents.
 - [Strategy examples](examples.md) - complete strategy patterns you can adapt.
 
 ## Common Paths
@@ -26,17 +26,19 @@ Use this page to choose the right guide. If you are new to tradelab, read the fi
 | Test parameter stability          | [Backtesting](backtest-engine.md#walk-forward-validation) |
 | Run a local paper session         | [Live trading](live-trading.md)                           |
 | Connect an MCP client             | [MCP server](mcp.md)                                      |
+| Let an AI agent research and trade | [MCP server](mcp.md)                                     |
 | Check exact function names        | [API reference](api-reference.md)                         |
 
 ## Package Scope
 
-tradelab is built for strategy research and operational dry-runs:
+tradelab is built for strategy research and operational dry-runs, by humans and AI agents alike:
 
 - candle and tick backtests
 - shared-capital portfolio simulation
 - realistic cost assumptions
 - walk-forward validation and overfitting checks
-- paper and live execution through broker adapters
+- single and multi-symbol paper and live execution through broker adapters
+- a 25-tool MCP server so an agent can research, validate, and trade end to end
 - local reports and machine-readable exports
 
 It is not an exchange simulator. It does not try to model full market depth, queue priority, latency, or venue-specific microstructure.

package/docs/api-reference.md

@@ -108,6 +108,7 @@ registerStrategy("my-strategy", {
 | `exportTradesCsv(trades, options)` | Write a trade or position CSV ledger         |
 | `exportMetricsJSON(options)`       | Write machine-readable metrics JSON          |
 | `exportBacktestArtifacts(options)` | Write HTML, CSV, and JSON artifacts together |
+| `summarize(metrics, options)`      | Render metrics into one plain-English paragraph |
 
 ### Research
 
@@ -127,6 +128,8 @@ import { research } from "tradelab";
 | `research.normalPpf(p)`                                      | Standard normal inverse CDF                                |
 | `research.moments(values)`                                   | Mean, standard deviation, skew, kurtosis                   |
 
+For the agent research loop, `createResearchStore({ dir })` returns a file-backed `{ open, log, recall, close }` store for tracking strategy hypotheses, their metrics, and overfitting verdicts across runs. The MCP `research_*` tools wrap it.
+
 ### Indicators And Helpers
 
 | Export                                | Summary                                      |
@@ -184,6 +187,17 @@ import { LiveEngine, PaperEngine, createDashboardServer } from "tradelab/live";
 | `PaperEngine`                     | In-process broker simulator                  |
 | `createPaperEngine(options)`      | Factory for `PaperEngine`                    |
 
+### Sessions And Notifications
+
+| Export                            | Summary                                                     |
+| --------------------------------- | ----------------------------------------------------------- |
+| `TradingSession`                  | One account, one or many symbols, with risk-sized brackets  |
+| `SessionManager`                  | Create and track sessions; gates live mode                  |
+| `createSessionManager(options)`   | Factory for `SessionManager`                                |
+| `attachNotifier(session, options)`| Fire a callback or webhook on fills, risk halts, drawdown   |
+
+`SessionManager.create({ symbols: ["BTC", "ETH"] })` opens a multi-symbol portfolio session; pass a single `symbol` for the original behavior. Per-symbol calls take a `symbol` argument (`pushBar(bar, symbol)`, `placeOrder({ symbol })`). Portfolio-level `RiskManager` options `maxGrossExposurePct` and `maxNetExposurePct` (default 0, off) reject orders that would breach the cap.
+
 ### Broker Adapters
 
 | Export                                                        | Summary                                 |
@@ -287,7 +301,7 @@ import { createServer, startStdioServer } from "tradelab/mcp";
 | `createServer()`     | Build an MCP server with tradelab tools |
 | `startStdioServer()` | Start the MCP server on stdio           |
 
-See [mcp.md](mcp.md) for client configuration and tool payload examples.
+The server exposes 25 tools: 8 research, 4 research-loop (`research_open`, `research_log`, `research_recall`, `research_close`), and 13 live-trading (sessions, orders, brackets, kill-switch). See [mcp.md](mcp.md) for client configuration and tool payload examples.
 
 ## Types
 

package/docs/data-reporting-cli.md

@@ -198,6 +198,15 @@ tradelab walk-forward \
 
 You can pass `--strategy ./strategy.mjs` for local modules that export `signalFactory(params, args)` and either `parameterSets` or `createParameterSets(args)`.
 
+### Run a Preset
+
+```bash
+tradelab run ema-cross --source yahoo --symbol SPY --period 1y
+tradelab run rsi-reversion --source csv --csvPath ./btc.csv --params '{"period":14,"oversold":25}'
+```
+
+`tradelab run <preset>` backtests a named built-in strategy and prints a plain-English summary of the result. Use `--params` to override the preset defaults. Run `tradelab run` with an unknown name to see the available presets.
+
 ### Live and Paper
 
 ```bash

package/docs/mcp.md

@@ -6,7 +6,7 @@
 
 ## Safety
 
-**Paper is the default and always safe.** Every session is paper unless you explicitly request live mode. Live mode requires all three gates simultaneously — if any is missing the call throws and nothing is created:
+**Paper is the default and always safe.** Every session is paper unless you explicitly request live mode. Live mode requires all three gates simultaneously. If any is missing the call throws and nothing is created:
 
 1. Environment variable `TRADELAB_ALLOW_LIVE=true` must be set in the server process.
 2. The `create_session` call must include `confirmLive: true`.
@@ -14,8 +14,8 @@
 
 Every session also enforces:
 
-- `maxDailyLossPct` — if realized day PnL drops below this percentage of starting equity, all new `place_order` calls are rejected for the remainder of the day.
-- `halt_all` — an emergency kill-switch tool that flattens all positions and stops all sessions in the server process.
+- `maxDailyLossPct`: if realized day PnL drops below this percentage of starting equity, all new `place_order` calls are rejected for the remainder of the day.
+- `halt_all`: an emergency kill-switch tool that flattens all positions and stops all sessions in the server process.
 
 Brackets (stop + target) are true OCO: when one leg fills, the sibling is canceled automatically.
 

package/docs/research.md

@@ -154,4 +154,19 @@ For a strategy you might run live, combine several checks:
 5. Penalize multiple trials with deflated Sharpe or sweep haircut.
 6. Re-run on a later untouched data period before using live credentials.
 
+## Agent Research Loop
+
+`createResearchStore({ dir })` persists a research session so an agent (or you) can iterate across many runs without losing the thread:
+
+```js
+import { createResearchStore } from "tradelab";
+
+const store = createResearchStore({ dir: ".tradelab/research" });
+await store.open("btc-trend", "find a robust BTC trend strategy");
+await store.log("btc-trend", { hypothesis: "ema 20/50", params: { fast: 20, slow: 50 }, metrics, verdict });
+const { entries, summary } = await store.recall("btc-trend");
+```
+
+`recall` returns a synthesized summary naming the best Sharpe so far and how many runs were flagged as likely overfit. Over MCP, the same store backs the `research_open`, `research_log`, `research_recall`, and `research_close` tools, and `run_backtest` auto-logs an overfitting verdict when called with a `researchId`. See [the MCP guide](mcp.md).
+
 <small>[Back to docs](README.md)</small>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tradelab",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Backtesting toolkit for Node.js with strategy simulation, historical data loading, and report generation",
   "type": "module",
   "main": "./dist/cjs/index.cjs",

package/src/live/session.js

@@ -161,11 +161,11 @@ export class TradingSession {
     return order;
   }
 
-  // Sync event handler — fire-and-forget async OCO work via a stored promise
+  // Sync event handler; fire-and-forget async OCO work via a stored promise
   _onBrokerFillSync(order) {
     this._record("order:filled", this._withMeta(order));
 
-    // Resting entry order (e.g. a limit) just filled — attach its staged bracket.
+    // Resting entry order (e.g. a limit) just filled; attach its staged bracket.
     // Scan _pendingBrackets for a match (works for both single- and multi-symbol sessions).
     for (const [sym, staged] of this._pendingBrackets) {
       if (matchesOrderRef(staged, order)) {
@@ -179,11 +179,11 @@ export class TradingSession {
       }
     }
 
-    // Track bracket leg fills for OCO — find which symbol this fill belongs to
+    // Track bracket leg fills for OCO; find which symbol this fill belongs to
     for (const [sym, bracket] of this.brackets) {
       if (bracket && (order.orderId === bracket.stopId || order.orderId === bracket.targetId)) {
         const siblingId = order.orderId === bracket.stopId ? bracket.targetId : bracket.stopId;
-        // Schedule the cancel — simulateBar is still iterating orders, so we must not await here.
+        // Schedule the cancel; simulateBar is still iterating orders, so we must not await here.
         // We keep a pending cancel promise that refresh() awaits.
         this._pendingCancelPromise = (async () => {
           if (siblingId) await this.broker.cancelOrder(siblingId).catch(() => {});
@@ -310,7 +310,7 @@ export class TradingSession {
       clientOrderId: entryClientOrderId,
     });
 
-    // Stage bracket if needed — market orders fill synchronously in PaperEngine
+    // Stage bracket if needed; market orders fill synchronously in PaperEngine
     if (Number.isFinite(stop) || Number.isFinite(target) || Number.isFinite(rr)) {
       const parentEntryId = receipt?.clientOrderId ?? entryClientOrderId;
       if (receipt.status === "filled") {

package/src/mcp/tools.js

@@ -193,7 +193,7 @@ export const researchPlusTools = {
           metrics,
           monteCarlo: null,
           deflatedSharpe: null,
-          note: `Only ${tradePnls.length} trade(s) — need at least 2 for statistical analysis.`,
+          note: `Only ${tradePnls.length} trade(s), need at least 2 for statistical analysis.`,
         };
       }
       const mc = monteCarlo({