tradelab 1.2.1 → 1.3.1

package/docs/live-trading.md

@@ -151,6 +151,136 @@ tradelab paper \
   --once true
 ```
 
+## Multi-Symbol Portfolio Sessions
+
+`TradingSession` accepts a `symbols` array so one session can trade multiple instruments independently against a shared broker.
+
+```js
+import { SessionManager, PaperEngine } from "tradelab/live";
+
+const manager = new SessionManager();
+const session = await manager.create({
+  id: "crypto-portfolio",
+  symbols: ["BTC", "ETH"],
+  interval: "1h",
+  equity: 20_000,
+  riskPct: 1,
+  maxGrossExposurePct: 150, // cap total gross notional at 150% of equity
+  broker: new PaperEngine({ equity: 20_000 }),
+});
+```
+
+Feed bars and place orders per symbol:
+
+```js
+await session.pushBar({ time, open, high, low, close, volume }, "BTC");
+await session.pushBar({ time, open, high, low, close, volume }, "ETH");
+
+await session.placeOrder({ symbol: "BTC", side: "long", riskPct: 1, stop: 29_500, rr: 3 });
+await session.placeOrder({ symbol: "ETH", side: "long", riskPct: 1, stop: 1_900, rr: 2 });
+```
+
+Close a single position without touching the other:
+
+```js
+await session.closePosition("ETH");
+```
+
+Per-symbol accessors:
+
+```js
+session.lastPriceFor("BTC");         // last close fed via pushBar
+session.candleBufferFor("ETH");      // up to 200 candles
+```
+
+`getStatus()` now includes a `symbols` array alongside the primary `symbol`:
+
+```js
+const status = session.getStatus();
+// { id, symbol: "BTC", symbols: ["BTC", "ETH"], positions, openOrders, equity, ... }
+```
+
+Single-symbol usage (`symbol: "AAPL"`) is unchanged. `session.symbol`, `session.lastPrice`, and `session.candleBuffer` all still work as before.
+
+## Exposure Caps
+
+Pass `maxGrossExposurePct` or `maxNetExposurePct` to `SessionManager.create()` (or directly to `TradingSession`) to cap portfolio exposure. Both default to `0` (off).
+
+| Option                | Meaning                                                                     |
+| --------------------- | --------------------------------------------------------------------------- |
+| `maxGrossExposurePct` | Maximum sum of absolute position notional as a percent of equity            |
+| `maxNetExposurePct`   | Maximum absolute net long/short notional imbalance as a percent of equity   |
+
+When a `placeOrder()` call would push exposure past a cap, it throws:
+
+```
+Error: risk rejected: max gross exposure exceeded
+```
+
+The check includes the pending order size, so the cap is evaluated before a fill, not after.
+
+## Trade Attribution
+
+Every `order:submitted` and `order:filled` event now carries a `sizing` block that records how the position was sized:
+
+```js
+session.eventBus.onAny(({ event, payload }) => {
+  if (event === "order:filled") {
+    console.log(payload.sizing);
+    // {
+    //   entry: 100, stop: 98, target: 104, rr: 2,
+    //   riskFraction: 0.01, riskAmount: 100,
+    //   qty: 50, notional: 5000
+    // }
+    if (payload.rationale) console.log(payload.rationale);
+  }
+});
+```
+
+Pass `rationale` to `placeOrder()` to attach a free-text note that propagates to all fill events for that order:
+
+```js
+await session.placeOrder({
+  symbol: "AAPL",
+  side: "long",
+  riskPct: 1,
+  stop: 148,
+  rr: 2,
+  rationale: "EMA cross on hourly, trend continuation",
+});
+```
+
+Bracket legs carry `parentEntryId` (the client order id of the entry) and a `leg` field (`"stop"` or `"target"`), making it straightforward to correlate fills across entry and exit legs.
+
+## Event Notifier
+
+`attachNotifier()` wires a callback and/or a webhook URL to a session's event bus.
+
+```js
+import { attachNotifier } from "tradelab/live";
+
+const unsubscribe = attachNotifier(session, {
+  events: ["order:filled", "risk:halt"],
+  onEvent({ event, payload }) {
+    console.log(event, payload);
+  },
+  webhookUrl: "https://hooks.example.com/tradelab",
+  drawdownPct: 5, // also fires "drawdown:breach" when equity drops 5% from peak
+});
+
+// When done:
+unsubscribe();
+```
+
+`attachNotifier` options:
+
+| Option        | Default                          | Meaning                                                  |
+| ------------- | -------------------------------- | -------------------------------------------------------- |
+| `events`      | `["order:filled","risk:halt"]`   | Events to forward                                        |
+| `onEvent`     | `undefined`                      | Async callback `({ event, payload }) => void`            |
+| `webhookUrl`  | `undefined`                      | HTTP endpoint; receives `POST` with JSON body            |
+| `drawdownPct` | `0`                              | Also fires `drawdown:breach` when equity falls this far  |
+
 ## Run Multiple Systems
 
 Use `LiveOrchestrator` when several systems share one account and broker.

package/docs/mcp.md

@@ -6,7 +6,7 @@
 
 ## Safety
 
-**Paper is the default and always safe.** Every session is paper unless you explicitly request live mode. Live mode requires all three gates simultaneously — if any is missing the call throws and nothing is created:
+**Paper is the default and always safe.** Every session is paper unless you explicitly request live mode. Live mode requires all three gates simultaneously. If any is missing the call throws and nothing is created:
 
 1. Environment variable `TRADELAB_ALLOW_LIVE=true` must be set in the server process.
 2. The `create_session` call must include `confirmLive: true`.
@@ -14,8 +14,8 @@
 
 Every session also enforces:
 
-- `maxDailyLossPct` — if realized day PnL drops below this percentage of starting equity, all new `place_order` calls are rejected for the remainder of the day.
-- `halt_all` — an emergency kill-switch tool that flattens all positions and stops all sessions in the server process.
+- `maxDailyLossPct`: if realized day PnL drops below this percentage of starting equity, all new `place_order` calls are rejected for the remainder of the day.
+- `halt_all`: an emergency kill-switch tool that flattens all positions and stops all sessions in the server process.
 
 Brackets (stop + target) are true OCO: when one leg fills, the sibling is canceled automatically.
 
@@ -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/docs/research.md

@@ -154,4 +154,19 @@ For a strategy you might run live, combine several checks:
 5. Penalize multiple trials with deflated Sharpe or sweep haircut.
 6. Re-run on a later untouched data period before using live credentials.
 
+## Agent Research Loop
+
+`createResearchStore({ dir })` persists a research session so an agent (or you) can iterate across many runs without losing the thread:
+
+```js
+import { createResearchStore } from "tradelab";
+
+const store = createResearchStore({ dir: ".tradelab/research" });
+await store.open("btc-trend", "find a robust BTC trend strategy");
+await store.log("btc-trend", { hypothesis: "ema 20/50", params: { fast: 20, slow: 50 }, metrics, verdict });
+const { entries, summary } = await store.recall("btc-trend");
+```
+
+`recall` returns a synthesized summary naming the best Sharpe so far and how many runs were flagged as likely overfit. Over MCP, the same store backs the `research_open`, `research_log`, `research_recall`, and `research_close` tools, and `run_backtest` auto-logs an overfitting verdict when called with a `researchId`. See [the MCP guide](mcp.md).
+
 <small>[Back to docs](README.md)</small>

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.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/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 };
+}