tradelab 1.2.1 → 1.3.1

package/src/index.js

@@ -27,10 +27,12 @@ export {
   saveCandlesToCache,
 } from "./data/index.js";
 
+export { createResearchStore } from "./research/store.js";
 export { renderHtmlReport, exportHtmlReport } from "./reporting/renderHtmlReport.js";
 export { exportTradesCsv } from "./reporting/exportTradesCsv.js";
 export { exportMetricsJSON } from "./reporting/exportMetricsJson.js";
 export { exportBacktestArtifacts } from "./reporting/exportBacktestArtifacts.js";
+export { summarize } from "./reporting/summarize.js";
 
 export {
   ema,

package/src/live/engine/riskManager.js

@@ -21,6 +21,8 @@ export class RiskManager {
       cooldownAfterLossMs: 0,
       allowedSessions: "AUTO",
       allowedWindows: null,
+      maxGrossExposurePct: 0,
+      maxNetExposurePct: 0,
       ...options,
     };
     this.allowedWindows = parseWindowsCSV(this.options.allowedWindows);
@@ -114,6 +116,8 @@ export class RiskManager {
     positionCount = 0,
     positionValue = 0,
     equity = null,
+    grossExposure = undefined,
+    netExposure = undefined,
   } = {}) {
     const base = this.canTrade({ timeMs });
     if (!base.ok) return base;
@@ -135,6 +139,40 @@ export class RiskManager {
       }
     }
 
+    return this._checkExposureCaps({ grossExposure, netExposure, equity: eq });
+  }
+
+  /**
+   * Check only the portfolio exposure caps (no session/halt/trade-count checks).
+   * Called from placeOrder after the halt check has already run.
+   */
+  checkExposure({ grossExposure = undefined, netExposure = undefined, equity = null } = {}) {
+    const eq = Number.isFinite(equity) ? equity : this.currentEquity;
+    return this._checkExposureCaps({ grossExposure, netExposure, equity: eq });
+  }
+
+  /**
+   * Shared gross/net exposure cap logic used by canOpenPosition and checkExposure.
+   * Expects a resolved equity value (NaN/null fallback already applied by caller).
+   * Returns { ok: true, reason: null } when within caps or caps are disabled.
+   */
+  _checkExposureCaps({ grossExposure = undefined, netExposure = undefined, equity } = {}) {
+    const eq = equity;
+
+    const grossCap = pctToFraction(this.options.maxGrossExposurePct, 0);
+    if (grossCap > 0 && Number.isFinite(eq) && eq > 0 && Number.isFinite(grossExposure)) {
+      if (Math.abs(grossExposure) / eq > grossCap) {
+        return { ok: false, reason: "max gross exposure exceeded" };
+      }
+    }
+
+    const netCap = pctToFraction(this.options.maxNetExposurePct, 0);
+    if (netCap > 0 && Number.isFinite(eq) && eq > 0 && Number.isFinite(netExposure)) {
+      if (Math.abs(netExposure) / eq > netCap) {
+        return { ok: false, reason: "max net exposure exceeded" };
+      }
+    }
+
     return { ok: true, reason: null };
   }
 

package/src/live/index.js

@@ -28,3 +28,4 @@ export { LiveOrchestrator, createLiveOrchestrator } from "./orchestrator.js";
 export { createDashboardServer } from "./dashboard/server.js";
 
 export { TradingSession, SessionManager, createSessionManager } from "./session.js";
+export { attachNotifier } from "./notify.js";

package/src/live/notify.js

@@ -0,0 +1,42 @@
+// src/live/notify.js
+const DEFAULT_EVENTS = ["order:filled", "risk:halt"];
+
+/**
+ * Subscribe a notifier to a trading session's event bus. Returns an unsubscribe
+ * function. Fires onEvent and/or POSTs to webhookUrl for the configured events,
+ * plus a drawdown breach on equity updates.
+ */
+export function attachNotifier(session, { onEvent, webhookUrl, events = DEFAULT_EVENTS, drawdownPct = 0 } = {}) {
+  const wanted = new Set(events);
+  let peak = null;
+
+  const deliver = async (event, payload) => {
+    if (typeof onEvent === "function") {
+      try { await onEvent({ event, payload }); } catch { /* non-fatal */ }
+    }
+    if (webhookUrl && typeof fetch === "function") {
+      try {
+        await fetch(webhookUrl, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ event, payload }),
+        });
+      } catch { /* non-fatal */ }
+    }
+  };
+
+  const handler = ({ event, payload }) => {
+    if (wanted.has(event)) { deliver(event, payload).catch(() => {}); return; }
+    if (drawdownPct > 0 && event === "equity:update") {
+      const eq = payload?.equity;
+      if (Number.isFinite(eq)) {
+        if (peak === null || eq > peak) peak = eq;
+        if (peak > 0 && ((peak - eq) / peak) * 100 >= drawdownPct) {
+          deliver("drawdown:breach", { equity: eq, peak, drawdownPct: ((peak - eq) / peak) * 100 }).catch(() => {});
+        }
+      }
+    }
+  };
+
+  return session.eventBus.onAny(handler);
+}

package/src/live/session.js

@@ -29,6 +29,7 @@ export class TradingSession {
   constructor({
     id,
     symbol,
+    symbols,
     interval = "1m",
     broker,
     mode = "paper",
@@ -36,6 +37,8 @@ export class TradingSession {
     riskPct = 1,
     maxDailyLossPct = 0,
     maxPositionPct = 1,
+    maxGrossExposurePct = 0,
+    maxNetExposurePct = 0,
     qtyStep = 0.001,
     minQty = 0.001,
     maxLeverage = 2,
@@ -48,10 +51,14 @@ export class TradingSession {
       );
     }
     if (!broker) throw new Error("TradingSession requires a broker (PaperEngine by default)");
-    if (!symbol) throw new Error("TradingSession requires a symbol");
 
-    this.id = id || `${symbol}-${interval}`;
-    this.symbol = symbol;
+    const symbolList = Array.isArray(symbols) && symbols.length ? symbols : symbol ? [symbol] : null;
+    if (!symbolList) throw new Error("TradingSession requires a symbol or symbols");
+
+    this.symbols = symbolList;
+    this.symbol = symbolList[0]; // back-compat primary symbol
+
+    this.id = id || `${this.symbol}-${interval}`;
     this.interval = interval;
     this.broker = broker;
     this.mode = mode;
@@ -63,20 +70,50 @@ export class TradingSession {
     this.minQty = minQty;
     this.maxLeverage = maxLeverage;
     this.eventBus = eventBus || new EventBus();
-    this.riskManager = new RiskManager({ maxDailyLossPct, maxDrawdownPct: 0 });
-    this.lastPrice = null;
+    this.riskManager = new RiskManager({ maxDailyLossPct, maxDrawdownPct: 0, maxGrossExposurePct, maxNetExposurePct });
     this.running = false;
     this.events = [];
     this.brackets = new Map(); // symbol -> { stopId, targetId }
-    this._pendingBracket = null;
+    this._pendingBrackets = new Map(); // symbol -> staged bracket
+    this._entryMeta = new Map(); // clientOrderId -> { sizing, rationale }
+    this._legMeta = new Map();   // clientOrderId -> { parentEntryId, leg }
     this._cachedPositions = [];
     this._cachedOpenOrders = [];
-    this.candleBuffer = [];
-    this._strategy = null;
+    this._lastPrice = new Map();      // symbol -> price
+    this._candleBuffers = new Map();  // symbol -> bar[]
+    this._strategies = new Map();     // symbol -> signalFn
+    for (const sym of this.symbols) this._candleBuffers.set(sym, []);
+
+    this._wasHalted = false;
+    this._coidSeq = 0;
 
     this._wireBrokerEvents();
   }
 
+  // Back-compat getters/setters for single-symbol usage and MCP feed_price handler
+  get lastPrice() { return this._lastPrice.get(this.symbol) ?? null; }
+  set lastPrice(v) { this._lastPrice.set(this.symbol, v); }
+  get candleBuffer() { return this._candleBuffers.get(this.symbol) ?? []; }
+  set candleBuffer(v) { this._candleBuffers.set(this.symbol, v); }
+  get _strategy() { return this._strategies.get(this.symbol) ?? null; }
+  set _strategy(fn) { this._strategies.set(this.symbol, fn); }
+  // Back-compat for tests that read/write _pendingBracket directly (primary symbol only)
+  get _pendingBracket() { return this._pendingBrackets.get(this.symbol) ?? null; }
+  set _pendingBracket(v) {
+    if (v == null) this._pendingBrackets.delete(this.symbol);
+    else this._pendingBrackets.set(this.symbol, v);
+  }
+
+  // Per-symbol accessors
+  lastPriceFor(sym = this.symbol) { return this._lastPrice.get(sym) ?? null; }
+  candleBufferFor(sym = this.symbol) { return this._candleBuffers.get(sym) ?? []; }
+
+  _resolveSymbol(symbol) {
+    if (symbol) return symbol;
+    if (this.symbols.length === 1) return this.symbol;
+    throw new Error("symbol is required for a multi-symbol session");
+  }
+
   static liveAllowed() {
     return process.env.TRADELAB_ALLOW_LIVE === "true";
   }
@@ -91,7 +128,7 @@ export class TradingSession {
   _wireBrokerEvents() {
     // 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:submitted", (order) => this._record("order:submitted", this._withMeta(order)));
     this.broker.on?.("order:canceled", (order) =>
       this._onBrokerTerminalOrderSync("order:canceled", order)
     );
@@ -103,37 +140,58 @@ export class TradingSession {
 
   _onBrokerTerminalOrderSync(event, order) {
     this._record(event, order);
-    if (matchesOrderRef(this._pendingBracket, order)) {
-      this._pendingBracket = null;
+    // Scan all pending brackets to clear any that match this terminal order
+    for (const [sym, staged] of this._pendingBrackets) {
+      if (matchesOrderRef(staged, order)) {
+        this._pendingBrackets.delete(sym);
+        break;
+      }
     }
   }
 
-  // Sync event handler — fire-and-forget async OCO work via a stored promise
+  _withMeta(order) {
+    const key = order.clientOrderId;
+    if (key && this._entryMeta?.has(key)) {
+      const m = this._entryMeta.get(key);
+      return { ...order, sizing: m.sizing, ...(m.rationale ? { rationale: m.rationale } : {}) };
+    }
+    if (key && this._legMeta?.has(key)) {
+      return { ...order, ...this._legMeta.get(key) };
+    }
+    return order;
+  }
+
+  // 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 (matchesOrderRef(this._pendingBracket, order)) {
-      const staged = this._pendingBracket;
-      this._pendingBracket = null;
-      // simulateBar may still be iterating orders, so schedule attach without awaiting.
-      this._pendingCancelPromise = Promise.resolve(
-        this._attachBracket({ ...staged, receipt: order })
-      );
-      return;
+    this._record("order:filled", this._withMeta(order));
+
+    // 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)) {
+        this._pendingBrackets.delete(sym);
+        const parentEntryId = staged.parentEntryId ?? order.clientOrderId;
+        // simulateBar may still be iterating orders, so schedule attach without awaiting.
+        this._pendingCancelPromise = Promise.resolve(
+          this._attachBracket({ ...staged, symbol: sym, receipt: order, parentEntryId })
+        );
+        return;
+      }
     }
 
-    // Track bracket leg fills for OCO
-    const bracket = this.brackets.get(this.symbol);
-    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.
-      // We keep a pending cancel promise that refresh() awaits.
-      this._pendingCancelPromise = (async () => {
-        if (siblingId) await this.broker.cancelOrder(siblingId).catch(() => {});
-        this.brackets.delete(this.symbol);
-        this._record("position:closed", { reason: order.orderId === bracket.stopId ? "SL" : "TP" });
-      })();
+    // 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.
+        // We keep a pending cancel promise that refresh() awaits.
+        this._pendingCancelPromise = (async () => {
+          if (siblingId) await this.broker.cancelOrder(siblingId).catch(() => {});
+          this.brackets.delete(sym);
+          this._record("position:closed", { symbol: sym, reason: order.orderId === bracket.stopId ? "SL" : "TP" });
+        })();
+        return;
+      }
     }
   }
 
@@ -155,19 +213,22 @@ export class TradingSession {
     this._record("shutdown", {});
   }
 
-  async pushBar(b) {
-    this.lastPrice = b.close;
+  async pushBar(b, symbol) {
+    const sym = this._resolveSymbol(symbol);
+    this._lastPrice.set(sym, b.close);
     if (typeof this.broker.simulateBar === "function") {
-      await this.broker.simulateBar(this.symbol, this.interval, b);
+      await this.broker.simulateBar(sym, this.interval, b);
     }
     // Wait for any pending OCO cancel triggered by simulateBar fills
     if (this._pendingCancelPromise) {
       await this._pendingCancelPromise;
       this._pendingCancelPromise = null;
     }
-    this.candleBuffer.push(b);
-    if (this.candleBuffer.length > 200) this.candleBuffer.shift();
-    this._record("bar", { close: b.close, time: b.time });
+    const buf = this._candleBuffers.get(sym) ?? [];
+    buf.push(b);
+    if (buf.length > 200) buf.shift();
+    this._candleBuffers.set(sym, buf);
+    this._record("bar", { symbol: sym, close: b.close, time: b.time });
     await this._syncEquityAndRisk();
     await this.refresh();
   }
@@ -177,15 +238,16 @@ export class TradingSession {
     return Boolean(state.halted);
   }
 
-  async placeOrder({ side, type = "market", qty, riskPct, stop, target, rr, limitPrice } = {}) {
+  async placeOrder({ side, type = "market", qty, riskPct, stop, target, rr, limitPrice, rationale, symbol } = {}) {
     if (!this.running) throw new Error("session not started");
     if (this._riskHalted()) throw new Error("session is risk-halted for the day");
-    const entryRef = type === "limit" ? limitPrice : this.lastPrice;
+    const sym = this._resolveSymbol(symbol);
+    const entryRef = type === "limit" ? limitPrice : this.lastPriceFor(sym);
     if (!Number.isFinite(entryRef)) throw new Error("no price available; pushBar() a price first");
 
+    const fraction = Number.isFinite(riskPct) ? riskPct / 100 : this.riskPct / 100;
     let size = qty;
     if (!Number.isFinite(size)) {
-      const fraction = Number.isFinite(riskPct) ? riskPct / 100 : this.riskPct / 100;
       if (!Number.isFinite(stop)) throw new Error("risk-based sizing requires a stop");
       size = calculatePositionSize({
         equity: this.equity,
@@ -200,9 +262,47 @@ 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 targetPx = Number.isFinite(target)
+      ? target
+      : Number.isFinite(rr) && Number.isFinite(stop)
+        ? (side === "long" || side === "buy"
+            ? entryRef + rr * Math.abs(entryRef - stop)
+            : entryRef - rr * Math.abs(entryRef - stop))
+        : null;
+    const sizing = {
+      entry: entryRef,
+      stop: Number.isFinite(stop) ? stop : null,
+      target: targetPx,
+      rr: Number.isFinite(rr) ? rr : null,
+      riskFraction: fraction,
+      riskAmount: this.equity * fraction,
+      qty: size,
+      notional: size * entryRef,
+    };
+
+    const positions = this._cachedPositions ?? [];
+    const newNotional = sizing.notional * ((side === "long" || side === "buy") ? 1 : -1);
+    let gross = Math.abs(sizing.notional);
+    let net = newNotional;
+    for (const p of positions) {
+      const px = p.avgEntry ?? p.avgPrice ?? p.entryPrice ?? entryRef;
+      const pv = Number.isFinite(p.marketValue) ? p.marketValue : (p.qty ?? 0) * px;
+      const signed = (p.side === "long" || p.side === "buy") ? pv : -pv;
+      gross += Math.abs(pv);
+      net += signed;
+    }
+    const gate = this.riskManager.checkExposure({
+      grossExposure: gross,
+      netExposure: net,
+      equity: this.equity,
+    });
+    if (!gate.ok) throw new Error(`risk rejected: ${gate.reason}`);
+
+    const entryClientOrderId = `${this.id}-entry-${Date.now()}-${++this._coidSeq}`;
+    this._entryMeta.set(entryClientOrderId, { sizing, rationale });
+
     const receipt = await this.broker.submitOrder({
-      symbol: this.symbol,
+      symbol: sym,
       side: toBrokerSide(side),
       type,
       qty: size,
@@ -210,12 +310,13 @@ 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") {
-        await this._attachBracket({ side, size, stop, target, rr, entryRef, receipt });
+        await this._attachBracket({ side, size, stop, target, rr, entryRef, receipt, parentEntryId, symbol: sym });
       } else if (receipt.status !== "rejected") {
-        this._pendingBracket = {
+        this._pendingBrackets.set(sym, {
           side,
           size,
           stop,
@@ -224,9 +325,10 @@ export class TradingSession {
           entryRef,
           orderId: receipt.orderId,
           clientOrderId: receipt.clientOrderId || entryClientOrderId,
-        };
+          parentEntryId,
+        });
       } else {
-        this._pendingBracket = null;
+        this._pendingBrackets.delete(sym);
       }
     }
 
@@ -234,7 +336,8 @@ export class TradingSession {
     return receipt;
   }
 
-  async _attachBracket({ side, size, stop, target, rr, entryRef, receipt }) {
+  async _attachBracket({ side, size, stop, target, rr, entryRef, receipt, parentEntryId, symbol }) {
+    const sym = symbol ?? this.symbol;
     const entryFill = receipt?.avgFillPrice ?? entryRef;
     const risk = Number.isFinite(stop) ? Math.abs(entryFill - stop) : null;
     const targetPrice = Number.isFinite(target)
@@ -248,28 +351,32 @@ export class TradingSession {
     const bracket = {};
 
     if (Number.isFinite(stop)) {
+      const stopCoid = `${this.id}-stop-${Date.now()}-${++this._coidSeq}`;
+      if (parentEntryId) this._legMeta.set(stopCoid, { parentEntryId, leg: "stop" });
       const stopOrder = await this.broker.submitOrder({
-        symbol: this.symbol,
+        symbol: sym,
         side: exitSide,
         type: "stop",
         qty: size,
         stopPrice: stop,
-        clientOrderId: `${this.id}-stop-${Date.now()}`,
+        clientOrderId: stopCoid,
       });
       bracket.stopId = stopOrder.orderId;
     }
     if (Number.isFinite(targetPrice)) {
+      const tgtCoid = `${this.id}-target-${Date.now()}-${++this._coidSeq}`;
+      if (parentEntryId) this._legMeta.set(tgtCoid, { parentEntryId, leg: "target" });
       const tgtOrder = await this.broker.submitOrder({
-        symbol: this.symbol,
+        symbol: sym,
         side: exitSide,
         type: "limit",
         qty: size,
         limitPrice: targetPrice,
-        clientOrderId: `${this.id}-target-${Date.now()}`,
+        clientOrderId: tgtCoid,
       });
       bracket.targetId = tgtOrder.orderId;
     }
-    this.brackets.set(this.symbol, bracket);
+    this.brackets.set(sym, bracket);
   }
 
   async _syncEquityAndRisk() {
@@ -284,6 +391,12 @@ export class TradingSession {
     } else {
       this.riskManager.update({ timeMs: Date.now(), equity: this.equity });
     }
+    // Emit risk:halt once per halt transition
+    const nowHalted = Boolean(this.riskManager.getState?.().halted);
+    if (nowHalted && !this._wasHalted) {
+      this._record("risk:halt", { reason: this.riskManager.haltReason ?? this.riskManager.getState?.().haltReason ?? "risk halt" });
+    }
+    this._wasHalted = nowHalted;
   }
 
   async closePosition(symbol = this.symbol) {
@@ -342,6 +455,7 @@ export class TradingSession {
     return {
       id: this.id,
       symbol: this.symbol,
+      symbols: this.symbols,
       interval: this.interval,
       mode: this.mode,
       running: this.running,

package/src/mcp/liveTools.js

@@ -10,20 +10,6 @@ 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,
@@ -46,6 +32,7 @@ export const liveTools = {
     handler: async ({
       sessionId,
       symbol,
+      symbols,
       mode = "paper",
       interval = "1m",
       equity = 10_000,
@@ -56,6 +43,7 @@ export const liveTools = {
       const session = await manager.create({
         id: sessionId,
         symbol,
+        symbols,
         mode,
         interval,
         equity,
@@ -86,21 +74,36 @@ export const liveTools = {
   feed_price: {
     description:
       "Feed a price bar (or single price) to a session, advancing paper simulations and triggering fills.",
-    handler: async ({ sessionId, bar, price } = {}) => {
+    handler: async ({ sessionId, bar, price, symbol } = {}) => {
       const session = requireSession(sessionId);
       let b = bar;
       if (!b && Number.isFinite(price)) {
         b = { time: Date.now(), open: price, high: price, low: price, close: price, volume: 0 };
       }
       if (!b) throw new Error("Provide either `bar` (OHLCV) or `price` (number)");
-      await session.pushBar(b);
-
-      // If a strategy is attached and session is flat, evaluate it
-      if (session._strategy && session.getStatus().positions.length === 0) {
+      await session.pushBar(b, symbol);
+
+      // If a strategy is attached for this symbol and the session is flat for it, evaluate it
+      const effectiveSym = symbol ?? session.symbol;
+      const strategyFn = session._strategies.get(effectiveSym);
+      const positions = session.getStatus().positions;
+      const symPositions = positions.filter((p) => !p.symbol || p.symbol === effectiveSym);
+      if (strategyFn && symPositions.length === 0) {
         try {
-          const signal = session._strategy(strategyContext(session));
+          const candles = session.candleBufferFor(effectiveSym);
+          const bar = candles[candles.length - 1] ?? null;
+          const status = session.getStatus();
+          const ctx = {
+            candles,
+            index: candles.length - 1,
+            bar,
+            equity: status.equity,
+            openPosition: positions.find((p) => !p.symbol || p.symbol === effectiveSym) ?? null,
+            pendingOrder: null,
+          };
+          const signal = strategyFn(ctx);
           if (signal && (signal.side || signal.direction || signal.action)) {
-            await session.placeOrder(signalToOrder(signal)).catch(() => {});
+            await session.placeOrder({ ...signalToOrder(signal), symbol: effectiveSym }).catch(() => {});
           }
         } catch {
           // strategy errors are non-fatal
@@ -124,9 +127,10 @@ export const liveTools = {
       target,
       rr,
       limitPrice,
+      symbol,
     } = {}) => {
       const session = requireSession(sessionId);
-      return session.placeOrder({ side, type, qty, riskPct, stop, target, rr, limitPrice });
+      return session.placeOrder({ side, type, qty, riskPct, stop, target, rr, limitPrice, symbol });
     },
   },
 
@@ -183,11 +187,11 @@ export const liveTools = {
   attach_strategy: {
     description:
       "Attach a named built-in strategy to a session. It will auto-evaluate on each feed_price and place orders when flat.",
-    handler: async ({ sessionId, strategy, params = {} } = {}) => {
+    handler: async ({ sessionId, strategy, params = {}, symbol } = {}) => {
       const session = requireSession(sessionId);
       const factory = getStrategy(strategy);
       const signal = factory(params);
-      session._strategy = signal;
+      session._strategies.set(symbol ?? session.symbol, signal);
       return { ok: true, strategy, params };
     },
   },

package/src/mcp/researchSession.js

@@ -0,0 +1,24 @@
+import { createResearchStore } from "../research/store.js";
+
+export function researchTools({ dir } = {}) {
+  const store = createResearchStore(dir ? { dir } : {});
+  return {
+    research_open: {
+      description: "Open or resume a persistent research session for iterating on strategy hypotheses.",
+      handler: async ({ id, goal } = {}) => store.open(id, goal),
+    },
+    research_log: {
+      description: "Append a tested hypothesis (params, metrics, optional overfitting verdict) to a research session.",
+      handler: async ({ id, hypothesis, params, metrics, verdict } = {}) =>
+        store.log(id, { hypothesis, params, metrics, verdict }),
+    },
+    research_recall: {
+      description: "Recall recent research entries plus a synthesized summary (best Sharpe, overfit count).",
+      handler: async ({ id, limit } = {}) => store.recall(id, limit),
+    },
+    research_close: {
+      description: "Mark a research session complete and return its final record.",
+      handler: async ({ id } = {}) => store.close(id),
+    },
+  };
+}

package/src/mcp/schemas.js

@@ -109,7 +109,8 @@ export const schemas = {
   // Live trading tools
   create_session: {
     sessionId: z.string(),
-    symbol: z.string(),
+    symbol: z.string().optional(),
+    symbols: z.array(z.string()).optional(),
     mode: sessionMode,
     interval: z.string().optional(),
     equity: z.number().optional(),
@@ -125,6 +126,7 @@ export const schemas = {
     sessionId: z.string(),
     bar: barShape.optional(),
     price: z.number().optional(),
+    symbol: z.string().optional(),
   },
   place_order: {
     sessionId: z.string(),
@@ -136,6 +138,7 @@ export const schemas = {
     target: z.number().optional(),
     rr: z.number().optional(),
     limitPrice: z.number().optional(),
+    symbol: z.string().optional(),
   },
   close_position: {
     sessionId: z.string(),
@@ -162,6 +165,7 @@ export const schemas = {
     sessionId: z.string(),
     strategy: z.string(),
     params: z.record(z.string(), z.any()).optional(),
+    symbol: z.string().optional(),
   },
   halt_all: {},
 };