monoco-toolkit 0.3.9__py3-none-any.whl → 0.3.11__py3-none-any.whl

monoco/features/agent/__init__.py

@@ -1,10 +1,10 @@
-from .models import RoleTemplate, AgentConfig, SchedulerConfig
+from .models import RoleTemplate, AgentRoleConfig as AgentConfig, SchedulerConfig
 from .worker import Worker
 from .config import load_scheduler_config, load_agent_config
 from .defaults import DEFAULT_ROLES
 from .session import Session, RuntimeSession
 from .manager import SessionManager
-from .reliability import ApoptosisManager
+from .apoptosis import ApoptosisManager
 
 __all__ = [
     "RoleTemplate",

monoco/features/agent/adapter.py

@@ -0,0 +1,41 @@
+from pathlib import Path
+from typing import Dict
+from monoco.core.loader import FeatureModule, FeatureMetadata
+from monoco.core.feature import IntegrationData
+
+
+class AgentFeature(FeatureModule):
+    """Agent management feature module with unified lifecycle support."""
+
+    @property
+    def metadata(self) -> FeatureMetadata:
+        return FeatureMetadata(
+            name="agent",
+            version="1.0.0",
+            description="Agent session and role management",
+            dependencies=["core"],
+            priority=20,
+        )
+
+    def _on_mount(self, context: "FeatureContext") -> None:  # type: ignore
+        """Agent feature doesn't require special initialization."""
+        pass
+
+    def integrate(self, root: Path, config: Dict) -> IntegrationData:
+        """Provide integration data for agent environment."""
+        # Determine language from config, default to 'en'
+        lang = config.get("i18n", {}).get("source_lang", "en")
+
+        # Resource path: monoco/features/agent/resources/{lang}/AGENTS.md
+        base_dir = Path(__file__).parent / "resources"
+
+        # Try specific language, fallback to 'en'
+        prompt_file = base_dir / lang / "AGENTS.md"
+        if not prompt_file.exists():
+            prompt_file = base_dir / "en" / "AGENTS.md"
+
+        content = ""
+        if prompt_file.exists():
+            content = prompt_file.read_text(encoding="utf-8").strip()
+
+        return IntegrationData(system_prompts={"Agent": content})

monoco/features/agent/apoptosis.py

@@ -0,0 +1,44 @@
+from .manager import SessionManager
+from .models import RoleTemplate
+
+class ApoptosisManager:
+    """
+    Manages the controlled shutdown (Apoptosis) and investigation (Autopsy) 
+    of failed agent sessions.
+    """
+    
+    def __init__(self, session_manager: SessionManager):
+        self.session_manager = session_manager
+        
+    def trigger_apoptosis(self, session_id: str, failure_reason: str = "Unknown") -> None:
+        """
+        Trigger the apoptosis process for a given session.
+        1. Mark session as crashed.
+        2. Spin up a Coroner agent to diagnose.
+        """
+        session = self.session_manager.get_session(session_id)
+        if not session:
+            return
+            
+        # 1. Mark as crashed
+        session.model.status = "crashed"
+        
+        # 2. Start Coroner
+        self._perform_autopsy(session, failure_reason)
+        
+    def _perform_autopsy(self, victim_session, failure_reason: str):
+        coroner_role = RoleTemplate(
+            name="Coroner",
+            description="Investigates cause of death for failed agents.",
+            trigger="system.crash",
+            goal=f"Determine why the previous agent failed. Reason: {failure_reason}",
+            system_prompt="You are the Coroner. Analyze the logs.",
+            engine="gemini"
+        )
+        
+        coroner_session = self.session_manager.create_session(
+            issue_id=victim_session.model.issue_id,
+            role=coroner_role
+        )
+        
+        coroner_session.start()

monoco/features/agent/cli.py

@@ -2,7 +2,7 @@ import typer
 import time
 from pathlib import Path
 from typing import Optional
-from monoco.core.output import print_output
+from monoco.core.output import print_output, print_error
 from monoco.core.config import get_config
 from monoco.features.agent import SessionManager, load_scheduler_config
 
@@ -50,16 +50,20 @@ def list_providers():
     """
     from monoco.core.integrations import get_all_integrations
 
-    settings = get_config()
     # Ideally we'd pass project-specific integrations here if they existed in config objects
     integrations = get_all_integrations(enabled_only=False)
 
     output = []
     for key, integration in integrations.items():
+        # Perform health check
+        health = integration.check_health()
+        status_icon = "✅" if health.available else "❌"
+        
         output.append(
             {
                 "key": key,
                 "name": integration.name,
+                "status": status_icon,
                 "binary": integration.bin_name or "-",
                 "enabled": integration.enabled,
                 "rules": integration.system_prompt_file,
@@ -95,87 +99,130 @@ def check_providers():
 
 @app.command()
 def run(
-    target: Optional[str] = typer.Argument(
-        None, help="Issue ID (e.g. FEAT-101) or a Task Description in quotes."
-    ),
-    role: Optional[str] = typer.Option(
-        None,
-        help="Specific role to use (Planner/Builder/Reviewer). Default: intelligent selection.",
+    prompt: Optional[list[str]] = typer.Argument(None, help="Instructions for the agent (e.g. 'Fix the bug')."),
+    issue: Optional[str] = typer.Option(
+        None, "--issue", "-i", help="Link to a specific Issue ID (e.g. FEAT-101)."
     ),
-    type: str = typer.Option(
-        "feature", "--type", "-t", help="Issue type for new tasks (feature/chore/fix)."
+    role: str = typer.Option(
+        "Default", "--role", "-r", help="Specific role to use."
     ),
     detach: bool = typer.Option(
         False, "--detach", "-d", help="Run in background (Daemon)"
     ),
-    fail: bool = typer.Option(
-        False, "--fail", help="Simulate a crash for testing Apoptosis."
+    provider: Optional[str] = typer.Option(
+        None, "--provider", "-p", help="Override the default engine/provider for this session."
     ),
 ):
     """
     Start an agent session.
 
-    If TARGET is an Issue ID, it starts a session for that issue.
-    If TARGET is a description, it starts a 'Planner' session to draft a new issue.
+    Usage:
+      monoco agent run "Check memos"
+      monoco agent run -i FEAT-101 "Implement feature"
     """
-    from monoco.core.output import print_error
-
-    # Normal run mode - target is required
-    if not target:
-        from monoco.core.output import print_error
-
-        print_error("TARGET (Issue ID or Task Description) is required.")
-        raise typer.Exit(code=1)
-        raise typer.Exit(code=1)
-
-    # 1. Smart Intent Recognition
-    import re
-
-    is_id = re.match(r"^[a-zA-Z]+-\d+$", target)
-
-    if is_id:
-        issue_id = target.upper()
-        role_name = role or "Builder"
-        description = None
+    settings = get_config()
+    project_root = Path(settings.paths.root).resolve()
+    
+    # 1. Resolve Inputs
+    full_prompt = " ".join(prompt) if prompt else ""
+    
+    if issue:
+        # User explicitly linked an issue
+        issue_id = issue.upper()
+        description = full_prompt or None
     else:
-        # Implicit Draft Mode via run command (target is description)
+        # Ad-hoc task check
+        import re
+        # Heuristic: if prompt looks like an ID and is short, maybe they meant ID?
+        # But explicit is better. Let's assume everything in prompt is instructions.
         issue_id = "NEW_TASK"
-        role_name = role or "Planner"
-        description = target
+        description = full_prompt
+
+    if not description and not issue:
+        print_error("Please provide either a PROMPT or an --issue ID.")
+        raise typer.Exit(code=1)
 
     # 2. Load Roles
     roles = load_scheduler_config(project_root)
-    selected_role = roles.get(role_name)
+    selected_role = roles.get(role)
 
     if not selected_role:
-        print_error(f"Role '{role_name}' not found. Available: {list(roles.keys())}")
+        print_error(f"Role '{role}' not found. Available: {list(roles.keys())}")
         raise typer.Exit(code=1)
 
+    # 3. Provider Override & Fallback Logic
+    target_engine = provider or selected_role.engine
+    from monoco.core.integrations import get_integration, get_all_integrations
+    
+    integration = get_integration(target_engine)
+    
+    # If integration is found, check health
+    is_available = False
+    if integration:
+        health = integration.check_health()
+        is_available = health.available
+        if not is_available and provider:
+            # If user explicitly requested this provider, fail hard
+            print_error(f"Requested provider '{target_engine}' is not available.")
+            print_error(f"Error: {health.error}")
+            raise typer.Exit(code=1)
+            
+    # Auto-fallback if default provider is unavailable
+    if not is_available:
+        print_output(f"⚠️  Provider '{target_engine}' is not available. Searching for fallback...", style="yellow")
+        
+        all_integrations = get_all_integrations(enabled_only=True)
+        fallback_found = None
+        
+        # Priority list for fallback
+        priority = ["cursor", "claude", "gemini", "qwen", "kimi"]
+        
+        # Try priority matches first
+        for key in priority:
+            if key in all_integrations:
+                if all_integrations[key].check_health().available:
+                    fallback_found = key
+                    break
+        
+        # Determine strict fallback
+        if fallback_found:
+             print_output(f"🔄 Falling back to available provider: [bold green]{fallback_found}[/bold green]")
+             selected_role.engine = fallback_found
+        else:
+             # If NO CLI tools available, maybe generic agent?
+             if "agent" in all_integrations:
+                 print_output("🔄 Falling back to Generic Agent (No CLI execution).", style="yellow")
+                 selected_role.engine = "agent"
+             else:
+                 print_error("❌ No available agent providers found on this system.")
+                 print_error("Please install Cursor, Claude Code, or Gemini CLI.")
+                 raise typer.Exit(code=1)
+    elif provider:
+        # If available and user overrode it
+        print_output(f"Overriding provider: {selected_role.engine} -> {provider}")
+        selected_role.engine = provider
+
+    display_target = issue if issue else (full_prompt[:50] + "..." if len(full_prompt) > 50 else full_prompt)
     print_output(
-        f"Starting Agent Session for '{target}' as {role_name}...",
-        title="Agent Scheduler",
+        f"Starting Agent Session for '{display_target}' as {role} (via {selected_role.engine})...",
+        title="Agent Framework",
     )
 
-    # 3. Initialize Session
+    # 4. Initialize Session
     manager = SessionManager()
     session = manager.create_session(issue_id, selected_role)
 
-    if detach:
-        print_output(
-            "Background mode not fully implemented yet. Running in foreground."
-        )
 
     try:
         # Pass description if it's a new task
         context = {"description": description} if description else None
+        session.start(context=context)
 
-        if fail:
-            from monoco.core.output import rprint
-
-            rprint("[bold yellow]DEBUG: Simulating immediate crash...[/bold yellow]")
-            session.model.status = "failed"
-        else:
-            session.start(context=context)
+        if detach:
+            print_output(
+                 f"Session {session.model.id} started in background (detached)."
+            )
+            return
 
         # Monitoring Loop
         while session.refresh_status() == "running":
@@ -183,12 +230,12 @@ def run(
 
         if session.model.status == "failed":
             print_error(
-                f"Session {session.model.id} FAILED. Use 'monoco agent session autopsy {session.model.id}' for analysis."
+                f"Session {session.model.id} FAILED. Review logs for details."
             )
         else:
             print_output(
                 f"Session finished with status: {session.model.status}",
-                title="Agent Scheduler",
+                title="Agent Framework",
             )
 
     except KeyboardInterrupt:
@@ -211,96 +258,6 @@ def kill_session(session_id: str):
         print_output(f"Session {session_id} not found.", style="red")
 
 
-@session_app.command(name="autopsy")
-def autopsy_command(target: str):
-    """Execute Post-Mortem analysis on a failed session or target Issue."""
-    _run_autopsy(target)
-
-
-def _run_autopsy(target: str):
-    """Execute Post-Mortem analysis on a failed session or target Issue."""
-    from .reliability import ApoptosisManager
-    from monoco.core.output import print_error
-
-    manager = SessionManager()
-
-    print_output(f"Initiating Autopsy for '{target}'...", title="Coroner")
-
-    # Try to find session
-    session = manager.get_session(target)
-    if not session:
-        # Fallback: Treat target as Issue ID and create a dummy failed session context
-        import re
-
-        if re.match(r"^[a-zA-Z]+-\d+$", target):
-            print_output(f"Session not in memory. Analyzing Issue {target} directly.")
-            # We create a transient session just to trigger the coroner
-            settings = get_config()
-            project_root = Path(settings.paths.root).resolve()
-            roles = load_scheduler_config(project_root)
-            builder_role = roles.get("Builder")
-
-            if not builder_role:
-                print_error("Builder role not found.")
-                raise typer.Exit(code=1)
-
-            session = manager.create_session(target.upper(), builder_role)
-            session.model.status = "failed"
-        else:
-            print_error(f"Could not find session or valid Issue ID for '{target}'")
-            raise typer.Exit(code=1)
-
-    apoptosis = ApoptosisManager(manager)
-    apoptosis.trigger_apoptosis(session.model.id)
-
-
-def _run_draft(desc: str, type: str, detach: bool):
-    """Draft a new issue based on a natural language description."""
-    from monoco.core.output import print_error
-
-    settings = get_config()
-    project_root = Path(settings.paths.root).resolve()
-
-    # Load Roles
-    roles = load_scheduler_config(project_root)
-    # Use 'Planner' as the role for drafting (it handles new tasks)
-    role_name = "Planner"
-    selected_role = roles.get(role_name)
-
-    if not selected_role:
-        print_error(f"Role '{role_name}' not found.")
-        raise typer.Exit(code=1)
-
-    print_output(
-        f"Drafting {type} from description: '{desc}'",
-        title="Agent Drafter",
-    )
-
-    manager = SessionManager()
-    # We use a placeholder ID as we don't know the ID yet.
-    # The agent is expected to create the file, so the ID will be generated then.
-    session = manager.create_session("NEW_TASK", selected_role)
-
-    context = {"description": desc, "type": type}
-
-    try:
-        session.start(context=context)
-
-        # Monitoring Loop
-        while session.refresh_status() == "running":
-            time.sleep(1)
-
-        if session.model.status == "failed":
-            print_error("Drafting failed.")
-        else:
-            print_output("Drafting completed.", title="Agent Drafter")
-
-    except KeyboardInterrupt:
-        print("\nStopping...")
-        session.terminate()
-        print_output("Drafting cancelled.")
-
-
 @session_app.command(name="list")
 def list_sessions():
     """

monoco/features/agent/config.py

@@ -1,16 +1,16 @@
 from typing import Dict, Optional
 import yaml
 from pathlib import Path
-from .models import RoleTemplate, AgentConfig
+from .models import RoleTemplate, AgentRoleConfig as AgentConfig
 from .defaults import DEFAULT_ROLES
 
 
 class RoleLoader:
     """
     Tiered configuration loader for Agent Roles.
-    Level 1: Builtin Fallback
-    Level 2: Global (~/.monoco/roles.yaml)
-    Level 3: Project (./.monoco/roles.yaml)
+    Level 1: Builtin Resources (monoco/features/agent/resources/roles/*.yaml)
+    Level 2: Global (~/.monoco/roles/*.yaml)
+    Level 3: Project (./.monoco/roles/*.yaml)
     """
 
     def __init__(self, project_root: Optional[Path] = None):
@@ -20,23 +20,33 @@ class RoleLoader:
         self.sources: Dict[str, str] = {}  # role_name -> source description
 
     def load_all(self) -> Dict[str, RoleTemplate]:
-        # Level 1: Defaults
+        # Level 1: Defaults (Hardcoded)
         for role in DEFAULT_ROLES:
-            self.roles[role.name] = role
-            self.sources[role.name] = "builtin"
+            if role.name not in self.roles:
+                self.roles[role.name] = role
+                self.sources[role.name] = "builtin (default)"
 
         # Level 2: Global
-        global_path = self.user_home / ".monoco" / "roles.yaml"
-        self._load_from_path(global_path, "global")
+        global_monoco = self.user_home / ".monoco"
+        self._load_from_file(global_monoco / "roles.yaml", "global")
+        self._load_from_dir(global_monoco / "roles", "global")
 
         # Level 3: Project
         if self.project_root:
-            project_path = self.project_root / ".monoco" / "roles.yaml"
-            self._load_from_path(project_path, "project")
+            project_monoco = self.project_root / ".monoco"
+            self._load_from_file(project_monoco / "roles.yaml", "project")
+            self._load_from_dir(project_monoco / "roles", "project")
 
         return self.roles
 
-    def _load_from_path(self, path: Path, source_label: str):
+    def _load_from_dir(self, directory: Path, source_label: str):
+        if not directory.exists() or not directory.is_dir():
+            return
+        
+        for file in directory.glob("*.yaml"):
+            self._load_from_file(file, source_label)
+
+    def _load_from_file(self, path: Path, source_label: str):
         if not path.exists():
             return
 
@@ -44,21 +54,25 @@ class RoleLoader:
             with open(path, "r") as f:
                 data = yaml.safe_load(f) or {}
 
-            if "roles" in data:
-                # Validate using AgentConfig
+            # Case A: Config object with "roles" list
+            if "roles" in data and isinstance(data["roles"], list):
                 config = AgentConfig(roles=data["roles"])
                 for role in config.roles:
-                    # Level 3 > Level 2 > Level 1 (名字相同的 Role 进行覆盖/Merge)
-                    # Currently we do total replacement for same-named roles
-                    self.roles[role.name] = role
-                    self.sources[role.name] = str(path)
+                    self._upsert_role(role, str(path))
+            
+            # Case B: Single Role object
+            elif "name" in data and "system_prompt" in data:
+                role = RoleTemplate(**data)
+                self._upsert_role(role, str(path))
+                
         except Exception as e:
-            # We don't want to crash the whole tool if a config is malformed,
-            # but we should probably warn.
             import sys
-
             print(f"Warning: Failed to load roles from {path}: {e}", file=sys.stderr)
 
+    def _upsert_role(self, role: RoleTemplate, source: str):
+        self.roles[role.name] = role
+        self.sources[role.name] = source
+
 
 def load_scheduler_config(project_root: Path) -> Dict[str, RoleTemplate]:
     """

monoco/features/agent/defaults.py

@@ -2,54 +2,11 @@ from .models import RoleTemplate
 
 DEFAULT_ROLES = [
     RoleTemplate(
-        name="Planner",
-        description="Responsible for requirement analysis, design documents, and issue drafting.",
-        trigger="task.received",
-        goal="Produce a structured design document or issue ticket.",
-        system_prompt=(
-            "You are a Planner agent. Your goal is to transform requirements into structured plans.\n"
-            "Analyze the workspace context and produce detailed issue tickets or design documents."
-        ),
+        name="Default",
+        description="A generic, jack-of-all-trades agent used when no specific role is configured.",
+        trigger="task.dispatch",
+        goal="Complete the assigned task.",
+        system_prompt="You are a helpful Agent. Complete the task assigned to you.",
         engine="gemini",
-    ),
-    RoleTemplate(
-        name="Builder",
-        description="Responsible for implementing code and tests based on the design.",
-        trigger="design.approved",
-        goal="Implement functional code and passing tests.",
-        system_prompt="You are a Builder agent. Your job is to implement the solution as specified in the issue.",
-        engine="gemini",
-    ),
-    RoleTemplate(
-        name="Reviewer",
-        description="Responsible for code quality, architectural consistency, and linting.",
-        trigger="implementation.submitted",
-        goal="Provide critical feedback and approve or reject submissions.",
-        system_prompt="You are a Reviewer agent. Analyze code changes for bugs, style, and correctness.",
-        engine="gemini",
-    ),
-    RoleTemplate(
-        name="Merger",
-        description="Responsible for branch management and merging verified changes into trunk.",
-        trigger="review.passed",
-        goal="Safely merge feature branches and prune resources.",
-        system_prompt="You are a Merger agent. Handle the final integration of features and clean up environment.",
-        engine="gemini",
-    ),
-    RoleTemplate(
-        name="Coroner",
-        description="Responsible for post-mortem analysis and root cause identification on failure.",
-        trigger="session.crashed",
-        goal="Generate a detailed autopsy report.",
-        system_prompt="You are a Coroner agent. Analyze the failure state and generate a ## Post-mortem report.",
-        engine="gemini",
-    ),
-    RoleTemplate(
-        name="Manager",
-        description="The central orchestrator that processes memos and schedules other roles.",
-        trigger="daily.check / memo.added",
-        goal="Orchestrate the development workflow and manage team priorities.",
-        system_prompt="You are the Manager agent. You act as the scheduler and coordinator for the entire agentic system.",
-        engine="gemini",
-    ),
+    )
 ]

monoco/features/agent/engines.py

@@ -48,12 +48,13 @@ class GeminiAdapter(EngineAdapter):
     """
     Adapter for Google Gemini CLI.
 
-    Command format: gemini -y <prompt>
+    Command format: gemini -p <prompt> -y
     The -y flag enables "YOLO mode" (auto-approval of actions).
     """
 
     def build_command(self, prompt: str) -> List[str]:
-        return ["gemini", "-y", prompt]
+        # Based on Gemini CLI help: -p <prompt> for non-interactive
+        return ["gemini", "-p", prompt, "-y"]
 
     @property
     def name(self) -> str:
@@ -69,10 +70,12 @@ 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).
+    The -p/--print flag enables non-interactive mode.
     """
 
     def build_command(self, prompt: str) -> List[str]:
+        # Based on Claude CLI help: -p <prompt> is NOT standard, usually -p means print/non-interactive.
+        # But for one-shot execution, we do passing prompt as argument with -p flag.
         return ["claude", "-p", prompt]
 
     @property
@@ -89,12 +92,12 @@ class QwenAdapter(EngineAdapter):
     """
     Adapter for Qwen Code CLI.
 
-    Command format: qwen -y <prompt>
-    The -y flag enables "YOLO mode" (auto-approval of actions).
+    Command format: qwen -p <prompt> -y
     """
 
     def build_command(self, prompt: str) -> List[str]:
-        return ["qwen", "-y", prompt]
+        # Assuming Qwen follows similar patterns (based on user feedback)
+        return ["qwen", "-p", prompt, "-y"]
 
     @property
     def name(self) -> str:
@@ -105,6 +108,28 @@ class QwenAdapter(EngineAdapter):
         return True
 
 
+class KimiAdapter(EngineAdapter):
+    """
+    Adapter for Kimi CLI (Moonshot AI).
+
+    Command format: kimi -p <prompt> --print
+    Note: --print implicitly adds --yolo.
+    """
+
+    def build_command(self, prompt: str) -> List[str]:
+        # Based on Kimi CLI help: -p, --prompt TEXT.
+        # Also using --print for non-interactive mode (which enables yolo).
+        return ["kimi", "-p", prompt, "--print"]
+
+    @property
+    def name(self) -> str:
+        return "kimi"
+
+    @property
+    def supports_yolo_mode(self) -> bool:
+        return True
+
+
 class EngineFactory:
     """
     Factory for creating engine adapter instances.
@@ -118,6 +143,7 @@ class EngineFactory:
         "gemini": GeminiAdapter,
         "claude": ClaudeAdapter,
         "qwen": QwenAdapter,
+        "kimi": KimiAdapter,
     }
 
     @classmethod