horizon-code 0.1.0

package/src/strategy/tools.ts

@@ -0,0 +1,764 @@
+// Strategy mode AI tools — full coding partner
+// The LLM can: write strategy code, run it, backtest it, read logs, build dashboards, deploy it
+
+import { tool } from "ai";
+import { z } from "zod";
+import { validateStrategyCode, autoFixStrategyCode } from "./validator.ts";
+import { gammaEvents } from "../research/apis.ts";
+import { platform } from "../platform/client.ts";
+import { store } from "../state/store.ts";
+import { dashboard } from "./dashboard.ts";
+import { runInSandbox, spawnInSandbox } from "./sandbox.ts";
+import { saveStrategy, loadStrategy, listSavedStrategies } from "./persistence.ts";
+import { hyperlink } from "../util/hyperlink.ts";
+import type { StrategyDraft } from "../state/types.ts";
+
+const t = tool as any;
+
+const docsCache = new Map<string, string>();
+
+// ── Process management ──
+
+interface ManagedProcess {
+  proc: ReturnType<typeof Bun.spawn>;
+  stdout: string[];
+  stderr: string[];
+  startedAt: number;
+  cleanup?: () => Promise<void>;
+}
+
+export const runningProcesses = new Map<number, ManagedProcess>();
+const customServers: ReturnType<typeof Bun.serve>[] = [];
+
+function startCapturing(pid: number, managed: ManagedProcess): void {
+  // Stream stdout/stderr into rolling buffers
+  const readStream = async (stream: ReadableStream<Uint8Array>, buffer: string[]) => {
+    try {
+      const reader = stream.getReader();
+      const decoder = new TextDecoder();
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        const text = decoder.decode(value);
+        for (const line of text.split("\n")) {
+          if (line) buffer.push(line);
+        }
+        // Rolling buffer — keep last 200 lines
+        while (buffer.length > 200) buffer.shift();
+      }
+    } catch {}
+  };
+  readStream(managed.proc.stdout as ReadableStream<Uint8Array>, managed.stdout);
+  readStream(managed.proc.stderr as ReadableStream<Uint8Array>, managed.stderr);
+
+  // Clean up when process exits
+  managed.proc.exited.then(() => {
+    // Keep in map for log reading — cleaned up on next run or quit
+  });
+}
+
+/** Clean up all running processes and servers */
+export function cleanupStrategyProcesses(): void {
+  for (const [pid, managed] of runningProcesses) {
+    managed.cleanup?.();
+    runningProcesses.delete(pid);
+  }
+  for (const server of customServers) {
+    try { server.stop(); } catch {}
+  }
+  customServers.length = 0;
+}
+
+// ── Helper: extract hz.run() kwargs from strategy code ──
+
+function extractRunKwargs(code: string) {
+  // Use multiline-aware extraction
+  const pipelineMatch = code.match(/pipeline\s*=\s*\[([\s\S]*?)\]/);
+  const pipelineFns = pipelineMatch
+    ? pipelineMatch[1]!.split(",").map((s) => s.trim()).filter((s) => s && !s.startsWith("#"))
+    : [];
+
+  const riskMatch = code.match(/hz\.Risk\(([\s\S]*?)\)/);
+  const riskArgs = riskMatch ? riskMatch[1]!.replace(/\n/g, " ").trim() : "max_position=100, max_drawdown_pct=10";
+
+  // Match params={...} — handle nested braces by counting depth
+  let paramsStr = "{}";
+  const paramsStart = code.indexOf("params={");
+  if (paramsStart !== -1) {
+    let depth = 0;
+    let end = paramsStart + 7;
+    for (let i = paramsStart + 7; i < code.length; i++) {
+      if (code[i] === "{") depth++;
+      if (code[i] === "}") {
+        if (depth === 0) { end = i + 1; break; }
+        depth--;
+      }
+    }
+    paramsStr = code.slice(paramsStart + 7, end);
+  }
+
+  // Match all market slugs
+  const marketsMatch = code.match(/markets\s*=\s*\[([\s\S]*?)\]/);
+  let marketNames: string[] = ["test-market"];
+  if (marketsMatch) {
+    const raw = marketsMatch[1]!;
+    const slugs = [...raw.matchAll(/["']([^"']+)["']/g)].map((m) => m[1]!);
+    if (slugs.length > 0) marketNames = slugs;
+  }
+
+  return { pipelineFns, riskArgs, paramsStr, marketNames };
+}
+
+// ── Safe environment for run_command (no secrets) ──
+
+function commandEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  const allow = ["PATH", "HOME", "LANG", "LC_ALL", "TERM", "PYTHONPATH", "VIRTUAL_ENV", "CONDA_PREFIX", "SHELL", "USER", "LOGNAME"];
+  for (const key of allow) {
+    if (process.env[key]) env[key] = process.env[key]!;
+  }
+  return env;
+}
+
+// ── Tools ──
+// Code generation uses text streaming (```python fences) detected by app.ts.
+// These tools handle editing, validation, execution, and deployment.
+
+export const strategyTools: Record<string, any> = {
+
+  edit_strategy: t({
+    description: "Make a targeted edit to the current strategy code using find-and-replace. Use for tweaking parameters, fixing bugs, adding a few lines. The find string must match exactly.",
+    parameters: z.object({
+      find: z.string().describe("Exact string to find in the current code"),
+      replace: z.string().describe("String to replace it with"),
+      change_summary: z.string().describe("What changed (1 sentence)"),
+    }),
+    execute: async (args: any) => {
+      const draft = store.getActiveSession()?.strategyDraft;
+      if (!draft) return { error: "No strategy loaded. Write a strategy in a ```python code fence first." };
+
+      if (!draft.code.includes(args.find)) {
+        return { error: `Could not find the text to replace. Make sure 'find' matches exactly.`, find: args.find };
+      }
+
+      const newCode = draft.code.replace(args.find, args.replace);
+      const fixedCode = autoFixStrategyCode(newCode);
+      const errors = validateStrategyCode(fixedCode);
+
+      store.updateStrategyDraft({
+        code: fixedCode,
+        validationStatus: errors.length === 0 ? "valid" : "invalid",
+        validationErrors: errors,
+        phase: "iterated",
+      });
+
+      // Auto-save
+      await saveStrategy(draft.name, fixedCode).catch(() => {});
+
+      return {
+        strategy_name: draft.name,
+        code: fixedCode,
+        change_summary: args.change_summary,
+        validation: { valid: errors.length === 0, errors },
+        lines_changed: args.replace.split("\n").length,
+      };
+    },
+  }),
+
+  validate_strategy: t({
+    description: "Re-validate the current strategy code. Validation runs automatically — only call if the user explicitly asks to validate.",
+    parameters: z.object({
+      code: z.string().optional().describe("Code to validate. Omit to validate current draft."),
+    }),
+    execute: async (args: any) => {
+      const code = args.code ?? store.getActiveSession()?.strategyDraft?.code;
+      if (!code) return { valid: false, errors: [{ line: null, message: "No strategy code to validate" }] };
+
+      const errors = validateStrategyCode(code);
+
+      if (!args.code && store.getActiveSession()?.strategyDraft) {
+        store.updateStrategyDraft({
+          validationStatus: errors.length === 0 ? "valid" : "invalid",
+          validationErrors: errors,
+        });
+      }
+      return { valid: errors.length === 0, errors };
+    },
+  }),
+
+  lookup_sdk_docs: t({
+    description: "Look up advanced Horizon SDK docs (arbitrage, copy-trading, wallet-intelligence, stealth, sentinel, oracle). Do NOT call for basic SDK usage — types, feeds, pipeline, risk, backtesting are in the system prompt.",
+    parameters: z.object({
+      topic: z.string().describe("SDK topic: types, feeds, context, pipeline, hz.run, risk, backtesting, plotting, ascii-plotting, exchanges, arbitrage, signals, etc."),
+    }),
+    execute: async (args: any) => {
+      const topic = args.topic.toLowerCase().replace(/\s+/g, "-");
+      const cached = docsCache.get(topic);
+      if (cached) return { topic: args.topic, content: cached };
+
+      // Fetch the full markdown docs index (llms-full.txt) and extract the relevant section
+      try {
+        if (!docsCache.has("__full__")) {
+          const res = await fetch("https://mathematicalcompany.mintlify.app/llms-full.txt", {
+            signal: AbortSignal.timeout(8000),
+          });
+          if (res.ok) {
+            docsCache.set("__full__", await res.text());
+          }
+        }
+
+        const fullDocs = docsCache.get("__full__");
+        if (fullDocs) {
+          // Find the section matching the topic — look for markdown headers
+          const topicVariants = [topic, topic.replace(/-/g, " "), args.topic];
+          let bestMatch = "";
+          for (const variant of topicVariants) {
+            // Find a heading containing the topic
+            const headingPattern = new RegExp(`^#+\\s+.*${variant.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}.*$`, "im");
+            const headingMatch = fullDocs.match(headingPattern);
+            if (headingMatch?.index !== undefined) {
+              // Extract from this heading to the next same-level heading (or 4000 chars)
+              const level = headingMatch[0].match(/^#+/)![0].length;
+              const rest = fullDocs.slice(headingMatch.index);
+              const nextHeading = rest.slice(1).search(new RegExp(`^#{1,${level}}\\s`, "m"));
+              const section = nextHeading !== -1 ? rest.slice(0, nextHeading + 1) : rest;
+              bestMatch = section.slice(0, 4000);
+              break;
+            }
+          }
+
+          if (bestMatch) {
+            docsCache.set(topic, bestMatch);
+            return { topic: args.topic, content: bestMatch };
+          }
+
+          // Fallback: keyword search in the full doc
+          const lines = fullDocs.split("\n");
+          const relevant: string[] = [];
+          const keywords = topic.split("-").filter((w: string) => w.length > 2);
+          for (let i = 0; i < lines.length && relevant.length < 80; i++) {
+            const line = lines[i]!.toLowerCase();
+            if (keywords.some((kw: string) => line.includes(kw))) {
+              // Include surrounding context
+              const start = Math.max(0, i - 2);
+              const end = Math.min(lines.length, i + 5);
+              for (let j = start; j < end; j++) {
+                if (!relevant.includes(lines[j]!)) relevant.push(lines[j]!);
+              }
+            }
+          }
+          if (relevant.length > 0) {
+            const content = relevant.join("\n").slice(0, 4000);
+            docsCache.set(topic, content);
+            return { topic: args.topic, content };
+          }
+        }
+      } catch {}
+
+      return { topic: args.topic, content: `SDK docs for "${args.topic}" not found. Use the embedded reference in your system prompt.` };
+    },
+  }),
+
+  polymarket_data: t({
+    description: "Search Polymarket for real market slugs, spreads, volume. Call only when you need a real market slug or the user asks about specific markets.",
+    parameters: z.object({
+      query: z.string().describe("Search query (e.g. 'bitcoin', 'election')"),
+      limit: z.number().optional().describe("Max results (default 5)"),
+    }),
+    execute: async (args: any) => {
+      const events = await gammaEvents({ query: args.query, limit: args.limit ?? 5 });
+      return {
+        query: args.query,
+        markets: events.map((e: any) => ({
+          title: e.title, slug: e.slug,
+          yesPrice: e.markets?.[0]?.yesPrice,
+          noPrice: e.markets?.[0]?.noPrice,
+          volume24hr: e.volume24hr, liquidity: e.liquidity,
+          spread: e.markets?.[0]?.bestAsk && e.markets?.[0]?.bestBid
+            ? +(e.markets[0].bestAsk - e.markets[0].bestBid).toFixed(4) : null,
+        })),
+      };
+    },
+  }),
+
+  // ── Backtest (real hz.backtest()) ──
+
+  backtest_strategy: t({
+    description: "Run hz.backtest() on the current strategy using the Horizon SDK locally. Returns real metrics, equity curve, and ASCII dashboard.",
+    parameters: z.object({
+      data_points: z.number().optional().describe("Synthetic price ticks (default 500)"),
+      initial_capital: z.number().optional().describe("Starting capital USD (default 1000)"),
+      base_price: z.number().optional().describe("Base price (default 0.50)"),
+      fill_model: z.enum(["deterministic", "probabilistic", "glft"]).optional().describe("Fill model (default deterministic)"),
+    }),
+    execute: async (args: any) => {
+      const draft = store.getActiveSession()?.strategyDraft;
+      if (!draft) return { error: "No strategy loaded yet." };
+      if (draft.validationStatus === "invalid") {
+        return { error: "Strategy has validation errors. Fix them first.", errors: draft.validationErrors };
+      }
+
+      const dataPoints = args.data_points ?? 500;
+      const capital = args.initial_capital ?? 1000;
+      const basePrice = args.base_price ?? 0.50;
+      const fillModel = args.fill_model ?? "deterministic";
+
+      const code = draft.code;
+      const hzRunIdx = code.search(/hz\.run\s*\(/);
+      const pipelineCode = hzRunIdx !== -1 ? code.slice(0, hzRunIdx).trimEnd() : code;
+      const { pipelineFns, riskArgs, paramsStr, marketNames } = extractRunKwargs(code);
+
+      if (pipelineFns.length === 0) {
+        return { error: "Could not extract pipeline functions. Ensure pipeline=[...] is in hz.run()." };
+      }
+
+      // Write backtest config to a JSON file (avoids template injection)
+      const backtestConfig = {
+        name: draft.name.replace(/[^a-zA-Z0-9_-]/g, "_"),
+        markets: marketNames,
+        data_points: dataPoints,
+        base_price: basePrice,
+        initial_capital: capital,
+        fill_model: fillModel,
+        risk_args: riskArgs,
+        params_str: paramsStr,
+        pipeline_fns: pipelineFns,
+      };
+
+      const script = `
+import horizon as hz
+from horizon.context import FeedData
+import json, sys
+
+${pipelineCode}
+
+# Load config from JSON file (no string interpolation)
+with open("backtest_config.json") as f:
+    _cfg = json.load(f)
+
+data = []
+price = _cfg["base_price"]
+for i in range(_cfg["data_points"]):
+    noise = (((i * 7 + 13) % 100) / 100 - 0.5) * 0.05
+    revert = (_cfg["base_price"] - price) * 0.05
+    price = max(0.01, min(0.99, price + noise + revert))
+    data.append({"timestamp": float(i), "price": round(price, 4)})
+
+try:
+    result = hz.backtest(
+        name=_cfg["name"],
+        markets=_cfg["markets"],
+        data=data,
+        pipeline=[${pipelineFns.join(", ")}],
+        risk=hz.Risk(${riskArgs}),
+        params=${paramsStr},
+        initial_capital=_cfg["initial_capital"],
+        fill_model=_cfg["fill_model"],
+    )
+    m = result.metrics
+    out = {
+        "strategy_name": _cfg["name"],
+        "equity_curve": [round(e, 2) for _, e in result.equity_curve],
+        "trade_count": len(result.trades),
+        "metrics": {
+            "total_return": round(getattr(m, 'total_return', 0), 4),
+            "max_drawdown": round(getattr(m, 'max_drawdown', 0), 4),
+            "sharpe_ratio": round(getattr(m, 'sharpe_ratio', 0), 2),
+            "sortino_ratio": round(getattr(m, 'sortino_ratio', 0), 2),
+            "win_rate": round(getattr(m, 'win_rate', 0), 4),
+            "profit_factor": round(getattr(m, 'profit_factor', 0), 2),
+            "total_trades": getattr(m, 'trade_count', 0),
+            "expectancy": round(getattr(m, 'expectancy', 0), 4),
+            "total_fees": round(getattr(m, 'total_fees', 0), 4),
+        },
+        "pnl_by_market": result.pnl_by_market(),
+    }
+    try:
+        out["summary"] = result.summary()
+    except:
+        pass
+    print("---BACKTEST_JSON---")
+    print(json.dumps(out))
+    print("---END_BACKTEST_JSON---")
+    try:
+        bundle = hz.from_backtest(result)
+        print("---ASCII_DASHBOARD---")
+        print(hz.dashboard(bundle))
+        print("---END_ASCII_DASHBOARD---")
+    except Exception as de:
+        print(f"---ASCII_DASHBOARD---\\nDashboard error: {de}\\n---END_ASCII_DASHBOARD---")
+except Exception as e:
+    import traceback
+    print("---BACKTEST_ERROR---")
+    print(str(e))
+    traceback.print_exc()
+    print("---END_BACKTEST_ERROR---")
+    sys.exit(1)
+`;
+
+      try {
+        // Write config to a temp file that the Python script reads (avoids template injection)
+        const { mkdtemp } = await import("fs/promises");
+        const { join } = await import("path");
+        const { tmpdir } = await import("os");
+        const sandboxDir = await mkdtemp(join(tmpdir(), "horizon-backtest-"));
+        await Bun.write(join(sandboxDir, "backtest_config.json"), JSON.stringify(backtestConfig));
+
+        const { stdout, stderr, exitCode, timedOut } = await runInSandbox({ code: script, timeout: 60000, cwd: sandboxDir });
+
+        if (timedOut) return { error: "Backtest timed out (60s limit)" };
+
+        // Check for early crash (import failure, syntax error, etc.)
+        if (exitCode !== 0 && !stdout.includes("---BACKTEST_ERROR---") && !stdout.includes("---BACKTEST_JSON---")) {
+          const errLines = (stderr || stdout).trim().split("\n").slice(-10).join("\n");
+          return {
+            error: `Python exited with code ${exitCode}`,
+            detail: errLines || "No output",
+            hint: stderr.includes("ModuleNotFoundError") ? "Horizon SDK not found. Run: pip install horizon" : undefined,
+          };
+        }
+
+        if (stdout.includes("---BACKTEST_ERROR---")) {
+          const errMsg = stdout.split("---BACKTEST_ERROR---")[1]?.split("---END_BACKTEST_ERROR---")[0]?.trim();
+          return { error: `Backtest failed: ${errMsg}` };
+        }
+
+        const jsonMatch = stdout.match(/---BACKTEST_JSON---([\s\S]*?)---END_BACKTEST_JSON---/);
+        const dashMatch = stdout.match(/---ASCII_DASHBOARD---([\s\S]*?)---END_ASCII_DASHBOARD---/);
+
+        if (!jsonMatch) {
+          return {
+            error: "Could not parse backtest output",
+            detail: stderr ? stderr.slice(0, 800) : stdout.slice(0, 800),
+            hint: "The Python process ran but produced no structured output",
+          };
+        }
+
+        const result = JSON.parse(jsonMatch[1]!.trim());
+        return { ...result, ascii_dashboard: dashMatch ? dashMatch[1]!.trim() : null, duration: `${dataPoints} ticks` };
+      } catch (err) {
+        return { error: `Backtest execution failed: ${err instanceof Error ? err.message : String(err)}`, hint: "Ensure Horizon SDK is installed: pip install horizon" };
+      }
+    },
+  }),
+
+  // ── Local Execution & Process Management ──
+
+  run_strategy: t({
+    description: "Run the current strategy code locally as a background Python process. Returns PID. Use read_logs(pid) to monitor. Must use mode='paper'. Process shows in the status bar as 'N running'.",
+    parameters: z.object({
+      timeout_secs: z.number().optional().describe("Max runtime seconds (default 3600 = 1 hour)"),
+    }),
+    execute: async (args: any) => {
+      const draft = store.getActiveSession()?.strategyDraft;
+      if (!draft) return { error: "No strategy loaded yet." };
+      if (draft.validationStatus !== "valid") {
+        return { error: "Strategy must pass validation first." };
+      }
+
+      // Safety: require paper mode
+      if (!/mode\s*=\s*["']paper["']/.test(draft.code)) {
+        return { error: 'Safety: strategy must use mode="paper" for local execution.' };
+      }
+
+      const timeout = args.timeout_secs ?? 3600;
+      try {
+        const { proc, cleanup } = spawnInSandbox(draft.code);
+
+        const pid = proc.pid;
+        const managed: ManagedProcess = { proc, stdout: [], stderr: [], startedAt: Date.now(), cleanup };
+        runningProcesses.set(pid, managed);
+        startCapturing(pid, managed);
+
+        // Auto-kill after timeout
+        setTimeout(() => {
+          const m = runningProcesses.get(pid);
+          if (m) { m.cleanup?.(); runningProcesses.delete(pid); }
+        }, timeout * 1000);
+
+        // Wait a beat to check for immediate crash
+        await new Promise((r) => setTimeout(r, 500));
+        const exitCode = proc.exitCode;
+        if (exitCode !== null && exitCode !== 0) {
+          const err = managed.stderr.join("\n");
+          runningProcesses.delete(pid);
+          return { error: `Process crashed immediately (exit ${exitCode})`, stderr: err.slice(0, 1000) };
+        }
+
+        return {
+          success: true, pid, status: "running", timeout_secs: timeout,
+          initial_output: managed.stdout.slice(0, 5).join("\n"),
+          message: `Strategy running (PID ${pid}). Use read_logs(${pid}) to see output. Auto-stops after ${Math.round(timeout / 60)}min.`,
+        };
+      } catch (err) {
+        return { error: `Failed to start: ${err instanceof Error ? err.message : String(err)}` };
+      }
+    },
+  }),
+
+  read_logs: t({
+    description: "Read stdout/stderr from a running or recently-exited background process. Use after run_strategy to monitor what the strategy is doing.",
+    parameters: z.object({
+      pid: z.number().describe("Process ID"),
+      lines: z.number().optional().describe("Number of recent lines (default 50)"),
+      stream: z.enum(["stdout", "stderr", "both"]).optional().describe("Which stream (default both)"),
+    }),
+    execute: async (args: any) => {
+      const managed = runningProcesses.get(args.pid);
+      if (!managed) return { error: `No process with PID ${args.pid}` };
+
+      const n = args.lines ?? 50;
+      const stream = args.stream ?? "both";
+      const alive = managed.proc.exitCode === null;
+
+      const result: any = {
+        pid: args.pid,
+        alive,
+        uptime_secs: Math.round((Date.now() - managed.startedAt) / 1000),
+      };
+
+      if (stream === "stdout" || stream === "both") {
+        result.stdout = managed.stdout.slice(-n).join("\n");
+      }
+      if (stream === "stderr" || stream === "both") {
+        result.stderr = managed.stderr.slice(-n).join("\n");
+      }
+      if (!alive) {
+        result.exit_code = managed.proc.exitCode;
+      }
+      return result;
+    },
+  }),
+
+  stop_process: t({
+    description: "Stop a running background process by PID.",
+    parameters: z.object({
+      pid: z.number().describe("Process ID to stop"),
+    }),
+    execute: async (args: any) => {
+      const managed = runningProcesses.get(args.pid);
+      if (!managed) return { error: `No process with PID ${args.pid}` };
+      const lastLogs = managed.stdout.slice(-10).join("\n");
+      managed.cleanup?.();
+      runningProcesses.delete(args.pid);
+      return { success: true, pid: args.pid, last_output: lastLogs };
+    },
+  }),
+
+  run_command: t({
+    description: "Execute a whitelisted shell command. For: pip install, file inspection, python scripts, git, opening URLs. Commands not in the whitelist are blocked.",
+    parameters: z.object({
+      command: z.string().describe("Shell command"),
+      timeout_secs: z.number().optional().describe("Max seconds (default 30)"),
+    }),
+    execute: async (args: any) => {
+      const cmd = args.command.trim().split(/\s+/)[0] ?? "";
+      const ALLOWED = new Set([
+        "pip", "pip3", "python", "python3", "node", "bun", "npm", "npx",
+        "cat", "head", "tail", "less", "wc", "ls", "find", "grep", "rg",
+        "pwd", "which", "git", "curl", "open", "xdg-open",
+        "mkdir", "touch", "cp", "mv",
+      ]);
+      // Strict whitelist — no bypass. "env", "echo", "chmod", "rm" removed to prevent secret leaking/destruction.
+      if (!ALLOWED.has(cmd)) {
+        return { error: `Command "${cmd}" is not allowed.` };
+      }
+
+      // Block shell tricks that could leak env or escape
+      const dangerous = /\$\(|`|\benv\b|\bexport\b|\bsource\b|\beval\b|\bexec\b|>\s*\/|\/etc\/|\/proc\/|~\/\.horizon/i;
+      if (dangerous.test(args.command)) {
+        return { error: "Command contains blocked patterns." };
+      }
+
+      const timeout = (args.timeout_secs ?? 30) * 1000;
+      try {
+        const proc = Bun.spawn(["bash", "-c", args.command], {
+          stdout: "pipe", stderr: "pipe",
+          env: commandEnv(), // restricted env — no secrets
+        });
+        const result = await Promise.race([
+          (async () => {
+            const stdout = await new Response(proc.stdout).text();
+            const stderr = await new Response(proc.stderr).text();
+            await proc.exited;
+            return { stdout, stderr, exitCode: proc.exitCode };
+          })(),
+          new Promise<never>((_, reject) =>
+            setTimeout(() => { proc.kill(); reject(new Error("timeout")); }, timeout)
+          ),
+        ]);
+        return { stdout: result.stdout.slice(0, 3000), stderr: result.stderr.slice(0, 1000), exit_code: result.exitCode };
+      } catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+      }
+    },
+  }),
+
+  // ── Save & Deploy ──
+
+  save_strategy: t({
+    description: "Save current strategy draft to the Horizon platform. Returns strategy_id needed for deploy_strategy. Code must pass validation first.",
+    parameters: z.object({ name: z.string().optional().describe("Override strategy name") }),
+    execute: async (args: any) => {
+      const draft = store.getActiveSession()?.strategyDraft;
+      if (!draft) return { error: "No strategy loaded." };
+      if (!draft.code) return { error: "Strategy has no code." };
+      if (draft.validationStatus === "invalid") {
+        return { error: "Strategy has validation errors. Fix them first.", errors: draft.validationErrors };
+      }
+      try {
+        const data = await platform.createStrategy({
+          name: args.name ?? draft.name, code: draft.code,
+          params: draft.params, risk_config: draft.riskConfig ?? undefined,
+        });
+        store.updateStrategyDraft({ strategyId: data.id, phase: "saved" });
+        return {
+          success: true,
+          strategy_id: data.id,
+          name: draft.name,
+          hint: "Now call list_credentials() to get a credential_id, then deploy_strategy().",
+        };
+      } catch (err) {
+        return { error: `Failed to save: ${err instanceof Error ? err.message : String(err)}` };
+      }
+    },
+  }),
+
+  // ── Local file persistence ──
+
+  load_saved_strategy: t({
+    description: "Load a previously saved strategy from disk. Only call when the user explicitly asks to load or resume a saved strategy.",
+    parameters: z.object({
+      name: z.string().describe("Strategy name (filename without .py)"),
+    }),
+    execute: async (args: any) => {
+      const result = await loadStrategy(args.name);
+      if (!result) return { error: `Strategy "${args.name}" not found in ~/.horizon/strategies/` };
+
+      const fixedCode = autoFixStrategyCode(result.code);
+      const errors = validateStrategyCode(fixedCode);
+
+      const draft: StrategyDraft = {
+        name: args.name,
+        code: fixedCode,
+        params: {},
+        explanation: "",
+        riskConfig: null,
+        validationStatus: errors.length === 0 ? "valid" : "invalid",
+        validationErrors: errors,
+        phase: "generated",
+      };
+      store.setStrategyDraft(draft);
+
+      return {
+        strategy_name: args.name,
+        code: fixedCode,
+        path: result.path,
+        validation: { valid: errors.length === 0, errors },
+      };
+    },
+  }),
+
+  list_saved_strategies: t({
+    description: "List saved strategies on disk. Only call when the user asks to see their saved strategies. Do NOT call this before generating a new strategy.",
+    parameters: z.object({}),
+    execute: async () => {
+      const strategies = await listSavedStrategies();
+      return {
+        count: strategies.length,
+        strategies: strategies.map((s) => ({
+          name: s.name,
+          path: s.path,
+          modified: s.modified ? new Date(s.modified).toISOString() : null,
+        })),
+      };
+    },
+  }),
+
+  // ── Dashboard ──
+
+  spawn_dashboard: t({
+    description: `Serve a local web dashboard. Two modes:
+
+1. **Built-in monitor** — pass strategy_id. Auto-connects to live platform metrics.
+2. **Custom HTML** — pass custom_html you write from scratch.
+
+Custom dashboards get a FREE live API:
+- GET /api/metrics → platform metrics (if strategy_id provided)
+- GET /api/logs → platform deployment logs
+- GET /api/strategy → current strategy draft (code, name, params, risk)
+- GET /api/local-logs → stdout/stderr from local run_strategy processes
+
+Your HTML can fetch("/api/metrics").then(r => r.json()) to get live data. Auto-refresh with setInterval.`,
+    parameters: z.object({
+      strategy_id: z.string().optional().describe("Strategy UUID — enables /api/metrics and /api/logs from the platform"),
+      custom_html: z.string().optional().describe("Complete HTML page you write from scratch (dark theme, Chart.js, etc.)"),
+      port: z.number().optional().describe("Port (default: random)"),
+    }),
+    execute: async (args: any) => {
+      try {
+        if (args.strategy_id && !args.custom_html) {
+          const url = dashboard.start(args.strategy_id, args.port);
+          return { success: true, url, message: `Monitor at ${hyperlink(url)}` };
+        }
+
+        // Custom HTML with live API backend
+        const html = args.custom_html ?? "";
+        const strategyId = args.strategy_id;
+
+        const server = Bun.serve({
+          port: args.port || 0,
+          hostname: "127.0.0.1", // localhost only — not accessible from network
+          fetch: async (req) => {
+            const url = new URL(req.url);
+
+            // Live API: platform metrics
+            if (url.pathname === "/api/metrics" && strategyId) {
+              try { return Response.json(await platform.getMetrics(strategyId, 20)); }
+              catch (e: any) { return Response.json({ error: e.message }, { status: 500 }); }
+            }
+
+            // Live API: platform logs
+            if (url.pathname === "/api/logs" && strategyId) {
+              try { return Response.json(await platform.getLogs(strategyId, 50)); }
+              catch (e: any) { return Response.json({ error: e.message }, { status: 500 }); }
+            }
+
+            // Live API: current strategy draft
+            if (url.pathname === "/api/strategy") {
+              const draft = store.getActiveSession()?.strategyDraft;
+              return Response.json(draft ? { name: draft.name, code: draft.code, params: draft.params, riskConfig: draft.riskConfig, validationStatus: draft.validationStatus } : { error: "No strategy loaded" });
+            }
+
+            // Live API: local process logs
+            if (url.pathname === "/api/local-logs") {
+              const allLogs: Record<string, { stdout: string[]; stderr: string[]; alive: boolean }> = {};
+              for (const [pid, managed] of runningProcesses) {
+                allLogs[pid] = { stdout: managed.stdout.slice(-50), stderr: managed.stderr.slice(-20), alive: managed.proc.exitCode === null };
+              }
+              return Response.json(allLogs);
+            }
+
+            // CORS preflight
+            if (req.method === "OPTIONS") {
+              return new Response(null, { headers: { "Access-Control-Allow-Origin": "http://127.0.0.1", "Access-Control-Allow-Methods": "GET", "Access-Control-Allow-Headers": "Content-Type" } });
+            }
+
+            // Serve the HTML
+            return new Response(html, { headers: { "Content-Type": "text/html", "Access-Control-Allow-Origin": "http://127.0.0.1" } });
+          },
+        });
+
+        const dashUrl = `http://localhost:${server.port}`;
+        customServers.push(server);
+
+        const apis = ["/api/strategy", "/api/local-logs"];
+        if (strategyId) apis.push("/api/metrics", "/api/logs");
+
+        return { success: true, url: dashUrl, available_apis: apis, message: `Dashboard at ${hyperlink(dashUrl)}` };
+      } catch (err) {
+        return { error: `Dashboard failed: ${err instanceof Error ? err.message : String(err)}` };
+      }
+    },
+  }),
+};