tradelab 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,59 @@ 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.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
+
+- `backtestPortfolio()` now reports aggregate `metrics.finalEquity` correctly when `collectEqSeries: false`.
+- `PaperEngine` now rejects market orders that have no price reference instead of filling them at zero.
+- `TradingSession` now clears staged brackets when an async entry is rejected or canceled, and staged brackets are matched by order id/client order id instead of a loose string check.
+- MCP `attach_strategy` now evaluates built-in strategies with the normal backtest signal context and auto-places returned order intents from `feed_price`.
+- `research.monteCarlo()` now rejects non-positive iteration counts instead of returning empty bands and `NaN` probability fields.
+- Public live types now include `TradingSessionOptions.confirmLive` and optional dashboard `source.refresh()`.
+
 ## [1.2.0] - 2026-06-26
 
 ### Added

package/README.md

@@ -1,4 +1,17 @@
-# tradelab
+<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>
+
+[![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)
+[![License: MIT](https://img.shields.io/badge/license-MIT-0f172a)](https://github.com/ishsharm0/tradelab/blob/main/LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-0f172a?logo=node.js)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-0f172a?logo=typescript)](https://github.com/ishsharm0/tradelab/blob/main/types/index.d.ts)
+
+</div>
+
+---
 
 A Node.js toolkit for testing, validating, and operating trading strategies.
 
@@ -74,11 +87,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
 
@@ -256,8 +274,12 @@ Add `--dashboard --dashboardPort 4317` to open a local Server-Sent Events dashbo
 
 **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:
@@ -279,9 +301,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,
@@ -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
@@ -3329,10 +3331,11 @@ function backtestPortfolio({
   const allCandles = systems.flatMap((system) => system.candles || []);
   const orderedCandles = [...allCandles].sort((left, right) => left.time - right.time);
   const metricsInterval = interval ?? systems[0]?.interval;
+  const finalState = portfolioState(runners, equity);
   const metrics = buildMetrics({
     closed: trades,
     equityStart: equity,
-    equityFinal: eqSeries.length ? eqSeries[eqSeries.length - 1].equity : equity,
+    equityFinal: eqSeries.length ? eqSeries[eqSeries.length - 1].equity : finalState.markedEquity,
     candles: orderedCandles,
     estBarMs: estimateBarMs(orderedCandles),
     eqSeries,
@@ -3967,13 +3970,17 @@ function monteCarlo({
   if (!Array.isArray(tradePnls) || tradePnls.length === 0) {
     throw new Error("monteCarlo() requires a non-empty tradePnls array");
   }
+  const runCount = Math.floor(Number(iterations));
+  if (!Number.isFinite(runCount) || runCount < 1) {
+    throw new Error("monteCarlo() requires positive iterations");
+  }
   const rng = makeRng(seed);
   const n = tradePnls.length;
   const block = Math.max(1, Math.floor(blockSize));
   const finals = [];
   const drawdowns = [];
   const pathSamples = Array.from({ length: n + 1 }, () => []);
-  for (let it = 0; it < iterations; it += 1) {
+  for (let it = 0; it < runCount; it += 1) {
     const path7 = [equityStart];
     let equity = equityStart;
     let filled = 0;
@@ -4005,7 +4012,7 @@ function monteCarlo({
     p95: percentile2(sorted, 0.95)
   });
   return {
-    iterations,
+    iterations: runCount,
     blockSize: block,
     finalEquity: bands(sortedFinals),
     maxDrawdown: bands(sortedDd),
@@ -4514,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);
@@ -4923,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,
@@ -4940,6 +5033,7 @@ function exportBacktestArtifacts({
   calculatePositionSize,
   candleStats,
   clampFinite,
+  createResearchStore,
   detectFVG,
   ema,
   exportBacktestArtifacts,
@@ -4970,6 +5064,7 @@ function exportBacktestArtifacts({
   research,
   saveCandlesToCache,
   structureState,
+  summarize,
   swingHigh,
   swingLow,
   walkForwardOptimize