gobby 0.2.5__py3-none-any.whl

gobby/hooks/__init__.py

@@ -0,0 +1,104 @@
+"""
+Gobby hooks package for Claude Code, Gemini CLI, and Codex integration.
+
+This package provides a hook system for intercepting and processing events
+from AI coding assistants. The architecture follows the Coordinator pattern:
+
+Core Components:
+    HookManager: Main entry point and coordinator. Receives hook events and
+        delegates to specialized components.
+
+    EventHandlers: Contains all event handler implementations for the 15
+        supported event types (session, agent, tool, etc.)
+
+    SessionCoordinator: Manages session lifecycle - registration, lookup,
+        status tracking, and cleanup.
+
+    HealthMonitor: Background daemon health check monitoring with caching.
+
+    WebhookDispatcher: Dispatches hook events to external webhook endpoints.
+
+Event Models:
+    HookEventType: Unified event type enum (15 types across all CLIs)
+    SessionSource: Enum identifying which CLI originated the session
+    HookEvent: Unified event dataclass from any CLI source
+    HookResponse: Unified response dataclass returned to CLIs
+
+Plugin System:
+    HookPlugin: Base class for custom hook plugins
+    PluginLoader: Discovers and loads plugins from configured paths
+    hook_handler: Decorator for registering plugin handlers
+
+Example:
+    ```python
+    from gobby.hooks import HookManager, HookEvent, HookEventType
+
+    # Create manager (typically done once in daemon)
+    manager = HookManager()
+
+    # Handle incoming events
+    response = manager.handle(event)
+    ```
+"""
+
+# Core coordinator and components
+# Artifact capture hook
+from gobby.hooks.artifact_capture import ArtifactCaptureHook
+from gobby.hooks.event_handlers import EventHandlers
+from gobby.hooks.events import (
+    EVENT_TYPE_CLI_SUPPORT,
+    HookEvent,
+    HookEventType,
+    HookResponse,
+    SessionSource,
+)
+from gobby.hooks.health_monitor import HealthMonitor
+from gobby.hooks.hook_manager import HookManager
+from gobby.hooks.plugins import (
+    HookPlugin,
+    PluginLoader,
+    PluginRegistry,
+    RegisteredHandler,
+    hook_handler,
+    run_plugin_handlers,
+)
+from gobby.hooks.session_coordinator import SessionCoordinator
+from gobby.hooks.webhooks import WebhookDispatcher
+
+# Legacy imports for backward compatibility
+from gobby.sessions.manager import SessionManager
+from gobby.sessions.summary import SummaryFileGenerator
+from gobby.sessions.transcripts.claude import ClaudeTranscriptParser
+
+# Backward-compatible alias
+TranscriptProcessor = ClaudeTranscriptParser
+
+__all__ = [
+    # Core coordinator
+    "HookManager",
+    # Extracted components (for advanced usage/testing)
+    "EventHandlers",
+    "SessionCoordinator",
+    "HealthMonitor",
+    "WebhookDispatcher",
+    # Artifact capture
+    "ArtifactCaptureHook",
+    # Unified hook event models
+    "HookEventType",
+    "SessionSource",
+    "HookEvent",
+    "HookResponse",
+    "EVENT_TYPE_CLI_SUPPORT",
+    # Plugin system
+    "HookPlugin",
+    "PluginLoader",
+    "PluginRegistry",
+    "RegisteredHandler",
+    "hook_handler",
+    "run_plugin_handlers",
+    # Legacy exports (backward compatibility)
+    "SessionManager",
+    "SummaryFileGenerator",
+    "TranscriptProcessor",
+    "ClaudeTranscriptParser",
+]

gobby/hooks/artifact_capture.py

@@ -0,0 +1,213 @@
+"""
+Artifact capture hook for extracting and storing artifacts from messages.
+
+Processes assistant messages to extract:
+- Code blocks (with language metadata)
+- File path references
+- Other classified content
+
+Uses artifact_classifier for type detection and LocalArtifactManager for storage.
+Tracks content hashes to prevent duplicate storage using a bounded LRU cache.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import re
+from collections import OrderedDict
+from typing import TYPE_CHECKING
+
+from gobby.storage.artifact_classifier import ArtifactType, classify_artifact
+
+if TYPE_CHECKING:
+    from gobby.storage.artifacts import Artifact, LocalArtifactManager
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["ArtifactCaptureHook"]
+
+# Maximum number of content hashes to track for duplicate detection
+MAX_HASH_CACHE = 10000
+
+# Pattern to extract markdown code blocks
+_CODE_BLOCK_PATTERN = re.compile(r"```(\w*)\n(.*?)```", re.DOTALL)
+
+# Pattern to extract backtick-wrapped file paths
+_FILE_REF_PATTERN = re.compile(r"`([^\s`]+\.[a-zA-Z0-9]+)`")
+
+# Pattern to extract bare file paths (Unix-style)
+_UNIX_PATH_PATTERN = re.compile(r"(?:^|\s)(/[^\s]+\.[a-zA-Z0-9]+)(?:\s|$)")
+
+
+class ArtifactCaptureHook:
+    """
+    Hook for capturing artifacts from assistant messages.
+
+    Extracts code blocks, file references, and other artifacts from messages,
+    classifies them using artifact_classifier, and stores via LocalArtifactManager.
+
+    Tracks content hashes to prevent storing duplicate artifacts.
+    """
+
+    def __init__(self, artifact_manager: LocalArtifactManager):
+        """
+        Initialize the artifact capture hook.
+
+        Args:
+            artifact_manager: LocalArtifactManager instance for storing artifacts
+        """
+        self._artifact_manager = artifact_manager
+        # Use OrderedDict as LRU cache for bounded duplicate tracking
+        self._seen_hashes: OrderedDict[str, None] = OrderedDict()
+
+    def _compute_hash(self, content: str) -> str:
+        """Compute a hash for content deduplication."""
+        return hashlib.sha256(content.encode()).hexdigest()
+
+    def _is_duplicate(self, content: str) -> bool:
+        """Check if content has already been seen.
+
+        Uses a bounded LRU cache to prevent unbounded memory growth.
+        """
+        content_hash = self._compute_hash(content)
+        if content_hash in self._seen_hashes:
+            # Move to end (most recently used)
+            self._seen_hashes.move_to_end(content_hash)
+            return True
+
+        # Add new hash, evict oldest if over capacity
+        self._seen_hashes[content_hash] = None
+        if len(self._seen_hashes) > MAX_HASH_CACHE:
+            # Remove oldest entry (first item)
+            self._seen_hashes.popitem(last=False)
+
+        return False
+
+    def reset_duplicate_tracking(self) -> None:
+        """Clear the duplicate tracking cache.
+
+        Useful to reset between sessions or when memory needs to be freed.
+        """
+        self._seen_hashes.clear()
+
+    def _extract_code_blocks(self, content: str) -> list[tuple[str, str]]:
+        """
+        Extract code blocks from content.
+
+        Args:
+            content: Message content to extract from
+
+        Returns:
+            List of (language, code) tuples
+        """
+        blocks = []
+        for match in _CODE_BLOCK_PATTERN.finditer(content):
+            language = match.group(1).lower() if match.group(1) else ""
+            code = match.group(2).strip()
+            if code:
+                blocks.append((language, code))
+        return blocks
+
+    def _extract_file_references(self, content: str) -> list[str]:
+        """
+        Extract file path references from content.
+
+        Args:
+            content: Message content to extract from
+
+        Returns:
+            List of file paths
+        """
+        paths = set()
+
+        # Extract backtick-wrapped file paths
+        for match in _FILE_REF_PATTERN.finditer(content):
+            path = match.group(1)
+            # Filter out obvious non-paths
+            if "/" in path or "\\" in path:
+                paths.add(path)
+
+        # Extract Unix-style paths
+        for match in _UNIX_PATH_PATTERN.finditer(content):
+            paths.add(match.group(1))
+
+        return list(paths)
+
+    def process_message(
+        self,
+        session_id: str,
+        role: str,
+        content: str,
+    ) -> list[Artifact] | None:
+        """
+        Process a message and extract artifacts.
+
+        Only processes assistant messages. Extracts code blocks and file
+        references, classifies them, and stores them as artifacts.
+
+        Args:
+            session_id: ID of the session this message belongs to
+            role: Message role ("assistant" or "user")
+            content: Message content
+
+        Returns:
+            List of created Artifact objects, or None/empty if none created
+        """
+        # Only process assistant messages
+        if role != "assistant":
+            return None
+
+        if not content or not content.strip():
+            return []
+
+        artifacts: list[Artifact] = []
+
+        # Extract and store code blocks
+        code_blocks = self._extract_code_blocks(content)
+        for language, code in code_blocks:
+            if self._is_duplicate(code):
+                continue
+
+            # Use classifier to get type and metadata
+            result = classify_artifact(f"```{language}\n{code}\n```")
+            metadata = result.metadata.copy()
+
+            # Ensure language is in metadata
+            if language and "language" not in metadata:
+                metadata["language"] = language
+
+            try:
+                artifact = self._artifact_manager.create_artifact(
+                    session_id=session_id,
+                    artifact_type=result.artifact_type.value,
+                    content=code,
+                    metadata=metadata,
+                )
+                artifacts.append(artifact)
+            except Exception as e:
+                logger.error(f"Failed to create code artifact: {e}")
+
+        # Extract and store file references
+        file_paths = self._extract_file_references(content)
+        for path in file_paths:
+            if self._is_duplicate(path):
+                continue
+
+            # Use classifier to verify it's a file path
+            result = classify_artifact(path)
+            if result.artifact_type != ArtifactType.FILE_PATH:
+                continue
+
+            try:
+                artifact = self._artifact_manager.create_artifact(
+                    session_id=session_id,
+                    artifact_type=ArtifactType.FILE_PATH.value,
+                    content=path,
+                    metadata=result.metadata,
+                )
+                artifacts.append(artifact)
+            except Exception as e:
+                logger.error(f"Failed to create file path artifact: {e}")
+
+        return artifacts

gobby/hooks/broadcaster.py

@@ -0,0 +1,243 @@
+"""
+Hook Event Broadcaster.
+
+Broadcasting of hook events to WebSocket clients with filtering and sanitization.
+"""
+
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+from gobby.config.app import DaemonConfig
+from gobby.hooks.events import HookEvent, HookResponse
+from gobby.hooks.hook_types import (
+    HOOK_INPUT_MODELS,
+    HOOK_OUTPUT_MODELS,
+    HookInput,
+    HookOutput,
+    HookType,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# Mapping from unified HookEventType to specific HookType Pydantic models
+EVENT_TYPE_TO_HOOK_TYPE: dict[str, HookType] = {
+    "session_start": HookType.SESSION_START,
+    "session_end": HookType.SESSION_END,
+    "before_agent": HookType.USER_PROMPT_SUBMIT,
+    "after_agent": HookType.STOP,
+    "stop": HookType.STOP,
+    "before_tool": HookType.PRE_TOOL_USE,
+    "after_tool": HookType.POST_TOOL_USE,
+    "before_tool_selection": HookType.PRE_TOOL_USE,  # Maps to same as before_tool
+    "pre_compact": HookType.PRE_COMPACT,
+    "subagent_start": HookType.SUBAGENT_START,
+    "subagent_stop": HookType.SUBAGENT_STOP,
+    "notification": HookType.NOTIFICATION,
+    "before_model": HookType.BEFORE_MODEL,
+    "after_model": HookType.AFTER_MODEL,
+    "permission_request": HookType.PERMISSION_REQUEST,
+}
+
+
+class HookEventBroadcaster:
+    """
+    Broadcasts hook events to connected WebSocket clients.
+
+    Handles configuration checking, filtering, payload sanitization,
+    and message formatting.
+    """
+
+    def __init__(self, websocket_server: Any | None, config: DaemonConfig | None):
+        """
+        Initialize broadcaster.
+
+        Args:
+            websocket_server: WebSocketServer instance (can be None)
+            config: Daemon configuration (can be None)
+        """
+        self.websocket_server = websocket_server
+        self.config = config
+
+    async def broadcast_event(self, event: HookEvent, response: HookResponse | None = None) -> None:
+        """
+        Broadcast a unified HookEvent to all connected clients.
+
+        Automatically converts HookEvent to appropriate Pydantic models.
+
+        Args:
+            event: The unified HookEvent
+            response: Optional HookResponse result
+        """
+        if not self.websocket_server:
+            return
+
+        try:
+            # Map unified event type to HookType enum for Pydantic models
+            # Use value string lookup to avoid circular imports if HookEventType not available here
+            # (Though we imported HookType, we didn't import HookEventType enum class yet, just used strings in dict keys safely)
+            enum_hook_type = EVENT_TYPE_TO_HOOK_TYPE.get(event.event_type.value)
+
+            if not enum_hook_type:
+                # Try direct map if values match (fallback)
+                try:
+                    enum_hook_type = HookType(event.event_type.value)
+                except ValueError:
+                    logger.warning(
+                        f"Skipping broadcast for unknown hook type: {event.event_type.value}"
+                    )
+                    return
+
+            # Get input/output models
+            input_model_cls = HOOK_INPUT_MODELS.get(enum_hook_type)
+            output_model_cls = HOOK_OUTPUT_MODELS.get(enum_hook_type)
+
+            if not input_model_cls or not output_model_cls:
+                return
+
+            # Prepare input data
+            raw_input = event.data.copy()
+            # Map 'session_id' -> 'external_id' if needed
+            if "external_id" not in raw_input and event.session_id:
+                raw_input["external_id"] = event.session_id
+
+            # Special handling for Subagent events: ensure subagent_id is present
+            if enum_hook_type in (HookType.SUBAGENT_START, HookType.SUBAGENT_STOP):
+                if "subagent_id" not in raw_input and "external_id" in raw_input:
+                    raw_input["subagent_id"] = raw_input["external_id"]
+
+            # Map 'prompt' -> 'prompt_text' for UserPromptSubmit
+            if enum_hook_type == HookType.USER_PROMPT_SUBMIT:
+                if "prompt_text" not in raw_input and "prompt" in raw_input:
+                    raw_input["prompt_text"] = raw_input["prompt"]
+
+            # Ensure 'permission_type' has a default for PermissionRequest
+            if enum_hook_type == HookType.PERMISSION_REQUEST:
+                if "permission_type" not in raw_input:
+                    raw_input["permission_type"] = "unknown"
+
+            # Validate input data structure matches Pydantic model
+            # Use construct/model_validate to avoid strict validation errors if possible,
+            # or just try/except. Let's rely on standard validation.
+            validated_input = input_model_cls(**raw_input)
+
+            # Prepare output data if response provided
+            validated_output = None
+            if response:
+                # Map unified HookResponse to dict that matches Pydantic output model
+                # Note: HookResponse is unified, but Pydantic output models vary.
+                # Usually outputs have: continue, decision, etc.
+                # Simplest is to dump HookResponse to dict and filter/map.
+
+                # Default mapping from HookResponse
+                response_dict: dict[str, Any] = {
+                    "continue": response.decision != "deny",
+                    "decision": response.decision,
+                    "stopReason": response.reason,
+                    "systemMessage": response.system_message,
+                }
+
+                # Special handling: hookSpecificOutput from context
+                if response.context:
+                    # This is tricky without specific model knowledge, but assuming
+                    # generic structure or specific model fields.
+                    # For SessionStartOutput: { continue: bool, message: str, ... }
+                    # SessionStartOutput has: context: dict[str, Any] | None
+
+                    # If model expects 'context' as dict, but we have string.
+                    # We identified this mismatch earlier.
+                    # If input model expects dict, we need to wrap or parse.
+                    # Let's check the fields of the output model.
+                    if "context" in output_model_cls.model_fields:
+                        if isinstance(response.context, str):
+                            # Wrap string in dict if needed, or just pass if model allows str
+                            # SessionStartOutput.context is dict[str, Any] | None.
+                            response_dict["context"] = {"additionalContext": response.context}
+                        else:
+                            response_dict["context"] = response.context
+
+                # Clean None values
+                response_dict = {k: v for k, v in response_dict.items() if v is not None}
+
+                # Allow pydantic to ignore extra fields
+                validated_output = output_model_cls.model_validate(response_dict, strict=False)
+
+            # Call internal broadcast method
+            await self.broadcast_hook_event(enum_hook_type, validated_input, validated_output)
+
+        except Exception as e:
+            logger.warning(f"Failed to broadcast event {event.event_type}: {e}")
+
+    async def broadcast_hook_event(
+        self,
+        event_type: HookType,
+        event_input: HookInput,
+        event_output: HookOutput | None = None,
+    ) -> None:
+        """
+        Broadcast a specific hook event type.
+
+        Args:
+            event_type: The type of hook event
+            event_input: The input data for the hook
+            event_output: The output data from the hook (optional)
+        """
+        # Checks: WebSocket server implementation required
+        if not self.websocket_server:
+            return
+
+        # Checks: Feature enabled
+        if not self.config:
+            return
+
+        ws_config = self.config.hook_extensions.websocket
+        if not ws_config.enabled:
+            return
+
+        # Checks: Event filtering
+        if event_type.value not in ws_config.broadcast_events:
+            return
+
+        try:
+            # Construct payload
+            payload: dict[str, Any] = {
+                "type": "hook_event",
+                "event_type": event_type.value,
+                "timestamp": datetime.now(UTC).isoformat(),
+            }
+
+            # Add input data if enabled
+            if ws_config.include_payload:
+                # Convert Pydantic model to dict
+                input_data = event_input.model_dump(mode="json", exclude_none=True)
+
+                # Ensuring privacy/security -> stripping potentially sensitive fields could go here
+
+                # Add to payload
+                payload["data"] = input_data
+
+                # Add specific fields top-level if needed for convenience
+                # e.g. extract session_id from input
+                if hasattr(event_input, "external_id"):
+                    payload["session_id"] = event_input.external_id
+                elif hasattr(event_input, "session_id"):
+                    payload["session_id"] = event_input.session_id
+
+            # Add output data if present and enabled
+            if event_output and ws_config.include_payload:
+                output_data = event_output.model_dump(mode="json", exclude_none=True)
+                payload["result"] = output_data
+
+            # Add task context if present
+            if hasattr(event_input, "task_id") and event_input.task_id:
+                payload["task_id"] = event_input.task_id
+                # Include full task context if available in metadata
+                if hasattr(event_input, "metadata") and "_task_context" in event_input.metadata:
+                    payload["task_context"] = event_input.metadata["_task_context"]
+
+            # Broadcast message
+            await self.websocket_server.broadcast(payload)
+
+        except Exception as e:
+            logger.exception(f"Error broadcasting hook event {event_type.value}: {e}")