monoco-toolkit 0.3.2__py3-none-any.whl → 0.3.5__py3-none-any.whl

monoco/features/scheduler/engines.py

@@ -0,0 +1,149 @@
+"""
+Agent Engine Adapters for Monoco Scheduler.
+
+This module provides a unified interface for different AI agent execution engines,
+allowing the Worker to seamlessly switch between Gemini, Claude, and future engines.
+"""
+
+from abc import ABC, abstractmethod
+from typing import List
+
+
+class EngineAdapter(ABC):
+    """
+    Abstract base class for agent engine adapters.
+
+    Each adapter is responsible for:
+    1. Constructing the correct CLI command for its engine
+    2. Handling engine-specific error scenarios
+    3. Providing metadata about the engine's capabilities
+    """
+
+    @abstractmethod
+    def build_command(self, prompt: str) -> List[str]:
+        """
+        Build the CLI command to execute the agent with the given prompt.
+
+        Args:
+            prompt: The instruction/context to send to the agent
+
+        Returns:
+            List of command arguments (e.g., ["gemini", "-y", "prompt text"])
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return the canonical name of this engine."""
+        pass
+
+    @property
+    def supports_yolo_mode(self) -> bool:
+        """Whether this engine supports auto-approval mode."""
+        return False
+
+
+class GeminiAdapter(EngineAdapter):
+    """
+    Adapter for Google Gemini CLI.
+
+    Command format: gemini -y <prompt>
+    The -y flag enables "YOLO mode" (auto-approval of actions).
+    """
+
+    def build_command(self, prompt: str) -> List[str]:
+        return ["gemini", "-y", prompt]
+
+    @property
+    def name(self) -> str:
+        return "gemini"
+
+    @property
+    def supports_yolo_mode(self) -> bool:
+        return True
+
+
+class ClaudeAdapter(EngineAdapter):
+    """
+    Adapter for Anthropic Claude CLI.
+
+    Command format: claude -p <prompt>
+    The -p/--print flag enables non-interactive mode (print response and exit).
+    """
+
+    def build_command(self, prompt: str) -> List[str]:
+        return ["claude", "-p", prompt]
+
+    @property
+    def name(self) -> str:
+        return "claude"
+
+    @property
+    def supports_yolo_mode(self) -> bool:
+        # Claude uses -p for non-interactive mode, similar concept
+        return True
+
+
+class QwenAdapter(EngineAdapter):
+    """
+    Adapter for Qwen Code CLI.
+
+    Command format: qwen -y <prompt>
+    The -y flag enables "YOLO mode" (auto-approval of actions).
+    """
+
+    def build_command(self, prompt: str) -> List[str]:
+        return ["qwen", "-y", prompt]
+
+    @property
+    def name(self) -> str:
+        return "qwen"
+
+    @property
+    def supports_yolo_mode(self) -> bool:
+        return True
+
+
+class EngineFactory:
+    """
+    Factory for creating engine adapter instances.
+
+    Usage:
+        adapter = EngineFactory.create("gemini")
+        command = adapter.build_command("Write a test")
+    """
+
+    _adapters = {
+        "gemini": GeminiAdapter,
+        "claude": ClaudeAdapter,
+        "qwen": QwenAdapter,
+    }
+
+    @classmethod
+    def create(cls, engine_name: str) -> EngineAdapter:
+        """
+        Create an adapter instance for the specified engine.
+
+        Args:
+            engine_name: Name of the engine (e.g., "gemini", "claude")
+
+        Returns:
+            An instance of the appropriate EngineAdapter
+
+        Raises:
+            ValueError: If the engine is not supported
+        """
+        adapter_class = cls._adapters.get(engine_name.lower())
+        if not adapter_class:
+            supported = ", ".join(cls._adapters.keys())
+            raise ValueError(
+                f"Unsupported engine: '{engine_name}'. "
+                f"Supported engines: {supported}"
+            )
+        return adapter_class()
+
+    @classmethod
+    def supported_engines(cls) -> List[str]:
+        """Return a list of all supported engine names."""
+        return list(cls._adapters.keys())

monoco/features/scheduler/manager.py

@@ -0,0 +1,49 @@
+from typing import Dict, List, Optional
+import uuid
+from .models import RoleTemplate
+from .worker import Worker
+from .session import Session, RuntimeSession
+
+
+class SessionManager:
+    """
+    Manages the lifecycle of sessions.
+    Responsible for creating, tracking, and retrieving sessions.
+    """
+
+    def __init__(self):
+        # In-memory storage for now. In prod, this might be a DB or file-backed.
+        self._sessions: Dict[str, RuntimeSession] = {}
+
+    def create_session(self, issue_id: str, role: RoleTemplate) -> RuntimeSession:
+        session_id = str(uuid.uuid4())
+        branch_name = (
+            f"agent/{issue_id}/{session_id[:8]}"  # Simple branch naming strategy
+        )
+
+        session_model = Session(
+            id=session_id,
+            issue_id=issue_id,
+            role_name=role.name,
+            branch_name=branch_name,
+        )
+
+        worker = Worker(role, issue_id)
+        runtime = RuntimeSession(session_model, worker)
+        self._sessions[session_id] = runtime
+        return runtime
+
+    def get_session(self, session_id: str) -> Optional[RuntimeSession]:
+        return self._sessions.get(session_id)
+
+    def list_sessions(self, issue_id: Optional[str] = None) -> List[RuntimeSession]:
+        if issue_id:
+            return [s for s in self._sessions.values() if s.model.issue_id == issue_id]
+        return list(self._sessions.values())
+
+    def terminate_session(self, session_id: str):
+        session = self.get_session(session_id)
+        if session:
+            session.terminate()
+            # We might want to keep the record for a while, so don't delete immediately
+            # del self._sessions[session_id]

monoco/features/scheduler/models.py

@@ -0,0 +1,24 @@
+from typing import List
+from pydantic import BaseModel, Field
+
+
+class RoleTemplate(BaseModel):
+    name: str = Field(
+        ..., description="Unique identifier for the role (e.g., 'crafter')"
+    )
+    description: str = Field(..., description="Human-readable description of the role")
+    trigger: str = Field(
+        ..., description="Event that triggers this agent (e.g., 'issue.created')"
+    )
+    goal: str = Field(..., description="The primary goal/output of this agent")
+    tools: List[str] = Field(default_factory=list, description="List of allowed tools")
+    system_prompt: str = Field(
+        ..., description="The system prompt template for this agent"
+    )
+    engine: str = Field(
+        default="gemini", description="CLI agent engine (gemini/claude)"
+    )
+
+
+class SchedulerConfig(BaseModel):
+    roles: List[RoleTemplate] = Field(default_factory=list)

monoco/features/scheduler/reliability.py

@@ -0,0 +1,106 @@
+from pathlib import Path
+from monoco.core.config import get_config
+from .manager import SessionManager
+from .session import RuntimeSession
+from .config import load_scheduler_config
+
+
+class ApoptosisManager:
+    """
+    Handles the 'Apoptosis' (Programmed Cell Death) lifecycle for agents.
+    Ensures that failing agents are killed, analyzed, and the environment is reset.
+    """
+
+    def __init__(self, session_manager: SessionManager):
+        self.session_manager = session_manager
+
+        # Load roles dynamically based on current project context
+        settings = get_config()
+        project_root = Path(settings.paths.root).resolve()
+        roles = load_scheduler_config(project_root)
+
+        # Find coroner role
+        self.coroner_role = roles.get("coroner")
+
+        if not self.coroner_role:
+            raise ValueError("Coroner role not defined!")
+
+    def check_health(self, session: RuntimeSession) -> bool:
+        """
+        Check if a session is healthy.
+        In a real implementation, this would check heartbeat, CPU usage, or token limits.
+        """
+        # Placeholder logic: Random failure or external flag?
+        # For now, always healthy unless explicitly marked 'crashed' (which we can simulate)
+        if hasattr(session, "simulate_crash") and session.simulate_crash:
+            return False
+        return True
+
+    def trigger_apoptosis(self, session_id: str):
+        """
+        Execute the full death and rebirth cycle.
+        """
+        session = self.session_manager.get_session(session_id)
+        if not session:
+            print(f"Session {session_id} not found for apoptosis.")
+            return
+
+        print(f"💀 [Apoptosis] Starting lifecycle for Session {session_id}")
+
+        # 1. Kill
+        self._kill(session)
+
+        # 2. Autopsy
+        try:
+            self._perform_autopsy(session)
+        except Exception as e:
+            print(f"⚠️ Autopsy failed: {e}")
+
+        # 3. Reset
+        self._reset_environment(session)
+
+        print(
+            f"✅ [Apoptosis] Task {session.model.issue_id} has been reset and analyzed."
+        )
+
+    def _kill(self, session: RuntimeSession):
+        print(f"🔪 Killing worker process for {session.model.id}...")
+        session.terminate()
+        session.model.status = "crashed"
+
+    def _perform_autopsy(self, victim_session: RuntimeSession):
+        print(
+            f"🔍 Performing autopsy on {victim_session.model.id} via Coroner agent..."
+        )
+
+        # Start a Coroner session
+        coroner_session = self.session_manager.create_session(
+            victim_session.model.issue_id, self.coroner_role
+        )
+
+        # Context for the coroner
+        context = {
+            "description": f"The previous agent session ({victim_session.model.id}) for role '{victim_session.model.role_name}' crashed. Please analyze the environment and the Issue {victim_session.model.issue_id}, then write a ## Post-mortem section in the issue file."
+        }
+
+        coroner_session.start(context=context)
+        print("📄 Coroner agent finished analysis.")
+
+    def _reset_environment(self, session: RuntimeSession):
+        print("🧹 Resetting environment (simulated git reset --hard)...")
+        # In real impl:
+        # import subprocess
+        # subprocess.run(["git", "reset", "--hard"], check=True)
+        pass
+
+    def _retry(self, session: RuntimeSession):
+        print("🔄 Reincarnating session...")
+        # Create a new session with the same role and issue
+        new_session = self.session_manager.create_session(
+            session.model.issue_id,
+            # We need to find the original role object.
+            # Simplified: assuming we can find it by name or pass it.
+            # For now, just placeholder.
+            session.worker.role,
+        )
+        new_session.start()

monoco/features/scheduler/session.py

@@ -0,0 +1,87 @@
+from datetime import datetime
+from typing import Optional
+from pydantic import BaseModel, Field
+from .worker import Worker
+
+
+class Session(BaseModel):
+    """
+    Represents a runtime session of a worker.
+    Persisted state of the session.
+    """
+
+    id: str = Field(..., description="Unique session ID (likely UUID)")
+    issue_id: str = Field(..., description="The Issue ID this session is working on")
+    role_name: str = Field(..., description="Name of the role employed")
+    status: str = Field(
+        default="pending", description="pending, running, suspended, terminated"
+    )
+    branch_name: str = Field(
+        ..., description="Git branch name associated with this session"
+    )
+    created_at: datetime = Field(default_factory=datetime.now)
+    updated_at: datetime = Field(default_factory=datetime.now)
+    # History could be a list of logs or pointers to git commits
+    # For now, let's keep it simple. The git log IS the history.
+
+    class Config:
+        arbitrary_types_allowed = True
+
+
+class RuntimeSession:
+    """
+    The in-memory wrapper around the Session model and the active Worker.
+    """
+
+    def __init__(self, session_model: Session, worker: Worker):
+        self.model = session_model
+        self.worker = worker
+
+    def start(self, context: Optional[dict] = None):
+        print(
+            f"Session {self.model.id}: Starting worker on branch {self.model.branch_name}"
+        )
+        # In real impl, checking out branch happening here
+        self.model.status = "running"
+        self.model.updated_at = datetime.now()
+
+        try:
+            self.worker.start(context)
+            # Async mode: we assume it started running.
+            # Use poll or refresh_status to check later.
+            self.model.status = "running"
+        except Exception:
+            self.model.status = "failed"
+            raise
+        finally:
+            self.model.updated_at = datetime.now()
+
+    def refresh_status(self) -> str:
+        """
+        Polls the worker and updates the session model status.
+        """
+        worker_status = self.worker.poll()
+        self.model.status = worker_status
+        self.model.updated_at = datetime.now()
+        return worker_status
+
+    def suspend(self):
+        print(f"Session {self.model.id}: Suspending worker")
+        self.worker.stop()
+        self.model.status = "suspended"
+        self.model.updated_at = datetime.now()
+        # In real impl, ensure git commit of current state?
+
+    def resume(self):
+        print(f"Session {self.model.id}: Resuming worker")
+        self.worker.start()  # In real impl, might need to re-init process
+
+        # Async mode: assume running
+        self.model.status = "running"
+        self.model.updated_at = datetime.now()
+
+    def terminate(self):
+        print(f"Session {self.model.id}: Terminating")
+        self.worker.stop()
+        self.model.status = "terminated"
+        self.model.updated_at = datetime.now()

monoco/features/scheduler/worker.py

@@ -0,0 +1,133 @@
+from typing import Optional
+from .models import RoleTemplate
+from .engines import EngineFactory
+
+
+class Worker:
+    """
+    Represents an active or pending agent session assigned to a specific role and issue.
+    """
+
+    def __init__(self, role: RoleTemplate, issue_id: str):
+        self.role = role
+        self.issue_id = issue_id
+        self.status = "pending"  # pending, running, suspended, terminated
+        self.process_id: Optional[int] = None
+        self._process = None
+
+    def start(self, context: Optional[dict] = None):
+        """
+        Start the worker session asynchronously.
+        """
+        # Allow restart if not currently running
+        if self.status == "running":
+            return
+
+        print(f"Starting worker {self.role.name} for issue {self.issue_id}")
+
+        try:
+            self._execute_work(context)
+            self.status = "running"
+        except Exception as e:
+            print(f"Worker failed to start: {e}")
+            self.status = "failed"
+            raise
+
+    def _execute_work(self, context: Optional[dict] = None):
+        import subprocess
+        import sys
+
+        # Prepare the prompt
+        # We treat 'crafter' as a drafter when context is provided (Draft Mode)
+        if (self.role.name == "drafter" or self.role.name == "crafter") and context:
+            issue_type = context.get("type", "feature")
+            description = context.get("description", "No description")
+            prompt = (
+                f"You are a Drafter in the Monoco project.\n\n"
+                f"Task: Create a new {issue_type} issue based on this request: {description}\n\n"
+                "Constraints:\n"
+                "1. Use 'monoco issue create' to generate the file.\n"
+                "2. Use 'monoco issue update' or direct file editing to enrich Objective and Tasks.\n"
+                "3. IMPORTANT: Once the issue file is created and filled with high-quality content, EXIT search or interactive mode immediately.\n"
+                "4. Do not perform any other development tasks."
+            )
+        else:
+            prompt = (
+                f"{self.role.system_prompt}\n\n"
+                f"Issue context: {self.issue_id}\n"
+                f"Goal: {self.role.goal}\n"
+            )
+            if context and "description" in context:
+                prompt += f"Specific Task: {context['description']}"
+
+        engine = self.role.engine
+
+        print(f"[{self.role.name}] Engine: {engine}")
+        print(f"[{self.role.name}] Goal: {self.role.goal}")
+
+        try:
+            # Use factory to get the appropriate engine adapter
+            adapter = EngineFactory.create(engine)
+            engine_args = adapter.build_command(prompt)
+
+            self._process = subprocess.Popen(
+                engine_args, stdout=sys.stdout, stderr=sys.stderr, text=True
+            )
+            self.process_id = self._process.pid
+
+            # DO NOT WAIT HERE.
+            # The scheduler/monitoring loop is responsible for checking status.
+
+        except ValueError as e:
+            # Engine not supported by factory
+            raise RuntimeError(f"Unsupported engine '{engine}'. {str(e)}")
+        except FileNotFoundError:
+            raise RuntimeError(
+                f"Agent engine '{engine}' not found. Please ensure it is installed and in PATH."
+            )
+        except Exception as e:
+            print(f"[{self.role.name}] Process Error: {e}")
+            raise
+
+    def poll(self) -> str:
+        """
+        Check process status. Returns current worker status.
+        Updates self.status if process has finished.
+        """
+        if not self._process:
+            return self.status
+
+        returncode = self._process.poll()
+        if returncode is None:
+            return "running"
+
+        if returncode == 0:
+            self.status = "completed"
+        else:
+            self.status = "failed"
+
+        return self.status
+
+    def wait(self):
+        """
+        Block until process finishes.
+        """
+        if self._process:
+            self._process.wait()
+            self.poll()  # Update status
+
+    def stop(self):
+        """
+        Stop the worker session.
+        """
+        if self.status == "terminated":
+            return
+
+        print(f"Stopping worker {self.role.name} for issue {self.issue_id}")
+        self.status = "terminated"
+        self.process_id = None
+
+    def __repr__(self):
+        return (
+            f"<Worker role={self.role.name} issue={self.issue_id} status={self.status}>"
+        )

monoco/main.py

@@ -166,6 +166,11 @@ app.add_typer(config_cmd.app, name="config", help="Manage configuration")
 app.add_typer(project_cmd.app, name="project", help="Manage projects")
 app.add_typer(workspace_cmd.app, name="workspace", help="Manage workspace")
 
+from monoco.features.scheduler import cli as scheduler_cmd
+
+app.add_typer(scheduler_cmd.app, name="agent", help="Manage agent sessions")
+app.add_typer(scheduler_cmd.role_app, name="role", help="Manage agent roles")
+
 
 from monoco.daemon.commands import serve