tapps-agents 3.5.39__py3-none-any.whl → 3.5.40__py3-none-any.whl

tapps_agents/hooks/manager.py

@@ -0,0 +1,143 @@
+"""
+Hook manager: lifecycle, registration by event, and triggering.
+
+Loads hooks from config, runs them via the executor with payload-derived env,
+and supports PostToolUse filtering by matcher and file_patterns.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+from pathlib import Path
+from typing import Any, Protocol
+
+from .config import HookDefinition, HooksConfig, load_hooks_config
+from .executor import HookResult, run_hook
+
+
+class _PayloadProtocol(Protocol):
+    """Payload must provide to_env() for hook execution."""
+
+    def to_env(self) -> dict[str, str]: ...
+    def to_dict(self) -> dict[str, Any]: ...
+
+
+def _tool_matches(hook: HookDefinition, tool_name: str) -> bool:
+    """True if hook has no matcher or tool_name matches the matcher regex."""
+    if not hook.matcher:
+        return True
+    try:
+        return re.search(hook.matcher, tool_name) is not None
+    except re.error:
+        return False
+
+
+def _file_matches(hook: HookDefinition, file_path: str | None) -> bool:
+    """True if hook has no file_patterns or file_path matches any pattern."""
+    if not hook.file_patterns or not file_path:
+        return True
+    name = Path(file_path).name
+    for pattern in hook.file_patterns:
+        if fnmatch.fnmatch(name, pattern) or fnmatch.fnmatch(file_path, pattern):
+            return True
+    return False
+
+
+def _filter_post_tool_use(
+    hooks: list[HookDefinition],
+    tool_name: str,
+    file_path: str | None,
+) -> list[HookDefinition]:
+    """Filter PostToolUse hooks by matcher and file_patterns."""
+    return [
+        h
+        for h in hooks
+        if _tool_matches(h, tool_name) and _file_matches(h, file_path)
+    ]
+
+
+class HookManager:
+    """
+    Loads and triggers hooks by event type.
+
+    Hooks are loaded from .tapps-agents/hooks.yaml (or explicit path).
+    Trigger invokes all enabled hooks for the event with payload-derived env.
+    """
+
+    def __init__(
+        self,
+        config: HooksConfig | None = None,
+        *,
+        config_path: Path | str | None = None,
+        project_root: Path | None = None,
+        timeout_seconds: int | None = None,
+    ) -> None:
+        """
+        Initialize manager from config or load from path.
+
+        Args:
+            config: Pre-loaded config. If None, loads from config_path/project_root.
+            config_path: Path to hooks.yaml (used when config is None).
+            project_root: Project root for loading config and running hooks.
+            timeout_seconds: Override default hook timeout.
+        """
+        self._project_root = Path(project_root) if project_root else Path.cwd()
+        self._timeout_seconds = timeout_seconds
+        if config is not None:
+            self._config = config
+        else:
+            self._config = load_hooks_config(
+                config_path=config_path,
+                project_root=self._project_root,
+            )
+
+    def _get_hooks_for_event(self, event_name: str) -> list[HookDefinition]:
+        """Return enabled hooks for the event."""
+        hooks = self._config.hooks.get(event_name, [])
+        return [h for h in hooks if h.enabled]
+
+    def trigger(
+        self,
+        event_name: str,
+        payload: _PayloadProtocol,
+        *,
+        tool_name: str | None = None,
+        file_path: str | None = None,
+    ) -> list[HookResult]:
+        """
+        Run all hooks registered for the event with payload env.
+
+        For PostToolUse, only hooks matching tool_name and file_path (matcher
+        and file_patterns) are run.
+
+        Args:
+            event_name: One of UserPromptSubmit, PostToolUse, SessionStart,
+                SessionEnd, WorkflowComplete.
+            payload: Event payload with to_env() returning TAPPS_* dict.
+            tool_name: For PostToolUse, the tool that was used (e.g. Write, Edit).
+            file_path: For PostToolUse, the affected file path.
+
+        Returns:
+            List of HookResult in execution order. Caller can check fail_on_error
+            and result.success to decide whether to fail the workflow.
+        """
+        hooks = self._get_hooks_for_event(event_name)
+        if event_name == "PostToolUse" and (tool_name is not None or file_path is not None):
+            hooks = _filter_post_tool_use(hooks, tool_name or "", file_path)
+        env = payload.to_env()
+        results: list[HookResult] = []
+        for hook in hooks:
+            result = run_hook(
+                hook,
+                env,
+                timeout_seconds=self._timeout_seconds,
+                project_root=self._project_root,
+            )
+            results.append(result)
+            if hook.fail_on_error and not result.success:
+                raise RuntimeError(
+                    f"Hook {hook.name} failed (fail_on_error=True): "
+                    f"returncode={result.returncode}, stderr={result.stderr[:200]!r}"
+                )
+        return results

tapps_agents/session/__init__.py

@@ -0,0 +1,19 @@
+"""
+CLI session lifecycle for TappsCodingAgents.
+
+Provides session tracking (session ID), SessionStart on first command,
+SessionEnd on process exit via atexit, and optional session log/state
+under .tapps-agents/sessions/.
+"""
+
+from .manager import (
+    get_session_id,
+    ensure_session_started,
+    register_session_end_atexit,
+)
+
+__all__ = [
+    "get_session_id",
+    "ensure_session_started",
+    "register_session_end_atexit",
+]

tapps_agents/session/manager.py

@@ -0,0 +1,256 @@
+"""
+CLI session lifecycle manager.
+
+SessionStart on first tapps-agents command, SessionEnd on exit via atexit;
+session tracking with session ID (TAPPS_SESSION_ID) and optional log/state
+under .tapps-agents/sessions/ when configured.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import logging
+import os
+import uuid
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tapps_agents.hooks.manager import HookManager
+
+logger = logging.getLogger(__name__)
+
+# Process-global: session id and whether we have already started/registered atexit
+_session_id: str | None = None
+_started: bool = False
+_atexit_registered: bool = False
+_project_root: Path | None = None
+
+
+def _reset_state_for_testing() -> None:
+    """Reset process-global session state. For use in unit tests only."""
+    global _session_id, _started, _atexit_registered, _project_root
+    _session_id = None
+    _started = False
+    _atexit_registered = False
+    _project_root = None
+
+
+def get_session_id() -> str | None:
+    """Return current session ID, or None if session not started."""
+    return _session_id
+
+
+def _get_sessions_dir(project_root: Path) -> Path | None:
+    """
+    Return .tapps-agents/sessions path if session state is enabled.
+
+    Session log/state is written when:
+    - TAPPS_SESSION_STATE=1 or TAPPS_SESSION_LOG=1, or
+    - The directory .tapps-agents/sessions already exists (user-configured).
+    """
+    sessions_dir = project_root / ".tapps-agents" / "sessions"
+    if os.environ.get("TAPPS_SESSION_STATE", "") == "1":
+        return sessions_dir
+    if os.environ.get("TAPPS_SESSION_LOG", "") == "1":
+        return sessions_dir
+    if sessions_dir.exists():
+        return sessions_dir
+    return None
+
+
+def _write_session_state(session_id: str, project_root: Path, started: bool) -> None:
+    """Write optional session state file under .tapps-agents/sessions/."""
+    sessions_dir = _get_sessions_dir(project_root)
+    if not sessions_dir:
+        return
+    try:
+        sessions_dir.mkdir(parents=True, exist_ok=True)
+        path = sessions_dir / f"{session_id}.json"
+        state = {
+            "session_id": session_id,
+            "project_root": str(project_root),
+            "started": started,
+        }
+        path.write_text(json.dumps(state, indent=2), encoding="utf-8")
+    except OSError as e:
+        logger.debug("Could not write session state: %s", e)
+
+
+def _session_hydration_enabled(project_root: Path) -> bool:
+    """True if session lifecycle hydration is enabled (not disabled and task-specs configured)."""
+    if os.environ.get("TAPPS_SESSION_HYDRATION", "").strip().lower() in ("0", "false", "no"):
+        return False
+    task_specs_dir = project_root / ".tapps-agents" / "task-specs"
+    return task_specs_dir.exists()
+
+
+def _run_session_start_hydration(project_root: Path, *, show_ready: bool = False) -> None:
+    """
+    On SessionStart: hydrate task specs to Beads; optionally run bd ready and log output.
+    No-op if hydration disabled or bd/task-specs not configured.
+    """
+    if not _session_hydration_enabled(project_root):
+        return
+    try:
+        from tapps_agents.beads.hydration import hydrate_to_beads
+        from tapps_agents.beads.client import is_available, run_bd
+
+        if not is_available(project_root):
+            return
+        report = hydrate_to_beads(project_root=project_root)
+        if report.bd_unavailable:
+            return
+        if report.created or report.deps_added:
+            logger.info(
+                "Session hydration: created=%d skipped=%d deps_added=%d",
+                report.created,
+                report.skipped,
+                report.deps_added,
+            )
+        if show_ready or os.environ.get("TAPPS_SESSION_SHOW_READY", "").strip() == "1":
+            r = run_bd(project_root, ["ready"])
+            if r.returncode == 0 and r.stdout:
+                logger.info("Beads ready: %s", r.stdout.strip()[:500])
+    except Exception as e:
+        logger.warning("SessionStart hydration error: %s", e)
+
+
+def _run_session_end_dehydration(project_root: Path) -> None:
+    """
+    On SessionEnd: dehydrate from Beads and log short report (updated count).
+    No-op if hydration disabled or bd not available.
+    """
+    if not _session_hydration_enabled(project_root):
+        return
+    try:
+        from tapps_agents.beads.hydration import dehydrate_from_beads
+
+        updated = dehydrate_from_beads(project_root=project_root)
+        if updated > 0:
+            logger.info("Session hydration: %d spec(s) updated from Beads", updated)
+    except Exception as e:
+        logger.warning("SessionEnd dehydration error: %s", e)
+
+
+def _fire_session_start(project_root: Path, hook_manager: HookManager) -> None:
+    """Fire SessionStart hook with current session ID and project root."""
+    sid = get_session_id()
+    if not sid:
+        return
+    from tapps_agents.hooks.events import SessionStartEvent
+
+    payload = SessionStartEvent(session_id=sid, project_root=str(project_root))
+    try:
+        hook_manager.trigger("SessionStart", payload)
+    except Exception as e:
+        logger.warning("SessionStart hook error: %s", e)
+    _run_session_start_hydration(project_root)
+
+
+def _fire_session_end(project_root: Path, hook_manager: HookManager) -> None:
+    """Fire SessionEnd hook; run dehydrate and log hydration report."""
+    _run_session_end_dehydration(project_root)
+    sid = get_session_id()
+    if not sid:
+        return
+    from tapps_agents.hooks.events import SessionEndEvent
+
+    payload = SessionEndEvent(session_id=sid, project_root=str(project_root))
+    try:
+        hook_manager.trigger("SessionEnd", payload)
+    except Exception as e:
+        logger.warning("SessionEnd hook error: %s", e)
+
+
+def ensure_session_started(
+    project_root: Path | str | None = None,
+    *,
+    hook_manager: HookManager | None = None,
+) -> str:
+    """
+    Start CLI session on first call: generate session ID, fire SessionStart, register atexit.
+
+    Idempotent: later calls in the same process return the same session ID and do not
+    fire SessionStart again.
+
+    Args:
+        project_root: Project root (default: cwd). Used for hooks and optional state.
+        hook_manager: HookManager instance. If None, one is created for project_root.
+
+    Returns:
+        Current session ID (UUID string).
+    """
+    global _session_id, _started, _atexit_registered, _project_root
+
+    root = Path(project_root) if project_root else Path.cwd()
+
+    if _started:
+        assert _session_id is not None
+        return _session_id
+
+    _session_id = str(uuid.uuid4())
+    _started = True
+    _project_root = root
+
+    if hook_manager is None:
+        from tapps_agents.hooks.manager import HookManager
+
+        hook_manager = HookManager(project_root=root)
+
+    _write_session_state(_session_id, root, started=True)
+    _fire_session_start(root, hook_manager)
+
+    if not _atexit_registered:
+        _atexit_registered = True
+        _hm = hook_manager
+
+        def _on_exit() -> None:
+            global _session_id, _project_root
+            root = _project_root or Path.cwd()
+            _fire_session_end(root, _hm)
+            if _session_id and _project_root:
+                _write_session_state(_session_id, _project_root, started=False)
+
+        atexit.register(_on_exit)
+
+    return _session_id
+
+
+def register_session_end_atexit(
+    project_root: Path | str | None = None,
+    *,
+    hook_manager: HookManager | None = None,
+) -> None:
+    """
+    Register atexit handler for SessionEnd only (does not start session).
+
+    Use when you have already started the session via ensure_session_started
+    and want to ensure SessionEnd is registered. If ensure_session_started
+    was called, atexit is already registered; this is for edge cases or tests.
+    """
+    global _atexit_registered, _project_root
+
+    root = Path(project_root) if project_root else Path.cwd()
+    _project_root = _project_root or root
+
+    if hook_manager is None:
+        from tapps_agents.hooks.manager import HookManager
+
+        hook_manager = HookManager(project_root=root)
+
+    if _atexit_registered:
+        return
+
+    _atexit_registered = True
+    _hm = hook_manager
+
+    def _on_exit() -> None:
+        global _session_id, _project_root
+        root = _project_root or Path.cwd()
+        _fire_session_end(root, _hm)
+        if _session_id and _project_root:
+            _write_session_state(_session_id, _project_root, started=False)
+
+    atexit.register(_on_exit)