overcode 0.1.0__py3-none-any.whl

overcode/settings.py

@@ -0,0 +1,412 @@
+"""
+Centralized configuration and settings for Overcode.
+
+This module consolidates all configuration constants, paths, and settings
+that were previously scattered across multiple modules.
+
+Configuration hierarchy:
+1. Environment variables (highest priority)
+2. Config file (~/.overcode/config.yaml)
+3. Default values (lowest priority)
+"""
+
+import os
+
+# =============================================================================
+# Version - increment when daemon code changes significantly
+# =============================================================================
+
+DAEMON_VERSION = 2  # Increment when daemon behavior changes
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+
+# =============================================================================
+# Base Paths
+# =============================================================================
+
+def get_overcode_dir() -> Path:
+    """Get the overcode data directory.
+
+    Can be overridden with OVERCODE_DIR environment variable.
+    """
+    env_dir = os.environ.get("OVERCODE_DIR")
+    if env_dir:
+        return Path(env_dir)
+    return Path.home() / ".overcode"
+
+
+def get_state_dir() -> Path:
+    """Get the state directory for session files.
+
+    Can be overridden with OVERCODE_STATE_DIR environment variable.
+    """
+    env_dir = os.environ.get("OVERCODE_STATE_DIR")
+    if env_dir:
+        return Path(env_dir)
+    return get_overcode_dir() / "sessions"
+
+
+def get_log_dir() -> Path:
+    """Get the log directory."""
+    return get_overcode_dir() / "logs"
+
+
+# =============================================================================
+# File Paths
+# =============================================================================
+
+@dataclass
+class OvercodePaths:
+    """All file paths used by Overcode."""
+
+    # Base directory
+    base_dir: Path = field(default_factory=get_overcode_dir)
+
+    @property
+    def config_file(self) -> Path:
+        """Configuration file path."""
+        return self.base_dir / "config.yaml"
+
+    @property
+    def state_dir(self) -> Path:
+        """Session state directory."""
+        return get_state_dir()
+
+    @property
+    def sessions_file(self) -> Path:
+        """Sessions state file."""
+        return self.state_dir / "sessions.json"
+
+    @property
+    def log_dir(self) -> Path:
+        """Log directory."""
+        return get_log_dir()
+
+    @property
+    def daemon_log(self) -> Path:
+        """Daemon log file."""
+        return self.base_dir / "daemon.log"
+
+    @property
+    def daemon_pid(self) -> Path:
+        """Daemon PID file."""
+        return self.base_dir / "daemon.pid"
+
+    @property
+    def daemon_state(self) -> Path:
+        """Daemon state file (legacy - supervisor daemon)."""
+        return self.base_dir / "daemon_state.json"
+
+    @property
+    def monitor_daemon_state(self) -> Path:
+        """Monitor daemon state file (new - single source of truth)."""
+        return self.base_dir / "monitor_daemon_state.json"
+
+    @property
+    def monitor_daemon_pid(self) -> Path:
+        """Monitor daemon PID file."""
+        return self.base_dir / "monitor_daemon.pid"
+
+    @property
+    def supervisor_daemon_pid(self) -> Path:
+        """Supervisor daemon PID file."""
+        return self.base_dir / "supervisor_daemon.pid"
+
+    @property
+    def presence_pid(self) -> Path:
+        """Presence logger PID file."""
+        return self.base_dir / "presence.pid"
+
+    @property
+    def presence_log(self) -> Path:
+        """Presence log file."""
+        return self.base_dir / "presence_log.csv"
+
+    @property
+    def activity_signal(self) -> Path:
+        """Activity signal file for daemon."""
+        return self.base_dir / "activity_signal"
+
+    @property
+    def agent_history(self) -> Path:
+        """Agent status history CSV."""
+        return self.base_dir / "agent_status_history.csv"
+
+    @property
+    def supervisor_log(self) -> Path:
+        """Supervisor log file."""
+        return self.base_dir / "supervisor.log"
+
+
+# Global paths instance
+PATHS = OvercodePaths()
+
+
+# =============================================================================
+# Daemon Settings
+# =============================================================================
+
+@dataclass
+class DaemonSettings:
+    """Settings for the daemon."""
+
+    # Polling intervals (seconds)
+    interval_fast: int = 10      # When active or agents working
+    interval_slow: int = 300     # When all agents need user input (5 min)
+    interval_idle: int = 3600    # When no agents at all (1 hour)
+
+    # Daemon Claude settings
+    daemon_claude_timeout: int = 300  # Max wait for daemon claude (5 min)
+    daemon_claude_poll: int = 5       # Poll interval for daemon claude
+
+    # Default tmux session name
+    default_tmux_session: str = "agents"
+
+
+# Global daemon settings
+DAEMON = DaemonSettings()
+
+
+# =============================================================================
+# Presence Logger Settings
+# =============================================================================
+
+@dataclass
+class PresenceSettings:
+    """Settings for the presence logger."""
+
+    sample_interval: int = 60   # Seconds between samples
+    idle_threshold: int = 60    # Seconds before considered idle
+
+
+# Global presence settings
+PRESENCE = PresenceSettings()
+
+
+# =============================================================================
+# TUI Settings
+# =============================================================================
+
+@dataclass
+class TUISettings:
+    """Settings for the TUI monitor."""
+
+    default_timeline_width: int = 60
+    refresh_interval: float = 1.0  # Seconds
+
+
+# Global TUI settings
+TUI = TUISettings()
+
+
+# =============================================================================
+# Config File Loading
+# =============================================================================
+
+@dataclass
+class UserConfig:
+    """User-configurable settings from config.yaml."""
+
+    default_standing_instructions: str = ""
+    tmux_session: str = "agents"
+
+    @classmethod
+    def load(cls) -> "UserConfig":
+        """Load configuration from config file."""
+        config_path = PATHS.config_file
+
+        if not config_path.exists():
+            return cls()
+
+        try:
+            with open(config_path) as f:
+                data = yaml.safe_load(f)
+                if not isinstance(data, dict):
+                    return cls()
+
+                return cls(
+                    default_standing_instructions=data.get(
+                        "default_standing_instructions", ""
+                    ),
+                    tmux_session=data.get("tmux_session", "agents"),
+                )
+        except (yaml.YAMLError, IOError):
+            return cls()
+
+
+# Cached user config (lazy loaded)
+_user_config: Optional[UserConfig] = None
+
+
+def get_user_config() -> UserConfig:
+    """Get the user configuration (cached)."""
+    global _user_config
+    if _user_config is None:
+        _user_config = UserConfig.load()
+    return _user_config
+
+
+def reload_user_config() -> UserConfig:
+    """Reload the user configuration from disk."""
+    global _user_config
+    _user_config = UserConfig.load()
+    return _user_config
+
+
+# =============================================================================
+# Session-Specific Paths
+# =============================================================================
+
+def get_session_dir(session: str) -> Path:
+    """Get the directory for session-specific files.
+
+    Each overcode session (tmux session) gets its own subdirectory
+    for isolation. This allows running multiple overcode instances
+    (e.g., one for work, one for development).
+
+    Respects OVERCODE_STATE_DIR environment variable for test isolation.
+    """
+    # Use get_state_dir() as base to respect OVERCODE_STATE_DIR
+    state_dir = get_state_dir()
+    # state_dir is already the sessions directory
+    return state_dir / session
+
+
+def get_monitor_daemon_pid_path(session: str) -> Path:
+    """Get monitor daemon PID file path for a specific session."""
+    return get_session_dir(session) / "monitor_daemon.pid"
+
+
+def get_monitor_daemon_state_path(session: str) -> Path:
+    """Get monitor daemon state file path for a specific session."""
+    return get_session_dir(session) / "monitor_daemon_state.json"
+
+
+def get_supervisor_daemon_pid_path(session: str) -> Path:
+    """Get supervisor daemon PID file path for a specific session."""
+    return get_session_dir(session) / "supervisor_daemon.pid"
+
+
+def get_agent_history_path(session: str) -> Path:
+    """Get agent status history CSV path for a specific session."""
+    return get_session_dir(session) / "agent_status_history.csv"
+
+
+def get_activity_signal_path(session: str) -> Path:
+    """Get activity signal file path for a specific session."""
+    return get_session_dir(session) / "activity_signal"
+
+
+def signal_activity(session: str = None) -> None:
+    """Signal user activity to the daemon (called by TUI on keypress).
+
+    Creates a signal file that the daemon checks each loop.
+    When it sees this file, it wakes up and runs immediately.
+    This provides responsiveness when users interact with TUI.
+    """
+    if session is None:
+        session = DAEMON.default_tmux_session
+    signal_path = get_activity_signal_path(session)
+    try:
+        signal_path.parent.mkdir(parents=True, exist_ok=True)
+        signal_path.touch()
+    except OSError:
+        pass  # Best effort
+
+
+def get_supervisor_stats_path(session: str) -> Path:
+    """Get supervisor stats file path for a specific session."""
+    return get_session_dir(session) / "supervisor_stats.json"
+
+
+def get_supervisor_log_path(session: str) -> Path:
+    """Get supervisor log file path for a specific session."""
+    return get_session_dir(session) / "supervisor.log"
+
+
+def ensure_session_dir(session: str) -> Path:
+    """Ensure session directory exists and return it."""
+    session_dir = get_session_dir(session)
+    session_dir.mkdir(parents=True, exist_ok=True)
+    return session_dir
+
+
+# =============================================================================
+# Convenience Functions
+# =============================================================================
+
+def get_default_standing_instructions() -> str:
+    """Get default standing instructions from config."""
+    return get_user_config().default_standing_instructions
+
+
+def get_default_tmux_session() -> str:
+    """Get default tmux session name from config."""
+    return get_user_config().tmux_session
+
+
+# =============================================================================
+# TUI Preferences (persisted between launches)
+# =============================================================================
+
+def get_tui_preferences_path(session: str) -> Path:
+    """Get TUI preferences file path for a specific session."""
+    return get_session_dir(session) / "tui_preferences.json"
+
+
+@dataclass
+class TUIPreferences:
+    """TUI preferences that persist between launches."""
+
+    summary_detail: str = "low"  # low, med, full
+    detail_lines: int = 5  # 5, 10, 20, 50
+    timeline_visible: bool = True
+    daemon_panel_visible: bool = False
+    view_mode: str = "tree"  # tree, list_preview
+
+    @classmethod
+    def load(cls, session: str) -> "TUIPreferences":
+        """Load TUI preferences from file."""
+        import json
+        prefs_path = get_tui_preferences_path(session)
+
+        if not prefs_path.exists():
+            return cls()
+
+        try:
+            with open(prefs_path) as f:
+                data = json.load(f)
+                if not isinstance(data, dict):
+                    return cls()
+
+                return cls(
+                    summary_detail=data.get("summary_detail", "low"),
+                    detail_lines=data.get("detail_lines", 5),
+                    timeline_visible=data.get("timeline_visible", True),
+                    daemon_panel_visible=data.get("daemon_panel_visible", False),
+                    view_mode=data.get("view_mode", "tree"),
+                )
+        except (json.JSONDecodeError, IOError):
+            return cls()
+
+    def save(self, session: str) -> None:
+        """Save TUI preferences to file."""
+        import json
+        prefs_path = get_tui_preferences_path(session)
+
+        try:
+            prefs_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(prefs_path, 'w') as f:
+                json.dump({
+                    "summary_detail": self.summary_detail,
+                    "detail_lines": self.detail_lines,
+                    "timeline_visible": self.timeline_visible,
+                    "daemon_panel_visible": self.daemon_panel_visible,
+                    "view_mode": self.view_mode,
+                }, f, indent=2)
+        except (IOError, OSError):
+            pass  # Best effort

overcode/standing_instructions.py

@@ -0,0 +1,276 @@
+"""
+Standing instructions library for overcode agents.
+
+Provides a library of pre-defined instruction presets that users can apply
+to agents. Presets are stored in ~/.overcode/presets.json and can be
+customized by the user.
+"""
+
+import json
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Optional, Dict, List
+
+PRESETS_PATH = Path.home() / ".overcode" / "presets.json"
+
+
+@dataclass
+class InstructionPreset:
+    """A pre-defined standing instruction preset."""
+    name: str           # Short name: DEFAULT, CODING, etc.
+    description: str    # One-line description for CLI help
+    instructions: str   # Full instruction text for daemon claude
+
+
+# Default presets - used to generate initial presets.json
+DEFAULT_PRESETS: Dict[str, InstructionPreset] = {
+    "DEFAULT": InstructionPreset(
+        name="DEFAULT",
+        description="General-purpose safe automation",
+        instructions=(
+            "Approve safe operations within the working directory: file reads/writes/edits, "
+            "web fetches, git status/add/commit, running tests. Reject operations outside "
+            "the project, rm -rf, or anything that could affect system stability. When "
+            "uncertain, err on the side of caution."
+        ),
+    ),
+    "PERMISSIVE": InstructionPreset(
+        name="PERMISSIVE",
+        description="Trusted agent, minimal friction",
+        instructions=(
+            "Approve most permission requests to keep work flowing. Trust the agent's "
+            "judgment on file operations, web access, and shell commands within reason. "
+            "Only reject clearly dangerous operations like rm -rf on large directories, "
+            "operations on system files, or commands that could crash the system."
+        ),
+    ),
+    "CAUTIOUS": InstructionPreset(
+        name="CAUTIOUS",
+        description="Sensitive project, careful oversight",
+        instructions=(
+            "Take a conservative approach. Approve read operations freely. For writes, "
+            "check they're within the project and make sense for the task. Reject any "
+            "git push, deployment commands, or operations that can't be easily undone. "
+            "When in doubt, let the session wait for the human user."
+        ),
+    ),
+    "RESEARCH": InstructionPreset(
+        name="RESEARCH",
+        description="Information gathering, exploration",
+        instructions=(
+            "Approve all read operations: file reads, web searches, web fetches, grep, "
+            "glob, directory listings. Approve writing notes or summary files. Be "
+            "cautious with code modifications - the goal is gathering information, not "
+            "making changes. Reject shell commands that modify state."
+        ),
+    ),
+    "CODING": InstructionPreset(
+        name="CODING",
+        description="Active development work",
+        instructions=(
+            "Approve file operations within the project: reads, writes, edits. Approve "
+            "running tests, linters, and build commands. Approve git add and commit. "
+            "Be cautious with git push - only if tests pass and work looks complete. "
+            "Reject operations outside the project directory."
+        ),
+    ),
+    "TESTING": InstructionPreset(
+        name="TESTING",
+        description="Running and fixing tests",
+        instructions=(
+            "Approve running test suites (pytest, jest, etc.) and viewing results. "
+            "Approve file edits to fix failing tests. Approve re-running tests after "
+            "fixes. Keep the agent focused on making tests pass. Reject unrelated "
+            "changes or scope creep beyond test fixes."
+        ),
+    ),
+    "REVIEW": InstructionPreset(
+        name="REVIEW",
+        description="Code review, analysis only",
+        instructions=(
+            "Approve only read operations: file reads, git log, git diff, grep searches. "
+            "The agent should analyze and report, not modify. Reject all write operations, "
+            "edits, and shell commands that change state. Let the agent provide analysis "
+            "and recommendations only."
+        ),
+    ),
+    "DEPLOY": InstructionPreset(
+        name="DEPLOY",
+        description="Deployment and release tasks",
+        instructions=(
+            "Approve deployment-related commands: git push, npm publish, docker build/push, "
+            "deployment scripts. Verify tests pass before approving pushes. Approve version "
+            "bumps and changelog updates. Be careful with production database commands - "
+            "verify they're read-only or explicitly requested."
+        ),
+    ),
+    "AUTONOMOUS": InstructionPreset(
+        name="AUTONOMOUS",
+        description="Fully autonomous operation",
+        instructions=(
+            "Approve all reasonable operations to maximize autonomous progress. Trust the "
+            "agent to make good decisions. Only intervene for clearly dangerous operations "
+            "(system file modifications, recursive deletes, credential exposure). The goal "
+            "is minimal human interruption."
+        ),
+    ),
+    "MINIMAL": InstructionPreset(
+        name="MINIMAL",
+        description="Just keep it from stalling",
+        instructions=(
+            "Only intervene when the agent is completely stuck on a permission prompt. "
+            "Approve simple, safe operations. For anything complex or uncertain, let it "
+            "wait for the human user. Don't provide guidance or redirect the agent - just "
+            "handle permission gates."
+        ),
+    ),
+}
+
+
+def _ensure_presets_file() -> None:
+    """Create presets.json with defaults if it doesn't exist."""
+    if PRESETS_PATH.exists():
+        return
+
+    # Ensure directory exists
+    PRESETS_PATH.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write default presets
+    presets_data = {
+        name: asdict(preset)
+        for name, preset in DEFAULT_PRESETS.items()
+    }
+    with open(PRESETS_PATH, 'w') as f:
+        json.dump(presets_data, f, indent=2)
+
+
+def load_presets() -> Dict[str, InstructionPreset]:
+    """Load presets from ~/.overcode/presets.json.
+
+    Creates the file with defaults if it doesn't exist.
+
+    Returns:
+        Dict mapping preset names to InstructionPreset objects
+    """
+    _ensure_presets_file()
+
+    try:
+        with open(PRESETS_PATH, 'r') as f:
+            data = json.load(f)
+
+        presets = {}
+        for name, preset_data in data.items():
+            presets[name.upper()] = InstructionPreset(
+                name=preset_data.get("name", name),
+                description=preset_data.get("description", ""),
+                instructions=preset_data.get("instructions", ""),
+            )
+        return presets
+
+    except (json.JSONDecodeError, IOError):
+        # Fall back to defaults if file is corrupted
+        return DEFAULT_PRESETS.copy()
+
+
+def save_presets(presets: Dict[str, InstructionPreset]) -> None:
+    """Save presets to ~/.overcode/presets.json.
+
+    Args:
+        presets: Dict mapping preset names to InstructionPreset objects
+    """
+    PRESETS_PATH.parent.mkdir(parents=True, exist_ok=True)
+
+    presets_data = {
+        name: asdict(preset)
+        for name, preset in presets.items()
+    }
+    with open(PRESETS_PATH, 'w') as f:
+        json.dump(presets_data, f, indent=2)
+
+
+def get_preset(name: str) -> Optional[InstructionPreset]:
+    """Get a preset by name (case-insensitive).
+
+    Args:
+        name: Preset name to look up
+
+    Returns:
+        InstructionPreset if found, None otherwise
+    """
+    presets = load_presets()
+    return presets.get(name.upper())
+
+
+def get_preset_names() -> List[str]:
+    """Get all preset names in order.
+
+    Returns:
+        List of preset names
+    """
+    presets = load_presets()
+    # Return in a consistent order (DEFAULT first, then alphabetical)
+    names = list(presets.keys())
+    if "DEFAULT" in names:
+        names.remove("DEFAULT")
+        names = ["DEFAULT"] + sorted(names)
+    else:
+        names = sorted(names)
+    return names
+
+
+def resolve_instructions(input_text: str) -> tuple[str, Optional[str]]:
+    """Resolve input to (full_instructions, preset_name_or_none).
+
+    If input matches a preset name (case-insensitive), returns the preset's
+    instructions and name. Otherwise returns the input as custom instructions.
+
+    Args:
+        input_text: User input - either a preset name or custom instructions
+
+    Returns:
+        Tuple of (full_instructions, preset_name_if_used)
+    """
+    preset = get_preset(input_text)
+    if preset:
+        return preset.instructions, preset.name
+    return input_text, None
+
+
+def add_preset(name: str, description: str, instructions: str) -> None:
+    """Add or update a preset.
+
+    Args:
+        name: Preset name (will be uppercased)
+        description: Short description
+        instructions: Full instruction text
+    """
+    presets = load_presets()
+    presets[name.upper()] = InstructionPreset(
+        name=name.upper(),
+        description=description,
+        instructions=instructions,
+    )
+    save_presets(presets)
+
+
+def remove_preset(name: str) -> bool:
+    """Remove a preset.
+
+    Args:
+        name: Preset name to remove
+
+    Returns:
+        True if preset was removed, False if not found
+    """
+    presets = load_presets()
+    name_upper = name.upper()
+    if name_upper in presets:
+        del presets[name_upper]
+        save_presets(presets)
+        return True
+    return False
+
+
+def reset_presets() -> None:
+    """Reset presets to defaults."""
+    save_presets(DEFAULT_PRESETS.copy())