tradelab 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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.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.
 

package/dist/cjs/index.cjs

@@ -3329,10 +3329,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 +3968,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 +4010,7 @@ function monteCarlo({
     p95: percentile2(sorted, 0.95)
   });
   return {
-    iterations,
+    iterations: runCount,
     blockSize: block,
     finalEquity: bands(sortedFinals),
     maxDrawdown: bands(sortedDd),

package/dist/cjs/live.cjs

@@ -2301,15 +2301,20 @@ var PaperEngine = class extends BrokerAdapter {
   _recordOrder(order) {
     this.orderHistory.set(order.orderId, { ...order });
   }
+  _rejectOrder(order, reason) {
+    order.status = "rejected";
+    order.rejectReason = reason;
+    this._recordOrder(order);
+    this.openOrders.delete(order.orderId);
+    const receipt = cloneOrder(order);
+    this.emit("order:rejected", receipt);
+    return receipt;
+  }
   _fillOrder(order, fillPrice, kind = "market", fillTime = Date.now()) {
     const side = normalizeOrderSide(order.side);
     const qty = Math.max(0, asNumber(order.qty, 0));
     if (!(qty > 0)) {
-      order.status = "rejected";
-      order.rejectReason = "invalid quantity";
-      this._recordOrder(order);
-      this.emit("order:rejected", cloneOrder(order));
-      return cloneOrder(order);
+      return this._rejectOrder(order, "invalid quantity");
     }
     const sideForFill = side === "buy" ? "long" : "short";
     const filled = applyFill(fillPrice, sideForFill, {
@@ -2417,17 +2422,16 @@ var PaperEngine = class extends BrokerAdapter {
       rejectReason: void 0
     };
     if (!(normalized.qty > 0)) {
-      normalized.status = "rejected";
-      normalized.rejectReason = "invalid quantity";
-      this._recordOrder(normalized);
-      this.emit("order:rejected", cloneOrder(normalized));
-      return cloneOrder(normalized);
+      return this._rejectOrder(normalized, "invalid quantity");
     }
     this._recordOrder(normalized);
     this.emit("order:submitted", cloneOrder(normalized));
     if (normalized.type === "market") {
       const mark = this.lastPrices.get(normalized.symbol);
-      const fillPrice = mark ?? normalized.limitPrice ?? normalized.stopPrice ?? 0;
+      const fillPrice = mark ?? normalized.limitPrice ?? normalized.stopPrice;
+      if (!Number.isFinite(fillPrice)) {
+        return this._rejectOrder(normalized, "no price available for market order");
+      }
       return this._fillOrder(normalized, fillPrice, "market");
     }
     this.openOrders.set(normalized.orderId, normalized);
@@ -3480,6 +3484,14 @@ function oppositeSide2(side) {
 function toBrokerSide(side) {
   return side === "long" || side === "buy" ? "buy" : "sell";
 }
+function matchesOrderRef(reference, order) {
+  if (!reference || !order) return false;
+  if (reference.orderId && order.orderId && reference.orderId === order.orderId) return true;
+  if (reference.clientOrderId && order.clientOrderId && reference.clientOrderId === order.clientOrderId) {
+    return true;
+  }
+  return false;
+}
 var TradingSession = class _TradingSession {
   constructor({
     id,
@@ -3541,13 +3553,26 @@ var TradingSession = class _TradingSession {
   _wireBrokerEvents() {
     this.broker.on?.("order:filled", (order) => this._onBrokerFillSync(order));
     this.broker.on?.("order:submitted", (order) => this._record("order:submitted", order));
-    this.broker.on?.("order:canceled", (order) => this._record("order:canceled", order));
+    this.broker.on?.(
+      "order:canceled",
+      (order) => this._onBrokerTerminalOrderSync("order:canceled", order)
+    );
+    this.broker.on?.(
+      "order:rejected",
+      (order) => this._onBrokerTerminalOrderSync("order:rejected", order)
+    );
     this.broker.on?.("equity:update", (acct) => this._record("equity:update", acct));
   }
+  _onBrokerTerminalOrderSync(event, order) {
+    this._record(event, order);
+    if (matchesOrderRef(this._pendingBracket, order)) {
+      this._pendingBracket = null;
+    }
+  }
   // Sync event handler — fire-and-forget async OCO work via a stored promise
   _onBrokerFillSync(order) {
     this._record("order:filled", order);
-    if (this._pendingBracket && String(order.clientOrderId || "").includes("-entry-")) {
+    if (matchesOrderRef(this._pendingBracket, order)) {
       const staged = this._pendingBracket;
       this._pendingBracket = null;
       this._pendingCancelPromise = Promise.resolve(
@@ -3622,19 +3647,31 @@ var TradingSession = class _TradingSession {
     }
     size = roundStep(size, this.qtyStep);
     if (!(size >= this.minQty)) throw new Error(`sized below minQty (${size})`);
+    const entryClientOrderId = `${this.id}-entry-${Date.now()}`;
     const receipt = await this.broker.submitOrder({
       symbol: this.symbol,
       side: toBrokerSide(side),
       type,
       qty: size,
       limitPrice: type === "limit" ? limitPrice : void 0,
-      clientOrderId: `${this.id}-entry-${Date.now()}`
+      clientOrderId: entryClientOrderId
     });
     if (Number.isFinite(stop) || Number.isFinite(target) || Number.isFinite(rr)) {
       if (receipt.status === "filled") {
         await this._attachBracket({ side, size, stop, target, rr, entryRef, receipt });
+      } else if (receipt.status !== "rejected") {
+        this._pendingBracket = {
+          side,
+          size,
+          stop,
+          target,
+          rr,
+          entryRef,
+          orderId: receipt.orderId,
+          clientOrderId: receipt.clientOrderId || entryClientOrderId
+        };
       } else {
-        this._pendingBracket = { side, size, stop, target, rr, entryRef };
+        this._pendingBracket = null;
       }
     }
     await this.refresh();

package/docs/live-trading.md

@@ -49,7 +49,7 @@ console.log(engine.getStatus());
 await engine.stop();
 ```
 
-`PaperEngine` implements the broker interface in memory. Use it first for CLI runs, dashboard checks, and strategy wiring.
+`PaperEngine` implements the broker interface in memory. Use it first for CLI runs, dashboard checks, and strategy wiring. Market orders need a price reference, so call `pushBar()`, `simulateBar()`, or the MCP `feed_price` tool before submitting one.
 
 ## Signal Contract
 

package/docs/mcp.md

@@ -129,7 +129,7 @@ A typical autonomous paper-trading loop:
 4. Call `session_status` any time for a snapshot of positions, orders, equity, and risk state.
 5. Call `flatten` or `halt_all` to emergency-close everything.
 
-If you attach a strategy with `attach_strategy`, `feed_price` will auto-evaluate it each bar and place orders when the session is flat.
+If you attach a strategy with `attach_strategy`, `feed_price` will auto-evaluate it each bar and place orders when the session is flat. Attached strategies receive the same `{ candles, index, bar, equity, openPosition, pendingOrder }` context as `backtest()`, and returned order intents default to a market order unless `type` is set.
 
 ## Typical Research Flow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tradelab",
-  "version": "1.2.0",
+  "version": "1.2.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/engine/portfolio.js

@@ -309,10 +309,11 @@ export 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,

package/src/live/engine/paperEngine.js

@@ -216,15 +216,21 @@ export class PaperEngine extends BrokerAdapter {
     this.orderHistory.set(order.orderId, { ...order });
   }
 
+  _rejectOrder(order, reason) {
+    order.status = "rejected";
+    order.rejectReason = reason;
+    this._recordOrder(order);
+    this.openOrders.delete(order.orderId);
+    const receipt = cloneOrder(order);
+    this.emit("order:rejected", receipt);
+    return receipt;
+  }
+
   _fillOrder(order, fillPrice, kind = "market", fillTime = Date.now()) {
     const side = normalizeOrderSide(order.side);
     const qty = Math.max(0, asNumber(order.qty, 0));
     if (!(qty > 0)) {
-      order.status = "rejected";
-      order.rejectReason = "invalid quantity";
-      this._recordOrder(order);
-      this.emit("order:rejected", cloneOrder(order));
-      return cloneOrder(order);
+      return this._rejectOrder(order, "invalid quantity");
     }
 
     const sideForFill = side === "buy" ? "long" : "short";
@@ -346,11 +352,7 @@ export class PaperEngine extends BrokerAdapter {
     };
 
     if (!(normalized.qty > 0)) {
-      normalized.status = "rejected";
-      normalized.rejectReason = "invalid quantity";
-      this._recordOrder(normalized);
-      this.emit("order:rejected", cloneOrder(normalized));
-      return cloneOrder(normalized);
+      return this._rejectOrder(normalized, "invalid quantity");
     }
 
     this._recordOrder(normalized);
@@ -358,7 +360,10 @@ export class PaperEngine extends BrokerAdapter {
 
     if (normalized.type === "market") {
       const mark = this.lastPrices.get(normalized.symbol);
-      const fillPrice = mark ?? normalized.limitPrice ?? normalized.stopPrice ?? 0;
+      const fillPrice = mark ?? normalized.limitPrice ?? normalized.stopPrice;
+      if (!Number.isFinite(fillPrice)) {
+        return this._rejectOrder(normalized, "no price available for market order");
+      }
       return this._fillOrder(normalized, fillPrice, "market");
     }
 

package/src/live/session.js

@@ -12,6 +12,19 @@ function toBrokerSide(side) {
   return side === "long" || side === "buy" ? "buy" : "sell";
 }
 
+function matchesOrderRef(reference, order) {
+  if (!reference || !order) return false;
+  if (reference.orderId && order.orderId && reference.orderId === order.orderId) return true;
+  if (
+    reference.clientOrderId &&
+    order.clientOrderId &&
+    reference.clientOrderId === order.clientOrderId
+  ) {
+    return true;
+  }
+  return false;
+}
+
 export class TradingSession {
   constructor({
     id,
@@ -79,16 +92,28 @@ export class TradingSession {
     // Forward broker fills/cancels onto the session bus, and run OCO bracket logic.
     this.broker.on?.("order:filled", (order) => this._onBrokerFillSync(order));
     this.broker.on?.("order:submitted", (order) => this._record("order:submitted", order));
-    this.broker.on?.("order:canceled", (order) => this._record("order:canceled", order));
+    this.broker.on?.("order:canceled", (order) =>
+      this._onBrokerTerminalOrderSync("order:canceled", order)
+    );
+    this.broker.on?.("order:rejected", (order) =>
+      this._onBrokerTerminalOrderSync("order:rejected", order)
+    );
     this.broker.on?.("equity:update", (acct) => this._record("equity:update", acct));
   }
 
+  _onBrokerTerminalOrderSync(event, order) {
+    this._record(event, order);
+    if (matchesOrderRef(this._pendingBracket, order)) {
+      this._pendingBracket = null;
+    }
+  }
+
   // Sync event handler — fire-and-forget async OCO work via a stored promise
   _onBrokerFillSync(order) {
     this._record("order:filled", order);
 
     // Resting entry order (e.g. a limit) just filled — attach its staged bracket.
-    if (this._pendingBracket && String(order.clientOrderId || "").includes("-entry-")) {
+    if (matchesOrderRef(this._pendingBracket, order)) {
       const staged = this._pendingBracket;
       this._pendingBracket = null;
       // simulateBar may still be iterating orders, so schedule attach without awaiting.
@@ -175,21 +200,33 @@ export class TradingSession {
     size = roundStep(size, this.qtyStep);
     if (!(size >= this.minQty)) throw new Error(`sized below minQty (${size})`);
 
+    const entryClientOrderId = `${this.id}-entry-${Date.now()}`;
     const receipt = await this.broker.submitOrder({
       symbol: this.symbol,
       side: toBrokerSide(side),
       type,
       qty: size,
       limitPrice: type === "limit" ? limitPrice : undefined,
-      clientOrderId: `${this.id}-entry-${Date.now()}`,
+      clientOrderId: entryClientOrderId,
     });
 
     // Stage bracket if needed — market orders fill synchronously in PaperEngine
     if (Number.isFinite(stop) || Number.isFinite(target) || Number.isFinite(rr)) {
       if (receipt.status === "filled") {
         await this._attachBracket({ side, size, stop, target, rr, entryRef, receipt });
+      } else if (receipt.status !== "rejected") {
+        this._pendingBracket = {
+          side,
+          size,
+          stop,
+          target,
+          rr,
+          entryRef,
+          orderId: receipt.orderId,
+          clientOrderId: receipt.clientOrderId || entryClientOrderId,
+        };
       } else {
-        this._pendingBracket = { side, size, stop, target, rr, entryRef };
+        this._pendingBracket = null;
       }
     }
 

package/src/mcp/liveTools.js

@@ -10,6 +10,33 @@ function requireSession(sessionId) {
   return s;
 }
 
+function strategyContext(session) {
+  const candles = session.candleBuffer;
+  const bar = candles[candles.length - 1] ?? null;
+  const status = session.getStatus();
+  return {
+    candles,
+    index: candles.length - 1,
+    bar,
+    equity: status.equity,
+    openPosition: status.positions[0] ?? null,
+    pendingOrder: null,
+  };
+}
+
+function signalToOrder(signal) {
+  return {
+    side: signal.side ?? signal.direction ?? signal.action,
+    type: signal.type ?? "market",
+    qty: signal.qty ?? signal.size,
+    riskPct: signal.riskPct,
+    stop: signal.stop ?? signal.stopLoss ?? signal.sl,
+    target: signal.target ?? signal.takeProfit ?? signal.tp,
+    rr: signal.rr ?? signal._rr,
+    limitPrice: signal.limitPrice ?? signal.limit ?? signal.entry ?? signal.price,
+  };
+}
+
 export { manager as sessionManager };
 
 export const liveTools = {
@@ -71,9 +98,9 @@ export const liveTools = {
       // If a strategy is attached and session is flat, evaluate it
       if (session._strategy && session.getStatus().positions.length === 0) {
         try {
-          const signal = session._strategy(session.candleBuffer, session.getStatus());
-          if (signal && signal.side && signal.type) {
-            await session.placeOrder(signal).catch(() => {});
+          const signal = session._strategy(strategyContext(session));
+          if (signal && (signal.side || signal.direction || signal.action)) {
+            await session.placeOrder(signalToOrder(signal)).catch(() => {});
           }
         } catch {
           // strategy errors are non-fatal
@@ -160,11 +187,7 @@ export const liveTools = {
       const session = requireSession(sessionId);
       const factory = getStrategy(strategy);
       const signal = factory(params);
-      // Wrap: accept (candleBuffer, status) and call signal with the buffer
-      session._strategy = (candleBuffer) => {
-        if (!candleBuffer || candleBuffer.length === 0) return null;
-        return signal(candleBuffer[candleBuffer.length - 1], candleBuffer);
-      };
+      session._strategy = signal;
       return { ok: true, strategy, params };
     },
   },

package/src/research/monteCarlo.js

@@ -35,6 +35,10 @@ export 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));
@@ -43,7 +47,7 @@ export function monteCarlo({
   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 path = [equityStart];
     let equity = equityStart;
     let filled = 0;
@@ -78,7 +82,7 @@ export function monteCarlo({
   });
 
   return {
-    iterations,
+    iterations: runCount,
     blockSize: block,
     finalEquity: bands(sortedFinals),
     maxDrawdown: bands(sortedDd),

package/types/live.d.ts

@@ -341,7 +341,8 @@ export interface DashboardServer {
 export function createDashboardServer(options: {
   source: {
     eventBus: EventBus;
-    getStatus?: () => Record<string, unknown>;
+    getStatus?: () => unknown;
+    refresh?: () => Promise<unknown>;
   };
   port?: number;
   maxBuffer?: number;
@@ -414,6 +415,7 @@ export interface TradingSessionOptions {
   minQty?: number;
   maxLeverage?: number;
   eventBus?: EventBus;
+  confirmLive?: boolean;
 }
 
 export interface SessionPlaceOrderOptions {