@creativeintelligence/abbie 0.1.0

package/src/lib/hooks/context.ts

@@ -0,0 +1,174 @@
+/**
+ * Hook context management - prevents recursive hook triggers.
+ *
+ * When hooks spawn agents (e.g., session-summary.sh calls copilot for AI summaries),
+ * those agents trigger their own hooks. Lockfiles prevent infinite loops.
+ *
+ * Usage in shell hooks:
+ *   abbie hook guard && exit 0
+ *   LOCK=$(abbie hook lock)
+ *   trap "abbie hook unlock $LOCK" EXIT
+ */
+
+import { randomBytes } from "node:crypto";
+import { existsSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const LOCKFILE_DIR = "/tmp";
+const LOCKFILE_PREFIX = ".abbie-hook-context-";
+const MAX_AGE_SECONDS = 120; // Lockfiles older than 2 minutes are stale
+
+export interface LockfileInfo {
+  path: string;
+  pid: string;
+  age: number;
+  stale: boolean;
+}
+
+/**
+ * Check if currently in a hook context (should skip hook execution).
+ * Returns true if a recent lockfile exists.
+ */
+export function isInHookContext(): boolean {
+  // Also check env var for direct children
+  if (process.env.AGENTS_HOOK_CONTEXT === "true") {
+    return true;
+  }
+
+  const lockfiles = getActiveLockfiles();
+  return lockfiles.length > 0;
+}
+
+/**
+ * Create a lockfile and return its path.
+ * Caller is responsible for cleanup (use trap in shell).
+ */
+export function createLockfile(): string {
+  const id = `${process.pid}-${randomBytes(4).toString("hex")}`;
+  const path = join(LOCKFILE_DIR, `${LOCKFILE_PREFIX}${id}`);
+  writeFileSync(path, `${Date.now()}\n${process.pid}`);
+  return path;
+}
+
+/**
+ * Remove a lockfile by path.
+ */
+export function removeLockfile(path: string): boolean {
+  try {
+    if (existsSync(path)) {
+      unlinkSync(path);
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get all active (non-stale) lockfiles.
+ */
+export function getActiveLockfiles(): LockfileInfo[] {
+  const lockfiles: LockfileInfo[] = [];
+  const now = Date.now();
+
+  try {
+    const files = readdirSync(LOCKFILE_DIR);
+    for (const file of files) {
+      if (!file.startsWith(LOCKFILE_PREFIX)) continue;
+
+      const path = join(LOCKFILE_DIR, file);
+      try {
+        const stat = statSync(path);
+        const ageSeconds = (now - stat.mtimeMs) / 1000;
+        const stale = ageSeconds > MAX_AGE_SECONDS;
+
+        // Extract PID from filename (format: .abbie-hook-context-{pid}-{random})
+        const pid = file.replace(LOCKFILE_PREFIX, "").split("-")[0];
+
+        lockfiles.push({
+          path,
+          pid,
+          age: Math.round(ageSeconds),
+          stale,
+        });
+      } catch {
+        // File disappeared, skip
+      }
+    }
+  } catch {
+    // Can't read /tmp, assume no lockfiles
+  }
+
+  // Only return non-stale lockfiles
+  return lockfiles.filter((l) => !l.stale);
+}
+
+/**
+ * Clean up stale lockfiles (older than MAX_AGE_SECONDS).
+ * Returns number of cleaned files.
+ */
+export function cleanupStaleLockfiles(): number {
+  let cleaned = 0;
+  const now = Date.now();
+
+  try {
+    const files = readdirSync(LOCKFILE_DIR);
+    for (const file of files) {
+      if (!file.startsWith(LOCKFILE_PREFIX)) continue;
+
+      const path = join(LOCKFILE_DIR, file);
+      try {
+        const stat = statSync(path);
+        const ageSeconds = (now - stat.mtimeMs) / 1000;
+
+        if (ageSeconds > MAX_AGE_SECONDS) {
+          unlinkSync(path);
+          cleaned++;
+        }
+      } catch {
+        // File disappeared or can't delete, skip
+      }
+    }
+  } catch {
+    // Can't read /tmp
+  }
+
+  return cleaned;
+}
+
+/**
+ * Get all lockfiles (including stale) for debugging.
+ */
+export function getAllLockfiles(): LockfileInfo[] {
+  const lockfiles: LockfileInfo[] = [];
+  const now = Date.now();
+
+  try {
+    const files = readdirSync(LOCKFILE_DIR);
+    for (const file of files) {
+      if (!file.startsWith(LOCKFILE_PREFIX)) continue;
+
+      const path = join(LOCKFILE_DIR, file);
+      try {
+        const stat = statSync(path);
+        const ageSeconds = (now - stat.mtimeMs) / 1000;
+        const stale = ageSeconds > MAX_AGE_SECONDS;
+        const pid = file.replace(LOCKFILE_PREFIX, "").split("-")[0];
+
+        lockfiles.push({
+          path,
+          pid,
+          age: Math.round(ageSeconds),
+          stale,
+        });
+      } catch {
+        // File disappeared, skip
+      }
+    }
+  } catch {
+    // Can't read /tmp
+  }
+
+  return lockfiles;
+}

package/src/lib/hooks/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Hooks module - unified hook discovery and management.
+ */
+
+// Adapters (for direct use if needed)
+export { ClaudeAdapter } from "./adapters/claude.js";
+export { CodexAdapter } from "./adapters/codex.js";
+export { CopilotAdapter } from "./adapters/copilot.js";
+// Context management (lockfiles for recursion prevention)
+export {
+  cleanupStaleLockfiles,
+  createLockfile,
+  getActiveLockfiles,
+  getAllLockfiles,
+  isInHookContext,
+  type LockfileInfo,
+  removeLockfile,
+} from "./context.js";
+// Registry functions
+export {
+  discoverAllHooks,
+  getAllHooks,
+  getConfigPaths,
+  getConfiguredPlatforms,
+  getHooksForPlatform,
+} from "./registry.js";
+// Runner functions
+export { generateMockPayload, runHook } from "./runner.js";
+export type {
+  AgentPlatform,
+  Hook,
+  HookAdapter,
+  HookDiscoveryError,
+  HookEventType,
+  HookRegistry,
+  HookTestResult,
+} from "./types.js";
+// Types and constants
+export { HOOK_PLATFORMS } from "./types.js";

package/src/lib/hooks/registry.ts

@@ -0,0 +1,101 @@
+/**
+ * Unified hook registry.
+ *
+ * Discovers hooks from all supported agent platforms:
+ * - Claude Code (~/.claude/settings.json)
+ * - Codex (~/.codex/config.toml)
+ * - Copilot (.github/hooks/hooks.json per-repo)
+ */
+
+import { ClaudeAdapter } from "./adapters/claude.js";
+import { CodexAdapter } from "./adapters/codex.js";
+import { CopilotAdapter } from "./adapters/copilot.js";
+import {
+  type AgentPlatform,
+  HOOK_PLATFORMS,
+  type Hook,
+  type HookAdapter,
+  type HookDiscoveryError,
+  type HookRegistry,
+} from "./types.js";
+
+/** All available adapters */
+const ADAPTERS: HookAdapter[] = [new ClaudeAdapter(), new CodexAdapter(), new CopilotAdapter()];
+
+/**
+ * Discover all hooks from all platforms.
+ */
+export async function discoverAllHooks(): Promise<HookRegistry> {
+  // Initialize all hook platforms with empty arrays
+  const platforms = Object.fromEntries(HOOK_PLATFORMS.map((p) => [p, []])) as unknown as Record<
+    AgentPlatform,
+    Hook[]
+  >;
+  const errors: HookDiscoveryError[] = [];
+
+  for (const adapter of ADAPTERS) {
+    try {
+      if (adapter.configExists()) {
+        const hooks = await adapter.discoverHooks();
+        platforms[adapter.platform] = hooks;
+      }
+    } catch (error) {
+      errors.push({
+        platform: adapter.platform,
+        message: error instanceof Error ? error.message : String(error),
+        path: adapter.getConfigPath(),
+      });
+    }
+  }
+
+  const totalCount = Object.values(platforms).flat().length;
+
+  return {
+    platforms,
+    totalCount,
+    discoveredAt: new Date().toISOString(),
+    errors,
+  };
+}
+
+/**
+ * Get hooks for a specific platform.
+ */
+export async function getHooksForPlatform(platform: AgentPlatform): Promise<Hook[]> {
+  const adapter = ADAPTERS.find((a) => a.platform === platform);
+  if (!adapter) {
+    throw new Error(`Unknown platform: ${platform}`);
+  }
+
+  if (!adapter.configExists()) {
+    return [];
+  }
+
+  return adapter.discoverHooks();
+}
+
+/**
+ * Get all hooks as a flat array.
+ */
+export async function getAllHooks(): Promise<Hook[]> {
+  const registry = await discoverAllHooks();
+  return Object.values(registry.platforms).flat();
+}
+
+/**
+ * Get config paths for all platforms.
+ */
+export function getConfigPaths(): Record<AgentPlatform, string> {
+  const paths: Record<AgentPlatform, string> = {} as Record<AgentPlatform, string>;
+  for (const adapter of ADAPTERS) {
+    paths[adapter.platform] = adapter.getConfigPath();
+  }
+  return paths;
+}
+
+/**
+ * Check which platforms have configurations.
+ */
+export function getConfiguredPlatforms(): AgentPlatform[] {
+  return ADAPTERS.filter((a) => a.configExists()).map((a) => a.platform);
+}

package/src/lib/hooks/runner.ts

@@ -0,0 +1,208 @@
+/**
+ * Hook runner - executes hooks with test or real payloads.
+ *
+ * Handles platform-specific invocation styles:
+ * - Claude Code: JSON via stdin
+ * - Codex: JSON as CLI argument
+ * - OpenCode: JSON via stdin to JS plugin
+ */
+
+import { spawn } from "node:child_process";
+import type { Hook, HookTestResult } from "./types.js";
+
+/** Mock payloads for different event types */
+const MOCK_PAYLOADS: Record<string, Record<string, unknown>> = {
+  stop: {
+    session_id: "test-session-123",
+    timestamp_utc: new Date().toISOString(),
+    cwd: process.cwd(),
+    stop_hook_active: true,
+    num_turns: 5,
+    cost_usd: 0.05,
+    duration_secs: 120,
+    duration_api_secs: 30,
+  },
+  start: {
+    session_id: "test-session-123",
+    timestamp_utc: new Date().toISOString(),
+    cwd: process.cwd(),
+  },
+  "turn-complete": {
+    type: "agent-turn-complete",
+    session_id: "test-session-123",
+    last_response: "Test response from agent",
+    timestamp: new Date().toISOString(),
+  },
+  "tool-call": {
+    tool_name: "test-tool",
+    tool_input: { test: true },
+    session_id: "test-session-123",
+  },
+  error: {
+    error: "Test error message",
+    session_id: "test-session-123",
+    timestamp: new Date().toISOString(),
+  },
+  custom: {
+    event: "custom",
+    session_id: "test-session-123",
+    data: { test: true },
+  },
+};
+
+/**
+ * Generate mock payload for a hook's event type.
+ */
+export function generateMockPayload(hook: Hook): Record<string, unknown> {
+  const base = MOCK_PAYLOADS[hook.event] ?? MOCK_PAYLOADS.custom;
+
+  // Add trace_id to simulate correlated events
+  return {
+    ...base,
+    trace_id: `tr_test_${Date.now()}`,
+    platform: hook.platform,
+  };
+}
+
+/**
+ * Execute a hook and return the result.
+ */
+export async function runHook(
+  hook: Hook,
+  payload?: Record<string, unknown>,
+): Promise<HookTestResult> {
+  const data = payload ?? generateMockPayload(hook);
+  const jsonPayload = JSON.stringify(data);
+  const startTime = Date.now();
+
+  try {
+    const result = await executeHook(hook, jsonPayload);
+    return {
+      hook,
+      success: result.exitCode === 0,
+      exitCode: result.exitCode,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      durationMs: Date.now() - startTime,
+    };
+  } catch (error) {
+    return {
+      hook,
+      success: false,
+      durationMs: Date.now() - startTime,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+interface ExecuteResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Execute hook with platform-specific invocation.
+ */
+async function executeHook(hook: Hook, jsonPayload: string): Promise<ExecuteResult> {
+  return new Promise((resolve, reject) => {
+    let command: string;
+    let args: string[];
+    let useStdin = true;
+
+    switch (hook.platform) {
+      case "claude":
+        // Claude hooks use the command from metadata or direct path
+        if (hook.path.endsWith(".sh")) {
+          command = "bash";
+          args = [hook.path];
+        } else if (hook.path.endsWith(".py")) {
+          command = "python3";
+          args = [hook.path];
+        } else {
+          command = hook.path;
+          args = [];
+        }
+        useStdin = true;
+        break;
+
+      case "codex": {
+        // Codex passes JSON as CLI argument
+        const codexCommand = hook.metadata?.command as string[] | undefined;
+        if (codexCommand && codexCommand.length > 0) {
+          command = codexCommand[0];
+          args = [...codexCommand.slice(1), jsonPayload];
+        } else if (hook.path.endsWith(".py")) {
+          command = "python3";
+          args = [hook.path, jsonPayload];
+        } else {
+          command = hook.path;
+          args = [jsonPayload];
+        }
+        useStdin = false;
+        break;
+      }
+
+      case "copilot":
+        // Copilot hooks receive JSON via stdin (same as Claude)
+        if (hook.path.endsWith(".sh")) {
+          command = "bash";
+          args = [hook.path];
+        } else if (hook.path.endsWith(".py")) {
+          command = "python3";
+          args = [hook.path];
+        } else if (hook.path.endsWith(".ps1")) {
+          command = "powershell";
+          args = ["-File", hook.path];
+        } else {
+          command = hook.path;
+          args = [];
+        }
+        useStdin = true;
+        break;
+
+      default:
+        command = hook.path;
+        args = [];
+        useStdin = true;
+    }
+
+    const proc = spawn(command, args, {
+      cwd: process.cwd(),
+      env: {
+        ...process.env,
+        TRACE_ID: `tr_test_${Date.now()}`,
+        HOOK_TEST_MODE: "true",
+      },
+      timeout: (hook.timeout ?? 30) * 1000,
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    proc.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+
+    proc.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+
+    if (useStdin) {
+      proc.stdin.write(jsonPayload);
+      proc.stdin.end();
+    }
+
+    proc.on("error", (error) => {
+      reject(error);
+    });
+
+    proc.on("close", (code) => {
+      resolve({
+        exitCode: code ?? 1,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+      });
+    });
+  });
+}

package/src/lib/hooks/types.ts

@@ -0,0 +1,89 @@
+/**
+ * Unified hook type definitions for multi-agent hook management.
+ *
+ * AgentPlatform tracks agents with hook support (native or bridged).
+ * Claude/Codex/Copilot/Gemini have native hooks.
+ * Pi bridges extension events to the unified bash hooks.
+ * opencode/droid can use the bash hooks when spawned via abbie.
+ */
+import type { AgentType } from "../types.js";
+
+/**
+ * Agent platforms with hook support (native or bridged).
+ * Using AgentType directly — all agents can go through the unified hooks.
+ */
+export type AgentPlatform = AgentType;
+
+/** All agent platforms with hook support */
+export { AGENTS as HOOK_PLATFORMS } from "../types.js";
+
+/** Hook event types (normalized across platforms) */
+export type HookEventType =
+  | "stop" // Session/task ended
+  | "start" // Session/task started
+  | "turn-complete" // Agent turn completed (codex)
+  | "tool-call" // Tool was called
+  | "error" // Error occurred
+  | "custom"; // Platform-specific
+
+/** Normalized hook definition */
+export interface Hook {
+  /** Unique identifier (platform:path or platform:name) */
+  id: string;
+  /** Which platform this hook is for */
+  platform: AgentPlatform;
+  /** Event type that triggers this hook */
+  event: HookEventType;
+  /** Path to the hook script/file */
+  path: string;
+  /** Display name */
+  name: string;
+  /** Whether the hook is currently enabled */
+  enabled: boolean;
+  /** Timeout in seconds (if applicable) */
+  timeout?: number;
+  /** Additional platform-specific metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/** Hook registry - all discovered hooks */
+export interface HookRegistry {
+  /** Hooks grouped by platform */
+  platforms: Record<AgentPlatform, Hook[]>;
+  /** Total hook count */
+  totalCount: number;
+  /** Discovery timestamp */
+  discoveredAt: string;
+  /** Any errors during discovery */
+  errors: HookDiscoveryError[];
+}
+
+/** Error during hook discovery */
+export interface HookDiscoveryError {
+  platform: AgentPlatform;
+  message: string;
+  path?: string;
+}
+
+/** Hook test result */
+export interface HookTestResult {
+  hook: Hook;
+  success: boolean;
+  exitCode?: number;
+  stdout?: string;
+  stderr?: string;
+  durationMs: number;
+  error?: string;
+}
+
+/** Platform adapter interface */
+export interface HookAdapter {
+  /** Platform identifier */
+  platform: AgentPlatform;
+  /** Discover hooks from platform config */
+  discoverHooks(): Promise<Hook[]>;
+  /** Check if platform config exists */
+  configExists(): boolean;
+  /** Get platform config path */
+  getConfigPath(): string;
+}