htmlgraph 0.20.1__py3-none-any.whl → 0.27.5__py3-none-any.whl

htmlgraph/session_hooks.py

@@ -0,0 +1,300 @@
+"""
+SessionStart Hook Integration - Initialize session registry with repo awareness.
+
+Integrates:
+- SessionRegistry: File-based session tracking
+- RepoHash: Git awareness and repository identification
+- AtomicFileWriter: Crash-safe writes
+
+Called by SessionStart hook to:
+1. Register new session with repo info
+2. Export session IDs to CLAUDE_ENV_FILE
+3. Detect parent sessions from environment
+4. Initialize heartbeat mechanism
+"""
+
+import logging
+import os
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def initialize_session_from_hook(env_file: str | None = None) -> str:
+    """
+    Initialize session registry from SessionStart hook.
+
+    Called automatically by SessionStart hook to set up session tracking.
+    Registers session with repository information and exports environment variables.
+
+    Args:
+        env_file: Path to CLAUDE_ENV_FILE (from hook environment).
+                 Allows exporting session IDs to parent process.
+
+    Returns:
+        session_id: Generated session ID for logging/tracking
+
+    Raises:
+        OSError: If registry initialization fails
+        RuntimeError: If session registration fails
+    """
+    from htmlgraph.repo_hash import RepoHash
+    from htmlgraph.session_registry import SessionRegistry
+
+    try:
+        # Initialize registry (creates .htmlgraph/sessions/registry structure)
+        registry = SessionRegistry()
+        logger.debug(f"Initialized SessionRegistry at {registry.registry_dir}")
+
+        # Get repo information
+        try:
+            repo_hash = RepoHash()
+            git_info = repo_hash.get_git_info()
+            repo_hash_value = repo_hash.compute_repo_hash()
+
+            repo_info = {
+                "path": str(repo_hash.repo_path),
+                "hash": repo_hash_value,
+                "branch": git_info.get("branch"),
+                "commit": git_info.get("commit"),
+                "remote": git_info.get("remote"),
+                "dirty": git_info.get("dirty", False),
+                "is_monorepo": repo_hash.is_monorepo(),
+                "monorepo_project": repo_hash.get_monorepo_project(),
+            }
+            logger.debug(f"Repo info: {repo_info}")
+        except OSError as e:
+            logger.warning(f"Failed to get repo info: {e}")
+            repo_info = {
+                "path": str(Path.cwd()),
+                "hash": "unknown",
+                "branch": None,
+                "commit": None,
+                "remote": None,
+                "dirty": False,
+                "is_monorepo": False,
+                "monorepo_project": None,
+            }
+
+        # Get instance information
+        instance_info = {
+            "pid": os.getpid(),
+            "hostname": _get_hostname(),
+            "start_time": _get_utc_timestamp(),
+        }
+
+        # Generate session ID
+        session_id = f"sess-{uuid.uuid4().hex[:8]}"
+
+        # Register session atomically
+        try:
+            registry_file = registry.register_session(
+                session_id=session_id,
+                repo_info=repo_info,
+                instance_info=instance_info,
+            )
+            logger.info(f"Registered session {session_id} at {registry_file}")
+        except OSError as e:
+            logger.error(f"Failed to register session: {e}")
+            raise RuntimeError(f"Session registration failed: {e}") from e
+
+        # Export to CLAUDE_ENV_FILE if provided
+        if env_file:
+            try:
+                _export_to_env_file(
+                    env_file=env_file,
+                    session_id=session_id,
+                    instance_id=registry.get_instance_id(),
+                    repo_hash=repo_hash_value
+                    if "repo_hash_value" in locals()
+                    else "unknown",
+                )
+                logger.debug(f"Exported session environment to {env_file}")
+            except OSError as e:
+                logger.warning(f"Failed to export environment: {e}")
+                # Don't fail - session is registered even if export fails
+
+        # Check for parent session
+        parent_session_id = _get_parent_session_id()
+        if parent_session_id:
+            logger.info(f"Parent session detected: {parent_session_id}")
+            # Store parent relationship in environment for subprocesses
+            os.environ["HTMLGRAPH_PARENT_SESSION_ID"] = parent_session_id
+
+        return session_id
+
+    except Exception as e:
+        logger.error(f"Failed to initialize session: {e}", exc_info=True)
+        raise
+
+
+def finalize_session(session_id: str, status: str = "ended") -> bool:
+    """
+    Finalize session (called by SessionEnd hook).
+
+    Archives the session and updates last activity timestamp.
+
+    Args:
+        session_id: Session ID to finalize
+        status: Final status (ended, failed, etc.)
+
+    Returns:
+        True if finalization succeeded, False otherwise
+    """
+    from htmlgraph.session_registry import SessionRegistry
+
+    try:
+        registry = SessionRegistry()
+        instance_id = registry.get_instance_id()
+
+        # Archive the session
+        success = registry.archive_session(instance_id)
+        if success:
+            logger.info(f"Archived session {session_id} (status: {status})")
+        else:
+            logger.warning(f"Failed to archive session {session_id}")
+
+        return success
+    except Exception as e:
+        logger.error(f"Failed to finalize session {session_id}: {e}")
+        return False
+
+
+def heartbeat(session_id: str | None = None) -> bool:
+    """
+    Update session activity timestamp (liveness heartbeat).
+
+    Called periodically to indicate the session is still active.
+    Should be called on each tool use or periodically (e.g., every 5 minutes).
+
+    Args:
+        session_id: Optional session ID (uses current instance if None)
+
+    Returns:
+        True if heartbeat succeeded, False otherwise
+    """
+    from htmlgraph.session_registry import SessionRegistry
+
+    try:
+        registry = SessionRegistry()
+        instance_id = registry.get_instance_id()
+
+        success = registry.update_activity(instance_id)
+        if success:
+            logger.debug(f"Updated activity for instance {instance_id}")
+        else:
+            logger.warning(f"Failed to update activity for instance {instance_id}")
+
+        return success
+    except Exception as e:
+        logger.error(f"Failed to update activity: {e}")
+        return False
+
+
+def get_current_session() -> dict | None:
+    """
+    Get current session for this instance.
+
+    Returns the registration data for the current instance's session.
+
+    Returns:
+        Session dict with instance_id, session_id, repo, etc., or None if not found
+    """
+    from htmlgraph.session_registry import SessionRegistry
+
+    try:
+        registry = SessionRegistry()
+        instance_id = registry.get_instance_id()
+        session = registry.read_session(instance_id)
+        return session
+    except Exception as e:
+        logger.error(f"Failed to get current session: {e}")
+        return None
+
+
+def get_parent_session_id() -> str | None:
+    """
+    Get parent session ID if this is a spawned task.
+
+    Returns:
+        Parent session ID from environment, or None if not a spawned task
+    """
+    return _get_parent_session_id()
+
+
+# Private helpers
+
+
+def _get_hostname() -> str:
+    """Get hostname safely."""
+    try:
+        import socket
+
+        return socket.gethostname()
+    except Exception:
+        return "unknown"
+
+
+def _get_utc_timestamp() -> str:
+    """Get current UTC timestamp in ISO 8601 format."""
+    now = datetime.now(timezone.utc)
+    return now.strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def _export_to_env_file(
+    env_file: str,
+    session_id: str,
+    instance_id: str,
+    repo_hash: str,
+) -> None:
+    """
+    Export session environment variables to CLAUDE_ENV_FILE.
+
+    Appends to the file to preserve any existing variables.
+
+    Args:
+        env_file: Path to environment file
+        session_id: Session ID to export
+        instance_id: Instance ID to export
+        repo_hash: Repository hash to export
+
+    Raises:
+        OSError: If file write fails
+    """
+    env_path = Path(env_file)
+
+    try:
+        # Append to environment file
+        with open(env_path, "a") as f:
+            f.write(f"export HTMLGRAPH_SESSION_ID={session_id}\n")
+            f.write(f"export HTMLGRAPH_INSTANCE_ID={instance_id}\n")
+            f.write(f"export HTMLGRAPH_REPO_HASH={repo_hash}\n")
+
+        logger.debug(f"Exported environment variables to {env_file}")
+    except OSError as e:
+        logger.error(f"Failed to export environment to {env_file}: {e}")
+        raise
+
+
+def _get_parent_session_id() -> str | None:
+    """
+    Detect parent session from environment.
+
+    Checks:
+    1. HTMLGRAPH_PARENT_SESSION_ID env var (set by Task spawning)
+    2. HTMLGRAPH_PARENT_SESSION env var (alternate name)
+
+    Returns:
+        Parent session ID if found, None otherwise
+    """
+    parent_id = os.environ.get("HTMLGRAPH_PARENT_SESSION_ID")
+    if parent_id:
+        return parent_id
+
+    parent_id = os.environ.get("HTMLGRAPH_PARENT_SESSION")
+    if parent_id:
+        return parent_id
+
+    return None

htmlgraph/session_manager.py

@@ -27,7 +27,7 @@ from htmlgraph.event_log import EventRecord, JsonlEventLog
 from htmlgraph.exceptions import SessionNotFoundError
 from htmlgraph.graph import HtmlGraph
 from htmlgraph.ids import generate_id
-from htmlgraph.models import ActivityEntry, Node, Session
+from htmlgraph.models import ActivityEntry, ErrorEntry, Node, Session
 from htmlgraph.services import ClaimingService
 from htmlgraph.spike_index import ActiveAutoSpikeIndex
 
@@ -186,7 +186,7 @@ class SessionManager:
         """Mark a session as stale (kept for history but not considered active)."""
         if session.status != "active":
             return
-        now = datetime.now()
+        now = datetime.now(timezone.utc)
         session.status = "stale"
         session.ended_at = now
         session.last_activity = now
@@ -230,6 +230,7 @@ class SessionManager:
         continued_from: str | None = None,
         start_commit: str | None = None,
         title: str | None = None,
+        parent_session_id: str | None = None,
     ) -> Session:
         """
         Start a new session.
@@ -241,6 +242,7 @@ class SessionManager:
             continued_from: Previous session ID if continuing
             start_commit: Git commit hash at session start
             title: Optional human-readable title
+            parent_session_id: ID of parent session (for subagents)
 
         Returns:
             New Session instance
@@ -309,6 +311,7 @@ class SessionManager:
             started_at=now,
             last_activity=now,
             title=title or "",
+            parent_session=parent_session_id,
         )
 
         # Add session start event
@@ -320,6 +323,12 @@ class SessionManager:
             )
         )
 
+        # Set parent session in environment for subsequent subprocesses (e.g. HeadlessSpawner)
+        # This ensures that any tools spawned by this session link back to it
+        import os
+
+        os.environ["HTMLGRAPH_PARENT_SESSION"] = session.id
+
         # Save to disk
         self.session_converter.save(session)
         self._sessions_cache_dirty = True
@@ -733,7 +742,7 @@ class SessionManager:
             ActivityEntry(
                 tool="SessionEnd",
                 summary="Session ended",
-                timestamp=datetime.now(),
+                timestamp=datetime.now(timezone.utc),
             )
         )
 
@@ -783,6 +792,158 @@ class SessionManager:
 
         return session
 
+    def continue_from_last(
+        self,
+        agent: str | None = None,
+        auto_create_session: bool = True,
+    ) -> tuple[Session | None, Any]:  # Returns (new_session, resume_info)
+        """
+        Continue work from the last completed session.
+
+        Loads context from the previous session including:
+        - Handoff notes and next focus
+        - Blockers
+        - Recommended context files
+        - Recent commits
+        - Features worked on
+
+        Args:
+            agent: Filter by agent (None = current agent)
+            auto_create_session: Create new session if True
+
+        Returns:
+            Tuple of (new_session, resume_info) or (None, None) if no previous session
+
+        Example:
+            >>> manager = SessionManager(".htmlgraph")
+            >>> new_session, resume = manager.continue_from_last(agent="claude")
+            >>> if resume:
+            ...     print(resume.summary)
+            ...     print(resume.recommended_files)
+        """
+        # Import handoff module
+        from typing import Any
+
+        from htmlgraph.sessions.handoff import SessionResume
+
+        # Create a minimal SDK-like object with just the directory
+        # to avoid circular dependency and database initialization issues
+        class MinimalSDK:
+            def __init__(self, directory: Path) -> None:
+                self._directory = directory
+
+        sdk: Any = MinimalSDK(self.graph_dir)
+        resume = SessionResume(sdk)
+
+        # Get last session
+        last_session = resume.get_last_session(agent=agent)
+        if not last_session:
+            return None, None
+
+        # Build resume info
+        resume_info = resume.build_resume_info(last_session)
+
+        # Create new session if requested
+        new_session = None
+        if auto_create_session:
+            from htmlgraph.ids import generate_id
+
+            session_id = generate_id("sess")
+            new_session = self.start_session(
+                session_id=session_id,
+                agent=agent or last_session.agent,
+                title=f"Continuing from {last_session.id}",
+            )
+
+            # Link to previous session
+            new_session.continued_from = last_session.id
+            self.session_converter.save(new_session)
+
+        return new_session, resume_info
+
+    def end_session_with_handoff(
+        self,
+        session_id: str,
+        summary: str | None = None,
+        next_focus: str | None = None,
+        blockers: list[str] | None = None,
+        keep_context: list[str] | None = None,
+        auto_recommend_context: bool = True,
+    ) -> Session | None:
+        """
+        End session with handoff information for next session.
+
+        Args:
+            session_id: Session to end
+            summary: What was accomplished (handoff notes)
+            next_focus: What should be done next
+            blockers: List of blockers preventing progress
+            keep_context: List of files to keep context for
+            auto_recommend_context: Auto-recommend files from git history
+
+        Returns:
+            Updated session or None
+
+        Example:
+            >>> manager.end_session_with_handoff(
+            ...     session_id="sess-123",
+            ...     summary="Completed OAuth integration",
+            ...     next_focus="Implement JWT token refresh",
+            ...     blockers=["Waiting for security review"],
+            ...     keep_context=["src/auth/oauth.py"]
+            ... )
+        """
+        from htmlgraph.sessions.handoff import (
+            ContextRecommender,
+            HandoffBuilder,
+        )
+
+        # Get session
+        session = self.get_session(session_id)
+        if not session:
+            return None
+
+        # Build handoff using HandoffBuilder
+        builder = HandoffBuilder(session)
+
+        if summary:
+            builder.add_summary(summary)
+
+        if next_focus:
+            builder.add_next_focus(next_focus)
+
+        if blockers:
+            builder.add_blockers(blockers)
+
+        if keep_context:
+            builder.add_context_files(keep_context)
+
+        # Auto-recommend context files
+        if auto_recommend_context:
+            recommender = ContextRecommender()
+            builder.auto_recommend_context(recommender, max_files=10)
+
+        handoff_data = builder.build()
+
+        # Update session with handoff data
+        session.handoff_notes = handoff_data["handoff_notes"]
+        session.recommended_next = handoff_data["recommended_next"]
+        session.blockers = handoff_data["blockers"]
+        session.recommended_context = handoff_data["recommended_context"]
+
+        # Persist handoff data to database before ending session
+        self.session_converter.save(session)
+
+        # End the session
+        self.end_session(session_id)
+
+        # Track handoff effectiveness (optional - only if database available)
+        # Note: SessionManager doesn't have direct database access,
+        # handoff tracking is primarily done through SDK
+        # Users should use SDK.end_session_with_handoff() for full tracking
+
+        return session
+
     def release_session_features(self, session_id: str) -> list[str]:
         """
         Release all features claimed by a specific session.
@@ -795,6 +956,126 @@ class SessionManager:
         """
         return self.claiming_service.release_session_features(session_id)
 
+    def log_error(
+        self,
+        session_id: str,
+        error: Exception,
+        traceback_str: str,
+        context: dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Log error with full traceback to session.
+
+        Stores complete error details for later retrieval via debug command.
+        Minimizes console output for better token efficiency.
+
+        Args:
+            session_id: Session ID to log error to
+            error: The exception object
+            traceback_str: Full traceback string
+            context: Optional context dict (e.g. current file, line number)
+        """
+        session = self.get_session(session_id)
+        if not session:
+            return
+
+        error_entry = ErrorEntry(
+            timestamp=datetime.now(),
+            error_type=error.__class__.__name__,
+            message=str(error),
+            traceback=traceback_str,
+        )
+
+        # Append error record to error_log
+        session.error_log.append(error_entry)
+
+        # Save updated session
+        self.session_converter.save(session)
+
+    def get_session_errors(self, session_id: str) -> list[dict[str, Any]]:
+        """
+        Retrieve all errors logged for a session.
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            List of error records, or empty list if none
+        """
+        session = self.get_session(session_id)
+        if not session:
+            return []
+        return [error.model_dump() for error in session.error_log]
+
+    def search_errors(
+        self,
+        session_id: str,
+        error_type: str | None = None,
+        pattern: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """
+        Search errors in a session by type and/or pattern.
+
+        Args:
+            session_id: Session ID to search
+            error_type: Filter by exception type (e.g., "ValueError")
+            pattern: Regex pattern to match in error message
+
+        Returns:
+            List of matching error records
+        """
+        session = self.get_session(session_id)
+        if not session:
+            return []
+
+        errors = [error.model_dump() for error in session.error_log]
+
+        # Filter by error type
+        if error_type:
+            errors = [e for e in errors if e.get("error_type") == error_type]
+
+        # Filter by pattern in message
+        if pattern:
+            compiled_pattern = re.compile(pattern, re.IGNORECASE)
+            errors = [
+                e for e in errors if compiled_pattern.search(e.get("message", ""))
+            ]
+
+        return errors
+
+    def get_error_summary(self, session_id: str) -> dict[str, Any]:
+        """
+        Get summary statistics of errors in a session.
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            Dictionary with error summary statistics
+        """
+        session = self.get_session(session_id)
+        if not session or not session.error_log:
+            return {
+                "total_errors": 0,
+                "error_types": {},
+                "first_error": None,
+                "last_error": None,
+            }
+
+        errors = session.error_log
+        error_types: dict[str, int] = {}
+
+        for error in errors:
+            error_type = error.error_type
+            error_types[error_type] = error_types.get(error_type, 0) + 1
+
+        return {
+            "total_errors": len(errors),
+            "error_types": error_types,
+            "first_error": errors[0].model_dump() if errors else None,
+            "last_error": errors[-1].model_dump() if errors else None,
+        }
+
     # =========================================================================
     # Activity Tracking
     # =========================================================================
@@ -925,6 +1206,7 @@ class SessionManager:
                     work_type=work_type,
                     session_status=session.status,
                     file_paths=file_paths,
+                    parent_session_id=session.parent_session,
                     payload=entry.payload
                     if isinstance(entry.payload, dict)
                     else payload,