heyhank 0.1.0

package/server/novnc-proxy.ts

@@ -0,0 +1,99 @@
+import type { ServerWebSocket } from "bun";
+import type { SocketData } from "./ws-bridge-types.js";
+import { containerManager } from "./container-manager.js";
+
+const NOVNC_CONTAINER_PORT = 6080;
+
+interface ProxyPair {
+  browserWs: ServerWebSocket<SocketData>;
+  upstreamWs: WebSocket;
+}
+
+/**
+ * Proxies noVNC WebSocket traffic between the user's browser and the
+ * container's websockify server. This allows the noVNC client to connect
+ * through HeyHank's single port instead of requiring direct access
+ * to the container's mapped port.
+ */
+export class NoVncProxy {
+  private pairs = new Map<ServerWebSocket<SocketData>, ProxyPair>();
+
+  handleOpen(ws: ServerWebSocket<SocketData>, sessionId: string): void {
+    const container = containerManager.getContainer(sessionId);
+    if (!container) {
+      console.warn(`[novnc-proxy] No container found for session ${sessionId}`);
+      ws.close(1011, "Container not found");
+      return;
+    }
+
+    const portMapping = container.portMappings.find(
+      (p) => p.containerPort === NOVNC_CONTAINER_PORT,
+    );
+    if (!portMapping) {
+      console.warn(`[novnc-proxy] No noVNC port mapping for session ${sessionId}`);
+      ws.close(1011, "noVNC port not mapped");
+      return;
+    }
+
+    // Connect to the container's websockify server
+    const upstreamUrl = `ws://127.0.0.1:${portMapping.hostPort}`;
+    const upstream = new WebSocket(upstreamUrl, ["binary"]);
+    upstream.binaryType = "arraybuffer";
+
+    const pair: ProxyPair = { browserWs: ws, upstreamWs: upstream };
+    this.pairs.set(ws, pair);
+
+    upstream.addEventListener("open", () => {
+      console.log(`[novnc-proxy] Upstream connected for session ${sessionId}`);
+    });
+
+    upstream.addEventListener("message", (event) => {
+      try {
+        if (event.data instanceof ArrayBuffer) {
+          ws.send(new Uint8Array(event.data));
+        } else {
+          ws.send(event.data);
+        }
+      } catch {
+        // Browser socket may have closed
+      }
+    });
+
+    upstream.addEventListener("close", () => {
+      this.pairs.delete(ws);
+      try { ws.close(); } catch { /* already closed */ }
+    });
+
+    upstream.addEventListener("error", (err) => {
+      console.error(`[novnc-proxy] Upstream error for session ${sessionId}:`, err);
+      this.pairs.delete(ws);
+      try { ws.close(1011, "Upstream connection failed"); } catch { /* already closed */ }
+    });
+  }
+
+  handleMessage(ws: ServerWebSocket<SocketData>, msg: string | Buffer): void {
+    const pair = this.pairs.get(ws);
+    if (!pair) return;
+
+    const { upstreamWs } = pair;
+    if (upstreamWs.readyState !== WebSocket.OPEN) return;
+
+    try {
+      upstreamWs.send(msg instanceof Buffer ? new Uint8Array(msg) : msg);
+    } catch {
+      // Upstream may have closed
+    }
+  }
+
+  handleClose(ws: ServerWebSocket<SocketData>): void {
+    const pair = this.pairs.get(ws);
+    if (!pair) return;
+
+    this.pairs.delete(ws);
+    try {
+      pair.upstreamWs.close();
+    } catch {
+      // Already closed
+    }
+  }
+}

package/server/path-resolver.ts

@@ -0,0 +1,186 @@
+/**
+ * PATH discovery and binary resolution for service environments.
+ *
+ * When HeyHank runs as a macOS launchd or Linux systemd service, it inherits
+ * a restricted PATH that omits directories from version managers (nvm, fnm, volta,
+ * mise, etc.) and user-local installs (~/.local/bin, ~/.cargo/bin). This module
+ * captures the user's real shell PATH at runtime and provides binary resolution
+ * that works regardless of how the server was started.
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Capture the user's full interactive shell PATH by spawning a login shell.
+ * This picks up all version manager initializations (nvm, fnm, volta, mise, etc.).
+ * Falls back to probing common directories if shell sourcing fails.
+ */
+export function captureUserShellPath(): string {
+  try {
+    const shell = process.env.SHELL || "/bin/bash";
+    const captured = execSync(
+      `${shell} -lic 'echo "___PATH_START___$PATH___PATH_END___"'`,
+      {
+        encoding: "utf-8",
+        timeout: 10_000,
+        env: { HOME: homedir(), USER: process.env.USER, SHELL: shell },
+      },
+    );
+    const match = captured.match(/___PATH_START___(.+)___PATH_END___/);
+    if (match?.[1]) {
+      return match[1];
+    }
+  } catch {
+    // Shell sourcing failed (timeout, compinit prompt, etc.)
+  }
+
+  return buildFallbackPath();
+}
+
+/**
+ * Build a PATH by probing common binary installation directories.
+ * Used as fallback when shell-sourcing fails.
+ */
+export function buildFallbackPath(): string {
+  const home = homedir();
+  const candidates = [
+    // Standard system paths
+    "/opt/homebrew/bin",
+    "/opt/homebrew/sbin",
+    "/usr/local/bin",
+    "/usr/bin",
+    "/bin",
+    "/usr/sbin",
+    "/sbin",
+    // Bun
+    join(home, ".bun", "bin"),
+    // Claude CLI / user-local installs
+    join(home, ".local", "bin"),
+    // Cargo / Rust
+    join(home, ".cargo", "bin"),
+    // Volta (Node version manager)
+    join(home, ".volta", "bin"),
+    // mise (formerly rtx)
+    join(home, ".local", "share", "mise", "shims"),
+    // pyenv
+    join(home, ".pyenv", "bin"),
+    join(home, ".pyenv", "shims"),
+    // Go
+    join(home, "go", "bin"),
+    "/usr/local/go/bin",
+    // Deno
+    join(home, ".deno", "bin"),
+  ];
+
+  // Probe nvm-managed node versions
+  const nvmDir = process.env.NVM_DIR || join(home, ".nvm");
+  const nvmVersionsDir = join(nvmDir, "versions", "node");
+  if (existsSync(nvmVersionsDir)) {
+    try {
+      for (const v of readdirSync(nvmVersionsDir)) {
+        candidates.push(join(nvmVersionsDir, v, "bin"));
+      }
+    } catch { /* ignore */ }
+  }
+
+  // fnm (Fast Node Manager) — versions stored in fnm multishell or XDG data
+  const fnmDir = join(home, "Library", "Application Support", "fnm", "node-versions");
+  if (existsSync(fnmDir)) {
+    try {
+      for (const v of readdirSync(fnmDir)) {
+        candidates.push(join(fnmDir, v, "installation", "bin"));
+      }
+    } catch { /* ignore */ }
+  }
+
+  const pathSep = process.platform === "win32" ? ";" : ":";
+  return [...new Set(candidates.filter((dir) => existsSync(dir)))].join(pathSep);
+}
+
+// ─── Enriched PATH (cached) ───────────────────────────────────────────────────
+
+let _cachedPath: string | null = null;
+
+/**
+ * Returns an enriched PATH that merges the user's shell PATH (or probed common
+ * directories) with the current process PATH. Deduplicates entries.
+ * Result is cached after the first call.
+ */
+export function getEnrichedPath(): string {
+  if (_cachedPath) return _cachedPath;
+
+  const currentPath = process.env.PATH || "";
+  const userPath = captureUserShellPath();
+  const pathSep = process.platform === "win32" ? ";" : ":";
+
+  // Merge: user shell PATH first (takes precedence), then current process PATH
+  const allDirs = [...userPath.split(pathSep), ...currentPath.split(pathSep)];
+  const seen = new Set<string>();
+  const deduped: string[] = [];
+  for (const dir of allDirs) {
+    if (dir && !seen.has(dir)) {
+      seen.add(dir);
+      deduped.push(dir);
+    }
+  }
+
+  _cachedPath = deduped.join(pathSep);
+  return _cachedPath;
+}
+
+/** Reset the cached PATH (for testing). */
+export function _resetPathCache(): void {
+  _cachedPath = null;
+}
+
+// ─── Binary resolution ────────────────────────────────────────────────────────
+
+/**
+ * Resolve a binary name to an absolute path using the enriched PATH.
+ * Returns null if the binary is not found anywhere.
+ */
+export function resolveBinary(name: string): string | null {
+  if (name.startsWith("/")) {
+    return existsSync(name) ? name : null;
+  }
+  // On Windows, also accept absolute paths like C:\... or D:\...
+  if (process.platform === "win32" && /^[a-zA-Z]:[/\\]/.test(name)) {
+    return existsSync(name) ? name : null;
+  }
+
+  const sanitized = name.replace(/[^a-zA-Z0-9._@/-]/g, "");
+  const enrichedPath = getEnrichedPath();
+
+  // Try `where` first on Windows (returns native Win32 paths), then `which` as fallback
+  const commands = process.platform === "win32" ? ["where", "which"] : ["which"];
+  for (const cmd of commands) {
+    try {
+      const result = execSync(`${cmd} ${sanitized}`, {
+        encoding: "utf-8",
+        timeout: 5_000,
+        env: { ...process.env, PATH: enrichedPath },
+      }).trim();
+      if (!result) continue;
+      // `where` on Windows may return multiple lines; prefer .cmd for Bun.spawn compatibility
+      if (cmd === "where") {
+        const lines = result.split(/\r?\n/).filter(Boolean);
+        return lines.find(l => l.endsWith(".cmd")) || lines[0];
+      }
+      return result;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Returns a PATH string suitable for embedding in service definitions
+ * (plist/systemd unit). Captures the user's shell PATH at install time.
+ */
+export function getServicePath(): string {
+  return getEnrichedPath();
+}

package/server/paths.ts

@@ -0,0 +1,13 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Base directory for all HeyHank configuration and state.
+ * Defaults to ~/.heyhank/ for self-hosted installs.
+ * Override with HEYHANK_HOME env var for managed deployments
+ * (e.g. HEYHANK_HOME=/data/heyhank on Fly.io volumes).
+ * Falls back to COMPANION_HOME for backward compatibility.
+ */
+export const HEYHANK_HOME =
+  process.env.HEYHANK_HOME || process.env.COMPANION_HOME || join(homedir(), ".heyhank");
+

package/server/pr-poller.ts

@@ -0,0 +1,162 @@
+import { fetchPRInfoAsync, computeAdaptiveTTL, type GitHubPRInfo } from "./github-pr.js";
+import type { WsBridge } from "./ws-bridge.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+interface WatchedPR {
+  cwd: string;
+  branch: string;
+  /** Sessions interested in this PR (same cwd:branch may be shared) */
+  sessionIds: Set<string>;
+  lastData: GitHubPRInfo | null;
+  timer: ReturnType<typeof setTimeout> | null;
+  lastFetchTime: number;
+  currentInterval: number;
+  fetching: boolean;
+}
+
+// ─── PR Poller ───────────────────────────────────────────────────────────────
+
+/**
+ * Server-side poller that fetches GitHub PR status at adaptive intervals
+ * and pushes updates to browsers via WebSocket.
+ *
+ * One timer per unique cwd:branch — shared across sessions on the same branch.
+ */
+export class PRPoller {
+  private watched = new Map<string, WatchedPR>();
+  private wsBridge: WsBridge;
+  /** Reverse index: sessionId → cwd:branch key (a session can only watch one PR at a time) */
+  private sessionToKey = new Map<string, string>();
+
+  constructor(wsBridge: WsBridge) {
+    this.wsBridge = wsBridge;
+  }
+
+  /**
+   * Start watching a PR for a session.
+   * Returns cached data immediately if available.
+   * Triggers an async fetch if cache is stale or missing.
+   */
+  watch(sessionId: string, cwd: string, branch: string): GitHubPRInfo | null {
+    const key = `${cwd}:${branch}`;
+
+    // If this session was watching a different PR, unregister from the old one
+    const prevKey = this.sessionToKey.get(sessionId);
+    if (prevKey && prevKey !== key) {
+      this.unwatchKey(sessionId, prevKey);
+    }
+    this.sessionToKey.set(sessionId, key);
+
+    const existing = this.watched.get(key);
+    if (existing) {
+      existing.sessionIds.add(sessionId);
+      // If cache is stale, trigger a refresh
+      if (Date.now() - existing.lastFetchTime > existing.currentInterval) {
+        this.fetchAndBroadcast(key);
+      }
+      return existing.lastData;
+    }
+
+    // New watch — create entry and fetch immediately
+    const entry: WatchedPR = {
+      cwd,
+      branch,
+      sessionIds: new Set([sessionId]),
+      lastData: null,
+      timer: null,
+      lastFetchTime: 0,
+      currentInterval: 10_000, // start aggressive for fast initial load
+      fetching: false,
+    };
+    this.watched.set(key, entry);
+    this.fetchAndBroadcast(key);
+
+    return null;
+  }
+
+  /** Stop watching for a specific session. */
+  unwatch(sessionId: string): void {
+    const key = this.sessionToKey.get(sessionId);
+    if (!key) return;
+    this.sessionToKey.delete(sessionId);
+    this.unwatchKey(sessionId, key);
+  }
+
+  /** Get current cached data for a cwd:branch pair (for REST fallback). */
+  getCached(cwd: string, branch: string): { available: boolean; pr: GitHubPRInfo | null } | null {
+    const key = `${cwd}:${branch}`;
+    const entry = this.watched.get(key);
+    if (!entry) return null;
+    return { available: true, pr: entry.lastData };
+  }
+
+  /** Stop all timers (for testing / cleanup). */
+  destroy(): void {
+    for (const entry of this.watched.values()) {
+      if (entry.timer) clearTimeout(entry.timer);
+    }
+    this.watched.clear();
+    this.sessionToKey.clear();
+  }
+
+  // ─── Internal ──────────────────────────────────────────────────────────
+
+  private unwatchKey(sessionId: string, key: string): void {
+    const entry = this.watched.get(key);
+    if (!entry) return;
+    entry.sessionIds.delete(sessionId);
+    if (entry.sessionIds.size === 0) {
+      if (entry.timer) clearTimeout(entry.timer);
+      this.watched.delete(key);
+    }
+  }
+
+  private async fetchAndBroadcast(key: string): Promise<void> {
+    const entry = this.watched.get(key);
+    if (!entry) return;
+
+    // Prevent concurrent fetches for the same key
+    if (entry.fetching) return;
+    entry.fetching = true;
+
+    // Clear existing timer (will be rescheduled after fetch)
+    if (entry.timer) {
+      clearTimeout(entry.timer);
+      entry.timer = null;
+    }
+
+    try {
+      const prInfo = await fetchPRInfoAsync(entry.cwd, entry.branch);
+      // Re-check entry still exists (may have been unwatched during async fetch)
+      const current = this.watched.get(key);
+      if (!current) return;
+
+      current.lastData = prInfo;
+      current.lastFetchTime = Date.now();
+      current.currentInterval = computeAdaptiveTTL(prInfo);
+
+      // Push to all sessions watching this PR
+      for (const sessionId of current.sessionIds) {
+        this.wsBridge.broadcastToSession(sessionId, {
+          type: "pr_status_update",
+          pr: prInfo,
+          available: true,
+        });
+      }
+    } catch {
+      // On error, use a moderate interval
+      const current = this.watched.get(key);
+      if (current) {
+        current.currentInterval = 30_000;
+      }
+    } finally {
+      const current = this.watched.get(key);
+      if (current) {
+        current.fetching = false;
+        // Schedule next fetch
+        current.timer = setTimeout(() => this.fetchAndBroadcast(key), current.currentInterval);
+      }
+    }
+  }
+}

package/server/prompt-manager.ts

@@ -0,0 +1,211 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { HEYHANK_HOME } from "./paths.js";
+
+export type PromptScope = "global" | "project";
+
+export interface SavedPrompt {
+  id: string;
+  name: string;
+  content: string;
+  scope: PromptScope;
+  projectPath?: string;
+  projectPaths?: string[];
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface PromptUpdateFields {
+  name?: string;
+  content?: string;
+  scope?: PromptScope;
+  projectPaths?: string[];
+}
+
+const PROMPTS_FILE = join(HEYHANK_HOME, "prompts.json");
+
+function ensureDir(): void {
+  mkdirSync(HEYHANK_HOME, { recursive: true });
+}
+
+function normalizePath(path: string): string {
+  return resolve(path).replace(/[\\/]+$/, "");
+}
+
+function loadPrompts(): SavedPrompt[] {
+  ensureDir();
+  if (!existsSync(PROMPTS_FILE)) return [];
+  try {
+    const raw = readFileSync(PROMPTS_FILE, "utf-8");
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((p): p is SavedPrompt => {
+      if (!p || typeof p !== "object") return false;
+      const candidate = p as Partial<SavedPrompt>;
+      return (
+        typeof candidate.id === "string"
+        && typeof candidate.name === "string"
+        && typeof candidate.content === "string"
+        && (candidate.scope === "global" || candidate.scope === "project")
+      );
+    });
+  } catch {
+    return [];
+  }
+}
+
+function savePrompts(prompts: SavedPrompt[]): void {
+  ensureDir();
+  writeFileSync(PROMPTS_FILE, JSON.stringify(prompts, null, 2), "utf-8");
+}
+
+function sortPrompts(prompts: SavedPrompt[]): SavedPrompt[] {
+  return [...prompts].sort((a, b) => b.updatedAt - a.updatedAt || a.name.localeCompare(b.name));
+}
+
+function visibleForCwd(prompt: SavedPrompt, cwd: string): boolean {
+  if (prompt.scope === "global") return true;
+  const paths = resolveProjectPaths(prompt);
+  if (paths.length === 0) return false;
+  const normalizedCwd = normalizePath(cwd);
+  return paths.some((p) => {
+    const normalizedProject = normalizePath(p);
+    return normalizedCwd === normalizedProject || normalizedCwd.startsWith(`${normalizedProject}/`);
+  });
+}
+
+/** Merges legacy projectPath and projectPaths into a single deduplicated list. */
+function resolveProjectPaths(prompt: SavedPrompt): string[] {
+  const paths: string[] = [];
+  if (prompt.projectPaths && prompt.projectPaths.length > 0) {
+    paths.push(...prompt.projectPaths);
+  }
+  if (prompt.projectPath && !paths.some((p) => normalizePath(p) === normalizePath(prompt.projectPath!))) {
+    paths.push(prompt.projectPath);
+  }
+  return paths;
+}
+
+export function listPrompts(opts?: { cwd?: string; scope?: "global" | "project" | "all" }): SavedPrompt[] {
+  const prompts = loadPrompts();
+  const scope = opts?.scope ?? "all";
+
+  const filteredByScope = prompts.filter((p) => {
+    if (scope === "all") return true;
+    return p.scope === scope;
+  });
+
+  if (!opts?.cwd) return sortPrompts(filteredByScope);
+
+  return sortPrompts(filteredByScope.filter((p) => visibleForCwd(p, opts.cwd!)));
+}
+
+export function getPrompt(id: string): SavedPrompt | null {
+  return loadPrompts().find((p) => p.id === id) ?? null;
+}
+
+export function createPrompt(
+  name: string,
+  content: string,
+  scope: PromptScope,
+  projectPath?: string,
+  projectPaths?: string[],
+): SavedPrompt {
+  const cleanName = name?.trim();
+  const cleanContent = content?.trim();
+  if (!cleanName) throw new Error("Prompt name is required");
+  if (!cleanContent) throw new Error("Prompt content is required");
+  if (scope !== "global" && scope !== "project") throw new Error("Invalid prompt scope");
+
+  // Merge projectPaths and legacy projectPath into a single deduplicated list
+  const mergedPaths = dedupeAndNormalizePaths(projectPaths, projectPath);
+  if (scope === "project" && mergedPaths.length === 0) {
+    throw new Error("Project path is required for project prompts");
+  }
+
+  const prompts = loadPrompts();
+  const now = Date.now();
+  const prompt: SavedPrompt = {
+    id: crypto.randomUUID(),
+    name: cleanName,
+    content: cleanContent,
+    scope,
+    projectPath: scope === "project" ? mergedPaths[0] : undefined,
+    projectPaths: scope === "project" ? mergedPaths : undefined,
+    createdAt: now,
+    updatedAt: now,
+  };
+  prompts.push(prompt);
+  savePrompts(prompts);
+  return prompt;
+}
+
+function dedupeAndNormalizePaths(paths?: string[], legacyPath?: string): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  const all = [...(paths ?? []), ...(legacyPath?.trim() ? [legacyPath] : [])];
+  for (const p of all) {
+    const trimmed = p.trim();
+    if (!trimmed) continue;
+    const normalized = normalizePath(trimmed);
+    if (!seen.has(normalized)) {
+      seen.add(normalized);
+      result.push(normalized);
+    }
+  }
+  return result;
+}
+
+export function updatePrompt(id: string, updates: PromptUpdateFields): SavedPrompt | null {
+  const prompts = loadPrompts();
+  const index = prompts.findIndex((p) => p.id === id);
+  if (index < 0) return null;
+
+  if (updates.name !== undefined && !updates.name.trim()) {
+    throw new Error("Prompt name cannot be empty");
+  }
+  if (updates.content !== undefined && !updates.content.trim()) {
+    throw new Error("Prompt content cannot be empty");
+  }
+
+  const newScope = updates.scope ?? prompts[index].scope;
+  if (updates.scope !== undefined && updates.scope !== "global" && updates.scope !== "project") {
+    throw new Error("Invalid prompt scope");
+  }
+
+  let newProjectPaths = prompts[index].projectPaths;
+  let newProjectPath = prompts[index].projectPath;
+  if (updates.projectPaths !== undefined) {
+    const normalized = dedupeAndNormalizePaths(updates.projectPaths);
+    newProjectPaths = normalized.length > 0 ? normalized : undefined;
+    newProjectPath = normalized.length > 0 ? normalized[0] : undefined;
+  }
+  if (newScope === "project" && (!newProjectPaths || newProjectPaths.length === 0)) {
+    throw new Error("Project path is required for project prompts");
+  }
+  if (newScope === "global") {
+    newProjectPaths = undefined;
+    newProjectPath = undefined;
+  }
+
+  const updated: SavedPrompt = {
+    ...prompts[index],
+    name: updates.name !== undefined ? updates.name.trim() : prompts[index].name,
+    content: updates.content !== undefined ? updates.content.trim() : prompts[index].content,
+    scope: newScope,
+    projectPath: newProjectPath,
+    projectPaths: newProjectPaths,
+    updatedAt: Date.now(),
+  };
+  prompts[index] = updated;
+  savePrompts(prompts);
+  return updated;
+}
+
+export function deletePrompt(id: string): boolean {
+  const prompts = loadPrompts();
+  const next = prompts.filter((p) => p.id !== id);
+  if (next.length === prompts.length) return false;
+  savePrompts(next);
+  return true;
+}

package/server/protocol/claude-upstream/README.md

@@ -0,0 +1,19 @@
+# Claude Upstream Snapshot
+
+This folder contains an offline snapshot of the official Claude Agent SDK TypeScript
+surface used by the bridge compatibility tests.
+
+Source package:
+- `@anthropic-ai/claude-agent-sdk@0.2.41`
+- tarball: `https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/-/claude-agent-sdk-0.2.41.tgz`
+
+Files:
+- `sdk.d.ts.txt` — copied from `package/sdk.d.ts` in the npm tarball
+
+Refresh command (example):
+```bash
+TARBALL=$(npm view @anthropic-ai/claude-agent-sdk dist.tarball)
+curl -fsSL "$TARBALL" -o /tmp/claude-agent-sdk.tgz
+tar -xzf /tmp/claude-agent-sdk.tgz -C /tmp package/sdk.d.ts
+cp /tmp/package/sdk.d.ts web/server/protocol/claude-upstream/sdk.d.ts.txt
+```