hanuscode 1.0.0__py3-none-any.whl

hanus/permissions.py

@@ -0,0 +1,182 @@
+# permissions.py
+"""
+Sistema de permisos: default, plan, bypass.
+Gestiona aprobaciones, denegaciones, auditoría y detección de loops.
+"""
+from __future__ import annotations
+import time
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Dict, List, Optional, Callable
+
+
+class PermissionMode(Enum):
+    DEFAULT = "default"   # Pide confirmación para acciones peligrosas
+    PLAN    = "plan"      # Aprueba el plan; ejecuta automáticamente
+    BYPASS  = "bypass"    # Sin restricciones (todo auto, excepto comandos absolutamente destructivos)
+
+
+class RiskLevel(Enum):
+    LOW    = "low"
+    MEDIUM = "medium"
+    HIGH   = "high"
+
+
+# ── Clasificación de riesgo por herramienta ───────────────────────────────────
+TOOL_RISK: Dict[str, RiskLevel] = {
+    "read_file":        RiskLevel.LOW,
+    "glob_search":      RiskLevel.LOW,
+    "grep_search":      RiskLevel.LOW,
+    "web_fetch":        RiskLevel.LOW,
+    "web_search":       RiskLevel.LOW,
+    "list_files":       RiskLevel.LOW,
+    "git_status":       RiskLevel.LOW,
+    "git_diff":         RiskLevel.LOW,
+    "append_to_file":   RiskLevel.LOW,
+    "create_file":      RiskLevel.MEDIUM,
+    "file_edit":        RiskLevel.MEDIUM,
+    "exec_file":        RiskLevel.MEDIUM,
+    "exec_cmd":         RiskLevel.MEDIUM,
+    "write_file":       RiskLevel.HIGH,
+    "git_push":         RiskLevel.HIGH,
+    "git_reset":        RiskLevel.HIGH,
+    "subagent":         RiskLevel.HIGH,
+}
+
+# ── Patrones absolutamente prohibidos (bloqueo siempre, incluso en BYPASS) ───
+ALWAYS_BLOCK = [
+    "rm -rf /", "rm -rf ~", "dd if=/dev/zero", "mkfs",
+    "format c:", ":(){:|:&};:", "shutdown -h now", "reboot",
+    "chmod 777 /", "chown -R root /",
+]
+
+# ── Patrones siempre seguros (auto-aprobados) ─────────────────────────────────
+ALWAYS_ALLOW_CMDS = [
+    "echo", "cat ", "ls", "pwd", "whoami", "date", "uname",
+    "python --version", "python3 --version", "pip list",
+    "git status", "git log", "git diff", "git branch",
+    "pytest", "python -m pytest",
+]
+
+
+@dataclass
+class PermissionDecision:
+    approved: bool
+    reason: str = ""
+    remember: bool = False   # "Aprobar siempre" en esta sesión
+
+
+@dataclass
+class DenialTracker:
+    counts: Dict[str, List[float]] = field(default_factory=dict)
+    WINDOW = 600    # 10 minutos
+    LIMIT  = 3      # máximo rechazos antes de poner en reposo
+
+    def record(self, tool: str):
+        now = time.time()
+        self.counts.setdefault(tool, []).append(now)
+        self.counts[tool] = [t for t in self.counts[tool] if now - t < self.WINDOW]
+
+    def in_reposo(self, tool: str) -> bool:
+        return len(self.counts.get(tool, [])) >= self.LIMIT
+
+
+class PermissionManager:
+    """Evalúa permisos para cada acción y gestiona auditoría."""
+
+    def __init__(self, mode: PermissionMode = PermissionMode.DEFAULT):
+        self.mode = mode
+        self._session_allows: Dict[str, bool] = {}
+        self._denial_tracker = DenialTracker()
+        self._audit: List[Dict] = []
+        self._ask_fn: Optional[Callable] = None   # callback de UI
+
+    def set_ask_callback(self, fn: Callable):
+        self._ask_fn = fn
+
+    def set_mode(self, mode: PermissionMode):
+        self.mode = mode
+
+    def check(self, tool: str, description: str, args: Optional[Dict] = None) -> PermissionDecision:
+        args = args or {}
+
+        # ── Bloqueo absoluto siempre ──────────────────────────────────────────
+        if self._is_blocked(tool, args):
+            d = PermissionDecision(False, "⛔ Patrón peligroso bloqueado siempre")
+            self._log(tool, args, False, d.reason)
+            return d
+
+        # ── BYPASS: todo aprobado ─────────────────────────────────────────────
+        if self.mode == PermissionMode.BYPASS:
+            self._log(tool, args, True, "Modo BYPASS")
+            return PermissionDecision(True, "Modo BYPASS")
+
+        # ── PLAN: aprobado automáticamente ───────────────────────────────────
+        if self.mode == PermissionMode.PLAN:
+            self._log(tool, args, True, "Modo PLAN")
+            return PermissionDecision(True, "Modo PLAN")
+
+        # ── DEFAULT ───────────────────────────────────────────────────────────
+        risk = TOOL_RISK.get(tool, RiskLevel.MEDIUM)
+
+        # Bajo riesgo → siempre aprobado
+        if risk == RiskLevel.LOW:
+            self._log(tool, args, True, "Bajo riesgo")
+            return PermissionDecision(True, "Bajo riesgo")
+
+        # Ya aprobado en sesión
+        if tool in self._session_allows:
+            return PermissionDecision(True, "Aprobado en sesión")
+
+        # Loop de rechazos
+        if self._denial_tracker.in_reposo(tool):
+            d = PermissionDecision(
+                False,
+                f"'{tool}' pausada ({DenialTracker.LIMIT} rechazos recientes — usa /mode bypass si confías)"
+            )
+            self._log(tool, args, False, d.reason)
+            return d
+
+        # Comando conocido como seguro
+        cmd = str(args.get("cmd", "") or args.get("command", ""))
+        for safe in ALWAYS_ALLOW_CMDS:
+            if cmd.startswith(safe):
+                self._log(tool, args, True, "Patrón seguro")
+                return PermissionDecision(True, "Patrón seguro conocido")
+
+        # Pedir al usuario
+        if self._ask_fn:
+            decision = self._ask_fn(tool, description, risk, args)
+            if not decision.approved:
+                self._denial_tracker.record(tool)
+            if decision.approved and decision.remember:
+                self._session_allows[tool] = True
+            self._log(tool, args, decision.approved, decision.reason)
+            return decision
+
+        # Sin callback → aprobado por defecto
+        self._log(tool, args, True, "Sin callback de UI")
+        return PermissionDecision(True, "Auto-aprobado")
+
+    # ── Helpers ───────────────────────────────────────────────────────────────
+
+    def _is_blocked(self, tool: str, args: Dict) -> bool:
+        cmd = str(args.get("cmd", "") or args.get("command", "")).lower()
+        return any(p in cmd for p in ALWAYS_BLOCK)
+
+    def _log(self, tool: str, args: Dict, approved: bool, reason: str):
+        self._audit.append({
+            "ts": time.time(),
+            "tool": tool,
+            "args_preview": str(args)[:120],
+            "approved": approved,
+            "reason": reason,
+        })
+
+    def get_audit(self) -> List[Dict]:
+        return list(self._audit)
+
+    def export_audit(self, path: Path):
+        path.write_text(json.dumps(self._audit, indent=2, ensure_ascii=False), encoding="utf-8")

hanus/plan/__init__.py

@@ -0,0 +1,8 @@
+# hanus/plan/__init__.py
+"""
+Sistema de planificación pre-ejecución.
+"""
+from hanus.plan.models import Plan, PlanStep, PlanStatus, StepStatus
+from hanus.plan.mode import PlanMode
+
+__all__ = ["Plan", "PlanStep", "PlanStatus", "StepStatus", "PlanMode"]

hanus/plan/mode.py

@@ -0,0 +1,267 @@
+# hanus/plan/mode.py
+"""
+Sistema de modo planificación.
+"""
+from __future__ import annotations
+import json
+import uuid
+from pathlib import Path
+from typing import Dict, List, Optional, Callable, Any
+
+from hanus.plan.models import Plan, PlanStep, PlanStatus, StepStatus
+
+
+class PlanMode:
+    """
+    Gestiona el modo de planificación.
+
+    En este modo, el agente solo puede usar herramientas de lectura
+    y debe crear un plan antes de ejecutar cualquier modificación.
+
+    Uso:
+        plan_mode = PlanMode(root_dir)
+
+        # Entrar en modo plan
+        plan_mode.enter("Implementar sistema de autenticación")
+        # ... el agente trabaja en el plan ...
+
+        # Aprobar y ejecutar
+        if user_approves:
+            plan_mode.approve(plan_id)
+            for step in plan.get_steps():
+                # ejecutar cada paso
+    """
+
+    # Herramientas permitidas en modo plan
+    PLAN_TOOLS = {
+        "read_file", "list_files", "glob_search", "grep_search",
+        "git_status", "git_diff", "git_log", "web_fetch", "web_search",
+        "plan_add_step", "plan_update_step", "plan_list", "plan_get",
+    }
+
+    def __init__(self, root_dir: Path, ask_callback: Optional[Callable] = None):
+        self.root_dir = root_dir
+        self.ask = ask_callback
+        self._plans: Dict[str, Plan] = {}
+        self._active_plan: Optional[str] = None
+        self._in_plan_mode = False
+        self._plan_file = root_dir / ".hanus" / "plans.json"
+        self._load_plans()
+
+    def _load_plans(self):
+        """Carga planes desde disco."""
+        if not self._plan_file.exists():
+            return
+        try:
+            data = json.loads(self._plan_file.read_text(encoding="utf-8"))
+            for pid, pdata in data.get("plans", {}).items():
+                self._plans[pid] = Plan.from_dict(pdata)
+        except Exception:
+            pass
+
+    def _save_plans(self):
+        """Guarda planes a disco."""
+        self._plan_file.parent.mkdir(parents=True, exist_ok=True)
+        data = {
+            "plans": {pid: p.to_dict() for pid, p in self._plans.items()},
+            "active": self._active_plan,
+        }
+        self._plan_file.write_text(
+            json.dumps(data, indent=2, ensure_ascii=False),
+            encoding="utf-8"
+        )
+
+    # ─── Estado ────────────────────────────────────────────────────────────────
+
+    def is_active(self) -> bool:
+        """Retorna True si estamos en modo planificación."""
+        return self._in_plan_mode
+
+    def get_active_plan(self) -> Optional[Plan]:
+        """Obtiene el plan activo."""
+        if self._active_plan:
+            return self._plans.get(self._active_plan)
+        return None
+
+    def is_tool_allowed(self, tool_name: str) -> bool:
+        """Verifica si una herramienta está permitida en modo plan."""
+        if not self._in_plan_mode:
+            return True
+        return tool_name in self.PLAN_TOOLS
+
+    # ─── Operaciones ───────────────────────────────────────────────────────────
+
+    def enter(self, description: str = "") -> str:
+        """
+        Entra en modo planificación.
+
+        Args:
+            description: Descripción de lo que se va a planificar
+
+        Returns:
+            ID del plan creado
+        """
+        plan_id = str(uuid.uuid4())[:8]
+        plan = Plan(
+            id=plan_id,
+            title=f"Plan #{plan_id}",
+            description=description,
+        )
+        self._plans[plan_id] = plan
+        self._active_plan = plan_id
+        self._in_plan_mode = True
+        self._save_plans()
+        return plan_id
+
+    def exit(self) -> Optional[Plan]:
+        """
+        Sale del modo planificación sin aprobar.
+
+        Returns:
+            El plan activo o None si no había
+        """
+        plan = self.get_active_plan()
+        self._in_plan_mode = False
+        self._active_plan = None
+        self._save_plans()
+        return plan
+
+    def approve(self, plan_id: Optional[str] = None) -> bool:
+        """
+        Aprueba un plan para ejecución.
+
+        Args:
+            plan_id: ID del plan, o None para el activo
+
+        Returns:
+            True si se aprobó exitosamente
+        """
+        pid = plan_id or self._active_plan
+        if not pid or pid not in self._plans:
+            return False
+
+        plan = self._plans[pid]
+        plan.status = PlanStatus.APPROVED
+        self._in_plan_mode = False
+        self._save_plans()
+        return True
+
+    def reject(self, plan_id: Optional[str] = None) -> bool:
+        """
+        Rechaza un plan.
+
+        Args:
+            plan_id: ID del plan, o None para el activo
+        """
+        pid = plan_id or self._active_plan
+        if not pid or pid not in self._plans:
+            return False
+
+        del self._plans[pid]
+        if self._active_plan == pid:
+            self._active_plan = None
+            self._in_plan_mode = False
+        self._save_plans()
+        return True
+
+    # ─── Manipulación de planes ────────────────────────────────────────────────
+
+    def create_plan(self, title: str, description: str = "") -> Plan:
+        """Crea un nuevo plan y lo establece como activo."""
+        plan_id = str(uuid.uuid4())[:8]
+        plan = Plan(
+            id=plan_id,
+            title=title if title else f"Plan #{plan_id}",
+            description=description,
+        )
+        self._plans[plan_id] = plan
+        self._active_plan = plan_id  # Establecer como activo
+        self._save_plans()
+        return plan
+
+    def add_step(self, plan_id: Optional[str], description: str) -> Optional[PlanStep]:
+        """Añade un paso a un plan."""
+        pid = plan_id or self._active_plan
+        if not pid or pid not in self._plans:
+            return None
+        step = self._plans[pid].add_step(description)
+        self._save_plans()
+        return step
+
+    def update_step(
+        self,
+        plan_id: Optional[str],
+        step_id: int,
+        status: Optional[StepStatus] = None,
+        notes: Optional[str] = None,
+    ) -> bool:
+        """Actualiza un paso del plan."""
+        pid = plan_id or self._active_plan
+        if not pid or pid not in self._plans:
+            return False
+        plan = self._plans[pid]
+        if status:
+            plan.mark_step(step_id, status, notes or "")
+        self._save_plans()
+        return True
+
+    def get_plan(self, plan_id: str) -> Optional[Plan]:
+        """Obtiene un plan por ID."""
+        return self._plans.get(plan_id)
+
+    def list_plans(self, status: Optional[PlanStatus] = None) -> List[Plan]:
+        """Lista planes, opcionalmente filtrados por estado."""
+        plans = list(self._plans.values())
+        if status:
+            plans = [p for p in plans if p.status == status]
+        return sorted(plans, key=lambda p: p.created_at, reverse=True)
+
+    def delete_plan(self, plan_id: str) -> bool:
+        """Elimina un plan."""
+        if plan_id in self._plans:
+            del self._plans[plan_id]
+            if self._active_plan == plan_id:
+                self._active_plan = None
+                self._in_plan_mode = False
+            self._save_plans()
+            return True
+        return False
+
+    def clear_completed(self):
+        """Elimina planes completados."""
+        to_remove = [
+            pid for pid, p in self._plans.items()
+            if p.status in (PlanStatus.COMPLETED, PlanStatus.FAILED)
+        ]
+        for pid in to_remove:
+            del self._plans[pid]
+        self._save_plans()
+
+    # ─── Interacción con usuario ────────────────────────────────────────────────
+
+    def request_approval(self, plan: Plan) -> bool:
+        """
+        Solicita aprobación del usuario para un plan.
+
+        Returns:
+            True si el usuario aprobó
+        """
+        if not self.ask:
+            return False
+
+        print()
+        print(plan.to_markdown())
+        print()
+
+        response = self.ask("¿Aprobar este plan? [S/n/e(ditar)] ")
+        if not response:
+            return True  # Default: aprobar
+        r = response.lower().strip()
+        if r in ("s", "si", "sí", "y", "yes", ""):
+            return True
+        if r in ("n", "no"):
+            return False
+        if r in ("e", "editar", "edit"):
+            # TODO: permitir edición interactiva
+            return False
+        return True

hanus/plan/models.py

@@ -0,0 +1,152 @@
+# hanus/plan/models.py
+"""
+Modelos de datos para el sistema de planificación.
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import List, Dict, Any, Optional
+from enum import Enum
+
+
+class PlanStatus(Enum):
+    """Estados de un plan."""
+    DRAFT = "draft"         # En desarrollo
+    APPROVED = "approved"   # Aprobado por usuario
+    EXECUTING = "executing" # En ejecución
+    COMPLETED = "completed" # Completado
+    FAILED = "failed"       # Falló
+
+
+class StepStatus(Enum):
+    """Estados de un paso del plan."""
+    PENDING = "pending"
+    IN_PROGRESS = "in_progress"
+    COMPLETED = "completed"
+    SKIPPED = "skipped"
+    FAILED = "failed"
+
+
+@dataclass
+class PlanStep:
+    """Un paso individual en un plan."""
+    id: int
+    description: str
+    status: StepStatus = StepStatus.PENDING
+    notes: str = ""
+    files_modified: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "description": self.description,
+            "status": self.status.value,
+            "notes": self.notes,
+            "files_modified": self.files_modified,
+        }
+
+    @classmethod
+    def from_dict(cls, d: Dict) -> PlanStep:
+        return cls(
+            id=d["id"],
+            description=d["description"],
+            status=StepStatus(d.get("status", "pending")),
+            notes=d.get("notes", ""),
+            files_modified=d.get("files_modified", []),
+        )
+
+
+@dataclass
+class Plan:
+    """Un plan de implementación completo."""
+    id: str
+    title: str
+    description: str
+    steps: List[PlanStep] = field(default_factory=list)
+    status: PlanStatus = PlanStatus.DRAFT
+    created_at: float = field(default_factory=lambda: __import__("time").time())
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def add_step(self, description: str) -> PlanStep:
+        """Añade un nuevo paso al plan."""
+        step_id = len(self.steps) + 1
+        step = PlanStep(id=step_id, description=description)
+        self.steps.append(step)
+        return step
+
+    def get_step(self, step_id: int) -> Optional[PlanStep]:
+        """Obtiene un paso por su ID."""
+        for step in self.steps:
+            if step.id == step_id:
+                return step
+        return None
+
+    def mark_step(self, step_id: int, status: StepStatus, notes: str = "") -> bool:
+        """Actualiza el estado de un paso."""
+        step = self.get_step(step_id)
+        if step:
+            step.status = status
+            if notes:
+                step.notes = notes
+            return True
+        return False
+
+    def current_step(self) -> Optional[PlanStep]:
+        """Obtiene el paso actual (primer pending o in_progress)."""
+        for step in self.steps:
+            if step.status in (StepStatus.PENDING, StepStatus.IN_PROGRESS):
+                return step
+        return None
+
+    def progress(self) -> tuple:
+        """Retorna (completados, total)."""
+        completed = sum(1 for s in self.steps if s.status == StepStatus.COMPLETED)
+        return completed, len(self.steps)
+
+    def is_complete(self) -> bool:
+        """Verifica si todos los pasos están completados o saltados."""
+        return all(
+            s.status in (StepStatus.COMPLETED, StepStatus.SKIPPED)
+            for s in self.steps
+        )
+
+    def to_markdown(self) -> str:
+        """Convierte el plan a formato markdown."""
+        lines = [f"# Plan: {self.title}", "", f"{self.description}", ""]
+        for step in self.steps:
+            icon = {
+                StepStatus.PENDING: "⏳",
+                StepStatus.IN_PROGRESS: "🔄",
+                StepStatus.COMPLETED: "✅",
+                StepStatus.SKIPPED: "⏭️",
+                StepStatus.FAILED: "❌",
+            }.get(step.status, "⏳")
+            lines.append(f"{icon} **{step.id}.** {step.description}")
+            if step.notes:
+                lines.append(f"   _{step.notes}_")
+        completed, total = self.progress()
+        lines.append("")
+        lines.append(f"_Progreso: {completed}/{total} pasos_")
+        return "\n".join(lines)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "description": self.description,
+            "steps": [s.to_dict() for s in self.steps],
+            "status": self.status.value,
+            "created_at": self.created_at,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, d: Dict) -> Plan:
+        return cls(
+            id=d["id"],
+            title=d["title"],
+            description=d["description"],
+            steps=[PlanStep.from_dict(s) for s in d.get("steps", [])],
+            status=PlanStatus(d.get("status", "draft")),
+            created_at=d.get("created_at", 0),
+            metadata=d.get("metadata", {}),
+        )