@creativeintelligence/abbie 0.1.0

package/src/lib/heartbeat.ts

@@ -0,0 +1,326 @@
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { createEvent, EventStore } from "./events.js";
+
+/**
+ * Session liveness state.
+ */
+export interface SessionLiveness {
+  session_id: string;
+  agent: string;
+  project: string;
+  issue?: string;
+  worktree?: string;
+  started_at: string;
+  last_heartbeat: string;
+  status: "active" | "idle" | "stale" | "dead";
+  current_task?: string;
+  pid?: number;
+}
+
+/**
+ * Heartbeat configuration.
+ */
+export interface HeartbeatConfig {
+  /** Heartbeat interval in milliseconds (default: 60000 = 1 min) */
+  interval_ms: number;
+  /** Time before session is considered stale (default: 300000 = 5 min) */
+  stale_threshold_ms: number;
+  /** Time before session is considered dead (default: 900000 = 15 min) */
+  dead_threshold_ms: number;
+}
+
+const DEFAULT_CONFIG: HeartbeatConfig = {
+  interval_ms: 60000,
+  stale_threshold_ms: 300000,
+  dead_threshold_ms: 900000,
+};
+
+/**
+ * Session heartbeat manager.
+ */
+export class HeartbeatManager {
+  private basePath: string;
+  private config: HeartbeatConfig;
+  private eventStore: EventStore;
+  private intervalId?: NodeJS.Timeout;
+
+  constructor(
+    basePath: string = "~/.abbie/sessions",
+    config: Partial<HeartbeatConfig> = {},
+    eventStore?: EventStore,
+  ) {
+    this.basePath = basePath.replace("~", process.env.HOME || "");
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.eventStore = eventStore || new EventStore();
+
+    if (!existsSync(this.basePath)) {
+      mkdirSync(this.basePath, { recursive: true });
+    }
+  }
+
+  /**
+   * Get the heartbeat file path for a session.
+   */
+  private getHeartbeatPath(sessionId: string): string {
+    const project = this.extractProject(sessionId);
+    const projectDir = join(this.basePath, project);
+    if (!existsSync(projectDir)) {
+      mkdirSync(projectDir, { recursive: true });
+    }
+    return join(projectDir, `${sessionId}.json`);
+  }
+
+  /**
+   * Register a new session.
+   */
+  register(
+    sessionId: string,
+    agent: string,
+    options: {
+      project: string;
+      issue?: string;
+      worktree?: string;
+      pid?: number;
+    },
+  ): SessionLiveness {
+    const now = new Date().toISOString();
+    const liveness: SessionLiveness = {
+      session_id: sessionId,
+      agent,
+      project: options.project,
+      issue: options.issue,
+      worktree: options.worktree,
+      started_at: now,
+      last_heartbeat: now,
+      status: "active",
+      pid: options.pid || process.pid,
+    };
+
+    writeFileSync(this.getHeartbeatPath(sessionId), JSON.stringify(liveness, null, 2));
+    return liveness;
+  }
+
+  /**
+   * Send a heartbeat for a session.
+   */
+  heartbeat(
+    sessionId: string,
+    options: {
+      status?: "active" | "idle";
+      current_task?: string;
+    } = {},
+  ): SessionLiveness | undefined {
+    const path = this.getHeartbeatPath(sessionId);
+    if (!existsSync(path)) {
+      return undefined;
+    }
+
+    const liveness: SessionLiveness = JSON.parse(readFileSync(path, "utf-8"));
+    liveness.last_heartbeat = new Date().toISOString();
+    liveness.status = options.status || "active";
+    liveness.current_task = options.current_task;
+
+    writeFileSync(path, JSON.stringify(liveness, null, 2));
+
+    // Also log to event store
+    this.eventStore.append(
+      createEvent.heartbeat(sessionId, liveness.agent, {
+        status: liveness.status,
+        current_task: liveness.current_task,
+      }),
+    );
+
+    return liveness;
+  }
+
+  /**
+   * Get session liveness state.
+   */
+  get(sessionId: string): SessionLiveness | undefined {
+    const path = this.getHeartbeatPath(sessionId);
+    if (!existsSync(path)) {
+      return undefined;
+    }
+
+    const liveness: SessionLiveness = JSON.parse(readFileSync(path, "utf-8"));
+    return this.updateStatus(liveness);
+  }
+
+  /**
+   * Update status based on heartbeat age.
+   */
+  private updateStatus(liveness: SessionLiveness): SessionLiveness {
+    const lastHeartbeat = new Date(liveness.last_heartbeat).getTime();
+    const now = Date.now();
+    const age = now - lastHeartbeat;
+
+    if (age > this.config.dead_threshold_ms) {
+      liveness.status = "dead";
+    } else if (age > this.config.stale_threshold_ms) {
+      liveness.status = "stale";
+    }
+
+    return liveness;
+  }
+
+  /**
+   * Deregister a session (on clean exit).
+   */
+  deregister(sessionId: string): void {
+    const path = this.getHeartbeatPath(sessionId);
+    if (existsSync(path)) {
+      unlinkSync(path);
+    }
+  }
+
+  /**
+   * List all sessions for a project.
+   */
+  listSessions(project: string): SessionLiveness[] {
+    const projectDir = join(this.basePath, project);
+    if (!existsSync(projectDir)) {
+      return [];
+    }
+
+    return readdirSync(projectDir)
+      .filter((f) => f.endsWith(".json"))
+      .map((f) => {
+        const path = join(projectDir, f);
+        const liveness: SessionLiveness = JSON.parse(readFileSync(path, "utf-8"));
+        return this.updateStatus(liveness);
+      });
+  }
+
+  /**
+   * List active sessions across all projects.
+   */
+  listActiveSessions(): SessionLiveness[] {
+    if (!existsSync(this.basePath)) {
+      return [];
+    }
+
+    const projects = readdirSync(this.basePath).filter((name) => {
+      const path = join(this.basePath, name);
+      return statSync(path).isDirectory();
+    });
+
+    const sessions: SessionLiveness[] = [];
+    for (const project of projects) {
+      sessions.push(...this.listSessions(project).filter((s) => s.status === "active"));
+    }
+
+    return sessions;
+  }
+
+  /**
+   * List stale/dead sessions for cleanup.
+   */
+  listStaleSessions(): SessionLiveness[] {
+    if (!existsSync(this.basePath)) {
+      return [];
+    }
+
+    const projects = readdirSync(this.basePath).filter((name) => {
+      const path = join(this.basePath, name);
+      return statSync(path).isDirectory();
+    });
+
+    const sessions: SessionLiveness[] = [];
+    for (const project of projects) {
+      sessions.push(
+        ...this.listSessions(project).filter((s) => s.status === "stale" || s.status === "dead"),
+      );
+    }
+
+    return sessions;
+  }
+
+  /**
+   * Clean up dead sessions.
+   */
+  cleanup(): number {
+    const staleSessions = this.listStaleSessions();
+    let cleaned = 0;
+
+    for (const session of staleSessions) {
+      if (session.status === "dead") {
+        this.deregister(session.session_id);
+        cleaned++;
+      }
+    }
+
+    return cleaned;
+  }
+
+  /**
+   * Check if a session is alive.
+   */
+  isAlive(sessionId: string): boolean {
+    const liveness = this.get(sessionId);
+    if (!liveness) return false;
+    return liveness.status === "active" || liveness.status === "idle";
+  }
+
+  /**
+   * Check if a worktree is in use.
+   */
+  isWorktreeInUse(worktree: string): SessionLiveness | undefined {
+    const activeSessions = this.listActiveSessions();
+    return activeSessions.find((s) => s.worktree === worktree);
+  }
+
+  /**
+   * Start automatic heartbeat for current session.
+   */
+  startAutoHeartbeat(sessionId: string, getCurrentTask?: () => string | undefined): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+    }
+
+    this.intervalId = setInterval(() => {
+      this.heartbeat(sessionId, {
+        status: "active",
+        current_task: getCurrentTask?.(),
+      });
+    }, this.config.interval_ms);
+
+    // Clean up on process exit
+    const cleanup = () => {
+      if (this.intervalId) {
+        clearInterval(this.intervalId);
+      }
+      this.deregister(sessionId);
+    };
+
+    process.on("exit", cleanup);
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+  }
+
+  /**
+   * Stop automatic heartbeat.
+   */
+  stopAutoHeartbeat(): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = undefined;
+    }
+  }
+
+  /**
+   * Extract project from session ID.
+   */
+  private extractProject(sessionId: string): string {
+    const parts = sessionId.split("-");
+    return parts[0];
+  }
+}

package/src/lib/hooks/adapters/claude.ts

@@ -0,0 +1,115 @@
+/**
+ * Claude Code hook adapter.
+ *
+ * Reads hooks from ~/.claude/settings.json
+ *
+ * Format:
+ * {
+ *   "hooks": {
+ *     "Stop": [{
+ *       "hooks": [{
+ *         "type": "command",
+ *         "command": "~/.claude/hooks/notify-stop.sh",
+ *         "timeout": 30
+ *       }]
+ *     }]
+ *   }
+ * }
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Hook, HookAdapter, HookEventType } from "../types.js";
+
+/** Claude Code hook event mapping */
+const EVENT_MAP: Record<string, HookEventType> = {
+  Stop: "stop",
+  Start: "start",
+  // Add more as Claude Code adds them
+};
+
+/** Claude Code settings.json hook structure */
+interface ClaudeHookEntry {
+  type?: string;
+  command?: string;
+  timeout?: number;
+}
+
+interface ClaudeHookGroup {
+  hooks?: ClaudeHookEntry[];
+}
+
+interface ClaudeSettings {
+  hooks?: Record<string, ClaudeHookGroup[]>;
+}
+
+export class ClaudeAdapter implements HookAdapter {
+  readonly platform = "claude" as const;
+
+  private configPath: string;
+
+  constructor() {
+    const home = process.env.HOME || "~";
+    this.configPath = join(home, ".claude", "settings.json");
+  }
+
+  configExists(): boolean {
+    return existsSync(this.configPath);
+  }
+
+  getConfigPath(): string {
+    return this.configPath;
+  }
+
+  async discoverHooks(): Promise<Hook[]> {
+    if (!this.configExists()) {
+      return [];
+    }
+
+    try {
+      const content = readFileSync(this.configPath, "utf-8");
+      const settings = JSON.parse(content) as ClaudeSettings;
+
+      if (!settings.hooks) {
+        return [];
+      }
+
+      const hooks: Hook[] = [];
+
+      for (const [eventKey, groups] of Object.entries(settings.hooks)) {
+        const eventType = EVENT_MAP[eventKey] || "custom";
+
+        for (const group of groups) {
+          if (!group.hooks) continue;
+
+          for (const hookEntry of group.hooks) {
+            if (hookEntry.type !== "command" || !hookEntry.command) continue;
+
+            // Expand ~ in path
+            const path = hookEntry.command.replace(/^~/, process.env.HOME || "~");
+            const name = path.split("/").pop() || hookEntry.command;
+
+            hooks.push({
+              id: `claude:${hookEntry.command}`,
+              platform: "claude",
+              event: eventType,
+              path,
+              name,
+              enabled: true,
+              timeout: hookEntry.timeout,
+              metadata: {
+                originalEvent: eventKey,
+                type: hookEntry.type,
+              },
+            });
+          }
+        }
+      }
+
+      return hooks;
+    } catch (_error) {
+      // Return empty on parse errors - registry will capture the error
+      return [];
+    }
+  }
+}

package/src/lib/hooks/adapters/codex.ts

@@ -0,0 +1,92 @@
+/**
+ * Codex hook adapter.
+ *
+ * Reads hooks from ~/.codex/config.toml
+ *
+ * Format:
+ * notify = ["python3", "/path/to/script.py"]
+ *
+ * Codex passes JSON as CLI argument (not stdin like Claude)
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Hook, HookAdapter } from "../types.js";
+
+/** Simple TOML parser for the notify array */
+function parseNotifyFromToml(content: string): string[] | null {
+  // Look for notify = [...] pattern
+  const match = content.match(/^notify\s*=\s*\[(.*?)\]/ms);
+  if (!match) return null;
+
+  // Extract array contents and parse
+  const arrayContent = match[1];
+  const items: string[] = [];
+
+  // Match quoted strings
+  const stringPattern = /"([^"\\]*(?:\\.[^"\\]*)*)"|'([^'\\]*(?:\\.[^'\\]*)*)'/g;
+  let stringMatch: RegExpExecArray | null = stringPattern.exec(arrayContent);
+  while (stringMatch !== null) {
+    items.push(stringMatch[1] || stringMatch[2]);
+    stringMatch = stringPattern.exec(arrayContent);
+  }
+
+  return items.length > 0 ? items : null;
+}
+
+export class CodexAdapter implements HookAdapter {
+  readonly platform = "codex" as const;
+
+  private configPath: string;
+
+  constructor() {
+    const home = process.env.HOME || "~";
+    this.configPath = join(home, ".codex", "config.toml");
+  }
+
+  configExists(): boolean {
+    return existsSync(this.configPath);
+  }
+
+  getConfigPath(): string {
+    return this.configPath;
+  }
+
+  async discoverHooks(): Promise<Hook[]> {
+    if (!this.configExists()) {
+      return [];
+    }
+
+    try {
+      const content = readFileSync(this.configPath, "utf-8");
+      const notifyCmd = parseNotifyFromToml(content);
+
+      if (!notifyCmd || notifyCmd.length === 0) {
+        return [];
+      }
+
+      // notify is a command array like ["python3", "/path/to/script.py"]
+      // The script path is typically the last element
+      const scriptPath = notifyCmd[notifyCmd.length - 1];
+      const expandedPath = scriptPath.replace(/^~/, process.env.HOME || "~");
+      const name = expandedPath.split("/").pop() || scriptPath;
+
+      const hook: Hook = {
+        id: `codex:${scriptPath}`,
+        platform: "codex",
+        event: "turn-complete", // Codex notify fires on agent-turn-complete
+        path: expandedPath,
+        name,
+        enabled: true,
+        metadata: {
+          command: notifyCmd,
+          invocationStyle: "cli-arg", // Codex passes JSON as CLI arg
+        },
+      };
+
+      return [hook];
+    } catch (_error) {
+      return [];
+    }
+  }
+}

package/src/lib/hooks/adapters/copilot.ts

@@ -0,0 +1,141 @@
+/**
+ * GitHub Copilot hook adapter.
+ *
+ * Reads hooks from .github/hooks/hooks.json in the current working directory.
+ * Also checks ~/.abbie/templates/github-hooks/hooks.json for global template.
+ *
+ * Format:
+ * {
+ *   "version": 1,
+ *   "hooks": {
+ *     "sessionStart": [{ "type": "command", "bash": "...", "timeoutSec": 30 }],
+ *     "sessionEnd": [...],
+ *     "preToolUse": [...],
+ *     "postToolUse": [...],
+ *     "errorOccurred": [...]
+ *   }
+ * }
+ */
+
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import type { Hook, HookAdapter, HookEventType } from "../types.js";
+
+/** Copilot hook event mapping */
+const EVENT_MAP: Record<string, HookEventType> = {
+  sessionStart: "start",
+  sessionEnd: "stop",
+  userPromptSubmitted: "custom",
+  preToolUse: "tool-call",
+  postToolUse: "tool-call",
+  errorOccurred: "error",
+};
+
+/** Copilot hook entry structure */
+interface CopilotHookEntry {
+  type?: string;
+  bash?: string;
+  powershell?: string;
+  cwd?: string;
+  timeoutSec?: number;
+  env?: Record<string, string>;
+  comment?: string;
+}
+
+interface CopilotHooksConfig {
+  version?: number;
+  hooks?: Record<string, CopilotHookEntry[]>;
+}
+
+export class CopilotAdapter implements HookAdapter {
+  readonly platform = "copilot" as const;
+
+  private configPath: string;
+  private globalTemplatePath: string;
+
+  constructor() {
+    // Per-repo config (relative to cwd)
+    this.configPath = join(process.cwd(), ".github", "hooks", "hooks.json");
+    // Global template
+    const home = process.env.HOME || "~";
+    this.globalTemplatePath = join(home, ".abbie", "templates", "github-hooks", "hooks.json");
+  }
+
+  configExists(): boolean {
+    return existsSync(this.configPath) || existsSync(this.globalTemplatePath);
+  }
+
+  getConfigPath(): string {
+    if (existsSync(this.configPath)) {
+      // If it's a symlink, show both paths
+      try {
+        const realPath = realpathSync(this.configPath);
+        if (realPath !== this.configPath) {
+          return `${this.configPath} -> ${realPath}`;
+        }
+      } catch {
+        // Ignore symlink resolution errors
+      }
+      return this.configPath;
+    }
+    return this.globalTemplatePath;
+  }
+
+  async discoverHooks(): Promise<Hook[]> {
+    const configPath = existsSync(this.configPath) ? this.configPath : this.globalTemplatePath;
+
+    if (!existsSync(configPath)) {
+      return [];
+    }
+
+    try {
+      const content = readFileSync(configPath, "utf-8");
+      const config = JSON.parse(content) as CopilotHooksConfig;
+
+      if (!config.hooks) {
+        return [];
+      }
+
+      const hooks: Hook[] = [];
+
+      for (const [eventKey, entries] of Object.entries(config.hooks)) {
+        const eventType = EVENT_MAP[eventKey] || "custom";
+
+        for (const entry of entries) {
+          if (entry.type !== "command") continue;
+
+          // Get the command (bash preferred on Unix)
+          const command = entry.bash || entry.powershell;
+          if (!command) continue;
+
+          // Expand ~ in path
+          const path = command.replace(/^~/, process.env.HOME || "~");
+          const name = path.split("/").pop() || command;
+
+          hooks.push({
+            id: `copilot:${eventKey}:${name}`,
+            platform: "copilot",
+            event: eventType,
+            path,
+            name,
+            enabled: true,
+            timeout: entry.timeoutSec,
+            metadata: {
+              originalEvent: eventKey,
+              type: entry.type,
+              cwd: entry.cwd,
+              env: entry.env,
+              comment: entry.comment,
+              configPath,
+            },
+          });
+        }
+      }
+
+      return hooks;
+    } catch (_error) {
+      // Return empty on parse errors - registry will capture the error
+      return [];
+    }
+  }
+}