heyhank 0.1.0

package/server/event-bus.ts

@@ -0,0 +1,124 @@
+// Zero-dependency, strongly-typed internal event bus for the HeyHank server.
+
+import type { HeyHankEventMap } from "./event-bus-types.js";
+
+type EventHandler<T> = (payload: T) => void | Promise<void>;
+
+/**
+ * Generic typed event bus. Handlers are invoked synchronously; async handlers
+ * are fire-and-forget. Errors in handlers are caught and logged, never
+ * propagated to emitters.
+ */
+export class EventBus<
+  TMap extends Record<string, any> = HeyHankEventMap,
+> {
+  private handlers = new Map<keyof TMap, Set<EventHandler<any>>>();
+  private onceHandlers = new Map<keyof TMap, Set<EventHandler<any>>>();
+
+  /** Subscribe to an event. Returns an unsubscribe function. */
+  on<K extends keyof TMap>(
+    event: K,
+    handler: EventHandler<TMap[K]>,
+  ): () => void {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set());
+    }
+    this.handlers.get(event)!.add(handler);
+    return () => {
+      this.handlers.get(event)?.delete(handler);
+    };
+  }
+
+  /** Subscribe to an event; auto-unsubscribe after the first invocation. */
+  once<K extends keyof TMap>(
+    event: K,
+    handler: EventHandler<TMap[K]>,
+  ): () => void {
+    if (!this.onceHandlers.has(event)) {
+      this.onceHandlers.set(event, new Set());
+    }
+    this.onceHandlers.get(event)!.add(handler);
+    return () => {
+      this.onceHandlers.get(event)?.delete(handler);
+    };
+  }
+
+  /** Remove a specific handler for an event. */
+  off<K extends keyof TMap>(
+    event: K,
+    handler: EventHandler<TMap[K]>,
+  ): void {
+    this.handlers.get(event)?.delete(handler);
+    this.onceHandlers.get(event)?.delete(handler);
+  }
+
+  /**
+   * Emit an event to all subscribed handlers.
+   * Errors are caught and logged — never propagated to the emitter.
+   */
+  emit<K extends keyof TMap>(event: K, payload: TMap[K]): void {
+    const regular = this.handlers.get(event);
+    if (regular && regular.size > 0) {
+      const snapshot = [...regular];
+      for (const handler of snapshot) {
+        try {
+          const result = handler(payload);
+          if (result && typeof (result as Promise<void>).catch === "function") {
+            (result as Promise<void>).catch((err) => {
+              console.error(
+                `[event-bus] Async handler error for "${String(event)}":`,
+                err,
+              );
+            });
+          }
+        } catch (err) {
+          console.error(
+            `[event-bus] Handler error for "${String(event)}":`,
+            err,
+          );
+        }
+      }
+    }
+
+    const onces = this.onceHandlers.get(event);
+    if (onces && onces.size > 0) {
+      const snapshot = [...onces];
+      onces.clear();
+      for (const handler of snapshot) {
+        try {
+          const result = handler(payload);
+          if (result && typeof (result as Promise<void>).catch === "function") {
+            (result as Promise<void>).catch((err) => {
+              console.error(
+                `[event-bus] Async once-handler error for "${String(event)}":`,
+                err,
+              );
+            });
+          }
+        } catch (err) {
+          console.error(
+            `[event-bus] Once-handler error for "${String(event)}":`,
+            err,
+          );
+        }
+      }
+    }
+  }
+
+  /** Remove all handlers (useful for testing or shutdown). */
+  clear(): void {
+    this.handlers.clear();
+    this.onceHandlers.clear();
+  }
+
+  /** Return the number of handlers registered for an event. */
+  listenerCount<K extends keyof TMap>(event: K): number {
+    return (
+      (this.handlers.get(event)?.size ?? 0) +
+      (this.onceHandlers.get(event)?.size ?? 0)
+    );
+  }
+}
+
+/** Singleton bus instance for the HeyHank server. */
+export const heyHankBus = new EventBus<HeyHankEventMap>();

package/server/execution-store.ts

@@ -0,0 +1,170 @@
+// ─── Execution Store ────────────────────────────────────────────────────────
+// Persists AgentExecution records to disk as JSONL (one file per day).
+// Used by the Runs view to display execution history across server restarts.
+
+import { mkdirSync, appendFileSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { AgentExecution } from "./agent-types.js";
+
+const EXECUTIONS_DIR = join(homedir(), ".heyhank", "executions");
+
+export interface ExecutionQuery {
+  agentId?: string;
+  triggerType?: string;
+  status?: "running" | "success" | "error";
+  limit?: number;
+  offset?: number;
+}
+
+export interface ExecutionListResult {
+  executions: AgentExecution[];
+  total: number;
+}
+
+export class ExecutionStore {
+  private dir: string;
+  /** In-memory cache of recent executions for fast access */
+  private recentCache: AgentExecution[] = [];
+  private static readonly MAX_CACHE_SIZE = 200;
+
+  constructor(dir?: string) {
+    this.dir = dir || EXECUTIONS_DIR;
+    mkdirSync(this.dir, { recursive: true });
+    this.loadRecentIntoCache();
+  }
+
+  /** Append an execution record to the daily JSONL file and in-memory cache. */
+  append(execution: AgentExecution): void {
+    const filename = this.dailyFilename(execution.startedAt);
+    const filepath = join(this.dir, filename);
+
+    try {
+      appendFileSync(filepath, JSON.stringify(execution) + "\n", "utf-8");
+    } catch (err) {
+      console.error("[execution-store] Failed to append execution:", err);
+    }
+
+    // Update cache
+    this.recentCache.unshift(execution);
+    if (this.recentCache.length > ExecutionStore.MAX_CACHE_SIZE) {
+      this.recentCache.length = ExecutionStore.MAX_CACHE_SIZE;
+    }
+  }
+
+  /** Update an existing execution in the cache and persist to disk. */
+  update(sessionId: string, updates: Partial<AgentExecution>): void {
+    const idx = this.recentCache.findIndex((e) => e.sessionId === sessionId);
+    if (idx < 0) {
+      console.warn(`[execution-store] update() called for unknown sessionId: ${sessionId} (not in cache)`);
+      return;
+    }
+    Object.assign(this.recentCache[idx], updates);
+    // Re-append the updated record to disk for durability.
+    // On next load, dedup by sessionId keeps the latest entry.
+    const updated = this.recentCache[idx];
+    const filename = this.dailyFilename(updated.startedAt);
+    const filepath = join(this.dir, filename);
+    try {
+      appendFileSync(filepath, JSON.stringify(updated) + "\n", "utf-8");
+    } catch (err) {
+      console.error("[execution-store] Failed to persist update:", err);
+    }
+  }
+
+  /** Query executions with pagination and filtering. */
+  list(opts?: ExecutionQuery): ExecutionListResult {
+    const limit = opts?.limit ?? 50;
+    const offset = opts?.offset ?? 0;
+
+    let filtered = this.getAllExecutions();
+
+    if (opts?.agentId) {
+      filtered = filtered.filter((e) => e.agentId === opts.agentId);
+    }
+    if (opts?.triggerType) {
+      filtered = filtered.filter((e) => e.triggerType === opts.triggerType);
+    }
+    if (opts?.status) {
+      filtered = filtered.filter((e) => {
+        if (opts.status === "running") return !e.completedAt;
+        if (opts.status === "success") return e.success === true;
+        if (opts.status === "error") return e.error !== undefined;
+        return true;
+      });
+    }
+
+    // Sort by startedAt descending (most recent first)
+    filtered.sort((a, b) => b.startedAt - a.startedAt);
+
+    const total = filtered.length;
+    const executions = filtered.slice(offset, offset + limit);
+
+    return { executions, total };
+  }
+
+  /** Get all executions from cache + disk. */
+  private getAllExecutions(): AgentExecution[] {
+    // For now, use the in-memory cache which is loaded from disk on startup.
+    // This is fast and sufficient for the Runs view.
+    return [...this.recentCache];
+  }
+
+  /** Load recent executions from disk into cache on startup. */
+  private loadRecentIntoCache(): void {
+    try {
+      const files = readdirSync(this.dir)
+        .filter((f) => f.startsWith("executions-") && f.endsWith(".jsonl"))
+        .sort()
+        .reverse(); // Most recent day first
+
+      const allLoaded: AgentExecution[] = [];
+
+      for (const file of files) {
+        if (allLoaded.length >= ExecutionStore.MAX_CACHE_SIZE * 2) break;
+
+        const filepath = join(this.dir, file);
+        const content = readFileSync(filepath, "utf-8");
+        const lines = content.trim().split("\n").filter(Boolean);
+
+        // Parse lines in reverse (most recent last in file = most up-to-date)
+        for (let i = lines.length - 1; i >= 0; i--) {
+          try {
+            const execution = JSON.parse(lines[i]) as AgentExecution;
+            allLoaded.push(execution);
+          } catch {
+            // Skip malformed lines
+          }
+        }
+      }
+
+      // Dedup by sessionId: since we read most-recent-last first, the first
+      // occurrence of a sessionId is the most up-to-date version.
+      const seen = new Set<string>();
+      for (const exec of allLoaded) {
+        if (seen.has(exec.sessionId)) continue;
+        seen.add(exec.sessionId);
+        this.recentCache.push(exec);
+        if (this.recentCache.length >= ExecutionStore.MAX_CACHE_SIZE) break;
+      }
+    } catch (err) {
+      // Log errors that aren't simply "directory not found" (ENOENT)
+      if (err && typeof err === "object" && "code" in err && (err as { code: string }).code !== "ENOENT") {
+        console.error("[execution-store] Failed to load executions from disk:", err);
+      }
+    }
+  }
+
+  /** Generate a daily JSONL filename from a timestamp. */
+  private dailyFilename(timestamp: number): string {
+    const date = new Date(timestamp);
+    const yyyy = date.getUTCFullYear();
+    const mm = String(date.getUTCMonth() + 1).padStart(2, "0");
+    const dd = String(date.getUTCDate()).padStart(2, "0");
+    return `executions-${yyyy}-${mm}-${dd}.jsonl`;
+  }
+
+  get directory(): string {
+    return this.dir;
+  }
+}

package/server/federation/node-connection.ts

@@ -0,0 +1,190 @@
+// ─── Node Connection ──────────────────────────────────────────────────────────
+// Single outbound WebSocket to a peer node.
+// Modeled on server/relay-client.ts: auth frame, exponential backoff, ping/pong.
+
+import type { NodeConfig, NodeMessage, RemoteSessionSummary } from "./node-types.js";
+import { PROTOCOL_VERSION, PING_INTERVAL_MS, RECONNECT_MIN_MS, RECONNECT_MAX_MS } from "./node-types.js";
+import { getNodeIdentity } from "./node-store.js";
+import type { NodeManager } from "./node-manager.js";
+
+export class NodeConnection {
+  readonly config: NodeConfig;
+  private manager: NodeManager;
+  private ws: WebSocket | null = null;
+
+  remoteNodeId: string | null = null;
+  remoteName: string | null = null;
+  connected = false;
+  authenticated = false;
+  remoteSessions: RemoteSessionSummary[] = [];
+
+  private reconnectDelay = RECONNECT_MIN_MS;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private pingTimer: ReturnType<typeof setInterval> | null = null;
+  private lastPong = 0;
+  private destroyed = false;
+
+  constructor(config: NodeConfig, manager: NodeManager) {
+    this.config = config;
+    this.manager = manager;
+  }
+
+  connect(): void {
+    if (this.destroyed) return;
+    this.cleanup();
+
+    const wsUrl = this.config.url.replace(/^http/, "ws") + "/ws/node";
+    try {
+      this.ws = new WebSocket(wsUrl);
+    } catch (err) {
+      console.log(`[federation] WS create error for ${this.config.name}: ${err instanceof Error ? err.message : String(err)}`);
+      this.scheduleReconnect();
+      return;
+    }
+
+    this.ws.addEventListener("open", () => {
+      this.reconnectDelay = RECONNECT_MIN_MS;
+      const identity = getNodeIdentity();
+      this.sendMsg({
+        type: "auth",
+        nodeId: identity.nodeId,
+        name: identity.name,
+        secret: this.config.secret,
+        version: PROTOCOL_VERSION,
+      });
+    });
+
+    this.ws.addEventListener("message", (event: MessageEvent) => {
+      try {
+        const msg = JSON.parse(typeof event.data === "string" ? event.data : String(event.data)) as NodeMessage;
+        this.handleMessage(msg);
+      } catch { /* malformed */ }
+    });
+
+    this.ws.addEventListener("close", () => {
+      this.onDisconnect();
+    });
+
+    this.ws.addEventListener("error", () => {
+      // Close event follows — reconnect handled there
+    });
+  }
+
+  private handleMessage(msg: NodeMessage): void {
+    if (msg.type === "auth_ok") {
+      this.authenticated = true;
+      this.connected = true;
+      this.remoteNodeId = msg.nodeId;
+      this.remoteName = msg.name;
+      this.lastPong = Date.now();
+      this.startPing();
+      console.log(`[federation] Connected to ${this.remoteName} (${this.remoteNodeId})`);
+      this.sendMsg({ type: "sessions_request" });
+      this.manager.onNodeConnected(this);
+      return;
+    }
+
+    if (msg.type === "auth_error") {
+      console.log(`[federation] Auth rejected by ${this.config.name}: ${msg.error}`);
+      // Don't reconnect on auth failure — secret is wrong
+      this.destroy();
+      return;
+    }
+
+    if (!this.authenticated) return;
+
+    switch (msg.type) {
+      case "pong":
+        this.lastPong = Date.now();
+        break;
+      case "ping":
+        this.sendMsg({ type: "pong" });
+        break;
+      case "sessions_request":
+        this.sendMsg({
+          type: "sessions_sync",
+          sessions: this.manager.getLocalSessionSummaries(),
+        });
+        break;
+      case "sessions_sync":
+        this.remoteSessions = msg.sessions ?? [];
+        this.manager.onSessionsUpdated();
+        break;
+      case "session_proxy":
+        this.manager.handleProxyRequest(this, msg);
+        break;
+      case "session_proxy_response":
+        if (msg.requestId) {
+          this.manager.resolveProxy(msg.requestId, msg);
+        }
+        break;
+    }
+  }
+
+  sendMsg(msg: NodeMessage): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(msg));
+    }
+  }
+
+  private startPing(): void {
+    this.stopPing();
+    this.pingTimer = setInterval(() => {
+      if (Date.now() - this.lastPong > PING_INTERVAL_MS * 3) {
+        console.log(`[federation] Ping timeout for ${this.config.name}`);
+        this.ws?.close();
+        return;
+      }
+      this.sendMsg({ type: "ping" });
+    }, PING_INTERVAL_MS);
+  }
+
+  private stopPing(): void {
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
+  }
+
+  private onDisconnect(): void {
+    const wasConnected = this.connected;
+    this.connected = false;
+    this.authenticated = false;
+    this.stopPing();
+    this.cleanup();
+    if (wasConnected) {
+      console.log(`[federation] Disconnected from ${this.config.name}`);
+      this.manager.onNodeDisconnected(this);
+    }
+    if (!this.destroyed) this.scheduleReconnect();
+  }
+
+  private scheduleReconnect(): void {
+    if (this.destroyed || this.reconnectTimer) return;
+    const jitter = Math.random() * 500;
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.reconnectDelay = Math.min(this.reconnectDelay * 2, RECONNECT_MAX_MS);
+      this.connect();
+    }, this.reconnectDelay + jitter);
+  }
+
+  private cleanup(): void {
+    if (this.ws) {
+      try { this.ws.close(); } catch { /* ignore */ }
+      this.ws = null;
+    }
+  }
+
+  destroy(): void {
+    this.destroyed = true;
+    this.stopPing();
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.cleanup();
+    this.connected = false;
+    this.authenticated = false;
+  }
+}