gobby 0.2.5__py3-none-any.whl

gobby/hooks/events.py

@@ -0,0 +1,218 @@
+"""Unified hook event models for multi-CLI session management.
+
+This module defines the unified internal representation for hook events across
+all supported CLIs (Claude Code, Gemini CLI, Codex CLI). Adapters translate
+between CLI-specific formats and these unified types.
+
+Design Decision: This file coexists with hook_types.py. The existing HookType enum
+in hook_types.py uses Claude-specific kebab-case names (session-start, pre-tool-use)
+and Pydantic models for input validation. The HookEventType enum here is the unified
+internal representation. Adapters translate between them.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Literal
+
+
+class HookEventType(str, Enum):
+    """Unified hook event types across all CLI sources.
+
+    These map to CLI-specific hook names via adapters:
+    - Claude Code: kebab-case (session-start, pre-tool-use)
+    - Gemini CLI: PascalCase (SessionStart, BeforeTool)
+    - Codex CLI: JSON-RPC methods (thread/started, item/completed)
+    """
+
+    # Session lifecycle
+    SESSION_START = "session_start"
+    SESSION_END = "session_end"
+
+    # Agent/turn lifecycle
+    BEFORE_AGENT = "before_agent"
+    AFTER_AGENT = "after_agent"
+    STOP = "stop"  # Agent is about to stop/exit (Claude Code only)
+
+    # Tool lifecycle
+    BEFORE_TOOL = "before_tool"
+    AFTER_TOOL = "after_tool"
+    BEFORE_TOOL_SELECTION = "before_tool_selection"  # Gemini only
+
+    # Model lifecycle (Gemini only)
+    BEFORE_MODEL = "before_model"
+    AFTER_MODEL = "after_model"
+
+    # Context management
+    PRE_COMPACT = "pre_compact"  # Claude: PreCompact, Gemini: PreCompress
+
+    # Subagent lifecycle (Claude Code only)
+    SUBAGENT_START = "subagent_start"
+    SUBAGENT_STOP = "subagent_stop"
+
+    # Permissions & notifications
+    PERMISSION_REQUEST = "permission_request"  # Claude Code only
+    NOTIFICATION = "notification"
+
+
+class SessionSource(str, Enum):
+    """Identifies which CLI originated the session."""
+
+    CLAUDE = "claude"  # Claude Code CLI
+    GEMINI = "gemini"
+    CODEX = "codex"
+    CLAUDE_SDK = "claude_sdk"
+    ANTIGRAVITY = "antigravity"  # Antigravity IDE (uses Claude Code format)
+
+
+@dataclass
+class HookEvent:
+    """Unified hook event from any CLI source.
+
+    This dataclass represents a normalized hook event that can originate from
+    any supported CLI. Adapters are responsible for translating CLI-specific
+    payloads into this format.
+
+    Attributes:
+        event_type: The type of hook event (from HookEventType enum).
+        session_id: External session identifier (external_id for Claude, thread_id for Codex).
+        source: Which CLI originated this event.
+        timestamp: When the event occurred.
+        data: Event-specific payload in native format (adapter passes through).
+
+        machine_id: Unique identifier for the machine (populated by adapter or manager).
+        cwd: Current working directory for the session.
+
+        user_id: Platform user ID (populated by HookManager after session lookup).
+        project_id: Platform project ID (populated by HookManager).
+        workflow_id: Future: ID of workflow evaluating this event.
+        metadata: Extensible key-value store for adapter-specific data.
+    """
+
+    # Core required fields
+    event_type: HookEventType
+    session_id: str  # external_id / thread_id (external ID)
+    source: SessionSource
+    timestamp: datetime
+    data: dict[str, Any]  # Event-specific payload (native format)
+
+    # Context (populated by adapter or manager)
+    machine_id: str | None = None
+    cwd: str | None = None
+
+    # Future extensibility
+    user_id: str | None = None
+    project_id: str | None = None
+    task_id: str | None = None
+    workflow_id: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class HookResponse:
+    """Unified response returned to CLI.
+
+    This dataclass represents the response that will be translated back to
+    CLI-specific format by the adapter.
+
+    Attributes:
+        decision: Whether to allow, deny, or ask the user about the action.
+        context: Text to inject into the agent's context (AI-only).
+        system_message: User-visible message to display (e.g., handoff notification).
+        reason: Explanation for the decision (useful for denials).
+
+        modify_args: Future: Dict of argument modifications for the action.
+        trigger_action: Future: Action to trigger in the CLI.
+        metadata: Extensible key-value store for adapter-specific data.
+    """
+
+    decision: Literal["allow", "deny", "ask", "block", "modify"] = "allow"
+    context: str | None = None  # Inject into agent context (AI-only)
+    system_message: str | None = None  # User-visible message (e.g., handoff notification)
+    reason: str | None = None  # Explanation for decision
+
+    # Future extensibility
+    modify_args: dict[str, Any] | None = None
+    trigger_action: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+# Event type mapping table for documentation (see plan-multi-cli.md section 1.2)
+# This is informational - actual mappings are in adapters
+EVENT_TYPE_CLI_SUPPORT: dict[HookEventType, dict[str, str | None]] = {
+    HookEventType.SESSION_START: {
+        "claude": "SessionStart",
+        "gemini": "SessionStart",
+        "codex": "thread/started",
+    },
+    HookEventType.SESSION_END: {
+        "claude": "SessionEnd",
+        "gemini": "SessionEnd",
+        "codex": "thread/archive",
+    },
+    HookEventType.BEFORE_AGENT: {
+        "claude": "UserPromptSubmit",
+        "gemini": "BeforeAgent",
+        "codex": "turn/started",
+    },
+    HookEventType.AFTER_AGENT: {
+        "claude": "Stop",
+        "gemini": "AfterAgent",
+        "codex": "turn/completed",
+    },
+    HookEventType.STOP: {
+        "claude": "Stop",
+        "gemini": None,
+        "codex": None,
+    },
+    HookEventType.BEFORE_TOOL: {
+        "claude": "PreToolUse",
+        "gemini": "BeforeTool",
+        "codex": "requestApproval",
+    },
+    HookEventType.AFTER_TOOL: {
+        "claude": "PostToolUse",
+        "gemini": "AfterTool",
+        "codex": "item/completed",
+    },
+    HookEventType.BEFORE_TOOL_SELECTION: {
+        "claude": None,
+        "gemini": "BeforeToolSelection",
+        "codex": None,
+    },
+    HookEventType.BEFORE_MODEL: {
+        "claude": None,
+        "gemini": "BeforeModel",
+        "codex": None,
+    },
+    HookEventType.AFTER_MODEL: {
+        "claude": None,
+        "gemini": "AfterModel",
+        "codex": None,
+    },
+    HookEventType.PRE_COMPACT: {
+        "claude": "PreCompact",
+        "gemini": "PreCompress",
+        "codex": None,
+    },
+    HookEventType.SUBAGENT_START: {
+        "claude": "SubagentStart",
+        "gemini": None,
+        "codex": None,
+    },
+    HookEventType.SUBAGENT_STOP: {
+        "claude": "SubagentStop",
+        "gemini": None,
+        "codex": None,
+    },
+    HookEventType.PERMISSION_REQUEST: {
+        "claude": "PermissionRequest",
+        "gemini": None,
+        "codex": None,
+    },
+    HookEventType.NOTIFICATION: {
+        "claude": "Notification",
+        "gemini": "Notification",
+        "codex": None,
+    },
+}

gobby/hooks/git.py

@@ -0,0 +1,169 @@
+"""Git-related hooks for merge operations.
+
+Provides hooks for pre-merge and post-merge events that can be used
+to integrate merge resolution with other systems.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+
+logger = logging.getLogger(__name__)
+
+# Type aliases for hook callbacks
+PreMergeHook = Callable[[str, str, str], bool]  # (worktree_id, source, target) -> allow
+PostMergeHook = Callable[[str, bool], None]  # (resolution_id, success) -> None
+
+
+class MergeHookManager:
+    """
+    Manager for merge-related hooks.
+
+    Allows registration of pre-merge and post-merge hooks that can be
+    used to integrate merge resolution with other systems (task status,
+    notifications, etc.).
+    """
+
+    def __init__(self) -> None:
+        """Initialize the hook manager."""
+        self._pre_merge_hooks: list[PreMergeHook] = []
+        self._post_merge_hooks: list[PostMergeHook] = []
+
+    def register_pre_merge(self, hook: PreMergeHook) -> None:
+        """
+        Register a pre-merge hook.
+
+        Pre-merge hooks are called before a merge operation starts.
+        They receive the worktree ID, source branch, and target branch.
+        If any hook returns False, the merge is blocked.
+
+        Args:
+            hook: Callback function (worktree_id, source_branch, target_branch) -> bool
+        """
+        self._pre_merge_hooks.append(hook)
+        logger.debug(f"Registered pre-merge hook: {hook.__name__}")
+
+    def register_post_merge(self, hook: PostMergeHook) -> None:
+        """
+        Register a post-merge hook.
+
+        Post-merge hooks are called after a merge operation completes.
+        They receive the resolution ID and success status.
+
+        Args:
+            hook: Callback function (resolution_id, success) -> None
+        """
+        self._post_merge_hooks.append(hook)
+        logger.debug(f"Registered post-merge hook: {hook.__name__}")
+
+    def unregister_pre_merge(self, hook: PreMergeHook) -> bool:
+        """
+        Unregister a pre-merge hook.
+
+        Args:
+            hook: Hook to unregister
+
+        Returns:
+            True if hook was found and removed
+        """
+        try:
+            self._pre_merge_hooks.remove(hook)
+            return True
+        except ValueError:
+            return False
+
+    def unregister_post_merge(self, hook: PostMergeHook) -> bool:
+        """
+        Unregister a post-merge hook.
+
+        Args:
+            hook: Hook to unregister
+
+        Returns:
+            True if hook was found and removed
+        """
+        try:
+            self._post_merge_hooks.remove(hook)
+            return True
+        except ValueError:
+            return False
+
+    def run_pre_merge_hooks(
+        self, worktree_id: str, source_branch: str, target_branch: str
+    ) -> tuple[bool, str | None]:
+        """
+        Run all pre-merge hooks.
+
+        Args:
+            worktree_id: ID of the worktree
+            source_branch: Branch being merged
+            target_branch: Target branch
+
+        Returns:
+            Tuple of (allowed, blocking_reason)
+            If any hook returns False, returns (False, reason)
+        """
+        for hook in self._pre_merge_hooks:
+            try:
+                result = hook(worktree_id, source_branch, target_branch)
+                if not result:
+                    reason = f"Merge blocked by pre-merge hook: {hook.__name__}"
+                    logger.warning(reason)
+                    return (False, reason)
+            except Exception as e:
+                reason = f"Pre-merge hook {hook.__name__} raised exception: {e}"
+                logger.error(reason)
+                # Continue with other hooks on exception
+                continue
+
+        return (True, None)
+
+    def run_post_merge_hooks(self, resolution_id: str, success: bool) -> None:
+        """
+        Run all post-merge hooks.
+
+        Args:
+            resolution_id: ID of the merge resolution
+            success: Whether the merge was successful
+        """
+        for hook in self._post_merge_hooks:
+            try:
+                hook(resolution_id, success)
+            except Exception as e:
+                logger.error(f"Post-merge hook {hook.__name__} raised exception: {e}")
+                # Continue with other hooks on exception
+                continue
+
+    @property
+    def pre_merge_hook_count(self) -> int:
+        """Get number of registered pre-merge hooks."""
+        return len(self._pre_merge_hooks)
+
+    @property
+    def post_merge_hook_count(self) -> int:
+        """Get number of registered post-merge hooks."""
+        return len(self._post_merge_hooks)
+
+
+# Singleton instance for global hook management
+_default_manager: MergeHookManager | None = None
+
+
+def get_merge_hook_manager() -> MergeHookManager:
+    """
+    Get the default MergeHookManager instance.
+
+    Returns:
+        The global MergeHookManager singleton
+    """
+    global _default_manager
+    if _default_manager is None:
+        _default_manager = MergeHookManager()
+    return _default_manager
+
+
+def reset_merge_hook_manager() -> None:
+    """Reset the default MergeHookManager (for testing)."""
+    global _default_manager
+    _default_manager = None

gobby/hooks/health_monitor.py

@@ -0,0 +1,171 @@
+"""
+Health monitor module for daemon health check monitoring.
+
+This module is extracted from hook_manager.py using Strangler Fig pattern.
+It provides background health check monitoring for the Gobby daemon.
+
+Classes:
+    HealthMonitor: Background daemon health check monitoring.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from gobby.utils.daemon_client import DaemonClient
+
+
+class HealthMonitor:
+    """
+    Background daemon health check monitoring.
+
+    Periodically checks daemon health via DaemonClient and caches the result
+    for fast access without HTTP calls. Thread-safe.
+
+    Extracted from HookManager to separate health monitoring concerns.
+    """
+
+    def __init__(
+        self,
+        daemon_client: DaemonClient,
+        health_check_interval: float = 10.0,
+        logger: logging.Logger | None = None,
+    ) -> None:
+        """
+        Initialize HealthMonitor.
+
+        Args:
+            daemon_client: DaemonClient for health checks
+            health_check_interval: Interval between checks in seconds (must be >= 0)
+            logger: Optional logger instance
+
+        Raises:
+            ValueError: If health_check_interval is negative
+        """
+        if health_check_interval < 0:
+            raise ValueError("health_check_interval must be non-negative")
+
+        self._daemon_client = daemon_client
+        self._health_check_interval = health_check_interval
+        self.logger = logger or logging.getLogger(__name__)
+
+        # Cached health status
+        self._cached_daemon_is_ready: bool = False
+        self._cached_daemon_message: str | None = None
+        self._cached_daemon_status: str = "not_running"
+        self._cached_daemon_error: str | None = None
+
+        # Threading state
+        self._health_check_timer: threading.Timer | None = None
+        self._health_check_lock = threading.Lock()
+        self._is_shutdown: bool = False
+
+    def start(self) -> None:
+        """
+        Start background health check monitoring.
+
+        Idempotent - safe to call multiple times.
+        """
+        with self._health_check_lock:
+            if self._health_check_timer is not None:
+                return  # Already running
+            if self._is_shutdown:
+                return  # Already shutdown
+
+            def health_check_loop() -> None:
+                """Background health check loop."""
+                try:
+                    # Update daemon status cache
+                    # check_status() returns tuple: (is_ready, message, status, error)
+                    is_ready, message, status, error = self._daemon_client.check_status()
+                    with self._health_check_lock:
+                        self._cached_daemon_is_ready = is_ready
+                        self._cached_daemon_message = message
+                        self._cached_daemon_status = status
+                        self._cached_daemon_error = error
+                except Exception as e:
+                    # Daemon not responding is expected when stopped, log at debug level
+                    self.logger.debug(f"Health check failed: {e}", exc_info=True)
+                    with self._health_check_lock:
+                        self._cached_daemon_is_ready = False
+                        self._cached_daemon_status = "not_running"
+                        self._cached_daemon_error = str(e)
+                finally:
+                    # Schedule next check only if not shutting down
+                    with self._health_check_lock:
+                        if not self._is_shutdown:
+                            self._health_check_timer = threading.Timer(
+                                self._health_check_interval,
+                                health_check_loop,
+                            )
+                            self._health_check_timer.daemon = True
+                            self._health_check_timer.start()
+
+            # Start first check immediately
+            self._health_check_timer = threading.Timer(0, health_check_loop)
+            self._health_check_timer.daemon = True
+            self._health_check_timer.start()
+
+    def stop(self) -> None:
+        """
+        Stop background health check monitoring.
+
+        Cancels any pending timer and prevents new timers from being scheduled.
+        Safe to call multiple times.
+        """
+        with self._health_check_lock:
+            self._is_shutdown = True
+            if self._health_check_timer is not None:
+                self._health_check_timer.cancel()
+                self._health_check_timer = None
+
+    def get_cached_status(self) -> tuple[bool, str | None, str, str | None]:
+        """
+        Get cached daemon status without making HTTP call.
+
+        Returns:
+            Tuple of (is_ready, message, status, error) where:
+            - is_ready: True if daemon is healthy
+            - message: Human-readable status message
+            - status: One of: "ready", "not_running", "cannot_access"
+            - error: Error details if status != "ready"
+        """
+        with self._health_check_lock:
+            return (
+                self._cached_daemon_is_ready,
+                self._cached_daemon_message,
+                self._cached_daemon_status,
+                self._cached_daemon_error,
+            )
+
+    def check_now(self) -> bool:
+        """
+        Perform immediate health check (not cached).
+
+        Makes a fresh HTTP call to check daemon status and updates the cache.
+        Used for retry logic when cached status indicates daemon is unavailable.
+
+        Returns:
+            True if daemon is healthy, False otherwise
+        """
+        try:
+            is_ready, message, status, error = self._daemon_client.check_status()
+            with self._health_check_lock:
+                self._cached_daemon_is_ready = is_ready
+                self._cached_daemon_message = message
+                self._cached_daemon_status = status
+                self._cached_daemon_error = error
+            return is_ready
+        except Exception as e:
+            self.logger.debug(f"Immediate health check failed: {e}")
+            with self._health_check_lock:
+                self._cached_daemon_is_ready = False
+                self._cached_daemon_status = "not_running"
+                self._cached_daemon_error = str(e)
+            return False
+
+
+__all__ = ["HealthMonitor"]