station-kit 1.0.0

package/src/cli.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+// Station CLI launcher — re-executes itself with tsx loader so user .ts files
+// (signals, broadcasts, configs) can be imported with full resolution.
+
+import { execPath } from "node:process";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const MARKER = "__STATION_TSX_LOADED";
+
+if (!process.env[MARKER]) {
+  // Re-exec with --import tsx
+  const main = fileURLToPath(new URL("./cli-main.js", import.meta.url));
+  const child = spawn(execPath, ["--import", "tsx", main], {
+    stdio: "inherit",
+    env: { ...process.env, [MARKER]: "1" },
+  });
+  child.on("exit", (code) => process.exit(code ?? 0));
+  child.on("error", (err) => {
+    console.error("[station] Failed to start:", err.message);
+    process.exit(1);
+  });
+} else {
+  // Already loaded with tsx — import main
+  await import("./cli-main.js");
+}

package/src/config/loader.ts

@@ -0,0 +1,33 @@
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { resolveConfig, type StationConfig } from "./schema.js";
+
+const CONFIG_NAMES = [
+  "station.config.ts",
+  "station.config.js",
+  "station.config.mjs",
+];
+
+export async function loadConfig(cwd: string): Promise<StationConfig> {
+  const configPath = findConfigFile(cwd);
+
+  if (!configPath) {
+    console.log("[station] No config file found. Using defaults.");
+    return resolveConfig({});
+  }
+
+  console.log(`[station] Loading ${configPath}`);
+
+  const mod = await import(pathToFileURL(resolve(configPath)).href);
+  const raw = mod.default ?? mod;
+  return resolveConfig(raw);
+}
+
+function findConfigFile(cwd: string): string | null {
+  for (const name of CONFIG_NAMES) {
+    const candidate = join(cwd, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}

package/src/config/schema.ts

@@ -0,0 +1,80 @@
+import type { SignalQueueAdapter } from "station-signal";
+import type { BroadcastQueueAdapter } from "station-broadcast";
+
+export interface AuthConfig {
+  username: string;
+  password: string;
+  sessionTtlMs?: number;
+}
+
+export interface RunnerConfig {
+  pollIntervalMs: number;
+  maxConcurrent: number;
+  maxAttempts: number;
+  retryBackoffMs: number;
+}
+
+export interface BroadcastRunnerConfig {
+  pollIntervalMs: number;
+}
+
+export interface StationConfig {
+  port: number;
+  host: string;
+  adapter?: SignalQueueAdapter;
+  broadcastAdapter?: BroadcastQueueAdapter;
+  signalsDir?: string;
+  broadcastsDir?: string;
+  runner: RunnerConfig;
+  broadcastRunner: BroadcastRunnerConfig;
+  runRunners: boolean;
+  open: boolean;
+  logLevel: "debug" | "info" | "warn" | "error";
+  auth?: AuthConfig;
+}
+
+export type StationUserConfig = Partial<Omit<StationConfig, "runner" | "broadcastRunner">> & {
+  runner?: Partial<RunnerConfig>;
+  broadcastRunner?: Partial<BroadcastRunnerConfig>;
+};
+
+const DEFAULTS: StationConfig = {
+  port: 4400,
+  host: "localhost",
+  runner: {
+    pollIntervalMs: 1000,
+    maxConcurrent: 5,
+    maxAttempts: 1,
+    retryBackoffMs: 1000,
+  },
+  broadcastRunner: {
+    pollIntervalMs: 1000,
+  },
+  runRunners: true,
+  open: true,
+  logLevel: "info",
+};
+
+export function resolveConfig(input: StationUserConfig): StationConfig {
+  return {
+    port: input.port ?? DEFAULTS.port,
+    host: input.host ?? DEFAULTS.host,
+    adapter: input.adapter,
+    broadcastAdapter: input.broadcastAdapter,
+    signalsDir: input.signalsDir,
+    broadcastsDir: input.broadcastsDir,
+    runner: {
+      pollIntervalMs: input.runner?.pollIntervalMs ?? DEFAULTS.runner.pollIntervalMs,
+      maxConcurrent: input.runner?.maxConcurrent ?? DEFAULTS.runner.maxConcurrent,
+      maxAttempts: input.runner?.maxAttempts ?? DEFAULTS.runner.maxAttempts,
+      retryBackoffMs: input.runner?.retryBackoffMs ?? DEFAULTS.runner.retryBackoffMs,
+    },
+    broadcastRunner: {
+      pollIntervalMs: input.broadcastRunner?.pollIntervalMs ?? DEFAULTS.broadcastRunner.pollIntervalMs,
+    },
+    runRunners: input.runRunners ?? DEFAULTS.runRunners,
+    open: input.open ?? DEFAULTS.open,
+    logLevel: input.logLevel ?? DEFAULTS.logLevel,
+    auth: input.auth,
+  };
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+import type { StationUserConfig } from "./config/schema.js";
+
+export function defineConfig(config: StationUserConfig): StationUserConfig {
+  return config;
+}
+
+export type { StationConfig, StationUserConfig, AuthConfig } from "./config/schema.js";

package/src/server/auth/keys.ts

@@ -0,0 +1,112 @@
+import crypto from "node:crypto";
+import Database from "better-sqlite3";
+
+export interface ApiKey {
+  id: string;
+  name: string;
+  keyHash: string;
+  keyPrefix: string;
+  scopes: string[];
+  createdAt: string;
+  lastUsed: string | null;
+  expiresAt: string | null;
+  revoked: boolean;
+}
+
+export class KeyStore {
+  private db: Database.Database;
+
+  constructor(dbPath: string) {
+    this.db = new Database(dbPath);
+    this.db.pragma("journal_mode = WAL");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS api_keys (
+        id          TEXT PRIMARY KEY,
+        name        TEXT NOT NULL,
+        key_hash    TEXT NOT NULL UNIQUE,
+        key_prefix  TEXT NOT NULL,
+        scopes      TEXT NOT NULL DEFAULT '[]',
+        created_at  TEXT NOT NULL,
+        last_used   TEXT,
+        expires_at  TEXT,
+        revoked     INTEGER NOT NULL DEFAULT 0
+      )
+    `);
+  }
+
+  /** Generate a new API key. Returns the full key (only shown once) and the stored record. */
+  create(name: string, scopes: string[] = ["trigger", "read"]): { key: string; record: ApiKey } {
+    const id = crypto.randomUUID();
+    const rawKey = `sk_live_${crypto.randomBytes(16).toString("hex")}`;
+    const keyHash = crypto.createHash("sha256").update(rawKey).digest("hex");
+    const keyPrefix = rawKey.slice(0, 12);
+    const createdAt = new Date().toISOString();
+
+    this.db.prepare(`
+      INSERT INTO api_keys (id, name, key_hash, key_prefix, scopes, created_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(id, name, keyHash, keyPrefix, JSON.stringify(scopes), createdAt);
+
+    return {
+      key: rawKey,
+      record: { id, name, keyHash, keyPrefix, scopes, createdAt, lastUsed: null, expiresAt: null, revoked: false },
+    };
+  }
+
+  /** Verify an API key. Returns the key record if valid, null otherwise. */
+  verify(rawKey: string): ApiKey | null {
+    const keyHash = crypto.createHash("sha256").update(rawKey).digest("hex");
+    const row = this.db.prepare(`
+      SELECT id, name, key_hash, key_prefix, scopes, created_at, last_used, expires_at, revoked
+      FROM api_keys WHERE key_hash = ?
+    `).get(keyHash) as Record<string, unknown> | undefined;
+
+    if (!row) return null;
+    if (row.revoked) return null;
+    if (row.expires_at && new Date(row.expires_at as string) < new Date()) return null;
+
+    // Update last_used
+    this.db.prepare("UPDATE api_keys SET last_used = ? WHERE id = ?").run(new Date().toISOString(), row.id);
+
+    return {
+      id: row.id as string,
+      name: row.name as string,
+      keyHash: row.key_hash as string,
+      keyPrefix: row.key_prefix as string,
+      scopes: JSON.parse(row.scopes as string),
+      createdAt: row.created_at as string,
+      lastUsed: row.last_used as string | null,
+      expiresAt: row.expires_at as string | null,
+      revoked: Boolean(row.revoked),
+    };
+  }
+
+  /** List all keys (without hashes). */
+  list(): Omit<ApiKey, "keyHash">[] {
+    const rows = this.db.prepare(`
+      SELECT id, name, key_prefix, scopes, created_at, last_used, expires_at, revoked
+      FROM api_keys ORDER BY created_at DESC
+    `).all() as Record<string, unknown>[];
+
+    return rows.map((row) => ({
+      id: row.id as string,
+      name: row.name as string,
+      keyPrefix: row.key_prefix as string,
+      scopes: JSON.parse(row.scopes as string),
+      createdAt: row.created_at as string,
+      lastUsed: row.last_used as string | null,
+      expiresAt: row.expires_at as string | null,
+      revoked: Boolean(row.revoked),
+    }));
+  }
+
+  /** Revoke a key by ID. */
+  revoke(id: string): boolean {
+    const result = this.db.prepare("UPDATE api_keys SET revoked = 1 WHERE id = ?").run(id);
+    return result.changes > 0;
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}

package/src/server/auth/session.ts

@@ -0,0 +1,48 @@
+import crypto from "node:crypto";
+
+const SESSION_TTL_MS = 86_400_000; // 24 hours
+
+export interface SessionConfig {
+  username: string;
+  password: string;
+  sessionTtlMs?: number;
+}
+
+/** HMAC-sign a token. The secret is derived from the password. */
+function sign(payload: string, secret: string): string {
+  const hmac = crypto.createHmac("sha256", secret);
+  hmac.update(payload);
+  return hmac.digest("hex");
+}
+
+export function createSessionToken(config: SessionConfig): string {
+  const exp = Date.now() + (config.sessionTtlMs ?? SESSION_TTL_MS);
+  const payload = `${config.username}:${exp}`;
+  const signature = sign(payload, config.password);
+  return Buffer.from(`${payload}:${signature}`).toString("base64url");
+}
+
+export function verifySessionToken(token: string, config: SessionConfig): boolean {
+  try {
+    const decoded = Buffer.from(token, "base64url").toString();
+    const parts = decoded.split(":");
+    if (parts.length !== 3) return false;
+    const [username, expStr, sig] = parts;
+    const exp = parseInt(expStr, 10);
+    if (isNaN(exp) || Date.now() > exp) return false;
+    if (username !== config.username) return false;
+    const expected = sign(`${username}:${expStr}`, config.password);
+    return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
+  } catch {
+    return false;
+  }
+}
+
+export function verifyCredentials(username: string, password: string, config: SessionConfig): boolean {
+  // Use timing-safe comparison to prevent timing attacks
+  const userMatch = username.length === config.username.length &&
+    crypto.timingSafeEqual(Buffer.from(username), Buffer.from(config.username));
+  const passMatch = password.length === config.password.length &&
+    crypto.timingSafeEqual(Buffer.from(password), Buffer.from(config.password));
+  return userMatch && passMatch;
+}

package/src/server/index.ts

@@ -0,0 +1,296 @@
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { createMiddleware } from "hono/factory";
+import { serve } from "@hono/node-server";
+import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+import type { Server } from "node:http";
+import { SignalRunner, MemoryAdapter } from "station-signal";
+import { BroadcastRunner, BroadcastMemoryAdapter } from "station-broadcast";
+import type { SignalQueueAdapter } from "station-signal";
+import type { BroadcastQueueAdapter } from "station-broadcast";
+import type { StationConfig } from "../config/schema.js";
+import { WebSocketHub } from "./ws.js";
+import { SSEHub } from "./sse.js";
+import { LogBuffer } from "./log-buffer.js";
+import { LogStore } from "./log-store.js";
+import { StationSignalSubscriber, StationBroadcastSubscriber } from "./subscriber.js";
+import { healthRoutes } from "./routes/health.js";
+import { signalRoutes } from "./routes/signals.js";
+import { runRoutes } from "./routes/runs.js";
+import { broadcastRoutes } from "./routes/broadcasts.js";
+import { KeyStore } from "./auth/keys.js";
+import { verifySessionToken, verifyCredentials, createSessionToken, type SessionConfig } from "./auth/session.js";
+import { authResolver } from "./middleware/auth.js";
+import { requireScope } from "./middleware/scope-guard.js";
+import { rateLimiter } from "./middleware/rate-limit.js";
+import { v1HealthRoutes } from "./routes/v1/health.js";
+import { v1SignalRoutes } from "./routes/v1/signals.js";
+import { v1RunRoutes } from "./routes/v1/runs.js";
+import { v1BroadcastRoutes } from "./routes/v1/broadcasts.js";
+import { v1TriggerRoutes } from "./routes/v1/trigger.js";
+import { v1KeyRoutes } from "./routes/v1/keys.js";
+import { v1AuthRoutes } from "./routes/v1/auth.js";
+import { v1EventRoutes } from "./routes/v1/events.js";
+
+export interface StationInstance {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}
+
+export async function createStation(config: StationConfig, cwd: string): Promise<StationInstance> {
+  const signalAdapter: SignalQueueAdapter = config.adapter ?? new MemoryAdapter();
+  const broadcastAdapter: BroadcastQueueAdapter | undefined =
+    config.broadcastAdapter ?? (config.broadcastsDir ? new BroadcastMemoryAdapter() : undefined);
+
+  const wsHub = new WebSocketHub();
+  const sseHub = new SSEHub();
+  const logBuffer = new LogBuffer();
+  const logStore = new LogStore(resolve(cwd, "station-logs.db"));
+
+  // Auth: create KeyStore and SessionConfig if auth is configured
+  let keyStore: KeyStore | undefined;
+  let sessionConfig: SessionConfig | undefined;
+
+  if (config.auth) {
+    keyStore = new KeyStore(resolve(cwd, "station-keys.db"));
+    sessionConfig = {
+      username: config.auth.username,
+      password: config.auth.password,
+      sessionTtlMs: config.auth.sessionTtlMs,
+    };
+  }
+
+  // Resolve directories
+  const signalsDir = config.signalsDir
+    ? resolve(cwd, config.signalsDir)
+    : existsSync(resolve(cwd, "signals"))
+      ? resolve(cwd, "signals")
+      : undefined;
+
+  const broadcastsDir = config.broadcastsDir
+    ? resolve(cwd, config.broadcastsDir)
+    : existsSync(resolve(cwd, "broadcasts"))
+      ? resolve(cwd, "broadcasts")
+      : undefined;
+
+  // Create subscribers (always — they collect metadata)
+  const stationSignalSub = new StationSignalSubscriber(wsHub, logBuffer, logStore);
+  const stationBroadcastSub = new StationBroadcastSubscriber(wsHub);
+
+  // Wire SSE hub into subscribers so events reach both WS and SSE clients
+  stationSignalSub.setSSEHub(sseHub);
+  stationBroadcastSub.setSSEHub(sseHub);
+
+  // Create runners if enabled
+  let signalRunner: SignalRunner | undefined;
+  let broadcastRunner: BroadcastRunner | undefined;
+
+  if (config.runRunners) {
+    signalRunner = new SignalRunner({
+      signalsDir,
+      adapter: signalAdapter,
+      pollIntervalMs: config.runner.pollIntervalMs,
+      maxConcurrent: config.runner.maxConcurrent,
+      maxAttempts: config.runner.maxAttempts,
+      retryBackoffMs: config.runner.retryBackoffMs,
+      subscribers: [stationSignalSub],
+    });
+
+    if (broadcastsDir || broadcastAdapter) {
+      broadcastRunner = new BroadcastRunner({
+        signalRunner,
+        broadcastsDir,
+        adapter: broadcastAdapter ?? new BroadcastMemoryAdapter(),
+        pollIntervalMs: config.broadcastRunner.pollIntervalMs,
+        subscribers: [stationBroadcastSub],
+      });
+    }
+  }
+
+  // Build Hono app
+  const app = new Hono();
+
+  // CORS for Next.js dev server and API clients
+  app.use("/*", cors({
+    origin: [`http://${config.host}:${config.port + 1}`, `http://localhost:${config.port + 1}`],
+    allowMethods: ["GET", "POST", "DELETE", "OPTIONS"],
+    allowHeaders: ["Content-Type", "Authorization"],
+    credentials: true,
+  }));
+
+  // ── Dashboard auth routes (always accessible) ──────────────────────
+  app.get("/api/auth/check", async (c) => {
+    if (!sessionConfig) {
+      return c.json({ data: { authenticated: true, authRequired: false } });
+    }
+    const cookie = c.req.header("cookie");
+    if (cookie) {
+      const match = cookie.match(/station_session=([^;]+)/);
+      if (match && verifySessionToken(match[1], sessionConfig)) {
+        return c.json({ data: { authenticated: true, authRequired: true } });
+      }
+    }
+    return c.json({ data: { authenticated: false, authRequired: true } });
+  });
+
+  app.post("/api/auth/login", async (c) => {
+    if (!sessionConfig) {
+      return c.json({ data: { ok: true } });
+    }
+    const body = await c.req.json().catch(() => ({}));
+    const { username, password } = body;
+    if (!username || !password) {
+      return c.json({ error: "bad_request", message: "Missing username or password." }, 400);
+    }
+    if (!verifyCredentials(username, password, sessionConfig)) {
+      return c.json({ error: "unauthorized", message: "Invalid credentials." }, 401);
+    }
+    const token = createSessionToken(sessionConfig);
+    const ttlSeconds = Math.floor((sessionConfig.sessionTtlMs ?? 86_400_000) / 1000);
+    c.header("Set-Cookie", `station_session=${token}; HttpOnly; SameSite=Lax; Path=/; Max-Age=${ttlSeconds}`);
+    return c.json({ data: { ok: true } });
+  });
+
+  app.post("/api/auth/logout", async (c) => {
+    c.header("Set-Cookie", "station_session=; HttpOnly; SameSite=Lax; Path=/; Max-Age=0");
+    return c.json({ data: { ok: true } });
+  });
+
+  // ── Dashboard API routes (session required when auth configured) ───
+  if (sessionConfig) {
+    app.use("/api/*", createMiddleware(async (c, next) => {
+      // Skip auth check for /api/auth/* (already handled above)
+      if (c.req.path.startsWith("/api/auth/")) return next();
+      // Skip auth check for /api/v1/* (has its own auth)
+      if (c.req.path.startsWith("/api/v1/")) return next();
+
+      const cookie = c.req.header("cookie");
+      if (cookie) {
+        const match = cookie.match(/station_session=([^;]+)/);
+        if (match && verifySessionToken(match[1], sessionConfig)) {
+          return next();
+        }
+      }
+      return c.json({ error: "unauthorized", message: "Session required." }, 401);
+    }));
+  }
+
+  app.route("/api", healthRoutes({ signalAdapter, broadcastAdapter }));
+  app.route("/api", signalRoutes({ signalRunner, signalAdapter, signalSubscriber: stationSignalSub }));
+  app.route("/api", runRoutes({ signalRunner, signalAdapter, logBuffer, logStore }));
+  app.route("/api", broadcastRoutes({ broadcastRunner, broadcastAdapter, broadcastSubscriber: stationBroadcastSub, logBuffer, logStore }));
+
+  // ── v1 API routes (authenticated) ──────────────────────────────────
+
+  // Public v1 routes (no auth required)
+  app.route("/api/v1", v1HealthRoutes({ signalAdapter, broadcastAdapter }));
+
+  // Auth routes: public but rate-limited to prevent brute force
+  const authApp = new Hono();
+  authApp.use("/*", rateLimiter({ windowMs: 60_000, max: 10 }));
+  authApp.route("/", v1AuthRoutes({ sessionConfig }));
+  app.route("/api/v1", authApp);
+
+  // Authenticated v1 routes — apply auth resolver middleware
+  const v1 = new Hono();
+  v1.use("/*", authResolver({ keyStore, sessionConfig }));
+
+  // Read-scope routes
+  const readRoutes = new Hono();
+  readRoutes.use("/*", requireScope("read"));
+  readRoutes.route("/", v1SignalRoutes({ signalRunner, signalSubscriber: stationSignalSub }));
+  readRoutes.route("/", v1RunRoutes({ signalRunner, signalAdapter, logBuffer, logStore }));
+  readRoutes.route("/", v1BroadcastRoutes({ broadcastRunner, broadcastAdapter, broadcastSubscriber: stationBroadcastSub }));
+  readRoutes.route("/", v1EventRoutes({ sseHub }));
+  v1.route("/", readRoutes);
+
+  // Trigger-scope routes
+  const triggerRoutes = new Hono();
+  triggerRoutes.use("/*", requireScope("trigger"));
+  triggerRoutes.route("/", v1TriggerRoutes({ signalRunner, signalAdapter, broadcastRunner, signalSubscriber: stationSignalSub }));
+  v1.route("/", triggerRoutes);
+
+  // Cancel-scope routes — only the cancel endpoints
+  const cancelRoutes = new Hono();
+  cancelRoutes.use("/*", requireScope("cancel"));
+  cancelRoutes.post("/runs/:id/cancel", async (c) => {
+    const id = c.req.param("id");
+    if (!signalRunner) {
+      return c.json({ error: "unavailable", message: "Station is in read-only mode." }, 503);
+    }
+    const success = await signalRunner.cancel(id);
+    if (!success) {
+      return c.json({ error: "cannot_cancel", message: "Run cannot be cancelled." }, 400);
+    }
+    return c.json({ data: { cancelled: true } });
+  });
+  cancelRoutes.post("/broadcast-runs/:id/cancel", async (c) => {
+    const id = c.req.param("id");
+    if (!broadcastRunner) {
+      return c.json({ error: "unavailable", message: "Station is in read-only mode." }, 503);
+    }
+    const success = await broadcastRunner.cancel(id);
+    if (!success) {
+      return c.json({ error: "cannot_cancel", message: "Broadcast run cannot be cancelled." }, 400);
+    }
+    return c.json({ data: { cancelled: true } });
+  });
+  v1.route("/", cancelRoutes);
+
+  // Admin-scope routes
+  const adminRoutes = new Hono();
+  adminRoutes.use("/*", requireScope("admin"));
+  adminRoutes.route("/", v1KeyRoutes({ keyStore }));
+  v1.route("/", adminRoutes);
+
+  app.route("/api/v1", v1);
+
+  let httpServer: Server | null = null;
+
+  return {
+    async start() {
+      // Start runners (non-blocking — they have internal poll loops)
+      if (config.runRunners) {
+        if (signalRunner) {
+          signalRunner.start().catch((err: unknown) => {
+            console.error("[station] Signal runner error:", err);
+          });
+        }
+        if (broadcastRunner) {
+          broadcastRunner.start().catch((err: unknown) => {
+            console.error("[station] Broadcast runner error:", err);
+          });
+        }
+      }
+
+      // Start Hono server
+      httpServer = serve(
+        { fetch: app.fetch, port: config.port, hostname: config.host },
+        (info) => {
+          console.log(`[station] API server on http://${config.host}:${info.port}`);
+        },
+      ) as unknown as Server;
+
+      // Attach WebSocket to the HTTP server
+      wsHub.attach(httpServer);
+    },
+
+    async stop() {
+      // Stop broadcast runner first — it queries the DB during graceful shutdown
+      if (broadcastRunner) {
+        await broadcastRunner.stop({ graceful: true, timeoutMs: 5000 });
+      }
+      if (signalRunner) {
+        await signalRunner.stop({ graceful: true, timeoutMs: 5000 });
+      }
+      wsHub.close();
+      sseHub.close();
+      logStore.close();
+      keyStore?.close();
+      if (httpServer) {
+        httpServer.close();
+      }
+    },
+  };
+}

package/src/server/log-buffer.ts

@@ -0,0 +1,43 @@
+export interface LogEntry {
+  runId: string;
+  signalName: string;
+  level: "stdout" | "stderr";
+  message: string;
+  timestamp: string;
+}
+
+export class LogBuffer {
+  private logs = new Map<string, LogEntry[]>();
+  private maxPerRun: number;
+  private maxRuns: number;
+
+  constructor(opts?: { maxPerRun?: number; maxRuns?: number }) {
+    this.maxPerRun = opts?.maxPerRun ?? 2000;
+    this.maxRuns = opts?.maxRuns ?? 500;
+  }
+
+  add(entry: LogEntry): void {
+    let entries = this.logs.get(entry.runId);
+    if (!entries) {
+      entries = [];
+      this.logs.set(entry.runId, entries);
+      // Prune oldest runs if over capacity
+      if (this.logs.size > this.maxRuns) {
+        const firstKey = this.logs.keys().next().value;
+        if (firstKey) this.logs.delete(firstKey);
+      }
+    }
+    entries.push(entry);
+    if (entries.length > this.maxPerRun) {
+      entries.shift();
+    }
+  }
+
+  get(runId: string): LogEntry[] {
+    return this.logs.get(runId) ?? [];
+  }
+
+  clear(): void {
+    this.logs.clear();
+  }
+}