gobby 0.2.5__py3-none-any.whl

gobby/sessions/__init__.py

@@ -0,0 +1,13 @@
+"""
+Sessions package for multi-CLI session management.
+
+This package provides:
+- SessionManager: Session registration, handoff, and context restoration
+- SummaryFileGenerator: LLM-powered session summaries (failover)
+- Transcript parsers: CLI-specific transcript parsing (Claude, Codex, Gemini, etc.)
+"""
+
+from gobby.sessions.manager import SessionManager
+from gobby.sessions.summary import SummaryFileGenerator
+
+__all__ = ["SessionManager", "SummaryFileGenerator"]

gobby/sessions/analyzer.py

@@ -0,0 +1,322 @@
+"""
+Transcript analyzer for autonomous session handoff.
+
+Extracts structured context from session transcripts to support
+autonomous continuity without relying on manual /clear boundaries.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from gobby.sessions.transcripts.base import TranscriptParser
+from gobby.sessions.transcripts.claude import ClaudeTranscriptParser
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class HandoffContext:
+    """Structured context for autonomous handoff."""
+
+    active_gobby_task: dict[str, Any] | None = None
+    todo_state: list[dict[str, Any]] = field(default_factory=list)
+    files_modified: list[str] = field(default_factory=list)
+    git_commits: list[dict[str, Any]] = field(default_factory=list)
+    git_status: str = ""
+    initial_goal: str = ""
+    recent_activity: list[str] = field(default_factory=list)
+    key_decisions: list[str] | None = None
+    active_worktree: dict[str, Any] | None = None
+    """Worktree context if session is operating in a worktree."""
+
+
+class TranscriptAnalyzer:
+    """
+    Transcript analysis for handoff context.
+
+    Primary: Claude Code
+    Extensible: Other CLIs via TranscriptParser protocol
+    """
+
+    def __init__(self, parser: TranscriptParser | None = None):
+        """
+        Initialize TranscriptAnalyzer.
+
+        Args:
+            parser: Optional specific parser. Defaults to ClaudeTranscriptParser.
+        """
+        self.parser = parser or ClaudeTranscriptParser()
+
+    def extract_handoff_context(
+        self, turns: list[dict[str, Any]], max_turns: int = 150
+    ) -> HandoffContext:
+        """
+        Extract context for autonomous handoff.
+
+        Analyzes recent turns to find:
+        - Active task state from gobby-tasks calls
+        - TodoWrite state from Claude's internal tracking (if available in transcript)
+        - Files modified from Edit/Write/Bash calls
+        - Git commits from Bash calls
+        - The original user goal (first user message)
+        - Recent tool activity summaries
+
+        Args:
+            turns: List of transcript turns (dicts)
+            max_turns: Maximum number of turns to look back for context
+
+        Returns:
+            HandoffContext object populated with extracted data
+        """
+        context = HandoffContext()
+
+        if not turns:
+            return context
+
+        # 1. Extract Initial Goal (First User Message)
+        # We scan from the beginning to find the first user message
+        for turn in turns:
+            if turn.get("type") == "user":
+                msg = turn.get("message", {})
+                context.initial_goal = str(msg.get("content", "")).strip()
+                break
+
+        # 2. Analyze Recent Activity (Scan backwards)
+        # We look at the last `max_turns` or less
+        relevant_turns = turns[-max_turns:] if len(turns) > max_turns else turns
+
+        # Track what we've found to avoid duplicates where appropriate
+        found_active_task = False
+        modified_files_set: set[str] = set()
+
+        for turn in reversed(relevant_turns):
+            message = turn.get("message", {})
+            content_blocks = message.get("content", [])
+
+            # Handle Claude's content block list format
+            if isinstance(content_blocks, list):
+                for block in content_blocks:
+                    if not isinstance(block, dict):
+                        continue
+
+                    block_type = block.get("type")
+
+                    # Check for Tool Use
+                    if block_type == "tool_use":
+                        self._analyze_tool_use(
+                            block, context, found_active_task, modified_files_set
+                        )
+                        if (
+                            block.get("name") == "mcp_call_tool"
+                            and block.get("input", {}).get("server_name") == "gobby-tasks"
+                        ):
+                            # We found a task interaction, but we want the *latest* active one
+                            # The helper _analyze_tool_use will handle extraction,
+                            # we just mark we found some task activity if needed.
+                            pass
+
+        context.files_modified = sorted(modified_files_set)
+
+        # 3. Extract TodoWrite state
+        context.todo_state = self._extract_todowrite(relevant_turns)
+
+        # 4. Recent Activity Summary (Last 10 calls)
+        # Extract meaningful details from recent tool uses
+        recent_tools = []
+        count = 0
+        for turn in reversed(turns):
+            if count >= 10:
+                break
+            message = turn.get("message", {})
+            content = message.get("content", [])
+            if isinstance(content, list):
+                for block in content:
+                    if isinstance(block, dict) and block.get("type") == "tool_use":
+                        description = self._format_tool_description(block)
+                        recent_tools.append(description)
+                        count += 1
+                        if count >= 10:
+                            break
+        context.recent_activity = recent_tools
+
+        return context
+
+    def _analyze_tool_use(
+        self,
+        block: dict[str, Any],
+        context: HandoffContext,
+        found_active_task: bool,
+        modified_files_set: set[str],
+    ) -> None:
+        """Helper to analyze a single tool use block."""
+        tool_name = block.get("name")
+        tool_input = block.get("input", {})
+
+        # -- Gobby Tasks --
+        if tool_name == "mcp_call_tool":
+            server = tool_input.get("server_name")
+            tool = tool_input.get("tool_name")
+            args = tool_input.get("arguments", {})
+
+            if server == "gobby-tasks":
+                # We want the most recent task interaction that implies working on a task
+                # e.g., create_task, update_task, get_task
+                if not context.active_gobby_task:
+                    # Heuristic: If we see a task interaction, it might be the active task
+                    # especially if it's get_task or update_task
+                    task_id = args.get("task_id") or args.get("id")
+                    if task_id:
+                        context.active_gobby_task = {
+                            "id": task_id,
+                            "action": tool,
+                            # We don't have the full task object here, just the ID and intent
+                            # The injection template might need to fetch it or we assume
+                            # the ID is enough for the user to know.
+                            # Ideally, we'd have the title, but we can't get it from the tool input easily
+                            # unless it was a create/update with title.
+                            # For now, store what we have.
+                            "title": args.get("title", f"Task {task_id}"),
+                        }
+
+        # -- File Modifications --
+        elif tool_name in ("Edit", "Write", "Replace", "replace_file_content", "write_to_file"):
+            # Claude Code uses Edit/Write? Antigravity uses write_to_file/replace_file_content
+            # We should support both if possible or stick to what we expect Claude to use.
+            # Claude Code typically uses `grep_search`, `view_file`, `edit_file`?
+            # Let's assume standard names or generic ones.
+            path = (
+                tool_input.get("file_path")
+                or tool_input.get("TargetFile")
+                or tool_input.get("path")
+            )
+            if path:
+                modified_files_set.add(path)
+
+        # -- Git Commits --
+        elif tool_name == "Bash":
+            command = tool_input.get("command", "")
+            if "git commit" in command:
+                # Attempt to extract message
+                # This is a bit brittle, but useful context
+                context.git_commits.append(
+                    {
+                        "command": command,
+                        "timestamp": datetime.now().isoformat(),  # Approx time
+                    }
+                )
+
+    def _format_tool_description(self, block: dict[str, Any]) -> str:
+        """
+        Format a tool use block into a human-readable description.
+
+        Extracts meaningful details instead of just showing the tool name.
+
+        Args:
+            block: Tool use block with 'name' and 'input' keys
+
+        Returns:
+            Human-readable description of what the tool call did
+        """
+        tool_name = block.get("name", "unknown")
+        tool_input = block.get("input", {})
+
+        # MCP tool calls - show server.tool
+        if tool_name in ("mcp__gobby__call_tool", "mcp_call_tool"):
+            server = tool_input.get("server_name", "unknown")
+            tool = tool_input.get("tool_name", "unknown")
+            return f"Called {server}.{tool}"
+
+        # Bash - show the command (truncated)
+        if tool_name == "Bash":
+            command = tool_input.get("command", "")
+            # Truncate long commands
+            if len(command) > 60:
+                command = command[:57] + "..."
+            return f"Ran: {command}"
+
+        # Edit/Write - show the file path
+        if tool_name in ("Edit", "Write"):
+            path = tool_input.get("file_path", "")
+            if path:
+                return f"{tool_name}: {path}"
+            return f"Called {tool_name}"
+
+        # Read - show the file path
+        if tool_name == "Read":
+            path = tool_input.get("file_path", "")
+            if path:
+                return f"Read: {path}"
+            return "Called Read"
+
+        # Glob - show the pattern
+        if tool_name == "Glob":
+            pattern = tool_input.get("pattern", "")
+            if pattern:
+                return f"Glob: {pattern}"
+            return "Called Glob"
+
+        # Grep - show the pattern
+        if tool_name == "Grep":
+            pattern = tool_input.get("pattern", "")
+            if pattern:
+                # Truncate long patterns
+                if len(pattern) > 40:
+                    pattern = pattern[:37] + "..."
+                return f"Grep: {pattern}"
+            return "Called Grep"
+
+        # TodoWrite - show count
+        if tool_name == "TodoWrite":
+            todos = tool_input.get("todos", [])
+            return f"TodoWrite: {len(todos)} items"
+
+        # Task tool - show subagent type
+        if tool_name == "Task":
+            subagent = tool_input.get("subagent_type", "")
+            desc = tool_input.get("description", "")
+            if subagent:
+                return f"Task ({subagent}): {desc}" if desc else f"Task ({subagent})"
+            return f"Task: {desc}" if desc else "Called Task"
+
+        # Default - just show the tool name
+        return f"Called {tool_name}"
+
+    def _extract_todowrite(self, turns: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """
+        Extract the most recent TodoWrite state from transcript.
+
+        Scans turns in reverse to find the last TodoWrite tool call and
+        extracts the todos list.
+
+        Args:
+            turns: List of transcript turns to scan
+
+        Returns:
+            List of todo dicts with 'content' and 'status' keys, or empty list
+        """
+        for turn in reversed(turns):
+            message = turn.get("message", {})
+            content = message.get("content", [])
+
+            if isinstance(content, list):
+                for block in content:
+                    if isinstance(block, dict) and block.get("type") == "tool_use":
+                        if block.get("name") == "TodoWrite":
+                            tool_input = block.get("input", {})
+                            todos = tool_input.get("todos", [])
+
+                            if todos:
+                                # Return the raw todo list for HandoffContext
+                                return [
+                                    {
+                                        "content": todo.get("content", ""),
+                                        "status": todo.get("status", "pending"),
+                                    }
+                                    for todo in todos
+                                ]
+
+        return []

gobby/sessions/lifecycle.py

@@ -0,0 +1,240 @@
+"""
+Session lifecycle manager.
+
+Handles background jobs for:
+- Expiring stale sessions
+- Processing transcripts for expired sessions
+"""
+
+import asyncio
+import logging
+import os
+from typing import Any
+
+from gobby.config.app import SessionLifecycleConfig
+from gobby.sessions.transcripts.claude import ClaudeTranscriptParser
+from gobby.sessions.transcripts.codex import CodexTranscriptParser
+from gobby.sessions.transcripts.gemini import GeminiTranscriptParser
+from gobby.storage.database import DatabaseProtocol
+from gobby.storage.session_messages import LocalSessionMessageManager
+from gobby.storage.sessions import LocalSessionManager
+
+logger = logging.getLogger(__name__)
+
+
+class SessionLifecycleManager:
+    """
+    Manages session lifecycle background jobs.
+
+    Two independent jobs:
+    1. expire_stale_sessions - marks old active/paused sessions as expired
+    2. process_pending_transcripts - processes transcripts for expired sessions
+    """
+
+    def __init__(self, db: DatabaseProtocol, config: SessionLifecycleConfig):
+        self.db = db
+        self.config = config
+        self.session_manager = LocalSessionManager(db)
+        self.message_manager = LocalSessionMessageManager(db)
+
+        self._running = False
+        self._expire_task: asyncio.Task[None] | None = None
+        self._process_task: asyncio.Task[None] | None = None
+
+    async def start(self) -> None:
+        """Start background jobs."""
+        if self._running:
+            return
+
+        self._running = True
+
+        # Start expire job
+        self._expire_task = asyncio.create_task(
+            self._expire_loop(),
+            name="session-lifecycle-expire",
+        )
+
+        # Start process job
+        self._process_task = asyncio.create_task(
+            self._process_loop(),
+            name="session-lifecycle-process",
+        )
+
+        logger.info(
+            f"SessionLifecycleManager started "
+            f"(expire every {self.config.expire_check_interval_minutes}m, "
+            f"process every {self.config.transcript_processing_interval_minutes}m)"
+        )
+
+    async def stop(self) -> None:
+        """Stop background jobs."""
+        self._running = False
+
+        tasks = [t for t in [self._expire_task, self._process_task] if t]
+        for task in tasks:
+            task.cancel()
+
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+        self._expire_task = None
+        self._process_task = None
+
+        logger.info("SessionLifecycleManager stopped")
+
+    async def _expire_loop(self) -> None:
+        """Background loop for expiring stale sessions."""
+        interval_seconds = self.config.expire_check_interval_minutes * 60
+
+        while self._running:
+            try:
+                await self._expire_stale_sessions()
+            except Exception as e:
+                logger.error(f"Error in expire loop: {e}")
+
+            try:
+                await asyncio.sleep(interval_seconds)
+            except asyncio.CancelledError:
+                break
+
+    async def _process_loop(self) -> None:
+        """Background loop for processing pending transcripts."""
+        interval_seconds = self.config.transcript_processing_interval_minutes * 60
+
+        while self._running:
+            try:
+                await self._process_pending_transcripts()
+            except Exception as e:
+                logger.error(f"Error in process loop: {e}")
+
+            try:
+                await asyncio.sleep(interval_seconds)
+            except asyncio.CancelledError:
+                break
+
+    async def _expire_stale_sessions(self) -> int:
+        """Pause inactive active sessions and expire stale sessions."""
+        # First, pause active sessions that have been idle too long
+        # This catches orphaned sessions that never got AFTER_AGENT hook
+        paused = self.session_manager.pause_inactive_active_sessions(
+            timeout_minutes=self.config.active_session_pause_minutes
+        )
+
+        # Then expire sessions that have been paused/active for too long
+        expired = self.session_manager.expire_stale_sessions(
+            timeout_hours=self.config.stale_session_timeout_hours
+        )
+
+        return paused + expired
+
+    async def _process_pending_transcripts(self) -> int:
+        """Process transcripts for expired sessions."""
+        sessions = self.session_manager.get_pending_transcript_sessions(
+            limit=self.config.transcript_processing_batch_size
+        )
+
+        if not sessions:
+            return 0
+
+        processed = 0
+        for session in sessions:
+            try:
+                await self._process_session_transcript(session.id, session.jsonl_path)
+                self.session_manager.mark_transcript_processed(session.id)
+                processed += 1
+                logger.debug(f"Processed transcript for session {session.id}")
+            except Exception as e:
+                logger.error(f"Failed to process transcript for {session.id}: {e}")
+
+        if processed > 0:
+            logger.info(f"Processed {processed} session transcripts")
+
+        return processed
+
+    async def _process_session_transcript(self, session_id: str, jsonl_path: str | None) -> None:
+        """
+        Process a full transcript for a session.
+
+        Reads the entire transcript and stores messages.
+        Aggregates token usage and costs.
+        Uses idempotent upsert so re-processing is safe.
+
+        Args:
+            session_id: Session ID
+            jsonl_path: Path to transcript JSONL file
+        """
+        if not jsonl_path or not os.path.exists(jsonl_path):
+            logger.warning(f"Transcript not found for session {session_id}: {jsonl_path}")
+            return
+
+        # Read entire file
+        try:
+            with open(jsonl_path, encoding="utf-8") as f:
+                lines = f.readlines()
+        except Exception as e:
+            logger.error(f"Error reading transcript {jsonl_path}: {e}")
+            raise
+
+        if not lines:
+            return
+
+        # Parse all lines
+        session = self.session_manager.get(session_id)
+        if not session:
+            return
+
+        # Choose parser based on source
+        # Default to Claude for backward compatibility or safety
+        # But we should rely on session.source if possible
+        parser: Any = ClaudeTranscriptParser()
+        if session.source == "gemini":
+            parser = GeminiTranscriptParser()
+        elif session.source == "codex":
+            parser = CodexTranscriptParser()
+        elif session.source == "antigravity":
+            parser = ClaudeTranscriptParser()
+        # Default (claude or unknown) uses Claude transcript format
+
+        messages = parser.parse_lines(lines, start_index=0)
+
+        if not messages:
+            return
+
+        # Store messages (upsert - safe for re-processing)
+        await self.message_manager.store_messages(session_id, messages)
+
+        # Aggregate usage
+        input_tokens = 0
+        output_tokens = 0
+        cache_creation_tokens = 0
+        cache_read_tokens = 0
+        total_cost_usd = 0.0
+
+        for msg in messages:
+            if msg.usage:
+                input_tokens += msg.usage.input_tokens
+                output_tokens += msg.usage.output_tokens
+                cache_creation_tokens += msg.usage.cache_creation_tokens
+                cache_read_tokens += msg.usage.cache_read_tokens
+                if msg.usage.total_cost_usd:
+                    total_cost_usd += msg.usage.total_cost_usd
+
+        # Update session with aggregated usage
+        # We only update if we found some usage, to avoid overwriting with zeros if re-processing
+        # (though re-processing from scratch IS the source of truth, so zeros might be correct if no usage found)
+        # Actually, let's always update to ensure consistency with the file
+        self.session_manager.update_usage(
+            session_id=session_id,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cache_creation_tokens=cache_creation_tokens,
+            cache_read_tokens=cache_read_tokens,
+            total_cost_usd=total_cost_usd,
+        )
+
+        # Update processing state
+        await self.message_manager.update_state(
+            session_id=session_id,
+            byte_offset=sum(len(line.encode("utf-8")) for line in lines),
+            message_index=messages[-1].index,
+        )