tradelab 1.2.1 → 1.3.0

package/docs/mcp.md

@@ -94,41 +94,78 @@ Local checkout example:
 | `fetch_candles`      | Load Yahoo or CSV candles and return first/last bars                  |
 | `run_backtest`       | Run one named strategy and return compact metrics                     |
 | `walk_forward`       | Run a parameter grid through walk-forward validation                  |
-| `analyze_robustness` | Backtest + Monte Carlo + Deflated Sharpe — validate before you trade  |
+| `analyze_robustness` | Backtest + Monte Carlo + Deflated Sharpe; validate before you trade   |
 | `optimize_strategy`  | In-process grid sweep; returns a leaderboard sorted by chosen metric  |
 | `compare_strategies` | Run several named strategies on the same dataset, ranked head-to-head |
 | `candle_stats`       | Sanity-check candle data: count, date range, price range, interval    |
 
+### Research loop tools
+
+| Tool               | Args (required)       | Returns                                              |
+| ------------------ | --------------------- | ---------------------------------------------------- |
+| `research_open`    | `id`, `goal?`         | Record with `id`, `goal`, `entries`, `createdAt`     |
+| `research_log`     | `id`, `hypothesis?`, `params?`, `metrics?`, `verdict?` | Appended entry |
+| `research_recall`  | `id`, `limit?`        | Recent entries plus a synthesized `summary` string   |
+| `research_close`   | `id`                  | Final record with `closedAt` timestamp               |
+
+Research sessions are file-backed in `.tradelab/research/` (one JSON file per `id`). They persist across MCP server restarts so agents can resume a session after a context reset.
+
+`run_backtest` also accepts a `researchId` argument. When provided, it auto-logs the backtest result and a Deflated Sharpe verdict to the session without requiring a separate `research_log` call:
+
+```json
+{
+  "data": { "source": "yahoo", "symbol": "SPY", "interval": "1d", "period": "2y" },
+  "strategy": "ema-cross",
+  "params": { "fast": 10, "slow": 30 },
+  "researchId": "spy-ema-study",
+  "numTrials": 3
+}
+```
+
+The auto-logged verdict contains:
+
+```json
+{
+  "deflatedSharpe": 0.87,
+  "overfit": true,
+  "note": "PSR 87.0%"
+}
+```
+
+`overfit: true` means the Probabilistic Sharpe Ratio fell below the 0.9 threshold given the number of trials.
+
 Tool responses are intentionally compact. They are meant for planning and comparison, not for replacing full HTML/CSV/JSON reports from the CLI.
 
 ### Live trading tools
 
-| Tool              | Args (required)                                          | Returns                              |
-| ----------------- | -------------------------------------------------------- | ------------------------------------ |
-| `create_session`  | `sessionId`, `symbol`                                    | session status snapshot              |
-| `list_sessions`   | —                                                        | array of session statuses            |
-| `session_status`  | `sessionId`                                              | full refresh (positions/orders/risk) |
-| `feed_price`      | `sessionId`, `bar` OR `price`                            | status after fills                   |
-| `place_order`     | `sessionId`, `side`, `type?`, `qty?` OR `riskPct`+`stop` | order receipt                        |
-| `close_position`  | `sessionId`, `symbol?`                                   | order receipt                        |
-| `flatten`         | `sessionId`                                              | `{ ok: true }`                       |
-| `cancel_order`    | `sessionId`, `orderId`                                   | `{ ok: true }`                       |
-| `account`         | `sessionId`                                              | broker account info                  |
-| `positions`       | `sessionId`                                              | open positions                       |
-| `recent_events`   | `sessionId`, `limit?`                                    | event log                            |
-| `attach_strategy` | `sessionId`, `strategy`, `params?`                       | `{ ok: true }`                       |
-| `halt_all`        | —                                                        | `{ ok: true, sessionsHalted: N }`    |
+| Tool              | Args (required)                                               | Returns                              |
+| ----------------- | ------------------------------------------------------------- | ------------------------------------ |
+| `create_session`  | `sessionId`, `symbol` OR `symbols`                            | session status snapshot              |
+| `list_sessions`   | `(none)`                                                      | array of session statuses            |
+| `session_status`  | `sessionId`                                                   | full refresh (positions/orders/risk) |
+| `feed_price`      | `sessionId`, `bar` OR `price`, `symbol?`                      | status after fills                   |
+| `place_order`     | `sessionId`, `side`, `type?`, `qty?` OR `riskPct`+`stop`, `symbol?` | order receipt               |
+| `close_position`  | `sessionId`, `symbol?`                                        | order receipt                        |
+| `flatten`         | `sessionId`                                                   | `{ ok: true }`                       |
+| `cancel_order`    | `sessionId`, `orderId`                                        | `{ ok: true }`                       |
+| `account`         | `sessionId`                                                   | broker account info                  |
+| `positions`       | `sessionId`                                                   | open positions                       |
+| `recent_events`   | `sessionId`, `limit?`                                         | event log                            |
+| `attach_strategy` | `sessionId`, `strategy`, `params?`, `symbol?`                 | `{ ok: true }`                       |
+| `halt_all`        | `(none)`                                                      | `{ ok: true, sessionsHalted: N }`    |
 
 ## Agent trading loop
 
 A typical autonomous paper-trading loop:
 
-1. Call `create_session` with `sessionId`, `symbol`, and `equity` (paper by default).
-2. Call `feed_price` with each new bar as it arrives — fills resting bracket orders automatically.
-3. Call `place_order` with `riskPct` + `stop` to size automatically; add `target` or `rr` for a bracket.
-4. Call `session_status` any time for a snapshot of positions, orders, equity, and risk state.
+1. Call `create_session` with `sessionId`, `symbol` (or `symbols` for a multi-symbol session), and `equity` (paper by default).
+2. Call `feed_price` with each new bar as it arrives, passing `symbol` when tracking more than one instrument. Fills resting bracket orders automatically.
+3. Call `place_order` with `riskPct` + `stop` to size automatically; add `target` or `rr` for a bracket. Pass `symbol` for multi-symbol sessions.
+4. Call `session_status` any time for a snapshot of positions, orders, equity, and risk state. The snapshot includes a `symbols` array.
 5. Call `flatten` or `halt_all` to emergency-close everything.
 
+For multi-symbol sessions you can also pass `maxGrossExposurePct` or `maxNetExposurePct` to `create_session` to cap portfolio-level exposure. Orders that would breach the cap are rejected before they reach the broker.
+
 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
@@ -140,6 +177,38 @@ If you attach a strategy with `attach_strategy`, `feed_price` will auto-evaluate
 5. Inspect trade count, profit factor, drawdown, return, and Sharpe fields.
 6. Call `walk_forward` with a grid to see whether parameters hold up out of sample.
 
+## Agent Research Loop
+
+The research loop tools let an agent track hypothesis iteration across many `run_backtest` calls without losing context:
+
+1. Call `research_open` with an `id` and a plain-text `goal`.
+2. For each parameter set you want to test: call `run_backtest` with `researchId` set to that `id`. The result is auto-logged with a Deflated Sharpe verdict.
+3. Alternatively, call `research_log` directly to record results from external tools or your own computations.
+4. Call `research_recall` at any time to get the last N entries plus a synthesized one-liner: best Sharpe, how many runs flagged as overfit.
+5. Call `research_close` when the study is complete.
+
+```json
+// Step 1: open
+{ "id": "spy-cross-study", "goal": "Find the best EMA pair for SPY daily" }
+
+// Step 2: run with auto-logging
+{
+  "data": { "source": "yahoo", "symbol": "SPY", "interval": "1d", "period": "3y" },
+  "strategy": "ema-cross",
+  "params": { "fast": 10, "slow": 30 },
+  "researchId": "spy-cross-study"
+}
+
+// Step 4: recall
+{ "id": "spy-cross-study", "limit": 10 }
+// returns: { goal, entries: [...], summary: "Best Sharpe so far: 1.42 via {fast:10,slow:30}. 1 of 4 flagged overfit." }
+
+// Step 5: close
+{ "id": "spy-cross-study" }
+```
+
+Research files are stored in `.tradelab/research/` in the directory where the MCP server was launched. They persist across server restarts.
+
 ## Example Calls
 
 Fetch candles:

package/examples/agentResearchLoop.js

@@ -0,0 +1,188 @@
+/**
+ * agentResearchLoop.js: Open a research session, run two backtests, log each
+ * result with an overfit verdict, then recall entries and print the synthesis
+ * plus a plain-English summary via summarize().
+ *
+ * Shows:
+ *   - createResearchStore() with open / log / recall / close
+ *   - Logging a backtest result manually (mirrors what run_backtest does when
+ *     researchId is passed to the MCP tool)
+ *   - research_recall synthesized summary (best Sharpe, overfit count)
+ *   - summarize(metrics) for a one-paragraph plain-English output
+ *
+ *   node examples/agentResearchLoop.js
+ */
+
+import { backtest, ema } from "../src/index.js";
+import { createResearchStore } from "../src/research/store.js";
+import { deflatedSharpe } from "../src/research/index.js";
+import { summarize } from "../src/reporting/summarize.js";
+
+// ---------------------------------------------------------------------------
+// Seeded candle generator; deterministic so the example output is stable.
+// ---------------------------------------------------------------------------
+function makeRng(seed) {
+  let s = seed >>> 0;
+  return () => {
+    s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
+    return s / 0x100000000;
+  };
+}
+
+function syntheticCandles(count = 500) {
+  const rng = makeRng(99999);
+  const candles = [];
+  let price = 100;
+  const base = Date.UTC(2022, 0, 3);
+  for (let i = 0; i < count; i++) {
+    const noise = (rng() - 0.5) * 5;
+    price = Math.max(price + noise + 0.1, 5);
+    const range = Math.abs(noise) + 1;
+    const open = price + (rng() - 0.5) * range * 0.4;
+    const close = price;
+    const high = Math.max(open, close) + rng() * range;
+    const low = Math.min(open, close) - rng() * range;
+    candles.push({ time: base + i * 86_400_000, open, high, low, close, volume: 10_000 });
+  }
+  return candles;
+}
+
+// ---------------------------------------------------------------------------
+// Simple bidirectional EMA-cross signal.
+// ---------------------------------------------------------------------------
+function makeEmaSignal({ fast = 10, slow = 30, rr = 2 } = {}) {
+  return ({ candles: history, bar }) => {
+    if (history.length < slow + 2) return null;
+    const closes = history.map((c) => c.close);
+    const f = ema(closes, fast);
+    const s = ema(closes, slow);
+    const last = closes.length - 1;
+    if (f[last - 1] <= s[last - 1] && f[last] > s[last]) {
+      const stop = Math.min(...history.slice(-15).map((c) => c.low));
+      if (stop >= bar.close) return null;
+      return { side: "long", entry: bar.close, stop, rr };
+    }
+    if (f[last - 1] >= s[last - 1] && f[last] < s[last]) {
+      const stop = Math.max(...history.slice(-15).map((c) => c.high));
+      if (stop <= bar.close) return null;
+      return { side: "short", entry: bar.close, stop, rr };
+    }
+    return null;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helper: run a backtest, compute a DSR overfit verdict, log to the store.
+// This mirrors what the MCP run_backtest tool does when researchId is passed.
+// ---------------------------------------------------------------------------
+async function runAndLog(store, researchId, { label, params, candles, symbol }) {
+  const signal = makeEmaSignal(params);
+  const result = backtest({ candles, symbol, interval: "1d", signal, collectReplay: false });
+  const m = result.metrics;
+
+  let verdict = null;
+  try {
+    const psr = deflatedSharpe({
+      sharpe: m.sharpe,
+      sampleSize: m.trades,
+      numTrials: 2, // two parameter sets tried in this session
+    });
+    verdict = {
+      deflatedSharpe: psr,
+      overfit: Number.isFinite(psr) ? psr < 0.9 : false,
+      note: Number.isFinite(psr) ? `PSR ${(psr * 100).toFixed(1)}%` : "insufficient data",
+    };
+  } catch {
+    verdict = { deflatedSharpe: null, overfit: false, note: "verdict unavailable" };
+  }
+
+  await store.log(researchId, {
+    hypothesis: label,
+    params,
+    metrics: {
+      trades: m.trades,
+      winRate: m.winRate,
+      profitFactor: m.profitFactor,
+      sharpe: m.sharpe,
+      maxDrawdown: m.maxDrawdown,
+      returnPct: m.returnPct,
+    },
+    verdict,
+  });
+
+  return { metrics: m, verdict };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+  const candles = syntheticCandles(500);
+  // Use a unique subdirectory so repeated runs start fresh.
+  const store = createResearchStore({ dir: ".tradelab/research-example" });
+  const researchId = "ema-cross-study";
+
+  // 1. Open (or resume) a named research session.
+  const session = await store.open(researchId, "Compare fast vs slow EMA-cross on synthetic data");
+  console.log("Research session:", session.id);
+  console.log("Goal:", session.goal);
+  console.log("");
+
+  // 2. First backtest: tighter EMA pair, moderate R:R.
+  const run1 = await runAndLog(store, researchId, {
+    label: "EMA 5/20 rr=2",
+    params: { fast: 5, slow: 20, rr: 2 },
+    candles,
+    symbol: "SYNTHETIC",
+  });
+  console.log("Run 1 (fast=5, slow=20, rr=2):");
+  console.log("  trades:", run1.metrics.trades);
+  console.log("  profitFactor:", run1.metrics.profitFactor?.toFixed(2));
+  console.log("  sharpe:", run1.metrics.sharpe?.toFixed(2));
+  console.log("  verdict:", run1.verdict);
+
+  // 3. Second backtest: wider EMA pair, higher R:R.
+  const run2 = await runAndLog(store, researchId, {
+    label: "EMA 10/30 rr=3",
+    params: { fast: 10, slow: 30, rr: 3 },
+    candles,
+    symbol: "SYNTHETIC",
+  });
+  console.log("\nRun 2 (fast=10, slow=30, rr=3):");
+  console.log("  trades:", run2.metrics.trades);
+  console.log("  profitFactor:", run2.metrics.profitFactor?.toFixed(2));
+  console.log("  sharpe:", run2.metrics.sharpe?.toFixed(2));
+  console.log("  verdict:", run2.verdict);
+
+  // 4. Recall entries: the store returns recent entries plus a plain-text synthesis.
+  const recall = await store.recall(researchId);
+  console.log("\nResearch recall summary:");
+  console.log(" ", recall.summary);
+  console.log("  entries logged:", recall.entries.length);
+
+  // 5. Pick the run with the better profitFactor and produce a human-readable summary.
+  const bestMetrics =
+    (run1.metrics.profitFactor ?? 0) >= (run2.metrics.profitFactor ?? 0)
+      ? run1.metrics
+      : run2.metrics;
+
+  // summarize() expects percent-valued drawdown/return; backtest returns fractions.
+  const normalized = {
+    trades: bestMetrics.trades,
+    winRate: bestMetrics.winRate,
+    totalReturnPct: (bestMetrics.returnPct ?? 0) * 100,
+    maxDrawdownPct: (bestMetrics.maxDrawdown ?? 0) * 100,
+    sharpe: bestMetrics.sharpe,
+  };
+  console.log("\nBest run plain-English summary:");
+  console.log(" ", summarize(normalized));
+
+  // 6. Close the research session.
+  const closed = await store.close(researchId);
+  console.log("\nResearch session closed:", closed.closedAt);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/multiSymbolPortfolio.js

@@ -0,0 +1,122 @@
+/**
+ * multiSymbolPortfolio.js: Paper session trading two symbols with independent
+ * bracket orders and a portfolio exposure cap.
+ *
+ * Shows:
+ *   - SessionManager.create() with a symbols array
+ *   - Per-symbol pushBar() and placeOrder()
+ *   - maxGrossExposurePct exposure cap blocking over-sized orders
+ *   - getStatus() reporting positions, equity, and the symbols list
+ *
+ *   node examples/multiSymbolPortfolio.js
+ */
+
+import { SessionManager, PaperEngine } from "../src/live/index.js";
+
+function bar(time, price, { high = price, low = price } = {}) {
+  return { time, open: price, high, low, close: price, volume: 1000 };
+}
+
+async function main() {
+  // 1. One shared broker for two symbols.
+  const broker = new PaperEngine({ equity: 20_000 });
+
+  const manager = new SessionManager();
+  const session = await manager.create({
+    id: "btc-eth-portfolio",
+    symbols: ["BTC", "ETH"],
+    interval: "1h",
+    equity: 20_000,
+    riskPct: 1,
+    // Cap total gross notional to 150% of equity.
+    // A second order that would push exposure past that limit is rejected.
+    maxGrossExposurePct: 150,
+    broker,
+  });
+
+  console.log("Session started:", session.id);
+  console.log("Tracked symbols:", session.symbols);
+
+  // 2. Feed opening bars for each symbol.
+  await session.pushBar(bar(1, 30_000), "BTC");
+  await session.pushBar(bar(1, 2_000), "ETH");
+
+  // 3. Place a risk-sized long bracket on BTC.
+  //    1% of $20k = $200 risk, $500/BTC stop distance -> 0.4 BTC.
+  const btcReceipt = await session.placeOrder({
+    symbol: "BTC",
+    side: "long",
+    riskPct: 1,
+    stop: 29_500,
+    rr: 3,
+  });
+  console.log(
+    "\nBTC entry filled:",
+    btcReceipt.status,
+    "qty:", btcReceipt.filledQty,
+    "@", btcReceipt.avgFillPrice
+  );
+
+  // 4. Place a risk-sized long bracket on ETH.
+  //    1% of $20k = $200 risk, $100/ETH stop distance -> 2 ETH.
+  const ethReceipt = await session.placeOrder({
+    symbol: "ETH",
+    side: "long",
+    riskPct: 1,
+    stop: 1_900,
+    rr: 2,
+  });
+  console.log(
+    "ETH entry filled:",
+    ethReceipt.status,
+    "qty:", ethReceipt.filledQty,
+    "@", ethReceipt.avgFillPrice
+  );
+
+  let status = session.getStatus();
+  console.log("\nAfter both entries:");
+  console.log("  positions:", status.positions.length, "(BTC + ETH)");
+  console.log("  open orders:", status.openOrders.length, "(4 bracket legs)");
+  console.log("  equity:", status.equity.toFixed(2));
+  console.log("  symbols:", status.symbols);
+
+  // 5. Demonstrate the exposure cap: trying to open a large third position is rejected.
+  try {
+    await session.placeOrder({
+      symbol: "BTC",
+      side: "long",
+      qty: 1,            // large fixed size that would exceed the 150% cap
+      stop: 28_000,
+    });
+    console.log("\nLarge order unexpectedly succeeded.");
+  } catch (err) {
+    console.log("\nExposure cap enforced:", err.message);
+  }
+
+  // 6. Simulate BTC hitting its target (high = 31_500).
+  await session.pushBar(bar(2, 31_500, { high: 31_500 }), "BTC");
+  await session.pushBar(bar(2, 2_000), "ETH");
+
+  // 7. Close the remaining ETH position manually.
+  await session.closePosition("ETH");
+
+  status = session.getStatus();
+  console.log("\nAfter BTC target + ETH close:");
+  console.log("  positions:", status.positions.length, "(should be 0)");
+  console.log("  open orders:", status.openOrders.length, "(should be 0)");
+  console.log("  final equity:", status.equity.toFixed(2));
+  console.log("  dayPnl:", status.dayPnl.toFixed(2));
+  console.log("  risk.halted:", status.risk.halted);
+
+  // 8. Per-symbol price and candle buffer accessors.
+  console.log("\nlastPriceFor BTC:", session.lastPriceFor("BTC"));
+  console.log("candleBufferFor ETH length:", session.candleBufferFor("ETH").length);
+
+  await session.stop();
+  console.log("\nDone.");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

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

package/src/cli/runPreset.js

@@ -0,0 +1,42 @@
+// src/cli/runPreset.js
+import { getStrategy, listStrategies } from "../strategies/index.js";
+import { backtest } from "../engine/backtest.js";
+import { summarize } from "../reporting/summarize.js";
+
+/**
+ * Run a named built-in strategy over provided candles and return metrics + summary.
+ *
+ * @param {{ preset: string, candles: object[], params?: object, symbol?: string, interval?: string }} options
+ * @returns {{ metrics: object, summary: string }}
+ */
+export function runPreset({ preset, candles, params = {}, symbol = "PRESET", interval = "1d" } = {}) {
+  let factory;
+  try {
+    factory = getStrategy(preset);
+  } catch {
+    factory = null;
+  }
+
+  if (!factory) {
+    const names = listStrategies()
+      .map((s) => s.name)
+      .join(", ");
+    throw new Error(`unknown preset "${preset}". Available: ${names}`);
+  }
+
+  const signal = factory(params);
+  const result = backtest({ candles, symbol, interval, signal, warmupBars: 0 });
+  const m = result.metrics;
+
+  // Normalize units: backtest metrics use fractions; summarize() expects percent-valued fields.
+  const normalized = {
+    trades: m.trades,
+    winRate: m.winRate,
+    totalReturnPct: m.returnPct * 100,
+    maxDrawdownPct: m.maxDrawdown * 100,
+    sharpe: m.sharpe,
+  };
+
+  const summary = summarize(normalized);
+  return { metrics: result.metrics, summary };
+}

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);
+}