tradelab 1.1.0 → 1.2.0

package/types/index.d.ts

@@ -132,6 +132,14 @@ export interface SideBreakdownEntry {
   avgR: number;
 }
 
+export interface BenchmarkStats {
+  alpha: number | null;
+  beta: number | null;
+  correlation: number | null;
+  informationRatio: number | null;
+  trackingError: number | null;
+}
+
 /** Aggregate performance metrics returned by `backtest()`. */
 export interface BacktestMetrics {
   /** Count of completed positions included in the aggregate metrics. */
@@ -146,6 +154,12 @@ export interface BacktestMetrics {
   avgR: number;
   /** Daily Sharpe ratio alias for quick access. */
   sharpe: number;
+  /** Annualized Sharpe ratio derived from the configured interval or bar spacing. */
+  sharpeAnnualized: number;
+  /** Annualized Sortino ratio derived from the configured interval or bar spacing. */
+  sortinoAnnualized: number;
+  /** Number of periods per year used for annualized metrics. */
+  annualizationPeriods: number;
   sharpePerTrade: number;
   sortinoPerTrade: number;
   /** Maximum drawdown percent alias. */
@@ -169,6 +183,7 @@ export interface BacktestMetrics {
   /** Daily Sharpe ratio computed from realized equity changes. */
   sharpeDaily: number;
   sortinoDaily: number;
+  benchmark: BenchmarkStats;
   /** Long/short breakdown grouped by completed position side. */
   sideBreakdown: {
     long: SideBreakdownEntry;
@@ -659,6 +674,7 @@ export function optimize(options: {
 export function backtestPortfolio(options: {
   systems: PortfolioSystem[];
   equity?: number;
+  interval?: string;
   allocation?: "equal" | "weight";
   collectEqSeries?: boolean;
   collectReplay?: boolean;
@@ -684,7 +700,16 @@ export function buildMetrics(input: {
   candles: Candle[];
   estBarMs: number;
   eqSeries?: EquityPoint[];
+  interval?: string;
+  benchmarkReturns?: number[];
 }): BacktestMetrics;
+export function benchmarkStats(
+  strategyReturns: number[],
+  benchmarkReturns: number[]
+): BenchmarkStats;
+export function clampFinite(value: unknown, fallback?: number): number;
+export const BIG_NUMBER: number;
+export function periodsPerYear(interval?: string, estBarMs?: number): number;
 
 export class LlmSignal {
   constructor(options: LlmSignalOptions);

package/types/live.d.ts

@@ -84,6 +84,8 @@ export interface StoredState {
   savedAt: number;
 }
 
+export const LIVE_EVENTS: string[];
+
 export class EventBus extends import("node:events").EventEmitter {
   emitEvent(event: string, payload?: Record<string, unknown>): true;
   onAny(handler: (input: { event: string; payload: Record<string, unknown> }) => void): () => void;
@@ -395,3 +397,100 @@ export function createLiveOrchestrator(options: {
 }): LiveOrchestrator;
 
 export type { SignalResult };
+
+// ── TradingSession / SessionManager ──────────────────────────────────────────
+
+export interface TradingSessionOptions {
+  id?: string;
+  symbol: string;
+  interval?: string;
+  broker: BrokerAdapter;
+  mode?: "paper" | "live";
+  equity?: number;
+  riskPct?: number;
+  maxDailyLossPct?: number;
+  maxPositionPct?: number;
+  qtyStep?: number;
+  minQty?: number;
+  maxLeverage?: number;
+  eventBus?: EventBus;
+}
+
+export interface SessionPlaceOrderOptions {
+  side: "long" | "short" | "buy" | "sell";
+  type?: "market" | "limit" | "stop" | "stop_limit";
+  qty?: number;
+  riskPct?: number;
+  stop?: number;
+  target?: number;
+  rr?: number;
+  limitPrice?: number;
+}
+
+export interface SessionStatus {
+  id: string;
+  symbol: string;
+  interval: string;
+  mode: "paper" | "live";
+  running: boolean;
+  equity: number;
+  dayPnl: number;
+  lastPrice: number | null;
+  positions: BrokerPosition[];
+  openOrders: OrderReceipt[];
+  risk: {
+    halted: boolean;
+    haltReason: string | null;
+    dayPnl: number;
+    dayTrades: number;
+    [key: string]: unknown;
+  };
+}
+
+export class TradingSession {
+  constructor(options: TradingSessionOptions);
+  readonly id: string;
+  readonly symbol: string;
+  readonly interval: string;
+  readonly mode: "paper" | "live";
+  readonly eventBus: EventBus;
+  equity: number;
+  lastPrice: number | null;
+  running: boolean;
+  candleBuffer: import("./index.d.ts").Candle[];
+  static liveAllowed(): boolean;
+  start(): Promise<void>;
+  stop(options?: { flatten?: boolean }): Promise<void>;
+  pushBar(bar: import("./index.d.ts").Candle): Promise<void>;
+  placeOrder(options: SessionPlaceOrderOptions): Promise<OrderReceipt>;
+  closePosition(symbol?: string): Promise<OrderReceipt | null>;
+  flatten(): Promise<void>;
+  cancelOrder(orderId: string): Promise<void>;
+  getAccount(): Promise<AccountInfo>;
+  getPositions(): Promise<BrokerPosition[]>;
+  recentEvents(limit?: number): Array<{ event: string; payload: unknown; t: number }>;
+  getStatus(): SessionStatus;
+  refresh(): Promise<SessionStatus>;
+}
+
+export interface SessionManagerOptions {
+  brokerFactory?: (options: Record<string, unknown>) => BrokerAdapter;
+}
+
+export interface CreateSessionOptions extends Partial<TradingSessionOptions> {
+  id: string;
+  symbol: string;
+  confirmLive?: boolean;
+  broker?: BrokerAdapter;
+}
+
+export class SessionManager {
+  constructor(options?: SessionManagerOptions);
+  create(options: CreateSessionOptions): Promise<TradingSession>;
+  get(id: string): TradingSession | null;
+  list(): TradingSession[];
+  remove(id: string, options?: { flatten?: boolean }): Promise<void>;
+  haltAll(): Promise<void>;
+}
+
+export function createSessionManager(options?: SessionManagerOptions): SessionManager;

package/types/mcp.d.ts

@@ -0,0 +1,17 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SessionManager } from "./live.d.ts";
+
+export function createServer(): McpServer;
+export function startStdioServer(): Promise<McpServer>;
+
+export interface McpToolHandler {
+  description: string;
+  handler(args: Record<string, unknown>): Promise<unknown>;
+}
+
+export const mcpTools: Record<string, McpToolHandler>;
+export const researchTools: Record<string, McpToolHandler>;
+export const liveTools: Record<string, McpToolHandler>;
+
+/** The shared SessionManager instance used by the MCP server process. */
+export const sessionManager: SessionManager;

package/docs/superpowers/plans/2026-00-overview.md

@@ -1,101 +0,0 @@
-# tradelab 2026 Roadmap — Overview & Sequencing
-
-> **For agentic workers:** Each subsystem below has its own plan file. Use
-> `superpowers:subagent-driven-development` (recommended) or
-> `superpowers:executing-plans` to implement one plan at a time, task-by-task.
-> All step lists use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Turn tradelab from a strong single-run backtester into an AI-native,
-statistically-defensible research + execution platform for quants, simple
-traders, and autonomous agents.
-
----
-
-## The 8 subsystems
-
-| #   | Plan file                                                            | What it delivers                                                                                      | Depends on  |
-| --- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------- |
-| 1   | [2026-01-metrics-correctness.md](2026-01-metrics-correctness.md)     | Annualized Sharpe/Sortino, finite-clamped metrics JSON, benchmark alpha/beta/IR                       | —           |
-| 2   | [2026-02-indicator-library.md](2026-02-indicator-library.md)         | `tradelab/ta` namespace: RSI, MACD, Bollinger, VWAP, Supertrend, Donchian, Keltner, stochastics       | —           |
-| 3   | [2026-03-overfitting-toolkit.md](2026-03-overfitting-toolkit.md)     | CPCV, PBO, Deflated Sharpe, Monte Carlo bands, sweep haircut                                          | 1           |
-| 4   | [2026-04-async-signals-seeding.md](2026-04-async-signals-seeding.md) | `async signal()` with per-bar budget + cache + no-lookahead guard, `LlmSignal`, configurable RNG seed | —           |
-| 5   | [2026-05-mcp-server.md](2026-05-mcp-server.md)                       | `tradelab/mcp` server exposing data/backtest/walk-forward/metrics as agent tools                      | 1, 4 (soft) |
-| 6   | [2026-06-parallel-param-sweep.md](2026-06-parallel-param-sweep.md)   | Worker-pool param sweep + `optimize()` API                                                            | —           |
-| 7   | [2026-07-funding-carry-costs.md](2026-07-funding-carry-costs.md)     | Funding/borrow/overnight carry in the cost model                                                      | —           |
-| 8   | [2026-08-live-dashboard.md](2026-08-live-dashboard.md)               | Local realtime dashboard for `LiveEngine`/`LiveOrchestrator`                                          | —           |
-
-### Dependency graph
-
-```
-1 metrics ──► 3 overfitting
-1 metrics ──► 5 mcp (soft: nicer tool output)
-4 async ────► 5 mcp (soft: agent-driven backtests)
-2, 6, 7, 8 are independent
-```
-
-### Recommended execution order
-
-1. **Plan 1 (metrics)** — small, corrects existing bugs, unblocks 3 and 5.
-2. **Plan 2 (indicators)** — independent, high user value, unblocks NL strategies later.
-3. **Plan 4 (async signals + seed)** — engine change; do before MCP so agents can drive live.
-4. **Plan 5 (MCP)** — the 2026 headline; sits on top of 1 + 4.
-5. **Plan 3 (overfitting)** — the quant moat; needs clean metrics.
-6. **Plans 6, 7, 8** — parallelizable, any order.
-
----
-
-## Shared conventions (all plans assume these)
-
-**Runtime:** Node `>=18`, ESM (`"type": "module"`). No transpile step for `src/`.
-The CJS build is generated by `npm run build` (esbuild) from `src/`.
-
-**Tests:** `node:test` + `node:assert/strict`. Run a single file with:
-
-```bash
-node --test test/<name>.test.js
-```
-
-Run everything with `npm test` (`node --test`). New test files live under `test/`
-mirroring `src/` layout (e.g. `src/metrics/finite.js` → `test/metrics/finite.test.js`).
-There is no test runner config — discovery is by filename.
-
-**Lint/format before commit:**
-
-```bash
-npm run lint
-npm run format:check
-```
-
-**Commit style:** match existing history — `feat:`, `fix:`, `docs:`, `perf:`,
-`test:`. Every commit message MUST end with the trailer:
-
-```
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
-```
-
-**Public exports:** add new top-level exports in [src/index.js](../../../src/index.js).
-New subpath entrypoints (`tradelab/ta`, `tradelab/mcp`) require an entry in the
-`exports` map of [package.json](../../../package.json) AND a matching CJS bundle
-in [scripts/build-cjs.mjs](../../../scripts/build-cjs.mjs).
-
-**Canonical result shape (do not break it):** every engine returns
-`{ symbol, interval, range, trades, positions, openPositions, metrics, eqSeries, replay }`.
-`buildMetrics` is the single source of truth for `metrics`. Plans that add metrics
-fields ADD keys; they never rename or remove existing ones (dashboards depend on them).
-
-**The signal contract (do not break it):** `signal(context)` receives
-`{ candles, index, bar, equity, openPosition, pendingOrder }` and returns `null`
-or `{ side, entry?, stop, rr|takeProfit, ... }`. Two engines call it independently:
-the standalone loop in [src/engine/backtest.js](../../../src/engine/backtest.js) and
-the shared [src/engine/barSystemRunner.js](../../../src/engine/barSystemRunner.js)
-(used by portfolio). The live path uses
-[src/live/engine/liveEngine.js](../../../src/live/engine/liveEngine.js). Plan 4
-touches all three call sites.
-
----
-
-## Out of scope for this roadmap
-
-- Natural-language → signal compiler (separate spec; depends on Plan 2 + a strategy schema).
-- New broker adapters / options / fundamentals data sources.
-- L2 microstructure simulator.