horizon-code 0.5.1 → 0.6.0

package/src/strategy/ledger.ts

@@ -0,0 +1,185 @@
+// Performance ledger — persistent log of every backtest and run
+// Storage: ~/.horizon/ledger/<strategy-slug>.jsonl (append-only)
+
+import { homedir } from "os";
+import { resolve, join } from "path";
+import { existsSync, mkdirSync, appendFileSync, readFileSync } from "fs";
+import { createHash } from "crypto";
+
+const LEDGER_ROOT = resolve(homedir(), ".horizon", "ledger");
+
+export interface LedgerEntry {
+  strategy_name: string;
+  code_hash: string;
+  type: "backtest" | "run";
+  timestamp: string;
+  duration_secs: number;
+  params: Record<string, unknown>;
+  metrics: {
+    pnl: number;
+    rpnl: number;
+    upnl: number;
+    sharpe: number;
+    max_dd: number;
+    win_rate: number;
+    trades: number;
+    exposure: number;
+    [key: string]: unknown;
+  };
+  label?: string;
+}
+
+function ensureDir(): void {
+  if (!existsSync(LEDGER_ROOT)) mkdirSync(LEDGER_ROOT, { recursive: true });
+}
+
+function slugify(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
+}
+
+export function codeHash(code: string): string {
+  return createHash("sha256").update(code).digest("hex").slice(0, 12);
+}
+
+/** Append a new entry to the ledger (append-only JSONL) */
+export function logEntry(entry: LedgerEntry): void {
+  ensureDir();
+  const slug = slugify(entry.strategy_name);
+  const path = join(LEDGER_ROOT, `${slug}.jsonl`);
+  appendFileSync(path, JSON.stringify(entry) + "\n");
+}
+
+/** Get all entries for a strategy, newest first */
+export function getHistory(name: string): LedgerEntry[] {
+  ensureDir();
+  const slug = slugify(name);
+  const path = join(LEDGER_ROOT, `${slug}.jsonl`);
+  if (!existsSync(path)) return [];
+
+  const lines = readFileSync(path, "utf-8").split("\n").filter(Boolean);
+  const entries: LedgerEntry[] = [];
+  for (const line of lines) {
+    try { entries.push(JSON.parse(line)); } catch {}
+  }
+  return entries.reverse();
+}
+
+/** Find the best run by a specific metric (e.g., "sharpe", "pnl", "win_rate") */
+export function getBestRun(name: string, metric: string = "sharpe"): LedgerEntry | null {
+  const history = getHistory(name);
+  if (history.length === 0) return null;
+
+  return history.reduce((best, entry) => {
+    const bestVal = (best.metrics as any)[metric] ?? -Infinity;
+    const entryVal = (entry.metrics as any)[metric] ?? -Infinity;
+    return entryVal > bestVal ? entry : best;
+  });
+}
+
+/** Generate a strategy performance report */
+export function generateReport(name: string): {
+  total_runs: number;
+  backtests: number;
+  live_runs: number;
+  best_sharpe: LedgerEntry | null;
+  best_pnl: LedgerEntry | null;
+  worst_dd: LedgerEntry | null;
+  avg_sharpe: number;
+  avg_win_rate: number;
+  avg_pnl: number;
+  trend: string;
+  versions_tested: number;
+  summary: string;
+} {
+  const history = getHistory(name);
+  if (history.length === 0) {
+    return {
+      total_runs: 0, backtests: 0, live_runs: 0,
+      best_sharpe: null, best_pnl: null, worst_dd: null,
+      avg_sharpe: 0, avg_win_rate: 0, avg_pnl: 0,
+      trend: "no data", versions_tested: 0,
+      summary: `No performance history for "${name}".`,
+    };
+  }
+
+  const backtests = history.filter(e => e.type === "backtest");
+  const runs = history.filter(e => e.type === "run");
+  const uniqueHashes = new Set(history.map(e => e.code_hash));
+
+  const sharpes = history.map(e => e.metrics.sharpe).filter(v => isFinite(v));
+  const winRates = history.map(e => e.metrics.win_rate).filter(v => isFinite(v));
+  const pnls = history.map(e => e.metrics.pnl).filter(v => isFinite(v));
+
+  const avg = (arr: number[]) => arr.length > 0 ? arr.reduce((a, b) => a + b, 0) / arr.length : 0;
+
+  // Trend: compare recent 3 vs older entries
+  let trend = "stable";
+  if (sharpes.length >= 6) {
+    const recent = avg(sharpes.slice(0, 3));
+    const older = avg(sharpes.slice(3, 6));
+    if (recent > older * 1.15) trend = "improving";
+    else if (recent < older * 0.85) trend = "degrading";
+  }
+
+  const bestSharpe = getBestRun(name, "sharpe");
+  const bestPnl = getBestRun(name, "pnl");
+  const worstDd = history.reduce((worst, e) => {
+    return (e.metrics.max_dd > (worst?.metrics.max_dd ?? 0)) ? e : worst;
+  }, history[0]!);
+
+  const summary = [
+    `${history.length} runs (${backtests.length} backtests, ${runs.length} live) across ${uniqueHashes.size} code versions.`,
+    `Avg Sharpe: ${avg(sharpes).toFixed(2)}, Avg Win Rate: ${(avg(winRates) * 100).toFixed(1)}%, Avg P&L: $${avg(pnls).toFixed(2)}.`,
+    bestSharpe ? `Best Sharpe: ${bestSharpe.metrics.sharpe.toFixed(2)} (${bestSharpe.code_hash}, ${new Date(bestSharpe.timestamp).toLocaleDateString()})` : "",
+    `Trend: ${trend}.`,
+  ].filter(Boolean).join(" ");
+
+  return {
+    total_runs: history.length,
+    backtests: backtests.length,
+    live_runs: runs.length,
+    best_sharpe: bestSharpe,
+    best_pnl: bestPnl,
+    worst_dd: worstDd ?? null,
+    avg_sharpe: avg(sharpes),
+    avg_win_rate: avg(winRates),
+    avg_pnl: avg(pnls),
+    trend,
+    versions_tested: uniqueHashes.size,
+    summary,
+  };
+}
+
+/** Get performance comparison between code versions */
+export function compareVersions(name: string): { hash: string; runs: number; avg_sharpe: number; avg_pnl: number; best_sharpe: number }[] {
+  const history = getHistory(name);
+  const byHash = new Map<string, LedgerEntry[]>();
+
+  for (const entry of history) {
+    const existing = byHash.get(entry.code_hash) ?? [];
+    existing.push(entry);
+    byHash.set(entry.code_hash, existing);
+  }
+
+  return [...byHash.entries()].map(([hash, entries]) => {
+    const sharpes = entries.map(e => e.metrics.sharpe).filter(v => isFinite(v));
+    const pnls = entries.map(e => e.metrics.pnl).filter(v => isFinite(v));
+    const avg = (arr: number[]) => arr.length > 0 ? arr.reduce((a, b) => a + b, 0) / arr.length : 0;
+    return {
+      hash,
+      runs: entries.length,
+      avg_sharpe: avg(sharpes),
+      avg_pnl: avg(pnls),
+      best_sharpe: sharpes.length > 0 ? Math.max(...sharpes) : 0,
+    };
+  }).sort((a, b) => b.avg_sharpe - a.avg_sharpe);
+}
+
+/** List all strategies with ledger entries */
+export function listLedgerStrategies(): string[] {
+  ensureDir();
+  const { readdirSync } = require("fs");
+  return readdirSync(LEDGER_ROOT)
+    .filter((f: string) => f.endsWith(".jsonl"))
+    .map((f: string) => f.replace(".jsonl", ""));
+}

package/src/strategy/prompts.ts

@@ -1042,6 +1042,18 @@ Read what the user says and match it to the RIGHT action. Do NOT generate code w
 | "what markets are available?" | Call polymarket_data |
 | "stop it" / "kill it" | Call stop_strategy |
 | "load my old strategy" | Call list_saved_strategies then load_saved_strategy |
+| "undo that" / "revert" | Call revert_strategy |
+| "show me versions" | Call strategy_versions |
+| "how has this performed?" | Call strategy_report |
+| "health check" / "score" | Call health_score |
+| "alert me if..." | Call set_alert |
+| "export this" / "share this" | Call export_strategy |
+| "try different spreads" | Call parameter_sweep |
+| "find opportunities" | Call scan_opportunities |
+| "what should I trade?" | Call scan_opportunities |
+| "are my markets correlated?" | Call scan_correlations |
+| "show me the replay" | Call replay_session |
+| "portfolio status" | Call portfolio_summary |
 
 **Key rule:** If the user asks a question about the code, strategy concepts, or markets — answer with text. Do NOT write code or call tools unless they explicitly want a change or action.
 
@@ -1153,6 +1165,56 @@ P&L (with realized sub-label), Win Rate (with trade count), Sharpe Ratio, Max Dr
 3. Main grid: equity chart (5fr) + positions list (2fr)
 4. Logs card (full width, max-height 180px with overflow scroll)
 
+## Version Control
+
+Every code change is automatically versioned. Tools:
+- **strategy_versions(name)** — List all versions with timestamps
+- **revert_strategy(name, version)** — Restore a previous version
+- **diff_versions(name, v1, v2)** — Show what changed between versions
+
+When the user says "undo that" or "go back" → call revert_strategy.
+
+## Performance Ledger
+
+Every backtest and run is logged to a persistent ledger. Tools:
+- **strategy_report(name)** — Full performance history, version comparison, trends
+- **health_score()** — Code quality score 0-100 (risk config, feed guards, pipeline depth, etc.)
+
+Reference ledger data when advising: "Last time you ran this, Sharpe was 0.8. This version looks better."
+
+## Alerts & Monitoring
+
+- **set_alert(condition_type, threshold, action_type)** — Create alerts (max_dd_exceeds, pnl_below, exposure_above, win_rate_below). Actions: log, stop_process, webhook.
+- **list_alerts()** / **remove_alert(id)** — Manage alerts
+
+When user says "alert me if drawdown exceeds 5%" → set_alert(condition_type="max_dd_exceeds", threshold=5, action_type="log").
+
+## Export / Import
+
+- **export_strategy()** — Export to .hz file (code + params + performance data)
+- **import_strategy(path)** — Import from .hz file
+
+## Replay & Attribution
+
+- **replay_session(file_name?)** — View execution replay (order timeline, metric snapshots, errors). Without file_name, lists replays.
+- **portfolio_summary()** — Aggregate P&L across all running processes
+
+After a strategy runs 30+ minutes, offer performance attribution: which positions drove P&L, which signals helped/hurt. Use replay data and metrics to explain what happened.
+
+## Parameter Tuning
+
+When the user asks to "try different values" or "sweep parameters" or "optimize":
+- **parameter_sweep(param_name, values)** — Runs backtests for each value, returns comparison table
+
+Example: User says "try spreads from 0.02 to 0.08" → call parameter_sweep(param_name="spread", values=[0.02, 0.04, 0.06, 0.08]). Present results as a comparison: "0.04 had the best Sharpe (1.42), 0.02 had most trades but worst DD."
+
+## Market Scanning
+
+- **scan_opportunities(limit?)** — Scan top Polymarket markets for wide spreads, high volume, mispricings
+- **scan_correlations(slugs[])** — Compute pairwise correlations between markets in a portfolio
+
+When user asks "what should I trade?" or "find opportunities" → scan_opportunities. When user has multiple markets → warn about correlation/concentration risk.
+
 ## Other Tools
 
 - **polymarket_data** — Search real markets (slugs, spreads, volume)

package/src/strategy/replay.ts

@@ -0,0 +1,191 @@
+// Execution replay — structured event log for post-mortem analysis
+// Records orders, fills, position changes, and metrics snapshots
+
+import { homedir } from "os";
+import { resolve, join } from "path";
+import { existsSync, mkdirSync, appendFileSync, readFileSync } from "fs";
+
+const REPLAY_ROOT = resolve(homedir(), ".horizon", "replays");
+
+export type ReplayEventType = "start" | "order" | "fill" | "position_change" | "metric_snapshot" | "error" | "stop";
+
+export interface ReplayEvent {
+  timestamp: string;
+  elapsed_secs: number;
+  type: ReplayEventType;
+  data: Record<string, unknown>;
+}
+
+export interface ReplaySession {
+  pid: number;
+  strategy_name: string;
+  started_at: string;
+  events: ReplayEvent[];
+}
+
+function ensureDir(): void {
+  if (!existsSync(REPLAY_ROOT)) mkdirSync(REPLAY_ROOT, { recursive: true });
+}
+
+// Active replay sessions indexed by PID
+const activeSessions = new Map<number, { path: string; startedAt: number; strategyName: string }>();
+
+/** Start recording a replay session for a process */
+export function startReplay(pid: number, strategyName: string): void {
+  ensureDir();
+  const slug = strategyName.toLowerCase().replace(/[^a-z0-9]+/g, "_");
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  const fileName = `${slug}_${ts}.jsonl`;
+  const path = join(REPLAY_ROOT, fileName);
+
+  activeSessions.set(pid, { path, startedAt: Date.now(), strategyName });
+
+  // Write header
+  const header = JSON.stringify({
+    timestamp: new Date().toISOString(),
+    elapsed_secs: 0,
+    type: "start",
+    data: { pid, strategy_name: strategyName },
+  });
+  appendFileSync(path, header + "\n");
+}
+
+/** Record a replay event */
+export function recordEvent(pid: number, type: ReplayEventType, data: Record<string, unknown>): void {
+  const session = activeSessions.get(pid);
+  if (!session) return;
+
+  const event: ReplayEvent = {
+    timestamp: new Date().toISOString(),
+    elapsed_secs: (Date.now() - session.startedAt) / 1000,
+    type,
+    data,
+  };
+
+  try {
+    appendFileSync(session.path, JSON.stringify(event) + "\n");
+  } catch {}
+}
+
+/** Record metrics snapshot from parsed __HZ_METRICS__ data */
+export function recordMetrics(pid: number, metrics: Record<string, unknown>): void {
+  recordEvent(pid, "metric_snapshot", metrics);
+}
+
+/** Record an order event parsed from logs */
+export function recordOrder(pid: number, order: {
+  side: string;
+  market: string;
+  size: number;
+  price: number;
+  type?: string;
+}): void {
+  recordEvent(pid, "order", order);
+}
+
+/** Stop recording and finalize the replay */
+export function stopReplay(pid: number, exitCode?: number): void {
+  const session = activeSessions.get(pid);
+  if (!session) return;
+
+  recordEvent(pid, "stop", { exit_code: exitCode ?? null, duration_secs: (Date.now() - session.startedAt) / 1000 });
+  activeSessions.delete(pid);
+}
+
+/** Load a replay session from disk */
+export function loadReplay(fileName: string): ReplaySession | null {
+  const path = join(REPLAY_ROOT, fileName);
+  if (!existsSync(path)) return null;
+
+  const lines = readFileSync(path, "utf-8").split("\n").filter(Boolean);
+  const events: ReplayEvent[] = [];
+  let pid = 0;
+  let strategyName = "";
+  let startedAt = "";
+
+  for (const line of lines) {
+    try {
+      const event: ReplayEvent = JSON.parse(line);
+      events.push(event);
+      if (event.type === "start") {
+        pid = (event.data.pid as number) ?? 0;
+        strategyName = (event.data.strategy_name as string) ?? "";
+        startedAt = event.timestamp;
+      }
+    } catch {}
+  }
+
+  return { pid, strategy_name: strategyName, started_at: startedAt, events };
+}
+
+/** List all replay files, newest first */
+export function listReplays(): { fileName: string; strategy: string; date: string; eventCount: number }[] {
+  ensureDir();
+  const { readdirSync, statSync } = require("fs");
+  const files: string[] = readdirSync(REPLAY_ROOT).filter((f: string) => f.endsWith(".jsonl"));
+
+  return files
+    .map((fileName: string) => {
+      const path = join(REPLAY_ROOT, fileName);
+      const stat = statSync(path);
+      // Extract strategy name from filename
+      const parts = fileName.replace(".jsonl", "").split("_");
+      const strategy = parts.slice(0, -6).join("_") || parts[0] || "unknown";
+      const lineCount = readFileSync(path, "utf-8").split("\n").filter(Boolean).length;
+
+      return {
+        fileName,
+        strategy,
+        date: stat.mtime.toISOString(),
+        eventCount: lineCount,
+      };
+    })
+    .sort((a: any, b: any) => new Date(b.date).getTime() - new Date(a.date).getTime());
+}
+
+/** Generate a human-readable replay summary */
+export function summarizeReplay(session: ReplaySession): string {
+  const metrics = session.events.filter(e => e.type === "metric_snapshot");
+  const orders = session.events.filter(e => e.type === "order");
+  const errors = session.events.filter(e => e.type === "error");
+  const stopEvent = session.events.find(e => e.type === "stop");
+
+  const duration = stopEvent?.elapsed_secs ?? (metrics.length > 0 ? metrics[metrics.length - 1]!.elapsed_secs : 0);
+  const durationStr = duration > 3600 ? `${(duration / 3600).toFixed(1)}h` : `${(duration / 60).toFixed(1)}m`;
+
+  const lines: string[] = [];
+  lines.push(`Strategy: ${session.strategy_name} | Duration: ${durationStr} | Events: ${session.events.length}`);
+  lines.push(`Orders: ${orders.length} | Metric snapshots: ${metrics.length} | Errors: ${errors.length}`);
+
+  if (metrics.length >= 2) {
+    const first = metrics[0]!.data;
+    const last = metrics[metrics.length - 1]!.data;
+    lines.push(`P&L: $${first.pnl ?? 0} → $${last.pnl ?? 0}`);
+    lines.push(`Positions: ${first.positions ?? 0} → ${last.positions ?? 0}`);
+  }
+
+  if (orders.length > 0) {
+    lines.push("");
+    lines.push("Order timeline:");
+    for (const o of orders.slice(0, 20)) {
+      const elapsed = o.elapsed_secs > 60 ? `${(o.elapsed_secs / 60).toFixed(1)}m` : `${o.elapsed_secs.toFixed(0)}s`;
+      lines.push(`  ${elapsed}: ${o.data.side} ${o.data.size} @ ${o.data.price} on ${o.data.market}`);
+    }
+    if (orders.length > 20) lines.push(`  ... and ${orders.length - 20} more orders`);
+  }
+
+  if (errors.length > 0) {
+    lines.push("");
+    lines.push("Errors:");
+    for (const e of errors.slice(0, 5)) {
+      lines.push(`  ${e.elapsed_secs.toFixed(0)}s: ${e.data.message ?? JSON.stringify(e.data)}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/** Check if replay is active for a PID */
+export function isRecording(pid: number): boolean {
+  return activeSessions.has(pid);
+}