hanuscode 1.0.0__py3-none-any.whl

hanus/skills/__init__.py

@@ -0,0 +1,4 @@
+# hanus/skills/__init__.py
+"""
+Skills directory - contains skill templates and definitions.
+"""

hanus/subagent/__init__.py

@@ -0,0 +1,8 @@
+# hanus/subagent/__init__.py
+"""
+Sistema de subagentes para delegar tareas complejas.
+"""
+from hanus.subagent.types import SubagentType, SubagentConfig, SubagentResult
+from hanus.subagent.manager import SubagentManager
+
+__all__ = ["SubagentType", "SubagentConfig", "SubagentResult", "SubagentManager"]

hanus/subagent/agents/__init__.py

@@ -0,0 +1,253 @@
+# hanus/subagent/agents/__init__.py
+"""
+Agent definitions loader and registry.
+
+Carga definiciones de agentes desde archivos .md y las registra
+para uso del SubagentManager.
+"""
+from __future__ import annotations
+import re
+from pathlib import Path
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Any
+from enum import Enum
+
+
+class AgentCategory(Enum):
+    """Categorías de agentes."""
+    ARCHITECTURE = "architecture"
+    REVIEWERS = "reviewers"
+    BUILD_RESOLVERS = "build_resolvers"
+    SPECIALIZED = "specialized"
+
+
+@dataclass
+class AgentConfig:
+    """Configuración de un agente."""
+    name: str
+    description: str
+    model: str = "sonnet"
+    tools: List[str] = field(default_factory=list)
+    prompt_defense: str = ""
+    role: str = ""
+    responsibilities: List[str] = field(default_factory=list)
+    checklist: Dict[str, List[str]] = field(default_factory=dict)
+    patterns: Dict[str, Any] = field(default_factory=dict)
+    best_practices: List[str] = field(default_factory=list)
+    tools_list: List[str] = field(default_factory=list)
+    category: AgentCategory = AgentCategory.SPECIALIZED
+    raw_content: str = ""
+
+    def get_system_prompt(self) -> str:
+        """Genera el system prompt para este agente."""
+        parts = []
+
+        # Prompt defense
+        if self.prompt_defense:
+            parts.append("## Security Guidelines\n")
+            parts.append(self.prompt_defense)
+            parts.append("\n")
+
+        # Role
+        if self.role:
+            parts.append("## Role\n")
+            parts.append(self.role)
+            parts.append("\n")
+
+        # Responsibilities
+        if self.responsibilities:
+            parts.append("## Responsibilities\n")
+            for resp in self.responsibilities:
+                parts.append(f"- {resp}")
+            parts.append("\n")
+
+        # Checklist
+        if self.checklist:
+            parts.append("## Review Checklist\n")
+            for severity, items in self.checklist.items():
+                parts.append(f"\n### {severity.upper()}\n")
+                for item in items:
+                    parts.append(f"- {item}")
+            parts.append("\n")
+
+        # Best practices
+        if self.best_practices:
+            parts.append("## Best Practices\n")
+            for bp in self.best_practices:
+                parts.append(f"- {bp}")
+            parts.append("\n")
+
+        return "\n".join(parts)
+
+
+class AgentLoader:
+    """Cargador de definiciones de agentes."""
+
+    def __init__(self, agents_dir: Path = None):
+        self.agents_dir = agents_dir or Path(__file__).parent
+        self._agents: Dict[str, AgentConfig] = {}
+        self._loaded = False
+
+    def load_all(self, force: bool = False) -> Dict[str, AgentConfig]:
+        """Carga todos los agentes desde los archivos .md."""
+        if self._loaded and not force:
+            return self._agents
+
+        self._agents.clear()
+
+        # Cargar desde cada subdirectorio
+        for category in AgentCategory:
+            category_dir = self.agents_dir / category.value
+            if category_dir.exists():
+                for agent_file in category_dir.glob("*.md"):
+                    agent = self._load_agent(agent_file, category)
+                    if agent:
+                        self._agents[agent.name] = agent
+
+        self._loaded = True
+        return self._agents
+
+    def _load_agent(self, file_path: Path, category: AgentCategory) -> Optional[AgentConfig]:
+        """Carga un agente desde un archivo .md."""
+        try:
+            content = file_path.read_text(encoding="utf-8")
+
+            # Parsear frontmatter y contenido
+            config = self._parse_agent_file(content, category)
+            if config:
+                config.raw_content = content
+
+            return config
+        except Exception as e:
+            print(f"[AgentLoader] Error loading {file_path}: {e}")
+            return None
+
+    def _parse_agent_file(self, content: str, category: AgentCategory) -> Optional[AgentConfig]:
+        """Parsea el contenido de un archivo de agente."""
+        lines = content.split("\n")
+
+        # Extraer campos básicos
+        data = {
+            "name": "",
+            "description": "",
+            "model": "sonnet",
+            "tools": [],
+            "prompt_defense": "",
+            "role": "",
+            "category": category,
+        }
+
+        current_section = None
+        section_content = []
+
+        for line in lines:
+            # Detectar campos simples
+            if line.startswith("name:"):
+                data["name"] = line.split(":", 1)[1].strip()
+            elif line.startswith("description:"):
+                data["description"] = line.split(":", 1)[1].strip()
+            elif line.startswith("model:"):
+                data["model"] = line.split(":", 1)[1].strip()
+            elif line.startswith("tools:"):
+                # Lista de herramientas
+                pass  # Se procesa después
+            elif line.startswith("prompt_defense:"):
+                current_section = "prompt_defense"
+                section_content = []
+            elif line.startswith("role:"):
+                current_section = "role"
+                section_content = []
+            elif line.startswith("responsibilities:"):
+                current_section = "responsibilities"
+                section_content = []
+            elif line.startswith("checklist:"):
+                current_section = "checklist"
+                section_content = []
+            elif line.startswith("tools:"):
+                # Ignorar, se parsea después
+                pass
+            elif line.startswith("  - "):
+                # Item de lista
+                if current_section:
+                    section_content.append(line.strip("  - "))
+            elif line.strip() and current_section:
+                section_content.append(line)
+            elif not line.strip():
+                # Línea vacía, guardar sección
+                if current_section and section_content:
+                    data[current_section] = "\n".join(section_content)
+                    section_content = []
+
+        # Guardar última sección
+        if current_section and section_content:
+            data[current_section] = "\n".join(section_content)
+
+        # Parsear tools desde el contenido
+        tools_match = re.search(r"tools:\s*\n((?:  - .+\n)+)", content)
+        if tools_match:
+            tools_text = tools_match.group(1)
+            data["tools"] = [
+                t.strip("- ") for t in tools_text.strip().split("\n")
+                if t.strip().startswith("-")
+            ]
+
+        if not data["name"]:
+            return None
+
+        return AgentConfig(
+            name=data["name"],
+            description=data.get("description", ""),
+            model=data.get("model", "sonnet"),
+            tools=data.get("tools", []),
+            prompt_defense=data.get("prompt_defense", ""),
+            role=data.get("role", ""),
+            category=data.get("category", AgentCategory.SPECIALIZED),
+        )
+
+    def get_agent(self, name: str) -> Optional[AgentConfig]:
+        """Obtiene un agente por nombre."""
+        if not self._loaded:
+            self.load_all()
+        return self._agents.get(name)
+
+    def list_agents(self, category: AgentCategory = None) -> List[AgentConfig]:
+        """Lista todos los agentes, opcionalmente filtrados por categoría."""
+        if not self._loaded:
+            self.load_all()
+
+        agents = list(self._agents.values())
+        if category:
+            agents = [a for a in agents if a.category == category]
+        return agents
+
+    def get_agents_by_tool(self, tool: str) -> List[AgentConfig]:
+        """Obtiene agentes que tienen acceso a una herramienta específica."""
+        if not self._loaded:
+            self.load_all()
+
+        return [
+            agent for agent in self._agents.values()
+            if tool in agent.tools or not agent.tools  # Sin restricción de tools
+        ]
+
+
+# Instancia global
+_loader: Optional[AgentLoader] = None
+
+
+def get_agent_loader(agents_dir: Path = None) -> AgentLoader:
+    """Obtiene el cargador de agentes."""
+    global _loader
+    if _loader is None:
+        _loader = AgentLoader(agents_dir)
+    return _loader
+
+
+def get_agent(name: str) -> Optional[AgentConfig]:
+    """Obtiene un agente por nombre."""
+    return get_agent_loader().get_agent(name)
+
+
+def list_all_agents() -> List[AgentConfig]:
+    """Lista todos los agentes disponibles."""
+    return get_agent_loader().list_agents()

hanus/subagent/manager.py

@@ -0,0 +1,309 @@
+# hanus/subagent/manager.py
+"""
+Gestor de subagentes para delegar tareas complejas.
+"""
+from __future__ import annotations
+import uuid
+from pathlib import Path
+from typing import Dict, List, Optional, Any, Callable
+
+from hanus.subagent.types import (
+    SubagentType, SubagentConfig, SubagentResult,
+    SUBAGENT_TOOLS, SUBAGENT_SYSTEM_PROMPTS,
+    get_subagent_type, get_tools_for_type, get_prompt_for_type
+)
+from hanus.subagent.agents import get_agent_loader, AgentConfig
+
+import hanus.logger as log
+
+
+class SubagentManager:
+    """
+    Gestiona el ciclo de vida de subagentes.
+
+    Los subagentes son instancias especializadas del agente que pueden
+    ejecutarse en paralelo o en segundo plano para tareas complejas.
+
+    Uso:
+        manager = SubagentManager(connector, executor, session_mgr, perms, root_dir)
+
+        # Ejecutar subagente de exploración
+        result = manager.execute(SubagentConfig(
+            agent_type=SubagentType.EXPLORE,
+            task_description="Encuentra todos los endpoints de API",
+            context="El proyecto es una app Flask en src/",
+        ))
+    """
+
+    def __init__(
+        self,
+        connector,
+        tool_executor,
+        session_manager,
+        permission_manager,
+        root_dir: Path,
+        progress_callback: Optional[Callable[[str, str, Dict], None]] = None,
+        tool_callback: Optional[Callable[[str, Dict, str, bool], None]] = None,
+    ):
+        self.connector = connector
+        self.executor = tool_executor
+        self.session = session_manager
+        self.perms = permission_manager
+        self.root_dir = root_dir
+        self.progress_callback = progress_callback  # (agent_id, event, data)
+        self.tool_callback = tool_callback  # (tool_name, args, result, success)
+        self._active_agents: Dict[str, Dict] = {}
+
+    def _emit_progress(self, agent_id: str, event: str, data: Dict = None):
+        """Emite un evento de progreso."""
+        log.info(f"[Subagent {agent_id}] {event}: {data or {}}")
+        if self.progress_callback:
+            self.progress_callback(agent_id, event, data or {})
+
+    def spawn(self, config: SubagentConfig) -> str:
+        """
+        Crea un nuevo subagente.
+
+        Args:
+            config: Configuración del subagente
+
+        Returns:
+            ID del subagente creado
+        """
+        agent_id = str(uuid.uuid4())[:8]
+        self._active_agents[agent_id] = {
+            "config": config,
+            "status": "pending",
+            "created_at": __import__("time").time(),
+        }
+        return agent_id
+
+    def execute(self, config: SubagentConfig) -> SubagentResult:
+        """
+        Ejecuta un subagente inmediatamente.
+
+        Este es un método de conveniencia que combina spawn + run.
+
+        Args:
+            config: Configuración del subagente
+
+        Returns:
+            Resultado de la ejecución
+        """
+        agent_id = self.spawn(config)
+        return self.run(agent_id)
+
+    def run(self, agent_id: str) -> SubagentResult:
+        """
+        Ejecuta un subagente existente.
+
+        Args:
+            agent_id: ID del subagente a ejecutar
+
+        Returns:
+            Resultado de la ejecución
+        """
+        if agent_id not in self._active_agents:
+            return SubagentResult(
+                success=False,
+                error=f"Subagente {agent_id} no encontrado",
+                agent_id=agent_id,
+            )
+
+        agent_info = self._active_agents[agent_id]
+        config: SubagentConfig = agent_info["config"]
+        agent_info["status"] = "running"
+
+        # Emitir inicio
+        self._emit_progress(agent_id, "started", {
+            "type": config.agent_type.value,
+            "task": config.task_description[:100],
+        })
+
+        try:
+            # Crear motor de consultas para el subagente
+            from hanus.query_engine import QueryEngine
+
+            # Filtrar herramientas según tipo
+            allowed_tools = SUBAGENT_TOOLS.get(config.agent_type)
+
+            # Crear un executor con herramientas filtradas y callback
+            filtered_executor = self._create_filtered_executor(allowed_tools, agent_id)
+
+            # Crear callback de streaming para mostrar progreso
+            def stream_callback(text: str):
+                self._emit_progress(agent_id, "stream", {"text": text[:200]})
+
+            # Crear callback de herramientas
+            def tool_start_callback(tool_name: str, args: Dict):
+                self._emit_progress(agent_id, "tool_start", {
+                    "tool": tool_name,
+                    "args": {k: str(v)[:50] for k, v in args.items()},
+                })
+
+            def tool_end_callback(tool_name: str, result: str, success: bool):
+                self._emit_progress(agent_id, "tool_end", {
+                    "tool": tool_name,
+                    "success": success,
+                    "result_preview": result[:200] if result else "",
+                })
+
+            # Crear motor con callbacks
+            engine = QueryEngine(
+                connector=self.connector,
+                tool_executor=filtered_executor,
+                session_manager=self.session,
+                permission_manager=self.perms,
+                plugin_manager=None,  # Sin plugins para subagentes
+                stream_callback=stream_callback,
+                tool_start_callback=tool_start_callback,
+                tool_end_callback=tool_end_callback,
+                budget_usd=0,
+            )
+
+            # Establecer system prompt específico
+            system_prompt = SUBAGENT_SYSTEM_PROMPTS.get(
+                config.agent_type,
+                SUBAGENT_SYSTEM_PROMPTS[SubagentType.GENERAL]
+            )
+            engine.set_system_prompt(system_prompt)
+
+            # Construir mensaje de tarea
+            task_message = self._build_task_message(config)
+
+            self._emit_progress(agent_id, "executing", {"message": "Iniciando ejecución..."})
+
+            # Ejecutar
+            response = engine.send(task_message)
+
+            # Construir resultado
+            result = SubagentResult(
+                success=response.stop_reason not in ("error", "interrupted"),
+                output=response.text or "",
+                tokens_used=response.input_tokens + response.output_tokens,
+                cost_usd=response.cost_usd,
+                agent_id=agent_id,
+            )
+
+            agent_info["status"] = "completed"
+            agent_info["result"] = result
+
+            # Emitir finalización
+            self._emit_progress(agent_id, "completed", {
+                "success": result.success,
+                "tokens": result.tokens_used,
+                "output_preview": result.output[:500] if result.output else "",
+            })
+
+            return result
+
+        except Exception as e:
+            agent_info["status"] = "failed"
+            self._emit_progress(agent_id, "error", {"error": str(e)})
+            return SubagentResult(
+                success=False,
+                error=f"Error ejecutando subagente: {type(e).__name__}: {e}",
+                agent_id=agent_id,
+            )
+
+    def _create_filtered_executor(self, allowed_tools: Optional[List[str]], agent_id: str = None):
+        """
+        Crea un executor con herramientas filtradas y callbacks de progreso.
+
+        Args:
+            allowed_tools: Lista de herramientas permitidas, o None para todas
+            agent_id: ID del subagente para callbacks
+
+        Returns:
+            Executor filtrado
+        """
+        parent_manager = self
+
+        class FilteredExecutor:
+            def __init__(self, parent, allowed, aid):
+                self._parent = parent
+                self._allowed = set(allowed) if allowed else None  # None = todas
+                self._agent_id = aid
+                self.perms = parent.perms
+                self.tasks = parent.tasks if hasattr(parent, 'tasks') else None
+                self.memory = parent.memory if hasattr(parent, 'memory') else None
+                self.root = parent.root
+
+            def execute(self, tool_name: str, args: Dict) -> Any:
+                # Verificar si la herramienta está permitida
+                if self._allowed is not None and tool_name not in self._allowed:
+                    from hanus.tools import ToolResult
+                    return ToolResult.err(
+                        f"Herramienta '{tool_name}' no disponible para este subagente. "
+                        f"Permitidas: {list(self._allowed)}"
+                    )
+
+                # Emitir progreso de herramienta
+                if parent_manager and self._agent_id:
+                    parent_manager._emit_progress(self._agent_id, "tool_exec", {
+                        "tool": tool_name,
+                        "args_preview": str(args)[:100],
+                    })
+
+                return self._parent.execute(tool_name, args)
+
+        return FilteredExecutor(self.executor, allowed_tools, agent_id)
+
+    def _build_task_message(self, config: SubagentConfig) -> str:
+        """Construye el mensaje de tarea para el subagente."""
+        parts = [f"## Tarea\n\n{config.task_description}"]
+
+        if config.context:
+            parts.append(f"\n## Contexto\n\n{config.context}")
+
+        # Añadir instrucciones específicas según tipo
+        if config.agent_type == SubagentType.EXPLORE:
+            parts.append("\n## Instrucciones")
+            parts.append("- Explora el código de forma eficiente")
+            parts.append("- Proporciona rutas de archivo y números de línea")
+            parts.append("- Resume los hallazgos de forma clara")
+
+        elif config.agent_type == SubagentType.REVIEW:
+            parts.append("\n## Revisa")
+            parts.append("- Bugs y errores potenciales")
+            parts.append("- Problemas de seguridad")
+            parts.append("- Calidad del código")
+            parts.append("- Best practices")
+
+        elif config.agent_type == SubagentType.TEST:
+            parts.append("\n## Instrucciones")
+            parts.append("- Escribe tests comprehensivos")
+            parts.append("- Ejecuta los tests para verificar que pasan")
+            parts.append("- Reporta cualquier problema encontrado")
+
+        return "\n".join(parts)
+
+    def get_status(self, agent_id: str) -> Optional[Dict]:
+        """Obtiene el estado de un subagente."""
+        return self._active_agents.get(agent_id)
+
+    def list_active(self) -> List[Dict]:
+        """Lista todos los subagentes activos."""
+        return [
+            {"id": aid, **info}
+            for aid, info in self._active_agents.items()
+        ]
+
+    def cancel(self, agent_id: str) -> bool:
+        """Cancela un subagente en ejecución."""
+        if agent_id not in self._active_agents:
+            return False
+
+        agent_info = self._active_agents[agent_id]
+        if agent_info["status"] == "running":
+            agent_info["status"] = "cancelled"
+        return True
+
+    def cleanup(self):
+        """Limpia subagentes completados."""
+        to_remove = [
+            aid for aid, info in self._active_agents.items()
+            if info["status"] in ("completed", "failed", "cancelled")
+        ]
+        for aid in to_remove:
+            del self._active_agents[aid]