hanzo-mcp 0.3.4__py3-none-any.whl → 0.5.0__py3-none-any.whl

hanzo_mcp/tools/shell/session_storage.py

@@ -0,0 +1,325 @@
+"""Session storage module for shell command sessions.
+
+This module provides storage functionality for managing persistent shell sessions.
+It supports both global class-based storage (for backward compatibility) and
+instance-based storage (for dependency injection scenarios).
+"""
+
+import time
+from typing import TYPE_CHECKING, final
+
+if TYPE_CHECKING:
+    from hanzo_mcp.tools.shell.bash_session import BashSession
+
+
+@final
+class SessionStorageInstance:
+    """Instance-based storage for shell command sessions.
+
+    This class provides isolated storage for different SessionManager instances,
+    preventing shared state between different contexts. It includes LRU eviction
+    and TTL-based cleanup to prevent memory leaks.
+    """
+
+    def __init__(self, max_sessions: int = 20, default_ttl_seconds: int = 300):
+        """Initialize instance storage.
+
+        Args:
+            max_sessions: Maximum number of sessions to keep (LRU eviction after this)
+            default_ttl_seconds: Default TTL for sessions in seconds (5 minutes)
+        """
+        self._sessions: dict[str, "BashSession"] = {}
+        self._last_access: dict[str, float] = {}
+        self._access_order: list[str] = []  # Track access order for LRU
+        self.max_sessions = max_sessions
+        self.default_ttl_seconds = default_ttl_seconds
+
+    def _update_access_order(self, session_id: str) -> None:
+        """Update the access order for LRU tracking.
+
+        Args:
+            session_id: The session that was accessed
+        """
+        # Remove from current position if exists
+        if session_id in self._access_order:
+            self._access_order.remove(session_id)
+        # Add to end (most recently used)
+        self._access_order.append(session_id)
+
+    def _evict_lru_if_needed(self) -> None:
+        """Evict least recently used sessions if over capacity."""
+        # More aggressive eviction: start evicting when we reach 80% capacity
+        eviction_threshold = max(1, int(self.max_sessions * 0.8))
+        while len(self._sessions) >= eviction_threshold and self._access_order:
+            # Get least recently used session (first in list)
+            lru_session_id = self._access_order[0]
+            self.remove_session(lru_session_id)
+
+    def get_session(self, session_id: str) -> "BashSession | None":
+        """Get a session by ID.
+
+        Args:
+            session_id: The session identifier
+
+        Returns:
+            The session if found, None otherwise
+        """
+        session = self._sessions.get(session_id)
+        if session:
+            current_time = time.time()
+            self._last_access[session_id] = current_time
+            self._update_access_order(session_id)
+
+            # Check if session has expired
+            session_age = current_time - self._last_access.get(session_id, current_time)
+            if session_age > self.default_ttl_seconds:
+                self.remove_session(session_id)
+                return None
+
+        return session
+
+    def set_session(self, session_id: str, session: "BashSession") -> None:
+        """Store a session.
+
+        Args:
+            session_id: The session identifier
+            session: The session to store
+        """
+        current_time = time.time()
+
+        # If session already exists, update it
+        if session_id in self._sessions:
+            self._sessions[session_id] = session
+            self._last_access[session_id] = current_time
+            self._update_access_order(session_id)
+        else:
+            # New session - check if we need to evict first
+            self._evict_lru_if_needed()
+
+            # Add new session
+            self._sessions[session_id] = session
+            self._last_access[session_id] = current_time
+            self._update_access_order(session_id)
+
+    def remove_session(self, session_id: str) -> bool:
+        """Remove a session from storage.
+
+        Args:
+            session_id: The session identifier
+
+        Returns:
+            True if session was removed, False if not found
+        """
+        session = self._sessions.pop(session_id, None)
+        self._last_access.pop(session_id, None)
+
+        # Remove from access order tracking
+        if session_id in self._access_order:
+            self._access_order.remove(session_id)
+
+        if session:
+            # Clean up the session resources
+            try:
+                session.close()
+            except Exception:
+                pass  # Ignore cleanup errors
+            return True
+        return False
+
+    def get_session_count(self) -> int:
+        """Get the number of active sessions.
+
+        Returns:
+            Number of active sessions
+        """
+        return len(self._sessions)
+
+    def get_all_session_ids(self) -> list[str]:
+        """Get all active session IDs.
+
+        Returns:
+            List of active session IDs
+        """
+        return list(self._sessions.keys())
+
+    def cleanup_expired_sessions(self, max_age_seconds: int | None = None) -> int:
+        """Clean up sessions that haven't been accessed recently.
+
+        Args:
+            max_age_seconds: Maximum age in seconds before cleanup.
+                           If None, uses instance default TTL.
+
+        Returns:
+            Number of sessions cleaned up
+        """
+        max_age = (
+            max_age_seconds if max_age_seconds is not None else self.default_ttl_seconds
+        )
+        current_time = time.time()
+        expired_sessions: list[str] = []
+
+        for session_id, last_access in self._last_access.items():
+            if current_time - last_access > max_age:
+                expired_sessions.append(session_id)
+
+        cleaned_count = 0
+        for session_id in expired_sessions:
+            if self.remove_session(session_id):
+                cleaned_count += 1
+
+        return cleaned_count
+
+    def clear_all_sessions(self) -> int:
+        """Clear all sessions.
+
+        Returns:
+            Number of sessions cleared
+        """
+        session_ids = list(self._sessions.keys())
+        cleared_count = 0
+
+        for session_id in session_ids:
+            if self.remove_session(session_id):
+                cleared_count += 1
+
+        return cleared_count
+
+    def get_lru_session_ids(self) -> list[str]:
+        """Get session IDs in LRU order (least recently used first).
+
+        Returns:
+            List of session IDs in LRU order
+        """
+        return self._access_order.copy()
+
+    def get_session_stats(self) -> dict:
+        """Get storage statistics.
+
+        Returns:
+            Dictionary with storage statistics
+        """
+        return {
+            "total_sessions": len(self._sessions),
+            "max_sessions": self.max_sessions,
+            "utilization": len(self._sessions) / self.max_sessions
+            if self.max_sessions > 0
+            else 0,
+            "default_ttl_seconds": self.default_ttl_seconds,
+        }
+
+
+class SessionStorage:
+    """Global class-based storage for shell command sessions.
+
+    This class maintains backward compatibility while providing the same
+    interface as SessionStorageInstance for global session management.
+    """
+
+    _sessions: dict[str, "BashSession"] = {}
+    _last_access: dict[str, float] = {}
+
+    @classmethod
+    def get_session(cls, session_id: str) -> "BashSession | None":
+        """Get a session by ID.
+
+        Args:
+            session_id: The session identifier
+
+        Returns:
+            The session if found, None otherwise
+        """
+        session = cls._sessions.get(session_id)
+        if session:
+            cls._last_access[session_id] = time.time()
+        return session
+
+    @classmethod
+    def set_session(cls, session_id: str, session: "BashSession") -> None:
+        """Store a session.
+
+        Args:
+            session_id: The session identifier
+            session: The session to store
+        """
+        cls._sessions[session_id] = session
+        cls._last_access[session_id] = time.time()
+
+    @classmethod
+    def remove_session(cls, session_id: str) -> bool:
+        """Remove a session from storage.
+
+        Args:
+            session_id: The session identifier
+
+        Returns:
+            True if session was removed, False if not found
+        """
+        session = cls._sessions.pop(session_id, None)
+        cls._last_access.pop(session_id, None)
+
+        if session:
+            # Clean up the session resources
+            try:
+                session.close()
+            except Exception:
+                pass  # Ignore cleanup errors
+            return True
+        return False
+
+    @classmethod
+    def get_session_count(cls) -> int:
+        """Get the number of active sessions.
+
+        Returns:
+            Number of active sessions
+        """
+        return len(cls._sessions)
+
+    @classmethod
+    def get_all_session_ids(cls) -> list[str]:
+        """Get all active session IDs.
+
+        Returns:
+            List of active session IDs
+        """
+        return list(cls._sessions.keys())
+
+    @classmethod
+    def cleanup_expired_sessions(cls, max_age_seconds: int = 300) -> int:
+        """Clean up sessions that haven't been accessed recently.
+
+        Args:
+            max_age_seconds: Maximum age in seconds before cleanup (default: 5 minutes)
+
+        Returns:
+            Number of sessions cleaned up
+        """
+        current_time = time.time()
+        expired_sessions: list[str] = []
+
+        for session_id, last_access in cls._last_access.items():
+            if current_time - last_access > max_age_seconds:
+                expired_sessions.append(session_id)
+
+        cleaned_count = 0
+        for session_id in expired_sessions:
+            if cls.remove_session(session_id):
+                cleaned_count += 1
+
+        return cleaned_count
+
+    @classmethod
+    def clear_all_sessions(cls) -> int:
+        """Clear all sessions.
+
+        Returns:
+            Number of sessions cleared
+        """
+        session_ids = list(cls._sessions.keys())
+        cleared_count = 0
+
+        for session_id in session_ids:
+            if cls.remove_session(session_id):
+                cleared_count += 1
+
+        return cleared_count

hanzo_mcp/tools/todo/__init__.py

@@ -0,0 +1,66 @@
+"""Todo tools package for Hanzo MCP.
+
+This package provides tools for managing todo lists across different Claude Desktop sessions,
+using in-memory storage to maintain separate task lists for each conversation.
+"""
+
+from fastmcp import FastMCP
+
+from hanzo_mcp.tools.common.base import BaseTool, ToolRegistry
+from hanzo_mcp.tools.todo.todo_read import TodoReadTool
+from hanzo_mcp.tools.todo.todo_write import TodoWriteTool
+
+# Export all tool classes
+__all__ = [
+    "TodoReadTool",
+    "TodoWriteTool",
+    "get_todo_tools",
+    "register_todo_tools",
+]
+
+
+def get_todo_tools() -> list[BaseTool]:
+    """Create instances of all todo tools.
+
+    Returns:
+        List of todo tool instances
+    """
+    return [
+        TodoReadTool(),
+        TodoWriteTool(),
+    ]
+
+
+def register_todo_tools(
+    mcp_server: FastMCP,
+    enabled_tools: dict[str, bool] | None = None,
+) -> list[BaseTool]:
+    """Register todo tools with the MCP server.
+
+    Args:
+        mcp_server: The FastMCP server instance
+        enabled_tools: Dictionary of individual tool enable states (default: None)
+
+    Returns:
+        List of registered tools
+    """
+    # Define tool mapping
+    tool_classes = {
+        "todo_read": TodoReadTool,
+        "todo_write": TodoWriteTool,
+    }
+    
+    tools = []
+    
+    if enabled_tools:
+        # Use individual tool configuration
+        for tool_name, enabled in enabled_tools.items():
+            if enabled and tool_name in tool_classes:
+                tool_class = tool_classes[tool_name]
+                tools.append(tool_class())
+    else:
+        # Use all tools (backward compatibility)
+        tools = get_todo_tools()
+    
+    ToolRegistry.register_tools(mcp_server, tools)
+    return tools

hanzo_mcp/tools/todo/base.py

@@ -0,0 +1,319 @@
+"""Base functionality for todo tools.
+
+This module provides common functionality for todo tools, including in-memory storage
+for managing todo lists across different Claude Desktop sessions.
+"""
+
+import re
+import time
+from abc import ABC
+from typing import Any, final
+
+from fastmcp import Context as MCPContext
+
+from hanzo_mcp.tools.common.base import BaseTool
+from hanzo_mcp.tools.common.context import ToolContext, create_tool_context
+
+
+@final
+class TodoStorage:
+    """In-memory storage for todo lists, separated by session ID.
+
+    This class provides persistent storage for the lifetime of the MCP server process,
+    allowing different Claude Desktop conversations to maintain separate todo lists.
+    Each session stores both the todo list and a timestamp of when it was last updated.
+    """
+
+    # Class-level storage shared across all tool instances
+    # Structure: {session_id: {"todos": [...], "last_updated": timestamp}}
+    _sessions: dict[str, dict[str, Any]] = {}
+
+    @classmethod
+    def get_todos(cls, session_id: str) -> list[dict[str, Any]]:
+        """Get the todo list for a specific session.
+
+        Args:
+            session_id: Unique identifier for the Claude Desktop session
+
+        Returns:
+            List of todo items for the session, empty list if session doesn't exist
+        """
+        session_data = cls._sessions.get(session_id, {})
+        return session_data.get("todos", [])
+
+    @classmethod
+    def set_todos(cls, session_id: str, todos: list[dict[str, Any]]) -> None:
+        """Set the todo list for a specific session.
+
+        Args:
+            session_id: Unique identifier for the Claude Desktop session
+            todos: Complete list of todo items to store
+        """
+        cls._sessions[session_id] = {"todos": todos, "last_updated": time.time()}
+
+    @classmethod
+    def get_session_count(cls) -> int:
+        """Get the number of active sessions.
+
+        Returns:
+            Number of sessions with stored todos
+        """
+        return len(cls._sessions)
+
+    @classmethod
+    def get_all_session_ids(cls) -> list[str]:
+        """Get all active session IDs.
+
+        Returns:
+            List of all session IDs with stored todos
+        """
+        return list(cls._sessions.keys())
+
+    @classmethod
+    def delete_session(cls, session_id: str) -> bool:
+        """Delete a session and its todos.
+
+        Args:
+            session_id: Session ID to delete
+
+        Returns:
+            True if session was deleted, False if it didn't exist
+        """
+        if session_id in cls._sessions:
+            del cls._sessions[session_id]
+            return True
+        return False
+
+    @classmethod
+    def get_session_last_updated(cls, session_id: str) -> float | None:
+        """Get the last updated timestamp for a session.
+
+        Args:
+            session_id: Session ID to check
+
+        Returns:
+            Timestamp when session was last updated, or None if session doesn't exist
+        """
+        session_data = cls._sessions.get(session_id)
+        if session_data:
+            return session_data.get("last_updated")
+        return None
+
+    @classmethod
+    def find_latest_active_session(cls) -> str | None:
+        """Find the chronologically latest session with unfinished todos.
+
+        Returns the session ID of the most recently updated session that has unfinished todos.
+        Returns None if no sessions have unfinished todos.
+
+        Returns:
+            Session ID with unfinished todos that was most recently updated, or None if none found
+        """
+        from hanzo_mcp.prompts.project_todo_reminder import has_unfinished_todos
+
+        latest_session = None
+        latest_timestamp = 0
+
+        for session_id, session_data in cls._sessions.items():
+            todos = session_data.get("todos", [])
+            if has_unfinished_todos(todos):
+                last_updated = session_data.get("last_updated", 0)
+                if last_updated > latest_timestamp:
+                    latest_timestamp = last_updated
+                    latest_session = session_id
+
+        return latest_session
+
+
+class TodoBaseTool(BaseTool, ABC):
+    """Base class for todo tools.
+
+    Provides common functionality for working with todo lists, including
+    session ID validation and todo structure validation.
+    """
+
+    def create_tool_context(self, ctx: MCPContext) -> ToolContext:
+        """Create a tool context with the tool name.
+
+        Args:
+            ctx: MCP context
+
+        Returns:
+            Tool context
+        """
+        tool_ctx = create_tool_context(ctx)
+        return tool_ctx
+
+    def set_tool_context_info(self, tool_ctx: ToolContext) -> None:
+        """Set the tool info on the context.
+
+        Args:
+            tool_ctx: Tool context
+        """
+        tool_ctx.set_tool_info(self.name)
+
+    def normalize_todo_item(self, todo: dict[str, Any], index: int) -> dict[str, Any]:
+        """Normalize a single todo item by auto-generating missing required fields.
+
+        Args:
+            todo: Todo item to normalize
+            index: Index of the todo item for generating unique IDs
+
+        Returns:
+            Normalized todo item with all required fields
+        """
+        normalized = dict(todo)  # Create a copy
+
+        # Auto-generate ID if missing or normalize existing ID to string
+        if "id" not in normalized or not str(normalized.get("id")).strip():
+            normalized["id"] = f"todo-{index + 1}"
+        else:
+            # Ensure ID is stored as a string for consistency
+            normalized["id"] = str(normalized["id"]).strip()
+
+        # Auto-generate priority if missing (but don't fix invalid values)
+        if "priority" not in normalized:
+            normalized["priority"] = "medium"
+
+        # Ensure status defaults to pending if missing (but don't fix invalid values)
+        if "status" not in normalized:
+            normalized["status"] = "pending"
+
+        return normalized
+
+    def normalize_todos_list(self, todos: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Normalize a list of todo items by auto-generating missing fields.
+
+        Args:
+            todos: List of todo items to normalize
+
+        Returns:
+            Normalized list of todo items with all required fields
+        """
+        if not isinstance(todos, list):
+            return []  # Return empty list for invalid input
+
+        normalized_todos = []
+        used_ids = set()
+
+        for i, todo in enumerate(todos):
+            if not isinstance(todo, dict):
+                continue  # Skip invalid items
+
+            normalized = self.normalize_todo_item(todo, i)
+
+            # Don't auto-fix duplicate IDs - let validation catch them
+            used_ids.add(normalized["id"])
+            normalized_todos.append(normalized)
+
+        return normalized_todos
+
+    def validate_session_id(self, session_id: str | None) -> tuple[bool, str]:
+        """Validate session ID format and security.
+
+        Args:
+            session_id: Session ID to validate
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        # Check for None or empty first
+        if session_id is None or session_id == "":
+            return False, "Session ID is required but was empty"
+
+        # Check if it's a string
+        if not isinstance(session_id, str):
+            return False, "Session ID must be a string"
+
+        # Check length (reasonable bounds)
+        if len(session_id) < 5:
+            return False, "Session ID too short (minimum 5 characters)"
+
+        if len(session_id) > 100:
+            return False, "Session ID too long (maximum 100 characters)"
+
+        # Check format - allow alphanumeric, hyphens, underscores
+        # This prevents path traversal and other security issues
+        if not re.match(r"^[a-zA-Z0-9_-]+$", session_id):
+            return (
+                False,
+                "Session ID can only contain alphanumeric characters, hyphens, and underscores",
+            )
+
+        return True, ""
+
+    def validate_todo_item(self, todo: dict[str, Any]) -> tuple[bool, str]:
+        """Validate a single todo item structure.
+
+        Args:
+            todo: Todo item to validate
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not isinstance(todo, dict):
+            return False, "Todo item must be an object"
+
+        # Check required fields
+        required_fields = ["content", "status", "priority", "id"]
+        for field in required_fields:
+            if field not in todo:
+                return False, f"Todo item missing required field: {field}"
+
+        # Validate content
+        content = todo.get("content")
+        if not isinstance(content, str) or not content.strip():
+            return False, "Todo content must be a non-empty string"
+
+        # Validate status
+        valid_statuses = ["pending", "in_progress", "completed"]
+        status = todo.get("status")
+        if status not in valid_statuses:
+            return False, f"Todo status must be one of: {', '.join(valid_statuses)}"
+
+        # Validate priority
+        valid_priorities = ["high", "medium", "low"]
+        priority = todo.get("priority")
+        if priority not in valid_priorities:
+            return False, f"Todo priority must be one of: {', '.join(valid_priorities)}"
+
+        # Validate ID
+        todo_id = todo.get("id")
+        if todo_id is None:
+            return False, "Todo id is required"
+
+        # Accept string, int, or float IDs
+        if not isinstance(todo_id, (str, int, float)):
+            return False, "Todo id must be a string, integer, or number"
+
+        # Convert to string and check if it's non-empty after stripping
+        todo_id_str = str(todo_id).strip()
+        if not todo_id_str:
+            return False, "Todo id must not be empty"
+
+        return True, ""
+
+    def validate_todos_list(self, todos: list[dict[str, Any]]) -> tuple[bool, str]:
+        """Validate a list of todo items.
+
+        Args:
+            todos: List of todo items to validate
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not isinstance(todos, list):
+            return False, "Todos must be a list"
+
+        # Check each todo item
+        for i, todo in enumerate(todos):
+            is_valid, error_msg = self.validate_todo_item(todo)
+            if not is_valid:
+                return False, f"Todo item {i}: {error_msg}"
+
+        # Check for duplicate IDs
+        todo_ids = [todo.get("id") for todo in todos]
+        if len(todo_ids) != len(set(todo_ids)):
+            return False, "Todo items must have unique IDs"
+
+        return True, ""