overcode 0.1.0__py3-none-any.whl

overcode/status_patterns.py

@@ -0,0 +1,264 @@
+"""
+Centralized status detection patterns.
+
+This module contains all the pattern lists used by StatusDetector to identify
+Claude's current state. Centralizing these makes them:
+- Easier to maintain and extend
+- Testable in isolation
+- Potentially configurable via config file in the future
+
+Each pattern set includes documentation about when it's used and what it matches.
+"""
+
+from dataclasses import dataclass, field
+from typing import List
+
+
+@dataclass
+class StatusPatterns:
+    """All patterns used for status detection.
+
+    Patterns are case-insensitive unless noted otherwise.
+    """
+
+    # Permission/confirmation prompts - HIGHEST priority
+    # These indicate Claude needs user approval before proceeding.
+    # Matched against the last few lines of output (lowercased).
+    permission_patterns: List[str] = field(default_factory=lambda: [
+        "enter to confirm",
+        "esc to reject",
+        # Note: removed "approve" - too broad, matches "auto-approve" in status bar
+        # Note: removed "permission" - too broad, matches "bypass permissions" in status bar
+        "allow this",
+        # Claude Code v2 permission dialog format
+        "do you want to proceed",
+        "❯ 1. yes",  # Menu selector on first option
+        "tell claude what to do differently",  # Option 3 text
+    ])
+
+    # Active work indicators - checked when content hasn't changed
+    # These indicate Claude is busy even if the prompt appears visible.
+    # Matched against the last few lines of output (lowercased).
+    active_indicators: List[str] = field(default_factory=lambda: [
+        "web search",
+        "searching",
+        "fetching",
+        "esc to interrupt",  # Shows active operation in progress
+        "thinking",
+        "✽",  # Spinner character
+        # Fun thinking indicators from Claude Code
+        "razzmatazzing",
+        "fiddle-faddling",
+        "pondering",
+        "cogitating",
+        # Note: removed "tokens" - too broad, matches normal text
+        # The spinner ✽ and "esc to interrupt" are sufficient
+    ])
+
+    # Tool execution indicators - CASE SENSITIVE
+    # These indicate Claude is executing a tool.
+    # Matched directly against lines (case-sensitive).
+    execution_indicators: List[str] = field(default_factory=lambda: [
+        "Reading",
+        "Writing",
+        "Editing",
+        "Running",
+        "Executing",
+        "Searching",
+        "Analyzing",
+        "Processing",
+        "Installing",
+        "Building",
+        "Compiling",
+        "Testing",
+        "Deploying",
+    ])
+
+    # Waiting patterns - indicate Claude is waiting for user decision
+    # Matched against the last few lines of output (lowercased).
+    waiting_patterns: List[str] = field(default_factory=lambda: [
+        "paused",
+        "do you want",
+        "proceed",
+        "continue",
+        "yes/no",
+        "[y/n]",
+        "press any key",
+    ])
+
+    # Prompt characters - indicate empty prompt waiting for user input
+    # These are exact matches for line content.
+    prompt_chars: List[str] = field(default_factory=lambda: [
+        ">",
+        "›",
+        "❯",  # Claude Code's prompt character (U+276F)
+    ])
+
+    # Line prefixes to clean/remove for display
+    # These are stripped from the beginning of lines.
+    line_prefixes: List[str] = field(default_factory=lambda: [
+        "› ",
+        "> ",
+        "❯ ",  # Claude Code's prompt character (U+276F)
+        "- ",
+        "• ",
+    ])
+
+    # Status bar prefixes to filter out
+    # Lines starting with these are UI chrome, not Claude output.
+    status_bar_prefixes: List[str] = field(default_factory=lambda: [
+        "⏵⏵",  # Status bar indicator (e.g., "⏵⏵ bypass permissions on")
+    ])
+
+    # Command menu pattern - regex pattern for slash command menu lines
+    # These appear when user types a slash command and Claude shows autocomplete
+    # Format: "  /command-name     Description text"
+    command_menu_pattern: str = r"^\s*/[\w-]+\s{2,}\S"
+
+
+# Default patterns instance
+DEFAULT_PATTERNS = StatusPatterns()
+
+
+def get_patterns() -> StatusPatterns:
+    """Get the status detection patterns.
+
+    Returns the default patterns. In the future, this could be
+    extended to load from a config file.
+
+    Returns:
+        StatusPatterns instance with all pattern lists
+    """
+    return DEFAULT_PATTERNS
+
+
+def matches_any(text: str, patterns: List[str], case_sensitive: bool = False) -> bool:
+    """Check if text matches any of the patterns.
+
+    Args:
+        text: Text to search in
+        patterns: List of patterns to match
+        case_sensitive: Whether matching is case-sensitive
+
+    Returns:
+        True if any pattern is found in text
+    """
+    if not case_sensitive:
+        text = text.lower()
+        return any(p.lower() in text for p in patterns)
+    return any(p in text for p in patterns)
+
+
+def find_matching_line(
+    lines: List[str],
+    patterns: List[str],
+    case_sensitive: bool = False,
+    reverse: bool = True
+) -> str | None:
+    """Find the first line that matches any pattern.
+
+    Args:
+        lines: Lines to search
+        patterns: Patterns to match
+        case_sensitive: Whether matching is case-sensitive
+        reverse: Search from end to beginning
+
+    Returns:
+        The matching line, or None if no match
+    """
+    search_lines = reversed(lines) if reverse else lines
+    for line in search_lines:
+        if matches_any(line, patterns, case_sensitive):
+            return line
+    return None
+
+
+def is_prompt_line(line: str, patterns: StatusPatterns = None) -> bool:
+    """Check if a line is an empty prompt waiting for input.
+
+    Args:
+        line: Line to check
+        patterns: StatusPatterns to use (defaults to DEFAULT_PATTERNS)
+
+    Returns:
+        True if line is an empty prompt
+    """
+    patterns = patterns or DEFAULT_PATTERNS
+    stripped = line.strip()
+    return stripped in patterns.prompt_chars
+
+
+def is_status_bar_line(line: str, patterns: StatusPatterns = None) -> bool:
+    """Check if a line is status bar UI chrome.
+
+    Args:
+        line: Line to check
+        patterns: StatusPatterns to use (defaults to DEFAULT_PATTERNS)
+
+    Returns:
+        True if line is status bar chrome
+    """
+    patterns = patterns or DEFAULT_PATTERNS
+    stripped = line.strip()
+    return any(stripped.startswith(prefix) for prefix in patterns.status_bar_prefixes)
+
+
+def is_command_menu_line(line: str, patterns: StatusPatterns = None) -> bool:
+    """Check if a line is part of a slash command menu.
+
+    Claude Code shows a menu of commands when user types a slash.
+    Format: "  /command-name     Description text"
+
+    Args:
+        line: Line to check
+        patterns: StatusPatterns to use (defaults to DEFAULT_PATTERNS)
+
+    Returns:
+        True if line is a command menu entry
+    """
+    import re
+    patterns = patterns or DEFAULT_PATTERNS
+    return bool(re.match(patterns.command_menu_pattern, line))
+
+
+def count_command_menu_lines(lines: List[str], patterns: StatusPatterns = None) -> int:
+    """Count how many lines in the list are command menu lines.
+
+    Args:
+        lines: Lines to check
+        patterns: StatusPatterns to use (defaults to DEFAULT_PATTERNS)
+
+    Returns:
+        Number of lines matching the command menu pattern
+    """
+    patterns = patterns or DEFAULT_PATTERNS
+    return sum(1 for line in lines if is_command_menu_line(line, patterns))
+
+
+def clean_line(line: str, patterns: StatusPatterns = None, max_length: int = 80) -> str:
+    """Clean a line for display.
+
+    Removes prefixes, strips whitespace, and truncates.
+
+    Args:
+        line: Line to clean
+        patterns: StatusPatterns to use (defaults to DEFAULT_PATTERNS)
+        max_length: Maximum length before truncation
+
+    Returns:
+        Cleaned line
+    """
+    patterns = patterns or DEFAULT_PATTERNS
+    cleaned = line.strip()
+
+    # Remove common prefixes
+    for prefix in patterns.line_prefixes:
+        if cleaned.startswith(prefix):
+            cleaned = cleaned[len(prefix):]
+            break  # Only remove one prefix
+
+    # Truncate if too long
+    if len(cleaned) > max_length:
+        cleaned = cleaned[:max_length - 3] + "..."
+
+    return cleaned

overcode/summarizer_client.py

@@ -0,0 +1,136 @@
+"""
+OpenAI API client for agent summarization.
+
+Uses GPT-4o-mini for cost-effective, high-frequency summaries.
+"""
+
+import json
+import logging
+import os
+import urllib.error
+import urllib.request
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+MODEL = "gpt-4o-mini"
+API_URL = "https://api.openai.com/v1/chat/completions"
+
+# Anti-oscillation prompt template
+SUMMARIZE_PROMPT = """You are summarizing a Claude Code agent's terminal output.
+
+## Current Terminal Content (last {lines} lines):
+{pane_content}
+
+## Current Status: {status}
+
+## Previous Summary:
+{previous_summary}
+
+## Instructions:
+1. Summarize what the agent has been doing in 1-2 sentences
+2. If not running, explain the halt state (waiting for user input, permission needed, etc.)
+3. IMPORTANT: Only provide a new summary if there's meaningful new information.
+   If the situation is essentially the same as the previous summary, respond with exactly:
+   UNCHANGED
+
+Keep summaries concise (under 80 words). Focus on:
+- What task/feature is being worked on
+- Current action (reading files, writing code, running tests, etc.)
+- If halted: why and what's needed to continue"""
+
+
+class SummarizerClient:
+    """Client for OpenAI API to generate agent summaries."""
+
+    def __init__(self, api_key: Optional[str] = None):
+        """Initialize the client.
+
+        Args:
+            api_key: OpenAI API key. If None, reads from OPENAI_API_KEY env var.
+        """
+        self.api_key = api_key or os.environ.get("OPENAI_API_KEY")
+        self._available = bool(self.api_key)
+
+    @property
+    def available(self) -> bool:
+        """Check if the client is available (API key present)."""
+        return self._available
+
+    def summarize(
+        self,
+        pane_content: str,
+        previous_summary: str,
+        current_status: str,
+        lines: int = 200,
+        max_tokens: int = 150,
+    ) -> Optional[str]:
+        """Get summary from GPT-4o-mini.
+
+        Args:
+            pane_content: Terminal pane content to summarize
+            previous_summary: Previous summary for anti-oscillation
+            current_status: Current agent status (running, waiting_user, etc.)
+            lines: Number of lines being summarized (for prompt context)
+            max_tokens: Maximum tokens in response
+
+        Returns:
+            New summary text, "UNCHANGED" if no update needed, or None on error
+        """
+        if not self.available:
+            return None
+
+        prompt = SUMMARIZE_PROMPT.format(
+            lines=lines,
+            pane_content=pane_content,
+            status=current_status,
+            previous_summary=previous_summary or "(no previous summary)",
+        )
+
+        payload = json.dumps({
+            "model": MODEL,
+            "max_tokens": max_tokens,
+            "temperature": 0.3,  # Low temperature for consistent summaries
+            "messages": [{"role": "user", "content": prompt}],
+        }).encode("utf-8")
+
+        req = urllib.request.Request(
+            API_URL,
+            data=payload,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            },
+            method="POST",
+        )
+
+        try:
+            with urllib.request.urlopen(req, timeout=15.0) as response:
+                if response.status == 200:
+                    result = json.loads(response.read().decode("utf-8"))
+                    content = result["choices"][0]["message"]["content"]
+                    return content.strip()
+                else:
+                    logger.warning(
+                        f"Summarizer API error: {response.status}"
+                    )
+                    return None
+
+        except urllib.error.URLError as e:
+            logger.warning(f"Summarizer API error: {e.reason}")
+            return None
+        except TimeoutError:
+            logger.warning("Summarizer API timeout")
+            return None
+        except Exception as e:
+            logger.warning(f"Summarizer API error: {e}")
+            return None
+
+    def close(self) -> None:
+        """Clean up resources (no-op for urllib)."""
+        pass
+
+    @staticmethod
+    def is_available() -> bool:
+        """Check if OPENAI_API_KEY is set in environment."""
+        return bool(os.environ.get("OPENAI_API_KEY"))

overcode/summarizer_component.py

@@ -0,0 +1,312 @@
+"""
+Summarizer component for generating agent activity summaries.
+
+Uses GPT-4o-mini to summarize what each agent has been doing and
+their current halt state if not running.
+"""
+
+import json
+import logging
+import os
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Optional, TYPE_CHECKING
+
+from .summarizer_client import SummarizerClient
+from .settings import get_session_dir
+
+if TYPE_CHECKING:
+    from .interfaces import TmuxInterface
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AgentSummary:
+    """Summary for a single agent."""
+
+    text: str = ""
+    updated_at: Optional[str] = None  # ISO timestamp
+    tokens_used: int = 0
+
+
+@dataclass
+class SummarizerConfig:
+    """Configuration for the summarizer."""
+
+    enabled: bool = False  # Off by default
+    interval: float = 5.0  # Seconds between updates per agent
+    lines: int = 200  # Pane lines to capture
+    max_tokens: int = 150  # Max response tokens
+
+
+class SummarizerComponent:
+    """Component for generating agent activity summaries.
+
+    Follows the daemon component pattern (like PresenceComponent).
+    Gracefully degrades if OPENAI_API_KEY is not available.
+    """
+
+    def __init__(
+        self,
+        tmux_session: str,
+        tmux: "TmuxInterface" = None,
+        config: Optional[SummarizerConfig] = None,
+    ):
+        """Initialize the summarizer component.
+
+        Args:
+            tmux_session: Name of the tmux session
+            tmux: TmuxInterface for pane capture (defaults to RealTmux)
+            config: SummarizerConfig (defaults to disabled)
+        """
+        self.tmux_session = tmux_session
+        self.config = config or SummarizerConfig()
+
+        # Dependency injection for testability
+        if tmux is None:
+            from .interfaces import RealTmux
+            tmux = RealTmux()
+        self.tmux = tmux
+
+        # Initialize client (gracefully handles missing API key)
+        self._client: Optional[SummarizerClient] = None
+        if self.config.enabled and SummarizerClient.is_available():
+            self._client = SummarizerClient()
+
+        # Per-agent summaries
+        self.summaries: Dict[str, AgentSummary] = {}
+
+        # Rate limiting per session
+        self._last_update: Dict[str, datetime] = {}
+
+        # Content hashes for change detection (avoid API calls when nothing changed)
+        self._last_content_hash: Dict[str, int] = {}
+
+        # Stats
+        self.total_calls = 0
+        self.total_tokens = 0
+
+        # Control file path
+        self._control_file = get_session_dir(tmux_session) / "summarizer_control.json"
+
+    @property
+    def available(self) -> bool:
+        """Check if summarizer is available (API key present)."""
+        return SummarizerClient.is_available()
+
+    @property
+    def enabled(self) -> bool:
+        """Check if summarizer is currently enabled."""
+        return self.config.enabled and self._client is not None
+
+    def check_control_file(self) -> None:
+        """Check control file for enable/disable commands."""
+        if not self._control_file.exists():
+            return
+
+        try:
+            with open(self._control_file) as f:
+                data = json.load(f)
+
+            should_enable = data.get("enabled", False)
+
+            if should_enable and not self.config.enabled:
+                # Enable requested
+                if SummarizerClient.is_available():
+                    self.config.enabled = True
+                    self._client = SummarizerClient()
+                    logger.info("Summarizer enabled via control file")
+                else:
+                    logger.warning("Summarizer enable requested but OPENAI_API_KEY not set")
+            elif not should_enable and self.config.enabled:
+                # Disable requested
+                self.config.enabled = False
+                if self._client:
+                    self._client.close()
+                    self._client = None
+                logger.info("Summarizer disabled via control file")
+
+        except (json.JSONDecodeError, OSError) as e:
+            logger.warning(f"Error reading summarizer control file: {e}")
+
+    def update(self, sessions) -> Dict[str, AgentSummary]:
+        """Update summaries for all sessions.
+
+        Args:
+            sessions: List of Session objects from SessionManager
+
+        Returns:
+            Dict mapping session_id to AgentSummary
+        """
+        # Check control file for enable/disable
+        self.check_control_file()
+
+        if not self.enabled:
+            return self.summaries
+
+        for session in sessions:
+            self._update_session(session)
+
+        return self.summaries
+
+    def _update_session(self, session) -> None:
+        """Update summary for a single session.
+
+        Args:
+            session: Session object with id, tmux_window, current_status
+        """
+        if not self._client:
+            return
+
+        session_id = session.id
+        now = datetime.now()
+
+        # Rate limiting - don't call API too frequently for same session
+        last_update = self._last_update.get(session_id)
+        if last_update:
+            elapsed = (now - last_update).total_seconds()
+            if elapsed < self.config.interval:
+                return
+
+        # Skip terminated sessions
+        current_status = getattr(session, 'stats', None)
+        if current_status:
+            status = getattr(current_status, 'current_state', 'unknown')
+            if status == 'terminated':
+                return
+
+        # Capture pane content
+        content = self._capture_pane(session.tmux_window)
+        if not content:
+            return
+
+        # Check if content has actually changed (avoid unnecessary API calls)
+        content_hash = hash(content)
+        if session_id in self._last_content_hash:
+            if self._last_content_hash[session_id] == content_hash:
+                # Content hasn't changed - skip API call
+                return
+
+        self._last_content_hash[session_id] = content_hash
+
+        # Get previous summary for anti-oscillation
+        prev_summary = self.summaries.get(session_id)
+        prev_text = prev_summary.text if prev_summary else ""
+
+        # Get current detected status
+        status = "unknown"
+        if current_status:
+            status = getattr(current_status, 'current_state', 'unknown')
+
+        # Call API
+        try:
+            result = self._client.summarize(
+                pane_content=content,
+                previous_summary=prev_text,
+                current_status=status,
+                lines=self.config.lines,
+                max_tokens=self.config.max_tokens,
+            )
+
+            self.total_calls += 1
+
+            if result and result.strip().upper() != "UNCHANGED":
+                # New summary
+                self.summaries[session_id] = AgentSummary(
+                    text=result.strip(),
+                    updated_at=now.isoformat(),
+                )
+                logger.debug(f"Updated summary for {session.name}: {result[:50]}...")
+            # If "UNCHANGED", keep the old summary
+
+            self._last_update[session_id] = now
+
+        except Exception as e:
+            logger.warning(f"Summarizer error for {session.name}: {e}")
+
+    def _capture_pane(self, window: int) -> Optional[str]:
+        """Capture pane content for summarization.
+
+        Args:
+            window: tmux window index
+
+        Returns:
+            Pane content string or None on error
+        """
+        try:
+            content = self.tmux.capture_pane(
+                self.tmux_session,
+                window,
+                lines=self.config.lines + 50,  # Capture extra for filtering
+            )
+            if not content:
+                return None
+
+            # Strip trailing blank lines and return last N lines
+            lines = content.rstrip().split('\n')
+            meaningful_lines = lines[-self.config.lines:] if len(lines) > self.config.lines else lines
+            return '\n'.join(meaningful_lines)
+
+        except Exception as e:
+            logger.warning(f"Failed to capture pane {window}: {e}")
+            return None
+
+    def get_summary(self, session_id: str) -> Optional[AgentSummary]:
+        """Get summary for a specific session.
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            AgentSummary or None if not available
+        """
+        return self.summaries.get(session_id)
+
+    def stop(self) -> None:
+        """Clean up resources."""
+        if self._client:
+            self._client.close()
+            self._client = None
+
+
+def get_summarizer_control_path(session: str) -> Path:
+    """Get the summarizer control file path for a session."""
+    return get_session_dir(session) / "summarizer_control.json"
+
+
+def set_summarizer_enabled(session: str, enabled: bool) -> None:
+    """Set summarizer enabled state via control file.
+
+    The daemon reads this file each loop and adjusts accordingly.
+
+    Args:
+        session: tmux session name
+        enabled: Whether to enable or disable
+    """
+    control_path = get_summarizer_control_path(session)
+    control_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(control_path, 'w') as f:
+        json.dump({"enabled": enabled}, f)
+
+
+def is_summarizer_enabled(session: str) -> bool:
+    """Check if summarizer is enabled for a session.
+
+    Args:
+        session: tmux session name
+
+    Returns:
+        True if enabled, False otherwise
+    """
+    control_path = get_summarizer_control_path(session)
+    if not control_path.exists():
+        return False
+
+    try:
+        with open(control_path) as f:
+            data = json.load(f)
+        return data.get("enabled", False)
+    except (json.JSONDecodeError, OSError):
+        return False