tradelab 1.2.1 → 1.3.1

package/CHANGELOG.md

@@ -5,6 +5,54 @@ 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
+
+- **Multi-symbol portfolio sessions**
+  - `SessionManager.create({ symbols: ["BTC", "ETH"] })` creates a single session that tracks multiple instruments against a shared broker.
+  - `pushBar(bar, symbol)` and `placeOrder({ symbol })` target a specific instrument; bracket OCO is managed per-symbol.
+  - `closePosition(symbol)` cancels the resting bracket for that symbol before submitting the flattening order.
+  - Per-symbol read accessors: `lastPriceFor(sym)` and `candleBufferFor(sym)`.
+  - `getStatus()` now includes a `symbols` array alongside the primary `symbol`. Single-symbol usage (`symbol: "AAPL"`) is unchanged.
+
+- **Portfolio exposure caps**
+  - `maxGrossExposurePct` and `maxNetExposurePct` options on `TradingSession` and `SessionManager.create()`. Both default to `0` (disabled).
+  - Enforced in `placeOrder()` before any broker call; throws `risk rejected: <reason>` when the cap is breached.
+  - The `RiskManager.checkExposure()` method is the shared gate used by both `canOpenPosition()` and `placeOrder()`.
+
+- **Trade attribution on order events**
+  - `order:submitted` and `order:filled` events now include a `sizing` block: `{ entry, stop, target, rr, riskFraction, riskAmount, qty, notional }`.
+  - Pass `rationale` to `placeOrder()` to attach a free-text note that propagates to all fill events for that order.
+  - Bracket legs carry `parentEntryId` (the entry's client order id) and a `leg` field (`"stop"` or `"target"`).
+
+- **Agent research loop**
+  - `createResearchStore({ dir? })` from `tradelab` returns `{ open, log, recall, close }` for file-backed hypothesis tracking.
+  - MCP tools `research_open`, `research_log`, `research_recall`, `research_close` expose the store over stdio.
+  - `run_backtest` accepts `researchId` and auto-logs the backtest result plus a Deflated Sharpe verdict (`{ deflatedSharpe, overfit, note }`) without a separate `research_log` call.
+
+- **Multi-symbol support in MCP live tools**
+  - `create_session` accepts a `symbols` array.
+  - `feed_price`, `place_order`, `close_position`, and `attach_strategy` accept an optional `symbol` argument to route operations to a specific instrument.
+
+- **`summarize(metrics)`**
+  - Exported from `tradelab`. Renders a `buildMetrics` output object as one plain-English paragraph. Accepts an optional `verdict` object to append an overfit caution sentence.
+
+- **`tradelab run <preset>` CLI subcommand**
+  - Runs a named built-in strategy on Yahoo or CSV data and prints the `summarize()` paragraph to stdout.
+  - Accepts `--params '{"fast":5}'` to override strategy defaults.
+
+- **`attachNotifier(session, opts)`**
+  - Exported from `tradelab/live`. Subscribes a callback and/or webhook URL to a session's event bus.
+  - Options: `events` (which events to forward), `onEvent` (async callback), `webhookUrl` (HTTP POST endpoint), `drawdownPct` (fires `drawdown:breach` when equity falls this far from peak).
+  - Returns an unsubscribe function.
+
 ## [1.2.1] - 2026-06-27
 
 ### Fixed

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
@@ -87,11 +88,16 @@ Start with `result.metrics` for the summary and `result.positions` for completed
 | Run a parallel parameter sweep     | `optimize({ signalModulePath, parameterSets })`                                                                                         |
 | Use indicators                     | `import { rsi, macd, vwap } from "tradelab/ta"`                                                                                         |
 | Check overfitting risk             | `research.monteCarlo`, `research.deflatedSharpe`                                                                                        |
-| Run in paper or live mode          | `LiveEngine`, `LiveOrchestrator`, `tradelab paper`                                                                                      |
-| Watch a live run locally           | `createDashboardServer({ source })` — equity curve, KPI strip, controls                                                                 |
-| Let MCP clients run research tools | `tradelab-mcp` — `run_backtest`, `walk_forward`, `analyze_robustness`, `optimize_strategy`, `compare_strategies`, `candle_stats`        |
-| Let MCP agents trade (paper/live)  | `tradelab-mcp` — `create_session`, `feed_price`, `place_order`, bracket orders, `halt_all` kill-switch (see [docs/mcp.md](docs/mcp.md)) |
-| Export reports and machine data    | `exportBacktestArtifacts`, `exportMetricsJSON`                                                                                          |
+| Run in paper or live mode          | `LiveEngine`, `LiveOrchestrator`, `tradelab paper`                                                                                          |
+| Trade multiple symbols in one session | `SessionManager.create({ symbols: ["BTC","ETH"] })` with per-symbol `pushBar` and `placeOrder`                                         |
+| Watch a live run locally           | `createDashboardServer({ source })` with equity curve, KPI strip, controls                                                                     |
+| Get notified on fills or risk halts | `attachNotifier(session, { onEvent, webhookUrl })` from `tradelab/live`                                                                    |
+| Let MCP clients run research tools | `tradelab-mcp` with `run_backtest`, `walk_forward`, `analyze_robustness`, `optimize_strategy`, `compare_strategies`, `candle_stats`            |
+| Let MCP agents trade (paper/live)  | `tradelab-mcp` with `create_session`, `feed_price`, `place_order`, bracket orders, `halt_all` kill-switch (see [docs/mcp.md](docs/mcp.md))     |
+| Track strategy research across runs | `tradelab-mcp` with `research_open`, `research_log`, `research_recall`, `research_close` (see [docs/mcp.md](docs/mcp.md))                |
+| Summarize metrics in plain English | `summarize(metrics)` returns one plain-English paragraph                                                                                    |
+| Run a built-in preset from the CLI | `tradelab run ema-cross --source yahoo --symbol SPY --period 1y`                                                                            |
+| Export reports and machine data    | `exportBacktestArtifacts`, `exportMetricsJSON`                                                                                              |
 
 ## The Signal Contract
 
@@ -265,12 +271,16 @@ 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`
 
+**Research loop tools:** `research_open`, `research_log`, `research_recall`, `research_close` for persistent file-backed hypothesis tracking. `run_backtest` auto-logs when `researchId` is passed.
+
 **Agent trading tools (paper by default; live gated):** `create_session`, `list_sessions`, `session_status`, `feed_price`, `place_order`, `close_position`, `flatten`, `cancel_order`, `account`, `positions`, `recent_events`, `attach_strategy`, `halt_all`
 
+`create_session` accepts a `symbols` array for multi-symbol portfolio sessions. Pass `symbol` to `feed_price` and `place_order` to direct bars and orders to a specific instrument.
+
 Paper trading needs no credentials. Live trading requires `TRADELAB_ALLOW_LIVE=true` and `confirmLive: true` plus a credentialed broker. `halt_all` is an emergency kill-switch that flattens all positions and stops every session.
 
 Use it from any MCP client that can launch a stdio server:
@@ -292,9 +302,12 @@ Use it from any MCP client that can launch a stdio server:
 tradelab backtest --source yahoo --symbol SPY --interval 1d --period 1y
 tradelab portfolio --csvPaths ./spy.csv,./qqq.csv --symbols SPY,QQQ
 tradelab walk-forward --source yahoo --symbol QQQ --interval 1d --period 2y
+tradelab run ema-cross --source yahoo --symbol SPY --period 1y
 tradelab status --dir ./output/live-state
 ```
 
+`tradelab run <preset>` runs a named built-in strategy on Yahoo or CSV data and prints a plain-English summary. Pass `--params '{"fast":5,"slow":20}'` to override defaults.
+
 ## Documentation
 
 - [Docs home](docs/README.md)

package/bin/tradelab.js

@@ -14,6 +14,7 @@ import {
   saveCandlesToCache,
   walkForwardOptimize,
 } from "../src/index.js";
+import { runPreset } from "../src/cli/runPreset.js";
 import {
   AlpacaBroker,
   BinanceBroker,
@@ -270,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]
 
@@ -278,6 +279,7 @@ Commands:
   backtest      Run a one-off backtest from Yahoo or CSV data
   portfolio     Run multiple CSV datasets as an equal-weight portfolio
   walk-forward  Run rolling or anchored train/test optimization
+  run           Run a named built-in preset and print a plain-English summary
   live          Run live trading engine (streaming or polling)
   paper         Run live engine in paper broker mode
   status        Read persisted live state
@@ -288,6 +290,8 @@ Examples:
   tradelab backtest --source yahoo --symbol SPY --interval 1d --period 1y
   tradelab backtest --source csv --csvPath ./data/btc.csv --strategy buy-hold --holdBars 3
   tradelab walk-forward --source csv --csvPath ./data/spy.csv --trainBars 120 --testBars 40
+  tradelab run ema-cross --source yahoo --symbol SPY --period 1y
+  tradelab run ema-cross --source csv --csvPath ./data/spy.csv --params '{"fast":5,"slow":15}'
   tradelab live --strategy ./mySignal.js --symbol AAPL --interval 5m --broker alpaca --paper
 
 Options:
@@ -473,6 +477,37 @@ async function commandPrefetch(args) {
   console.log(`Saved ${candles.length} candles to ${outputPath}`);
 }
 
+async function commandRun(args) {
+  const preset = args._[1];
+  if (!preset) {
+    throw new Error("run requires a preset name (e.g. tradelab run ema-cross)");
+  }
+  const symbol = args.symbol || "PRESET";
+  const interval = args.interval || "1d";
+  const params = parseJsonValue(args.params, {});
+
+  const source = args.source || (args.csvPath ? "csv" : null);
+  let candles;
+  if (source === "csv" || args.csvPath) {
+    candles = loadCandlesFromCSV(args.csvPath);
+  } else if (source === "yahoo" || args.symbol) {
+    candles = await getHistoricalCandles({
+      source: "yahoo",
+      symbol: args.symbol,
+      interval,
+      period: args.period || "1y",
+      cache: args.cache !== "false",
+    });
+  } else {
+    throw new Error(
+      "run requires candle data: provide --source yahoo --symbol TICKER or --source csv --csvPath PATH"
+    );
+  }
+
+  const out = runPreset({ preset, candles, params, symbol, interval });
+  console.log(out.summary);
+}
+
 async function commandImportCsv(args) {
   const csvPath = args.csvPath || args._[1];
   if (!csvPath) {
@@ -668,6 +703,7 @@ const commands = {
   backtest: commandBacktest,
   portfolio: commandPortfolio,
   "walk-forward": commandWalkForward,
+  run: commandRun,
   live: commandLive,
   paper: commandPaper,
   status: commandStatus,

package/dist/cjs/index.cjs

@@ -45,6 +45,7 @@ __export(index_exports, {
   calculatePositionSize: () => calculatePositionSize,
   candleStats: () => candleStats,
   clampFinite: () => clampFinite,
+  createResearchStore: () => createResearchStore,
   detectFVG: () => detectFVG,
   ema: () => ema,
   exportBacktestArtifacts: () => exportBacktestArtifacts,
@@ -75,6 +76,7 @@ __export(index_exports, {
   research: () => research_exports,
   saveCandlesToCache: () => saveCandlesToCache,
   structureState: () => structureState,
+  summarize: () => summarize,
   swingHigh: () => swingHigh,
   swingLow: () => swingLow,
   walkForwardOptimize: () => walkForwardOptimize
@@ -4519,6 +4521,66 @@ async function backtestHistorical({ backtestOptions = {}, data, ...legacy } = {}
   });
 }
 
+// src/research/store.js
+var import_promises = require("node:fs/promises");
+var import_node_path2 = require("node:path");
+var DEFAULT_DIR = ".tradelab/research";
+function fileFor(dir, id) {
+  if (!/^[\w.-]+$/.test(String(id))) throw new Error(`invalid research id: ${id}`);
+  return (0, import_node_path2.join)(dir, `${id}.json`);
+}
+async function load(dir, id) {
+  try {
+    const raw = await (0, import_promises.readFile)(fileFor(dir, id), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function save(dir, record) {
+  await (0, import_promises.mkdir)(dir, { recursive: true });
+  await (0, import_promises.writeFile)(fileFor(dir, record.id), JSON.stringify(record, null, 2));
+  return record;
+}
+function bestSharpe(entries) {
+  let best = null;
+  for (const e of entries) {
+    const s = e.metrics?.sharpe;
+    if (Number.isFinite(s) && (best === null || s > best.sharpe)) best = { sharpe: s, params: e.params };
+  }
+  return best;
+}
+function createResearchStore({ dir = DEFAULT_DIR } = {}) {
+  return {
+    async open(id, goal = "") {
+      const existing = await load(dir, id);
+      if (existing) return existing;
+      const record = { id, goal, createdAt: (/* @__PURE__ */ new Date()).toISOString(), closedAt: null, entries: [] };
+      return save(dir, record);
+    },
+    async log(id, { hypothesis = "", params = {}, metrics = {}, verdict = null } = {}) {
+      const record = await load(dir, id) || { id, goal: "", createdAt: (/* @__PURE__ */ new Date()).toISOString(), closedAt: null, entries: [] };
+      const entry = { at: (/* @__PURE__ */ new Date()).toISOString(), hypothesis, params, metrics, verdict };
+      record.entries.push(entry);
+      await save(dir, record);
+      return entry;
+    },
+    async recall(id, limit = 10) {
+      const record = await load(dir, id) || { goal: "", entries: [] };
+      const entries = record.entries.slice(-limit);
+      const best = bestSharpe(record.entries);
+      const flagged = record.entries.filter((e) => e.verdict?.overfit).length;
+      const summary = record.entries.length ? `Best Sharpe so far: ${best ? best.sharpe.toFixed(2) : "n/a"}${best ? ` via ${JSON.stringify(best.params)}` : ""}. ${flagged} of ${record.entries.length} flagged overfit.` : "No entries logged yet.";
+      return { goal: record.goal, entries, summary };
+    },
+    async close(id) {
+      const record = await load(dir, id) || { id, goal: "", createdAt: (/* @__PURE__ */ new Date()).toISOString(), entries: [] };
+      record.closedAt = (/* @__PURE__ */ new Date()).toISOString();
+      return save(dir, record);
+    }
+  };
+}
+
 // src/reporting/renderHtmlReport.js
 var import_fs2 = __toESM(require("fs"), 1);
 var import_path3 = __toESM(require("path"), 1);
@@ -4928,6 +4990,32 @@ function exportBacktestArtifacts({
   }
   return outputs;
 }
+
+// src/reporting/summarize.js
+function pct2(value, digits = 1) {
+  return Number.isFinite(value) ? `${value.toFixed(digits)}%` : "n/a";
+}
+function summarize(metrics = {}, { verdict } = {}) {
+  const trades = Number.isFinite(metrics.trades) ? metrics.trades : 0;
+  const win = Number.isFinite(metrics.winRate) ? Math.round(metrics.winRate * 100) : null;
+  const dd = Number.isFinite(metrics.maxDrawdownPct) ? metrics.maxDrawdownPct : Number.isFinite(metrics.maxDrawdown) ? metrics.maxDrawdown * 100 : null;
+  const ret = Number.isFinite(metrics.totalReturnPct) ? metrics.totalReturnPct : null;
+  const sharpe = Number.isFinite(metrics.sharpe) ? metrics.sharpe : null;
+  if (trades === 0) return "Ran with 0 trades, so there is nothing to evaluate yet.";
+  const parts = [`Made ${trades} trades`];
+  if (win !== null) parts.push(`won ${win}% of them`);
+  if (ret !== null) parts.push(`for a ${pct2(ret)} total return`);
+  if (dd !== null) parts.push(`with a worst drawdown of ${pct2(dd)}`);
+  let text = parts.join(", ");
+  if (sharpe !== null) {
+    text += ` (Sharpe ${sharpe.toFixed(2)})`;
+  }
+  text += ".";
+  if (verdict && verdict.overfit) {
+    text += ` Caution: robustness checks flag this result as likely overfit${verdict.note ? ` (${verdict.note})` : ""}.`;
+  }
+  return text;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BIG_NUMBER,
@@ -4945,6 +5033,7 @@ function exportBacktestArtifacts({
   calculatePositionSize,
   candleStats,
   clampFinite,
+  createResearchStore,
   detectFVG,
   ema,
   exportBacktestArtifacts,
@@ -4975,6 +5064,7 @@ function exportBacktestArtifacts({
   research,
   saveCandlesToCache,
   structureState,
+  summarize,
   swingHigh,
   swingLow,
   walkForwardOptimize