higpertext-cli 0.8.0__py3-none-any.whl

higpertext/hooks/hook_tasks/hook_context_manager.py

@@ -0,0 +1,44 @@
+"""Hook PreCompact — preserva estado higpertext crítico antes de compresión de contexto."""
+
+from __future__ import annotations
+from higpertext.hooks.hook_tasks._rules.context_rules import check_context_pressure
+from higpertext.hooks.hook_tasks.hook_utils import get_project_root
+import json
+import sys
+from pathlib import Path
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+_SRC = Path(__file__).resolve().parents[3]  # src/
+if str(_SRC) not in sys.path:
+    sys.path.insert(0, str(_SRC))
+
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+
+def main() -> None:
+    try:
+        root = get_project_root()
+        result = check_context_pressure(root)
+        if result.severity == "context":
+            print(
+                json.dumps(
+                    {
+                        "continue": True,
+                        "hookSpecificOutput": {
+                            "hookEventName": "PreCompact",
+                            "additionalContext": result.message,
+                        },
+                    }
+                )
+            )
+        else:
+            print(json.dumps({"continue": True}))
+    except Exception as exc:
+        print(json.dumps({"continue": True, "error": str(exc)}))
+
+
+if __name__ == "__main__":
+    main()

higpertext/hooks/hook_tasks/hook_io.py

@@ -0,0 +1,122 @@
+"""Protocolo I/O centralizado para hook tasks de higpertext.
+
+Single source of truth para:
+- Leer el payload de stdin (read_payload, read_tool_command)
+- Leer archivos JSON del disco (read_json_file)
+- Emitir respuestas JSON al runtime del asistente
+  (emit_continue, emit_context, emit_block, emit_stop_reason)
+- Whitelist cross-platform de comandos permitidos (WHITELIST)
+- Directorios de skills/subagentes por asistente (SKILL_DIRS, AGENT_DIRS)
+- Decorador @hook_main que envuelve cualquier main() con manejo de errores
+"""
+
+from __future__ import annotations
+from typing import Callable
+import functools
+import json
+import re
+import sys
+from pathlib import Path
+
+_SRC = Path(__file__).resolve().parents[3]  # src/
+if str(_SRC) not in sys.path:
+    sys.path.insert(0, str(_SRC))
+
+
+# Directorios efímeros de sesión por asistente — single source para todos los hooks
+SKILL_DIRS: dict[str, str] = {
+    "claude": ".claude/skills",
+    "gemini": ".gemini/skills",
+    "antigravity": ".agents/skills",
+    "opencode": ".opencode/skills",
+    "copilot": ".github/skills",
+}
+
+AGENT_DIRS: dict[str, str] = {
+    "claude": ".claude/subagents",
+    "gemini": ".gemini/subagents",
+    "antigravity": ".agents/subagents",
+    "opencode": ".opencode/subagents",
+    "copilot": ".github/subagents",
+}
+
+# Single source: permite htx.py directo o venv en Linux/Windows
+WHITELIST = re.compile(r"python htx\.py|\.venv[/\\](bin|Scripts)[/\\]python")
+
+
+def read_json_file(path: Path) -> dict:
+    """Lee y parsea un archivo JSON del disco. Retorna {} ante cualquier error."""
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def read_payload() -> dict:
+    """Lee y parsea el JSON de stdin. Retorna {} ante cualquier error."""
+    try:
+        return json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError, EOFError):
+        return {}
+
+
+def read_tool_command(payload: dict) -> str:
+    """Extrae el comando de tool_input, con fallback a CommandLine (PowerShell)."""
+    tool_input = payload.get("tool_input", {})
+    return tool_input.get("command") or tool_input.get("CommandLine") or ""
+
+
+def emit_continue(error: str = "") -> None:
+    """Emite continue:True, opcionalmente con campo error."""
+    out: dict = {"continue": True}
+    if error:
+        out["error"] = error
+    print(json.dumps(out))
+
+
+def emit_context(event: str, text: str) -> None:
+    """Emite continue:True con additionalContext (hook informativo)."""
+    print(
+        json.dumps(
+            {
+                "continue": True,
+                "hookSpecificOutput": {
+                    "hookEventName": event,
+                    "additionalContext": text,
+                },
+            }
+        )
+    )
+
+
+def emit_block(event: str, text: str) -> None:
+    """Emite continue:False bloqueando la herramienta (hard block)."""
+    print(
+        json.dumps(
+            {
+                "continue": False,
+                "hookSpecificOutput": {
+                    "hookEventName": event,
+                    "additionalContext": text,
+                },
+            }
+        )
+    )
+
+
+def emit_stop_reason(text: str) -> None:
+    """Emite continue:True con stopReason para el evento Stop."""
+    print(json.dumps({"continue": True, "stopReason": text}))
+
+
+def hook_main(fn: Callable) -> Callable:
+    """Decorador que envuelve main() capturando excepciones → emit_continue+error."""
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        try:
+            fn(*args, **kwargs)
+        except Exception as exc:
+            emit_continue(str(exc))
+
+    return wrapper

higpertext/hooks/hook_tasks/hook_loop_guard.py

@@ -0,0 +1,182 @@
+"""Hook PostToolUse + UserPromptSubmit — detección de bucle LLM en tiempo de ejecución.
+
+Detecta dos síntomas de repetition-collapse:
+
+1. **Repetición de tool_input** (PostToolUse): el agente invocó exactamente la misma
+   herramienta con exactamente los mismos parámetros N veces consecutivas sin éxito.
+   → emit_block al 3er intento idéntico.
+
+2. **Saturación de contexto** (PostToolUse): la respuesta de una herramienta supera
+   LARGE_OUTPUT_CHARS caracteres (dump masivo de error o archivo completo).
+   → emit_context con aviso al modelo para que no re-emita el blob.
+
+El estado de repetición se persiste en .higpertext/state/loop_guard.json dentro de la
+sesión activa, de modo que sobrevive entre turnos del mismo asistente.
+"""
+
+from __future__ import annotations
+import higpertext.hooks.hook_tasks.telemetry_utils as telem
+from higpertext.hooks.hook_tasks.hook_utils import get_project_root
+from higpertext.hooks.hook_tasks.hook_io import (
+    emit_block,
+    emit_context,
+    emit_continue,
+    hook_main,
+    read_json_file,
+)
+
+import hashlib
+import json
+import sys
+from pathlib import Path
+
+_SRC = Path(__file__).resolve().parents[3]  # src/
+if str(_SRC) not in sys.path:
+    sys.path.insert(0, str(_SRC))
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+from higpertext.kernel.app_config import IGNORE_TOOLS as _IGNORE_TOOLS
+from higpertext.kernel.infrastructure.logger import render_box
+
+MAX_IDENTICAL = 3
+LARGE_OUTPUT_CHARS = 8_000
+
+
+def _state_path(root: Path) -> Path:
+    return root / WORKSPACE_DIR_NAME / "state" / "loop_guard.json"
+
+
+def _load_state(root: Path) -> dict:
+    return read_json_file(_state_path(root))
+
+
+def _save_state(root: Path, state: dict) -> None:
+    try:
+        _state_path(root).write_text(
+            json.dumps(state, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+    except OSError:  # nosec B110
+        pass
+
+
+def _tool_fingerprint(tool_name: str, tool_input: dict) -> str:
+    """Hash determinista del par (herramienta, parámetros)."""
+    raw = json.dumps({"t": tool_name, "i": tool_input}, sort_keys=True, ensure_ascii=False)
+    return hashlib.sha1(raw.encode()).hexdigest()[:16]  # nosec B324
+
+
+def _session_id(root: Path) -> str:
+    try:
+        data = json.loads(
+            (root / WORKSPACE_DIR_NAME / "state" / "session.json").read_text(encoding="utf-8")
+        )
+        return data.get("session_id", "unknown")
+    except (OSError, json.JSONDecodeError):
+        return "unknown"
+
+
+def _handle_post_tool(root: Path, payload: dict) -> None:
+    tool_name = payload.get("tool_name", "")
+    tool_input = payload.get("tool_input", {}) or {}
+    tool_response = payload.get("tool_response", {}) or {}
+
+    if tool_name in _IGNORE_TOOLS:
+        emit_continue()
+        return
+
+    sid = _session_id(root)
+    state = _load_state(root)
+    fp = _tool_fingerprint(tool_name, tool_input)
+
+    # ── Check 1: Repetición de invocaciones idénticas ──────────────────────
+    last_fp = state.get("last_fp", "")
+    count = state.get("repeat_count", 0)
+
+    if fp == last_fp:
+        count += 1
+    else:
+        count = 1
+
+    state["last_fp"] = fp
+    state["repeat_count"] = count
+    state["last_tool"] = tool_name
+    _save_state(root, state)
+
+    if count >= MAX_IDENTICAL:
+        telem.record(
+            root,
+            "loop_guard_block",
+            session_id=sid,
+            tool=tool_name,
+            repeat_count=count,
+            fingerprint=fp,
+        )
+        state["repeat_count"] = 0
+        _save_state(root, state)
+        emit_block(
+            "PostToolUse",
+            render_box("HIGPERTEXT  ·  Loop Guard  ·  REPETICIÓN BLOQUEADA", [
+                f"│  Herramienta : {tool_name}",
+                f"│  Intentos    : {count} invocaciones idénticas consecutivas",
+                "│",
+                "│  El agente está en bucle. DEBES hacer UNA de estas acciones:",
+                "│    (a) Cambiar el enfoque — usa una capacidad higpertext diferente",
+                "│    (b) Preguntar al usuario qué archivo/comando confirmar",
+                "│    (c) Escribir [LOOP DETECTED] y detener la tarea",
+            ]),
+        )
+        return
+
+    # ── Check 2: Saturación de contexto por output masivo ──────────────────
+    output_str = json.dumps(tool_response, ensure_ascii=False)
+    if len(output_str) > LARGE_OUTPUT_CHARS:
+        telem.record(
+            root,
+            "loop_guard_large_output",
+            session_id=sid,
+            tool=tool_name,
+            output_chars=len(output_str),
+        )
+        emit_context(
+            "PostToolUse",
+            render_box("HIGPERTEXT  ·  Loop Guard  ·  OUTPUT MASIVO DETECTADO", [
+                f"│  Herramienta : {tool_name}",
+                f"│  Tamaño      : {len(output_str):,} caracteres",
+                "│",
+                "│  INSTRUCCIÓN ANTI-LOOP:",
+                "│    • NO re-emitas este contenido en tu respuesta.",
+                "│    • Referencia el archivo/resultado solo por nombre.",
+                "│    • Extrae ÚNICAMENTE la primera línea de error significativa.",
+                "│    • Si necesitas reprocesar este output, usa una capacidad",
+                "│      higpertext específica (common.grep-search, common.knowledge-asker).",
+            ]),
+        )
+        return
+
+    emit_continue()
+
+
+def _handle_user_prompt(root: Path) -> None:
+    """En cada nuevo prompt del usuario, reinicia el contador de repetición."""
+    state = _load_state(root)
+    if state.get("repeat_count", 0) > 0:
+        state["repeat_count"] = 0
+        state["last_fp"] = ""
+        _save_state(root, state)
+    emit_continue()
+
+
+@hook_main
+def main() -> None:
+    payload = json.load(sys.stdin)
+    root = get_project_root()
+
+    # El hook se registra para PostToolUse y UserPromptSubmit.
+    # Distinguimos por la presencia de tool_name.
+    if "tool_name" in payload:
+        _handle_post_tool(root, payload)
+    else:
+        _handle_user_prompt(root)
+
+
+if __name__ == "__main__":
+    main()

higpertext/hooks/hook_tasks/hook_post_observer.py

@@ -0,0 +1,54 @@
+"""Hook PostToolUse — registra telemetría de tokens y actividad por tool call."""
+
+from __future__ import annotations
+from higpertext.hooks.hook_tasks._rules.context_rules import (
+    check_large_output,
+    check_window_pressure,
+)
+from higpertext.hooks.hook_tasks._rules.telemetry_rules import record_telemetry
+from higpertext.hooks.hook_tasks.hook_utils import get_project_root
+import json
+import sys
+from pathlib import Path
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+_SRC = Path(__file__).resolve().parents[3]  # src/
+if str(_SRC) not in sys.path:
+    sys.path.insert(0, str(_SRC))
+
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+
+def main() -> None:
+    try:
+        payload = json.load(sys.stdin)
+        root = get_project_root()
+        record_telemetry(payload, root)
+
+        large = check_large_output(payload)
+        pressure = check_window_pressure(payload, root)
+
+        extra_parts = [r.message for r in (large, pressure) if r is not None]
+        if extra_parts:
+            print(
+                json.dumps(
+                    {
+                        "continue": True,
+                        "hookSpecificOutput": {
+                            "hookEventName": "PostToolUse",
+                            "additionalContext": "\n".join(extra_parts),
+                        },
+                    }
+                )
+            )
+        else:
+            print(json.dumps({"continue": True}))
+    except Exception as exc:
+        print(json.dumps({"continue": True, "error": str(exc)}))
+
+
+if __name__ == "__main__":
+    main()

higpertext/hooks/hook_tasks/hook_read_guard.py

@@ -0,0 +1,85 @@
+"""Hook PreToolUse:Read — bloquea lecturas completas de archivos grandes."""
+
+from __future__ import annotations
+from higpertext.hooks.hook_tasks.hook_utils import get_project_root
+from higpertext.hooks.hook_tasks.hook_io import (
+    hook_main,
+    read_payload,
+    emit_continue,
+    emit_block,
+)
+
+import os
+import sys
+from pathlib import Path
+
+_SRC = Path(__file__).resolve().parents[3]
+if str(_SRC) not in sys.path:
+    sys.path.insert(0, str(_SRC))
+
+
+def _threshold_bytes() -> int:
+    try:
+        return int(os.environ.get("HIGPERTEXT_READ_GUARD_BYTES", str(100 * 1024)))
+    except ValueError:
+        return 100 * 1024
+
+
+def _extract_path(tool_input: dict) -> str:
+    return (
+        tool_input.get("filePath")
+        or tool_input.get("filepath")
+        or tool_input.get("path")
+        or tool_input.get("file")
+        or ""
+    )
+
+
+def _has_range(tool_input: dict) -> bool:
+    return any(
+        key in tool_input and tool_input.get(key) not in (None, "") for key in ("offset", "limit")
+    )
+
+
+def evaluate_read_guard(tool_input: dict, root: Path) -> str:
+    """Devuelve mensaje de bloqueo o cadena vacía si la lectura es segura."""
+    raw_path = _extract_path(tool_input)
+    if not raw_path or _has_range(tool_input):
+        return ""
+    path = Path(raw_path)
+    if not path.is_absolute():
+        path = root / path
+    if not path.exists() or not path.is_file():
+        return ""
+    threshold = _threshold_bytes()
+    size = path.stat().st_size
+    if size <= threshold:
+        return ""
+    display = raw_path
+    return "\n".join(
+        [
+            "╔─ HIGPERTEXT  ·  Bloqueo de Read masivo ───────────────────",
+            f"│  Archivo : {display} ({size / 1024:.1f} KB)",
+            f"│  Límite  : {threshold / 1024:.1f} KB",
+            "│  ⚠  Evita leer el archivo completo para no saturar contexto.",
+            "│  → Usa lectura inteligente:",
+            f"│    htx task common.smart-read --path {display} --mode auto",
+            "│  → O inspecciona firmas:",
+            f"│    htx task common.code-skeletonizer --path {display}",
+            "╚────────────────────────────────────────────────────────────",
+        ]
+    )
+
+
+@hook_main
+def main() -> None:
+    payload = read_payload()
+    message = evaluate_read_guard(payload.get("tool_input", {}), get_project_root())
+    if message:
+        emit_block("PreToolUse", message)
+        return
+    emit_continue()
+
+
+if __name__ == "__main__":
+    main()

higpertext/hooks/hook_tasks/hook_security_guard.py

@@ -0,0 +1,81 @@
+"""Hook común de seguridad para PreToolUse y PostToolUse."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+_SRC = Path(__file__).resolve().parents[3]
+if str(_SRC) not in sys.path:
+    sys.path.insert(0, str(_SRC))
+
+from higpertext.hooks.hook_tasks.hook_io import (  # noqa: E402
+    hook_main,
+    read_payload,
+    read_tool_command,
+    emit_block,
+    emit_context,
+    emit_continue,
+)
+from higpertext.hooks.hook_tasks.hook_utils import get_project_root  # noqa: E402
+from higpertext.hooks.hook_tasks._rules.security_rules import (  # noqa: E402
+    evaluate_command_guard,
+    evaluate_path_guard,
+    mask_tool_output,
+)
+from higpertext.kernel.infrastructure.logger import get_logger
+
+_log = get_logger()
+
+
+def _tool_name(payload: dict) -> str:
+    return str(payload.get("tool_name") or payload.get("tool") or "")
+
+
+def _emit_masked_output(message: str, replacement_output: str) -> None:
+    print(
+        json.dumps(
+            {
+                "continue": True,
+                "hookSpecificOutput": {
+                    "hookEventName": "PostToolUse",
+                    "additionalContext": message,
+                    "replacementOutput": replacement_output,
+                },
+            }
+        )
+    )
+
+
+@hook_main
+def main() -> None:
+    payload = read_payload()
+    event = payload.get("event", "PreToolUse")
+    tool_name = _tool_name(payload)
+    root = get_project_root()
+
+    if event == "PreToolUse":
+        if tool_name in {"Bash", "PowerShell"}:
+            result = evaluate_command_guard(read_tool_command(payload), root)
+        else:
+            result = evaluate_path_guard(tool_name, payload.get("tool_input", {}))
+        if result:
+            if result.severity == "warn":
+                emit_context("PreToolUse", result.message)
+                return
+            emit_block("PreToolUse", result.message)
+            return
+        emit_continue()
+        return
+
+    if event == "PostToolUse":
+        result = mask_tool_output(payload.get("tool_response", {}), root)
+        if result:
+            _emit_masked_output(result.message, result.replacement_output)
+            return
+    emit_continue()
+
+
+if __name__ == "__main__":
+    main()

higpertext/hooks/hook_tasks/hook_session_prompt.py

@@ -0,0 +1,83 @@
+"""Hook UserPromptSubmit — inyecta estado de sesión y contexto de skills activas."""
+
+from __future__ import annotations
+from higpertext.hooks.hook_tasks._rules.context_engine_rule import inject_context_pack
+from higpertext.hooks.hook_tasks._rules.session_rules import (
+    auto_start_session,
+    reset_window_accumulator,
+    inject_session_status,
+    inject_skills_context,
+    handle_compact_command,
+)
+from higpertext.hooks.hook_tasks.hook_io import read_payload
+from higpertext.hooks.hook_tasks.hook_utils import get_project_root
+import json
+import sys
+from pathlib import Path
+
+_SRC = Path(__file__).resolve().parents[3]  # src/
+if str(_SRC) not in sys.path:
+    sys.path.insert(0, str(_SRC))
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+def _emit_hook_context(message: str) -> None:
+    print(
+        json.dumps(
+            {
+                "continue": True,
+                "hookSpecificOutput": {
+                    "hookEventName": "UserPromptSubmit",
+                    "additionalContext": message,
+                },
+            }
+        )
+    )
+
+
+def _handle_slash_commands(root: Path, prompt: str) -> bool:
+    if prompt == "/compact" or prompt.startswith("/compact "):
+        _emit_hook_context(handle_compact_command(root).message)
+        return True
+    return False
+
+
+def _ensure_active_session(root: Path) -> None:
+    session_file = root / WORKSPACE_DIR_NAME / "state" / "session.json"
+    session = json.loads(session_file.read_text(encoding="utf-8")) if session_file.exists() else {}
+    if session.get("status") != "active":
+        auto_start_session(root)
+
+
+def _build_context(root: Path, prompt: str) -> str:
+    reset_window_accumulator(root)
+    parts = [inject_session_status(root).message]
+    ctx = inject_skills_context(root)
+    if ctx and ctx.message:
+        parts.append(ctx.message)
+    pack = inject_context_pack(root, prompt)
+    if pack and pack.message:
+        parts.append(pack.message)
+    return "\n".join(parts)
+
+
+def main() -> None:
+    try:
+        root = get_project_root()
+        payload = read_payload()
+        prompt = (payload.get("prompt", "") or payload.get("user_prompt", "") or "").strip().lower()
+
+        if _handle_slash_commands(root, prompt):
+            return
+
+        _ensure_active_session(root)
+        _emit_hook_context(_build_context(root, prompt))
+    except Exception as exc:
+        print(json.dumps({"continue": True, "error": str(exc)}))
+
+
+if __name__ == "__main__":
+    main()