fast-resume 1.12.8__py3-none-any.whl

fast_resume/__init__.py

@@ -0,0 +1,5 @@
+"""fast-resume: Fuzzy finder for coding agent session history."""
+
+from importlib.metadata import version
+
+__version__ = version("fast-resume")

fast_resume/adapters/__init__.py

@@ -0,0 +1,25 @@
+"""Agent adapters for different coding tools."""
+
+from .base import AgentAdapter, ErrorCallback, ParseError, RawAdapterStats, Session
+from .claude import ClaudeAdapter
+from .codex import CodexAdapter
+from .copilot import CopilotAdapter
+from .copilot_vscode import CopilotVSCodeAdapter
+from .crush import CrushAdapter
+from .opencode import OpenCodeAdapter
+from .vibe import VibeAdapter
+
+__all__ = [
+    "AgentAdapter",
+    "ErrorCallback",
+    "ParseError",
+    "RawAdapterStats",
+    "Session",
+    "ClaudeAdapter",
+    "CodexAdapter",
+    "CopilotAdapter",
+    "CopilotVSCodeAdapter",
+    "CrushAdapter",
+    "OpenCodeAdapter",
+    "VibeAdapter",
+]

fast_resume/adapters/base.py

@@ -0,0 +1,263 @@
+"""Base protocol and abstract class for agent adapters."""
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime
+import logging
+from pathlib import Path
+from typing import Protocol
+
+logger = logging.getLogger(__name__)
+
+# 1ms tolerance for mtime comparison due to datetime precision loss
+MTIME_TOLERANCE = 0.001
+
+
+def truncate_title(text: str, max_length: int = 100, word_break: bool = True) -> str:
+    """Truncate title text with optional word-break.
+
+    Args:
+        text: The text to truncate
+        max_length: Maximum length before truncation (default 100)
+        word_break: If True, break at last word boundary; if False, hard truncate
+
+    Returns:
+        Truncated title with "..." suffix if text exceeded max_length
+    """
+    text = text.strip()
+    if len(text) <= max_length:
+        return text
+
+    truncated = text[:max_length]
+    if word_break:
+        # Break at last word boundary
+        truncated = truncated.rsplit(" ", 1)[0]
+    return truncated + "..."
+
+
+@dataclass
+class Session:
+    """Represents a coding agent session."""
+
+    id: str
+    agent: str  # "claude", "codex", "crush", "opencode", "vibe"
+    title: str
+    directory: str
+    timestamp: datetime
+    content: str  # Full searchable content
+    message_count: int = 0  # Number of user + assistant messages
+    mtime: float = 0.0  # File modification time for incremental updates
+    yolo: bool = False  # Session was started with auto-approve/skip-permissions
+
+
+@dataclass
+class RawAdapterStats:
+    """Raw statistics from an adapter's data folder."""
+
+    agent: str
+    data_dir: str  # Path to the data directory
+    available: bool  # Whether the data directory exists
+    file_count: int  # Number of session files
+    total_bytes: int  # Total size in bytes
+
+
+@dataclass
+class ParseError:
+    """Represents a session parsing error."""
+
+    agent: str  # Which adapter encountered the error
+    file_path: str  # Path to the problematic file
+    error_type: str  # e.g., "JSONDecodeError", "KeyError", "OSError"
+    message: str  # Human-readable error message
+
+
+# Type alias for error callback
+ErrorCallback = Callable[["ParseError"], None] | None
+
+
+class AgentAdapter(Protocol):
+    """Protocol for agent-specific session adapters."""
+
+    name: str
+    color: str
+    badge: str
+
+    def find_sessions(self) -> list[Session]:
+        """Find all sessions for this agent."""
+        ...
+
+    def find_sessions_incremental(
+        self,
+        known: dict[str, tuple[float, str]],
+        on_error: ErrorCallback = None,
+    ) -> tuple[list[Session], list[str]]:
+        """Find sessions incrementally, comparing against known sessions.
+
+        Args:
+            known: Dict mapping session_id to (mtime, agent_name) tuple
+            on_error: Optional callback for parse errors
+
+        Returns:
+            Tuple of (new_or_modified sessions, deleted session IDs)
+        """
+        ...
+
+    def get_resume_command(self, session: "Session", yolo: bool = False) -> list[str]:
+        """Get the command to resume a session.
+
+        Args:
+            session: The session to resume
+            yolo: If True, add auto-approve/skip-permissions flags
+        """
+        ...
+
+    def is_available(self) -> bool:
+        """Check if this agent's data directory exists."""
+        ...
+
+    def get_raw_stats(self) -> RawAdapterStats:
+        """Get raw statistics from the adapter's data folder."""
+        ...
+
+    @property
+    def supports_yolo(self) -> bool:
+        """Whether this adapter supports yolo mode in resume command."""
+        ...
+
+
+class BaseSessionAdapter(ABC):
+    """Base class for file-based session adapters.
+
+    Provides a template method for find_sessions_incremental().
+    Used by Claude, Copilot, Codex, and Vibe adapters.
+
+    Subclasses implement:
+        - _scan_session_files(): Return dict of session_id -> (path, mtime)
+        - _parse_session_file(): Parse a single file into a Session
+        - find_sessions(): Find all sessions
+        - get_resume_command(): Command to resume a session
+    """
+
+    name: str
+    color: str
+    badge: str
+    _sessions_dir: Path
+
+    def is_available(self) -> bool:
+        """Check if data directory exists."""
+        return self._sessions_dir.exists()
+
+    @property
+    def supports_yolo(self) -> bool:
+        """Whether this adapter supports yolo mode in resume command.
+
+        Override in subclasses that support yolo flags.
+        """
+        return False
+
+    @abstractmethod
+    def _scan_session_files(self) -> dict[str, tuple[Path, float]]:
+        """Scan session files and return current state.
+
+        Returns:
+            Dict mapping session_id to (file_path, mtime) tuple
+        """
+        ...
+
+    @abstractmethod
+    def _parse_session_file(
+        self, session_file: Path, on_error: ErrorCallback = None
+    ) -> Session | None:
+        """Parse a single session file.
+
+        Args:
+            session_file: Path to the session file
+            on_error: Optional callback for parse errors
+
+        Returns:
+            Session object or None if parsing failed
+        """
+        ...
+
+    @abstractmethod
+    def find_sessions(self) -> list[Session]:
+        """Find all sessions for this agent."""
+        ...
+
+    @abstractmethod
+    def get_resume_command(self, session: Session, yolo: bool = False) -> list[str]:
+        """Get command to resume a session."""
+        ...
+
+    def find_sessions_incremental(
+        self,
+        known: dict[str, tuple[float, str]],
+        on_error: ErrorCallback = None,
+    ) -> tuple[list[Session], list[str]]:
+        """Find sessions incrementally using template method pattern.
+
+        Args:
+            known: Dict mapping session_id to (mtime, agent_name) tuple
+            on_error: Optional callback for parse errors
+
+        Returns:
+            Tuple of (new_or_modified sessions, deleted session IDs)
+        """
+        if not self.is_available():
+            # All known sessions from this agent are deleted
+            deleted_ids = [
+                sid for sid, (_, agent) in known.items() if agent == self.name
+            ]
+            return [], deleted_ids
+
+        # Scan current session files
+        current_files = self._scan_session_files()
+
+        # Find new and modified sessions
+        new_or_modified = []
+        for session_id, (path, mtime) in current_files.items():
+            known_entry = known.get(session_id)
+            if known_entry is None or mtime > known_entry[0] + MTIME_TOLERANCE:
+                session = self._parse_session_file(path, on_error=on_error)
+                if session:
+                    session.mtime = mtime
+                    new_or_modified.append(session)
+
+        # Find deleted sessions (in known but not in current, for this agent only)
+        current_ids = set(current_files.keys())
+        deleted_ids = [
+            sid
+            for sid, (_, agent) in known.items()
+            if agent == self.name and sid not in current_ids
+        ]
+
+        return new_or_modified, deleted_ids
+
+    def get_raw_stats(self) -> RawAdapterStats:
+        """Get raw statistics from the adapter's data folder."""
+        if not self.is_available():
+            return RawAdapterStats(
+                agent=self.name,
+                data_dir=str(self._sessions_dir),
+                available=False,
+                file_count=0,
+                total_bytes=0,
+            )
+
+        # Use _scan_session_files to get file info
+        files = self._scan_session_files()
+        total_bytes = 0
+        for path, _ in files.values():
+            try:
+                total_bytes += path.stat().st_size
+            except OSError:
+                pass
+
+        return RawAdapterStats(
+            agent=self.name,
+            data_dir=str(self._sessions_dir),
+            available=True,
+            file_count=len(files),
+            total_bytes=total_bytes,
+        )

fast_resume/adapters/claude.py

@@ -0,0 +1,209 @@
+"""Claude Code session adapter."""
+
+import orjson
+from datetime import datetime
+from pathlib import Path
+
+from ..config import AGENTS, CLAUDE_DIR
+from ..logging_config import log_parse_error
+from .base import BaseSessionAdapter, ErrorCallback, ParseError, Session, truncate_title
+
+
+class ClaudeAdapter(BaseSessionAdapter):
+    """Adapter for Claude Code sessions."""
+
+    name = "claude"
+    color = AGENTS["claude"]["color"]
+    badge = AGENTS["claude"]["badge"]
+    supports_yolo = True
+
+    def __init__(self, sessions_dir: Path | None = None) -> None:
+        self._sessions_dir = sessions_dir if sessions_dir is not None else CLAUDE_DIR
+
+    def find_sessions(self) -> list[Session]:
+        """Find all Claude Code sessions."""
+        if not self.is_available():
+            return []
+
+        sessions = []
+        for project_dir in self._sessions_dir.iterdir():
+            if not project_dir.is_dir():
+                continue
+
+            for session_file in project_dir.glob("*.jsonl"):
+                # Skip agent subprocesses
+                if session_file.name.startswith("agent-"):
+                    continue
+
+                session = self._parse_session_file(session_file)
+                if session:
+                    sessions.append(session)
+
+        return sessions
+
+    def _parse_session_file(
+        self, session_file: Path, on_error: ErrorCallback = None
+    ) -> Session | None:
+        """Parse a Claude Code session file."""
+        try:
+            first_user_message = ""
+            directory = ""
+            timestamp = datetime.fromtimestamp(session_file.stat().st_mtime)
+            messages: list[str] = []
+            # Count conversation turns (user + assistant, not tool results)
+            turn_count = 0
+
+            with open(session_file, "rb") as f:
+                for line in f:
+                    if not line.strip():
+                        continue
+                    try:
+                        data = orjson.loads(line)
+                    except orjson.JSONDecodeError:
+                        # Skip malformed lines within the file
+                        continue
+
+                    msg_type = data.get("type", "")
+
+                    # Get directory from user message
+                    if msg_type == "user" and not directory:
+                        directory = data.get("cwd", "")
+
+                    # Process user messages
+                    if msg_type == "user":
+                        msg = data.get("message", {})
+                        content = msg.get("content", "")
+
+                        # Check if this is a real human input or automatic tool result
+                        is_human_input = False
+                        if isinstance(content, str):
+                            is_human_input = True
+                            if not data.get("isMeta") and not content.startswith(
+                                ("<command", "<local-command")
+                            ):
+                                messages.append(f"» {content}")
+                                if not first_user_message and len(content) > 10:
+                                    first_user_message = content
+                        elif isinstance(content, list):
+                            # Check first part - if it's text (not tool_result), it's human
+                            first_part = content[0] if content else {}
+                            if isinstance(first_part, dict):
+                                part_type = first_part.get("type", "")
+                                if part_type == "text":
+                                    is_human_input = True
+                                # tool_result means automatic response, not human input
+
+                            for part in content:
+                                if (
+                                    isinstance(part, dict)
+                                    and part.get("type") == "text"
+                                ):
+                                    text = part.get("text", "")
+                                    messages.append(f"» {text}")
+                                    if not first_user_message:
+                                        first_user_message = text
+                                elif isinstance(part, str):
+                                    messages.append(f"» {part}")
+
+                        if is_human_input:
+                            turn_count += 1
+
+                    # Extract assistant content
+                    if msg_type == "assistant":
+                        msg = data.get("message", {})
+                        content = msg.get("content", "")
+                        has_text = False
+                        if isinstance(content, str) and content:
+                            messages.append(f"  {content}")
+                            has_text = True
+                        elif isinstance(content, list):
+                            for part in content:
+                                if (
+                                    isinstance(part, dict)
+                                    and part.get("type") == "text"
+                                ):
+                                    text = part.get("text", "")
+                                    if text:
+                                        messages.append(f"  {text}")
+                                        has_text = True
+                                elif isinstance(part, str):
+                                    messages.append(f"  {part}")
+                                    has_text = True
+                        if has_text:
+                            turn_count += 1
+
+            # Skip sessions with no actual user message
+            if not first_user_message:
+                return None
+
+            # Always use first user message as title (matches Claude Code's Resume Session UI)
+            # The summary field is not a good title - it's often stale after session resume
+            title = truncate_title(first_user_message)
+
+            # Skip sessions with no actual conversation content
+            if not messages:
+                return None
+
+            full_content = "\n\n".join(messages)
+
+            return Session(
+                id=session_file.stem,
+                agent=self.name,
+                title=title,
+                directory=directory,
+                timestamp=timestamp,
+                content=full_content,
+                message_count=turn_count,
+            )
+        except OSError as e:
+            error = ParseError(
+                agent=self.name,
+                file_path=str(session_file),
+                error_type="OSError",
+                message=str(e),
+            )
+            log_parse_error(
+                error.agent, error.file_path, error.error_type, error.message
+            )
+            if on_error:
+                on_error(error)
+            return None
+        except (KeyError, TypeError, AttributeError) as e:
+            error = ParseError(
+                agent=self.name,
+                file_path=str(session_file),
+                error_type=type(e).__name__,
+                message=str(e),
+            )
+            log_parse_error(
+                error.agent, error.file_path, error.error_type, error.message
+            )
+            if on_error:
+                on_error(error)
+            return None
+
+    def _scan_session_files(self) -> dict[str, tuple[Path, float]]:
+        """Scan all Claude Code session files."""
+        current_files: dict[str, tuple[Path, float]] = {}
+
+        for project_dir in self._sessions_dir.iterdir():
+            if not project_dir.is_dir():
+                continue
+
+            for session_file in project_dir.glob("*.jsonl"):
+                if session_file.name.startswith("agent-"):
+                    continue
+
+                session_id = session_file.stem
+                mtime = session_file.stat().st_mtime
+                current_files[session_id] = (session_file, mtime)
+
+        return current_files
+
+    def get_resume_command(self, session: Session, yolo: bool = False) -> list[str]:
+        """Get command to resume a Claude Code session."""
+        cmd = ["claude"]
+        if yolo:
+            cmd.append("--dangerously-skip-permissions")
+        cmd.extend(["--resume", session.id])
+        return cmd