higpertext-cli 0.8.0__py3-none-any.whl

higpertext/hooks/hook_tasks/hook_session_stop.py

@@ -0,0 +1,115 @@
+"""Hook Stop — cierra sesión automáticamente y muestra resumen de turno."""
+
+from __future__ import annotations
+from higpertext.hooks.hook_tasks._rules.governance_adapter import get_session_limits
+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 (
+    hook_main,
+    read_json_file,
+    emit_stop_reason,
+)
+import sys
+import subprocess  # nosec B404
+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
+
+
+def _pending(root: Path) -> tuple[list[str], int, bool]:
+    try:
+        r = subprocess.run(  # nosec B603 B607
+            ["git", "status", "--porcelain"],
+            capture_output=True,
+            text=True,
+            cwd=str(root),
+            timeout=10,
+        )
+        lines = [line[3:] for line in r.stdout.strip().splitlines() if line.strip()]
+        limit = get_session_limits(root)
+        return lines, limit, len(lines) > limit
+    except (OSError, subprocess.TimeoutExpired):
+        return [], 5, False
+
+
+def _last_commit(root: Path) -> str:
+    try:
+        r = subprocess.run(  # nosec B603 B607
+            ["git", "log", "--oneline", "-1"],
+            capture_output=True,
+            text=True,
+            cwd=str(root),
+            timeout=5,
+        )
+        return r.stdout.strip()
+    except (OSError, subprocess.TimeoutExpired):
+        return "—"
+
+
+def _clean_session(root: Path) -> bool:
+    """Ejecuta session-clean y devuelve True si tuvo éxito."""
+    from higpertext.hooks.hook_tasks.hook_utils import get_htx
+
+    try:
+        r = subprocess.run(  # nosec B603
+            [get_htx(root), "task", "common.session-clean", "--action", "clean"],
+            capture_output=True,
+            text=True,
+            cwd=str(root),
+            timeout=20,
+        )
+        return r.returncode == 0
+    except Exception:
+        return False
+
+
+def _build_banner(
+    files: list[str],
+    limit: int,
+    exceeded: bool,
+    commit: str,
+    active: bool,
+    sid: str,
+    profile: str,
+) -> str:
+    lines = ["╔─ HIGPERTEXT  ·  Fin de turno ──────────────────────────────"]
+    if files:
+        indicator = "❌ [GOBERNANZA]" if exceeded else "⚠"
+        lines.append(f"│  {indicator}  {len(files)} archivo(s) sin commitear (Límite: {limit}):")
+        for f in files[:8]:
+            lines.append(f"│     • {f}")
+        if len(files) > 8:
+            lines.append(f"│     ... y {len(files) - 8} más")
+        lines.append('│  → committer --message "tipo(scope): descripción"')
+    else:
+        lines.append(f"│  ✓  Working tree limpio  ·  {commit}")
+    if active:
+        lines.append(f"│  Sesión : {sid}  ·  perfil: {profile}")
+        lines.append("│  ✓  Workspace restablecido al estado inicial")
+    lines.append("╚───────────────────────────────────────────────────────")
+    return "\n".join(lines)
+
+
+@hook_main
+def main() -> None:
+    root = get_project_root()
+    session = read_json_file(root / WORKSPACE_DIR_NAME / "state" / "session.json")
+    env = read_json_file(root / WORKSPACE_DIR_NAME / "config" / "environment.json")
+    active = session.get("status") == "active"
+    sid = session.get("session_id", "—")
+    profile = env.get("active_profile", "global")
+    files, limit, exceeded = _pending(root)
+    commit = _last_commit(root)
+
+    if active:
+        telem.session_stop(root, sid, profile)
+        _clean_session(root)
+
+    emit_stop_reason(_build_banner(files, limit, exceeded, commit, active, sid, profile))
+
+
+if __name__ == "__main__":
+    main()

higpertext/hooks/hook_tasks/hook_utils.py

@@ -0,0 +1,144 @@
+"""Utilidades compartidas para hook tasks de higpertext."""
+
+from __future__ import annotations
+import sys
+from pathlib import Path
+
+# Add src to sys.path so we can import from higpertext
+
+import json
+import platform
+import shutil
+# Helpers ejecutan htx con shell=False.
+import subprocess  # nosec B404
+from datetime import datetime, timezone
+
+sys_path_src = Path(__file__).resolve().parents[3]
+if str(sys_path_src) not in sys.path:
+    sys.path.insert(0, str(sys_path_src))
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+HIGPERTEXT_DIR = WORKSPACE_DIR_NAME
+
+
+
+def get_project_root() -> Path:
+    """Resuelve la raíz del proyecto desde environment.json.
+
+    Cuando un hook task se despliega en .<assistant>/hooks/, el archivo
+    environment.json se encuentra en ../../.higpertext/environment.json relativo
+    al script. Siempre hay un htx.py launcher en esa raíz.
+    """
+    # Busca environment.json en dos ubicaciones candidatas:
+    # 1. Relativo al script (cuando el hook está desplegado en .<assistant>/hooks/)
+    # 2. Relativo al CWD del proceso (cuando se ejecuta desde la raíz del proyecto)
+    candidates = [
+        Path(__file__).resolve().parent
+        / ".."
+        / ".."
+        / HIGPERTEXT_DIR
+        / "config"
+        / "environment.json",
+        Path.cwd() / HIGPERTEXT_DIR / "config" / "environment.json",
+    ]
+    for env_path in candidates:
+        env_path = env_path.resolve()
+        if env_path.exists():
+            try:
+                data = json.loads(env_path.read_text(encoding="utf-8"))
+                root = data.get("system_environment", {}).get("project_root")
+                if root:
+                    return Path(root)
+            except (OSError, json.JSONDecodeError):  # nosec B110
+                pass
+    # Fallback: CWD si contiene htx.py (indica que somos la raíz del proyecto)
+    cwd = Path.cwd()
+    if (cwd / "htx.py").exists():
+        return cwd
+    return Path(__file__).resolve().parents[1]
+
+
+def get_htx() -> str:
+    """Retorna el primer elemento del comando htx resuelto via htx_resolver."""
+    root = get_project_root()
+    try:
+        from higpertext.kernel.htx_resolver import get_htx_cmd
+
+        cmd = get_htx_cmd(root)
+        return cmd[0]
+    except ImportError:
+        venv_htx = root / ".venv" / ("Scripts" if platform.system() == "Windows" else "bin") / "htx"
+        if venv_htx.exists():
+            return str(venv_htx)
+        if htx := shutil.which("htx"):
+            return htx
+        return str(root / ".venv" / "bin" / "python")
+
+
+def _htx_args(capability: str, params: dict) -> list[str]:
+    htx = get_htx()
+    base = (
+        [htx, "task", capability]
+        if not htx.endswith("python")
+        else [htx, "htx.py", "task", capability]
+    )
+    return base + [arg for k, v in params.items() for arg in (f"--{k}", str(v))]
+
+
+def hook_log_path(root: Path | None = None) -> Path:
+    """Retorna la ruta del log estructurado de hooks."""
+    base = root or get_project_root()
+    return base / HIGPERTEXT_DIR / "logs" / "hooks.jsonl"
+
+
+def log_hook_event(event: dict, root: Path | None = None) -> None:
+    """Registra un evento JSONL de hook sin interrumpir la ejecución."""
+    try:
+        path = hook_log_path(root)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            **event,
+        }
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(payload, ensure_ascii=False, sort_keys=True) + "\n")
+    except OSError:  # nosec B110
+        pass
+
+
+def log_hook_error(hook_id: str, message: str, root: Path | None = None, **extra: object) -> None:
+    """Registra errores no bloqueantes de hooks."""
+    log_hook_event(
+        {
+            "severity": "error",
+            "hook_id": hook_id,
+            "message": message[:1000],
+            **extra,
+        },
+        root=root,
+    )
+
+
+def run_higpertext_task(capability: str, params: dict) -> str:
+    """Ejecuta una capability higpertext y retorna su output combinado."""
+    root = get_project_root()
+    args = _htx_args(capability, params)
+    try:
+        result = subprocess.run(args, capture_output=True, text=True, cwd=str(root), timeout=30)
+    except subprocess.TimeoutExpired as exc:
+        log_hook_error(
+            "run_higpertext_task",
+            f"Timeout ejecutando capability {capability}",
+            root=root,
+            capability=capability,
+            timeout=exc.timeout,
+        )
+        return str(exc)
+    if result.returncode != 0:
+        log_hook_error(
+            "run_higpertext_task",
+            f"Capability {capability} terminó con código {result.returncode}",
+            root=root,
+            capability=capability,
+            returncode=result.returncode,
+        )
+    return (result.stdout or "") + (result.stderr or "")

higpertext/hooks/hook_tasks/session_guard_hook.py

@@ -0,0 +1,23 @@
+"""Hook SessionStart — verifica estado de la sesión y emite continue."""
+
+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))
+
+
+def main() -> None:
+    raw = sys.stdin.read().strip()
+    try:
+        json.loads(raw) if raw else {}
+    except json.JSONDecodeError:  # nosec B110
+        pass
+    print(json.dumps({"continue": True}))
+
+
+if __name__ == "__main__":
+    main()

higpertext/hooks/hook_tasks/telemetry_utils.py

@@ -0,0 +1,176 @@
+"""Wrapper liviano de telemetría para uso desde hook tasks desplegados."""
+
+from __future__ import annotations
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def _store(root: Path) -> Path:
+    return root / WORKSPACE_DIR_NAME / "state" / "telemetry.jsonl"
+
+
+def _project_id(root: Path) -> str:
+    """Lee project_id desde environment.json → variables.repository_id."""
+    env_file = root / WORKSPACE_DIR_NAME / "config" / "environment.json"
+    try:
+        data = json.loads(env_file.read_text(encoding="utf-8"))
+        return (
+            data.get("variables", {}).get("repository_id") or data.get("project_name") or root.name
+        )
+    except (OSError, json.JSONDecodeError):
+        return root.name
+
+
+def record(root: Path, event: str, **fields) -> None:
+    entry = {"ts": _now(), "event": event, "project_id": _project_id(root), **fields}
+    try:
+        with _store(root).open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    except OSError:  # nosec B110
+        pass
+
+
+def session_start(root: Path, session_id: str, profile: str) -> None:
+    record(root, "session_start", session_id=session_id, profile=profile)
+
+
+def session_stop(root: Path, session_id: str, profile: str) -> None:
+    """Calcula duración buscando el session_start correspondiente en el store."""
+    duration_min = _calc_duration(root, session_id)
+    record(
+        root,
+        "session_stop",
+        session_id=session_id,
+        profile=profile,
+        duration_min=round(duration_min, 2),
+    )
+
+
+def tool_call(
+    root: Path,
+    session_id: str,
+    tool_name: str,
+    input_chars: int,
+    output_chars: int,
+    is_higpertext_call: bool = False,
+) -> None:
+    # Precios claude-sonnet-4-6 (junio 2026, por millón de tokens)
+    # Distribución real del usuario: 98% cache_read, 2% output/write
+    # input=$3/M  output=$15/M  cache_write=$3.75/M  cache_read=$0.30/M
+    input_tokens = input_chars // 4
+    output_tokens = output_chars // 4
+    # Aproximación: input_chars del LLM son mayoritariamente cache_read
+    # Se estima 80% cache_read + 20% cache_write del input
+    cache_read_tokens = int(input_tokens * 0.80)
+    cache_write_tokens = int(input_tokens * 0.20)
+    estimated_tokens = input_tokens + output_tokens
+
+    cost = (
+        cache_read_tokens * 0.30 / 1_000_000
+        + cache_write_tokens * 3.75 / 1_000_000
+        + output_tokens * 15.0 / 1_000_000
+    )
+    record(
+        root,
+        "tool_call",
+        session_id=session_id,
+        tool=tool_name,
+        input_chars=input_chars,
+        output_chars=output_chars,
+        estimated_tokens=estimated_tokens,
+        estimated_cost_usd=round(cost, 6),
+        is_higpertext_call=is_higpertext_call,
+    )
+
+
+def activity(
+    root: Path,
+    session_id: str,
+    tool: str,
+    op_type: str,
+    target: str,
+    scope: str = "",
+    higpertext_related: bool = False,
+) -> None:
+    """Registra una operación atómica del agente (Edit, Write, Read, Bash, etc.)."""
+    record(
+        root,
+        "activity",
+        session_id=session_id,
+        tool=tool,
+        op_type=op_type,
+        target=target[:120],
+        scope=scope,
+        higpertext_related=higpertext_related,
+    )
+
+
+def hook_intercept(root: Path, session_id: str, capability_id: str, fragment: str) -> None:
+    record(
+        root,
+        "hook_intercept",
+        session_id=session_id,
+        capability=capability_id,
+        fragment=fragment[:80],
+    )
+
+
+def capability_used(root: Path, session_id: str, capability_id: str) -> None:
+    record(root, "capability_used", session_id=session_id, capability=capability_id)
+
+
+def commit_event(
+    root: Path,
+    session_id: str,
+    commit_hash: str,
+    commit_type: str,
+    scope: str,
+    profile: str,
+) -> None:
+    record(
+        root,
+        "commit",
+        session_id=session_id,
+        hash=commit_hash,
+        type=commit_type,
+        scope=scope,
+        profile=profile,
+    )
+
+
+# ------------------------------------------------------------------
+# Helpers
+# ------------------------------------------------------------------
+
+
+def _calc_duration(root: Path, session_id: str) -> float:
+    """Busca el session_start del session_id y retorna minutos transcurridos."""
+    store = _store(root)
+    if not store.exists():
+        return 0.0
+    start_ts = None
+    try:
+        for line in store.read_text(encoding="utf-8").splitlines():
+            try:
+                e = json.loads(line)
+                if e.get("event") == "session_start" and e.get("session_id") == session_id:
+                    start_ts = e.get("ts")
+            except (json.JSONDecodeError, KeyError):
+                continue
+    except OSError:
+        return 0.0
+    if not start_ts:
+        return 0.0
+    try:
+        t0 = datetime.fromisoformat(start_ts)
+        t1 = datetime.now(timezone.utc)
+        return (t1 - t0).total_seconds() / 60
+    except ValueError:
+        return 0.0

higpertext/hooks/hook_tasks/test_echo_hook.py

@@ -0,0 +1,33 @@
+"""Hook de diagnóstico — devuelve continue:true con echo del payload."""
+
+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))
+
+
+def main() -> None:
+    raw = sys.stdin.read().strip()
+    try:
+        payload = json.loads(raw) if raw else {}
+    except json.JSONDecodeError:
+        payload = {}
+    print(
+        json.dumps(
+            {
+                "continue": True,
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "additionalContext": f"[hooks] echo: {json.dumps(payload)}",
+                },
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

higpertext/hooks/hook_tasks/webhook_hook.py

@@ -0,0 +1,54 @@
+"""Hook PostToolUse/Stop — dispara webhooks configurados en hooks_config.json."""
+from higpertext.kernel.config_paths import WORKSPACE_DIR_NAME
+
+import sys
+import json
+from pathlib import Path
+
+
+def main() -> None:
+    data = json.load(sys.stdin)
+    event = data.get("hook_event", "PostToolUse")
+    tool_name = data.get("tool_name", "")
+    session_id = data.get("session_id", "")
+
+    root = Path(__file__).resolve().parents[5]
+
+    # Importación dinámica para evitar dependencia de sys.path en tiempo de hook
+    import importlib.util
+
+    spec = importlib.util.spec_from_file_location(
+        "webhook_dispatcher",
+        root / "src" / "higpertext" / "hooks" / "webhook_dispatcher.py",
+    )
+    mod = importlib.util.module_from_spec(spec)  # type: ignore[arg-type]
+    spec.loader.exec_module(mod)  # type: ignore[union-attr]
+
+    env_path = root / WORKSPACE_DIR_NAME / "config" / "environment.json"
+    assistant = "claude"
+    profile = "software_developer"
+    if env_path.exists():
+        try:
+            env = json.loads(env_path.read_text(encoding="utf-8"))
+            assistant = env.get("assistant", assistant)
+            profile = env.get("active_profile", profile)
+        except (OSError, json.JSONDecodeError):  # nosec B110
+            pass
+
+    dispatcher = mod.WebhookDispatcher(root)
+    dispatcher.dispatch(
+        event,
+        assistant,
+        {
+            "tool": tool_name,
+            "session_id": session_id,
+            "profile": profile,
+            "assistant": assistant,
+        },
+    )
+
+    print(json.dumps({"continue": True}))
+
+
+if __name__ == "__main__":
+    main()

higpertext/hooks/hook_tasks/workflow_runner_hook.py

@@ -0,0 +1,49 @@
+"""Hook task — ejecuta un workflow higpertext como hook PostToolUse o Stop."""
+
+import sys
+import json
+import argparse
+from higpertext.hooks.hook_tasks.hook_utils import get_project_root, get_htx
+# Workflow runner usa comando htx controlado.
+import subprocess  # nosec B404
+
+from higpertext.kernel.infrastructure.logger import get_logger
+_log = get_logger()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--workflow", required=True)
+    args, _ = parser.parse_known_args()
+
+    hook_data: dict = {}
+    if not sys.stdin.isatty():
+        try:
+            hook_data = json.load(sys.stdin)
+        except (json.JSONDecodeError, ValueError):  # nosec B110
+            pass
+
+    root = get_project_root()
+    result = subprocess.run(
+        [get_htx(root), "workflow", "run", args.workflow],
+        capture_output=True,
+        text=True,
+        cwd=str(root),
+    )
+    output = result.stdout or result.stderr
+
+    print(
+        json.dumps(
+            {
+                "continue": True,
+                "hookSpecificOutput": {
+                    "hookEventName": hook_data.get("hook_event", "PostToolUse"),
+                    "additionalContext": output[:2000],
+                },
+            }
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()