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

tapps_agents/health/checks/outcomes.py

@@ -31,6 +31,90 @@ class OutcomeHealthCheck(HealthCheck):
         self.reports_dir = reports_dir or (self.project_root / ".tapps-agents" / "reports")
         self.accessor = CursorAnalyticsAccessor()
 
+    def _compute_outcomes_from_execution_metrics(self, days: int = 30) -> dict:
+        """
+        Compute outcomes from execution metrics when review artifacts don't exist.
+
+        Args:
+            days: Number of days to look back for metrics
+
+        Returns:
+            Dictionary with review_executions_count, success_rate, and gate_pass_rate
+        """
+        try:
+            from datetime import UTC
+            from ...workflow.execution_metrics import ExecutionMetricsCollector
+            import logging
+
+            collector = ExecutionMetricsCollector(project_root=self.project_root)
+
+            # Get metrics with reasonable limit (5000 max for ~30 days of heavy usage)
+            MAX_METRICS_TO_SCAN = 5000
+            all_metrics = collector.get_metrics(limit=MAX_METRICS_TO_SCAN)
+
+            # Log warning if we hit the limit
+            if len(all_metrics) >= MAX_METRICS_TO_SCAN:
+                logging.getLogger(__name__).warning(
+                    "Hit metrics scan limit (%d); results may be incomplete",
+                    MAX_METRICS_TO_SCAN
+                )
+
+            # Filter for review executions within the last N days (timezone-aware)
+            cutoff_date = datetime.now(UTC) - timedelta(days=days)
+            review_metrics = []
+            for m in all_metrics:
+                # Parse timestamp and ensure timezone-aware comparison
+                try:
+                    ts = datetime.fromisoformat(m.started_at.replace("Z", "+00:00"))
+                    # Convert naive datetime to UTC if needed
+                    if ts.tzinfo is None:
+                        from datetime import UTC
+                        ts = ts.replace(tzinfo=UTC)
+
+                    if ts >= cutoff_date:
+                        if m.command == "review" or (m.skill and "reviewer" in (m.skill or "").lower()):
+                            review_metrics.append(m)
+                except (ValueError, AttributeError):
+                    # Skip metrics with invalid timestamps
+                    continue
+
+            if not review_metrics:
+                return {
+                    "review_executions_count": 0,
+                    "success_rate": 0.0,
+                    "gate_pass_rate": None,
+                }
+
+            total = len(review_metrics)
+            success_count = sum(1 for m in review_metrics if m.status == "success")
+            success_rate = (success_count / total * 100) if total > 0 else 0.0
+
+            # Calculate gate pass rate (only for metrics that have gate_pass field)
+            gate_pass_metrics = [m for m in review_metrics if m.gate_pass is not None]
+            if gate_pass_metrics:
+                gate_pass_count = sum(1 for m in gate_pass_metrics if m.gate_pass is True)
+                gate_pass_rate = (gate_pass_count / len(gate_pass_metrics) * 100)
+            else:
+                gate_pass_rate = None
+
+            return {
+                "review_executions_count": total,
+                "success_rate": success_rate,
+                "gate_pass_rate": gate_pass_rate,
+            }
+
+        except Exception as e:
+            # If fallback fails, log and return empty result
+            import logging
+            logging.getLogger(__name__).debug(
+                "Failed to compute outcomes from execution metrics: %s", e
+            )
+            return {
+                "review_executions_count": 0,
+                "success_rate": 0.0,
+                "gate_pass_rate": None,
+            }
+
     def run(self) -> HealthCheckResult:
         """
         Run outcome health check.
@@ -111,52 +195,56 @@ class OutcomeHealthCheck(HealthCheck):
             # Check if we have any data; if not, try fallback to execution metrics (review steps)
             if not review_artifacts and not agents_data:
                 # Fallback: derive outcomes from execution metrics (review steps, gate_pass)
-                try:
-                    from ...workflow.execution_metrics import ExecutionMetricsCollector
-
-                    collector = ExecutionMetricsCollector(project_root=self.project_root)
-                    exec_metrics = collector.get_metrics(limit=2000)
-                    review_metrics = [
-                        m
-                        for m in exec_metrics
-                        if m.command == "review"
-                        or (m.skill and "review" in (m.skill or "").lower())
-                    ]
-                    if review_metrics:
-                        total = len(review_metrics)
-                        success = sum(1 for m in review_metrics if m.status == "success")
-                        gate_passed = sum(
-                            1 for m in review_metrics if getattr(m, "gate_pass", False)
-                        )
-                        gate_rate = (gate_passed / total * 100) if total else 0.0
-                        success_rate = (success / total * 100) if total else 0.0
-                        derived_score = 50.0 + min(25.0, success_rate / 4.0 + gate_rate / 4.0)
-                        return HealthCheckResult(
-                            name=self.name,
-                            status="degraded",
-                            score=min(75.0, derived_score),
-                            message=(
-                                f"Outcomes derived from execution metrics: {total} review steps, "
-                                f"{gate_rate:.0f}% passed gate"
-                            ),
-                            details={
-                                "average_score": 0.0,
-                                "score_trend": "unknown",
-                                "score_change": 0.0,
-                                "review_artifacts_count": 0,
-                                "improvement_cycles": 0,
-                                "reports_dir": str(self.reports_dir),
-                                "review_steps_from_execution_metrics": total,
-                                "gate_pass_rate": gate_rate,
-                                "success_rate": success_rate,
-                                "issues": [],
-                            },
-                            remediation=[
-                                "Run reviewer agent or quality workflows to generate metrics"
-                            ],
-                        )
-                except Exception:
-                    pass
+                import logging
+                fallback_data = self._compute_outcomes_from_execution_metrics(days=30)
+
+                if fallback_data["review_executions_count"] > 0:
+                    total = fallback_data["review_executions_count"]
+                    success_rate = fallback_data["success_rate"]
+                    gate_pass_rate = fallback_data["gate_pass_rate"]
+
+                    # Calculate score: 60 base + 10 if success_rate ≥80% + 5 if gate_pass_rate ≥70%
+                    fallback_score = 60.0
+                    if success_rate >= 80.0:
+                        fallback_score += 10.0
+                    if gate_pass_rate is not None and gate_pass_rate >= 70.0:
+                        fallback_score += 5.0
+
+                    # Build message
+                    gate_msg = f"{gate_pass_rate:.0f}% passed gate" if gate_pass_rate is not None else "no gate data"
+                    message = (
+                        f"Outcomes derived from execution metrics: {total} review steps, "
+                        f"{gate_msg}"
+                    )
+
+                    logging.getLogger(__name__).info(
+                        "Outcomes fallback activated: %d review executions processed", total
+                    )
+
+                    return HealthCheckResult(
+                        name=self.name,
+                        status="degraded",
+                        score=fallback_score,
+                        message=message,
+                        details={
+                            "average_score": 0.0,
+                            "score_trend": "unknown",
+                            "score_change": 0.0,
+                            "review_artifacts_count": 0,
+                            "improvement_cycles": 0,
+                            "reports_dir": str(self.reports_dir),
+                            "fallback_used": True,
+                            "fallback_source": "execution_metrics",
+                            "review_executions_count": total,
+                            "success_rate": success_rate,
+                            "gate_pass_rate": gate_pass_rate,
+                            "issues": [],
+                        },
+                        remediation=[
+                            "Run reviewer agent or quality workflows to generate review artifacts"
+                        ],
+                    )
+
                 score = 50.0
                 issues.append("No quality metrics available")
                 remediation.append("Run reviewer agent or quality workflows to generate metrics")

tapps_agents/health/orchestrator.py

@@ -175,9 +175,9 @@ class HealthOrchestrator:
 
         overall_score = weighted_score / total_weight if total_weight > 0 else 0.0
 
-        # Determine overall status
+        # Determine overall status (HM-001-S3: degraded when score >= 75 and only non-critical unhealthy)
         critical_checks = {"environment", "execution"}
-        non_critical_unhealthy_only = {"outcomes", "knowledge_base", "context7_cache"}
+        non_critical_checks = {"outcomes", "knowledge_base", "context7_cache", "automation"}
         unhealthy_checks = [
             name
             for name, result in results.items()
@@ -189,16 +189,19 @@ class HealthOrchestrator:
             if name in results
         )
 
+        status_reason: str | None = None
         if status_counts["unhealthy"] > 0:
             overall_status = "unhealthy"
-            # If score is high (>=75) and only non-critical checks are unhealthy, show degraded
             if (
                 overall_score >= 75.0
                 and critical_healthy
                 and unhealthy_checks
-                and all(c in non_critical_unhealthy_only for c in unhealthy_checks)
+                and all(c in non_critical_checks for c in unhealthy_checks)
             ):
                 overall_status = "degraded"
+                status_reason = (
+                    "Status degraded due to non-critical checks; core functionality is healthy"
+                )
         elif status_counts["degraded"] > 0:
             overall_status = "degraded"
         else:
@@ -243,12 +246,17 @@ class HealthOrchestrator:
             if rem not in prioritized_remediations:
                 prioritized_remediations.append(rem)
 
+        details: dict[str, Any] = {}
+        if status_reason:
+            details["status_reason"] = status_reason
+
         return {
             "status": overall_status,
             "score": overall_score,
             "message": f"Overall health: {overall_status} ({overall_score:.1f}/100)",
             "checks_count": len(results),
             "status_counts": status_counts,
+            "details": details,
             "checks": {
                 name: {
                     "status": result.status,

tapps_agents/hooks/__init__.py

@@ -0,0 +1,33 @@
+"""
+Hook system for TappsCodingAgents.
+
+Provides event-driven automation: UserPromptSubmit, PostToolUse, SessionStart,
+SessionEnd, WorkflowComplete. Configuration via .tapps-agents/hooks.yaml.
+"""
+
+from .config import HookDefinition, HooksConfig, load_hooks_config
+from .executor import HookResult, run_hook
+from .events import (
+    HookEventType,
+    PostToolUseEvent,
+    SessionEndEvent,
+    SessionStartEvent,
+    UserPromptSubmitEvent,
+    WorkflowCompleteEvent,
+)
+from .manager import HookManager
+
+__all__ = [
+    "HookDefinition",
+    "HookManager",
+    "HooksConfig",
+    "HookResult",
+    "load_hooks_config",
+    "run_hook",
+    "HookEventType",
+    "PostToolUseEvent",
+    "SessionEndEvent",
+    "SessionStartEvent",
+    "UserPromptSubmitEvent",
+    "WorkflowCompleteEvent",
+]

tapps_agents/hooks/config.py

@@ -0,0 +1,140 @@
+"""
+Hook configuration schema and loader.
+
+Loads and validates .tapps-agents/hooks.yaml with event definitions,
+matchers, and commands. Supported events: UserPromptSubmit, PostToolUse,
+SessionStart, SessionEnd, WorkflowComplete.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field, model_validator
+
+# Supported hook event types
+HOOK_EVENT_TYPES = frozenset({
+    "UserPromptSubmit",
+    "PostToolUse",
+    "SessionStart",
+    "SessionEnd",
+    "WorkflowComplete",
+})
+
+
+class HookDefinition(BaseModel):
+    """Single hook definition within an event."""
+
+    name: str = Field(..., min_length=1, description="Hook display name")
+    command: str = Field(..., min_length=1, description="Shell command to execute")
+    enabled: bool = Field(default=True, description="Whether hook is enabled")
+    matcher: str | None = Field(
+        default=None,
+        description="Tool name matcher for PostToolUse (e.g. 'Write|Edit')",
+    )
+    file_patterns: list[str] | None = Field(
+        default=None,
+        description="Glob patterns for file filtering (e.g. ['*.py'])",
+    )
+    fail_on_error: bool = Field(
+        default=False,
+        description="If true, non-zero exit fails workflow",
+    )
+
+    model_config = {"extra": "forbid"}
+
+
+class HooksConfig(BaseModel):
+    """
+    Root schema for hooks.yaml.
+
+    Top-level key is 'hooks'. Each event maps to a list of HookDefinition.
+    """
+
+    hooks: dict[str, list[HookDefinition]] = Field(
+        default_factory=dict,
+        description="Event name -> list of hook definitions",
+    )
+
+    model_config = {"extra": "forbid"}
+
+    @model_validator(mode="after")
+    def validate_event_names(self) -> "HooksConfig":
+        """Ensure only supported event names are used."""
+        for event_name in self.hooks:
+            if event_name not in HOOK_EVENT_TYPES:
+                raise ValueError(
+                    f"Unsupported hook event '{event_name}'. "
+                    f"Supported: {', '.join(sorted(HOOK_EVENT_TYPES))}"
+                )
+        return self
+
+
+def load_hooks_config(
+    config_path: Path | str | None = None,
+    project_root: Path | None = None,
+) -> HooksConfig:
+    """
+    Load and validate hooks.yaml.
+
+    Args:
+        config_path: Explicit path to hooks.yaml. If None, uses
+            project_root/.tapps-agents/hooks.yaml.
+        project_root: Project root (default: cwd). Used when config_path is None.
+
+    Returns:
+        Validated HooksConfig. Returns empty config (all events empty) when
+        file is missing (safe defaults).
+
+    Raises:
+        FileNotFoundError: If config_path is given and file doesn't exist.
+        yaml.YAMLError: On YAML parse errors (includes path/line in message).
+        ValueError: On schema validation failures.
+    """
+    project_root = project_root or Path.cwd()
+    if config_path is None:
+        config_path = project_root / ".tapps-agents" / "hooks.yaml"
+    else:
+        config_path = Path(config_path)
+        if not config_path.is_absolute():
+            config_path = project_root / config_path
+
+    if not config_path.exists():
+        return HooksConfig(hooks={})
+
+    try:
+        content = config_path.read_text(encoding="utf-8")
+    except OSError as e:
+        raise FileNotFoundError(
+            f"Cannot read hooks config from {config_path}: {e}"
+        ) from e
+
+    try:
+        raw = yaml.safe_load(content)
+    except yaml.YAMLError as e:
+        path_hint = str(config_path)
+        if hasattr(e, "problem_mark") and e.problem_mark:
+            line = e.problem_mark.line + 1
+            col = e.problem_mark.column + 1
+            path_hint = f"{config_path}:{line}:{col}"
+        raise yaml.YAMLError(f"Invalid YAML in {path_hint}: {e}") from e
+
+    if raw is None:
+        return HooksConfig(hooks={})
+
+    if not isinstance(raw, dict):
+        raise ValueError(
+            f"hooks.yaml must be a YAML object (dict), got {type(raw).__name__} "
+            f"at {config_path}"
+        )
+
+    if "hooks" not in raw:
+        return HooksConfig(hooks={})
+
+    try:
+        return HooksConfig.model_validate(raw)
+    except Exception as e:
+        raise ValueError(
+            f"Hooks config validation failed at {config_path}: {e}"
+        ) from e

tapps_agents/hooks/events.py

@@ -0,0 +1,135 @@
+"""
+Hook event definitions.
+
+Defines the five hook events with data structures and serialization for
+type-safe use across the hook system: UserPromptSubmit, PostToolUse,
+SessionStart, SessionEnd, WorkflowComplete.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from enum import Enum
+from typing import Any
+
+
+class HookEventType(str, Enum):
+    """Supported hook event types."""
+
+    USER_PROMPT_SUBMIT = "UserPromptSubmit"
+    POST_TOOL_USE = "PostToolUse"
+    SESSION_START = "SessionStart"
+    SESSION_END = "SessionEnd"
+    WORKFLOW_COMPLETE = "WorkflowComplete"
+
+
+@dataclass(frozen=True)
+class UserPromptSubmitEvent:
+    """Payload for UserPromptSubmit - before workflow starts."""
+
+    prompt: str
+    project_root: str
+    workflow_type: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize for logging and context injection."""
+        return asdict(self)
+
+    def to_env(self) -> dict[str, str]:
+        """Environment variables for hook execution."""
+        d: dict[str, str] = {"TAPPS_PROMPT": self.prompt, "TAPPS_PROJECT_ROOT": self.project_root}
+        if self.workflow_type:
+            d["TAPPS_WORKFLOW_TYPE"] = self.workflow_type
+        return d
+
+
+@dataclass(frozen=True)
+class PostToolUseEvent:
+    """Payload for PostToolUse - after Write/Edit completes."""
+
+    file_path: str | None
+    file_paths: list[str]
+    tool_name: str
+    project_root: str
+    workflow_id: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize for logging and context injection."""
+        return asdict(self)
+
+    def to_env(self) -> dict[str, str]:
+        """Environment variables for hook execution."""
+        d: dict[str, str] = {
+            "TAPPS_FILE_PATH": self.file_path or "",
+            "TAPPS_FILE_PATHS": " ".join(self.file_paths),
+            "TAPPS_TOOL_NAME": self.tool_name,
+            "TAPPS_PROJECT_ROOT": self.project_root,
+        }
+        if self.workflow_id:
+            d["TAPPS_WORKFLOW_ID"] = self.workflow_id
+        return d
+
+
+@dataclass(frozen=True)
+class SessionStartEvent:
+    """Payload for SessionStart - CLI/Cursor session begins."""
+
+    session_id: str
+    project_root: str
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize for logging and context injection."""
+        return asdict(self)
+
+    def to_env(self) -> dict[str, str]:
+        """Environment variables for hook execution."""
+        return {
+            "TAPPS_SESSION_ID": self.session_id,
+            "TAPPS_PROJECT_ROOT": self.project_root,
+        }
+
+
+@dataclass(frozen=True)
+class SessionEndEvent:
+    """Payload for SessionEnd - session ends."""
+
+    session_id: str
+    project_root: str
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize for logging and context injection."""
+        return asdict(self)
+
+    def to_env(self) -> dict[str, str]:
+        """Environment variables for hook execution."""
+        return {
+            "TAPPS_SESSION_ID": self.session_id,
+            "TAPPS_PROJECT_ROOT": self.project_root,
+        }
+
+
+@dataclass(frozen=True)
+class WorkflowCompleteEvent:
+    """Payload for WorkflowComplete - after workflow success/fail."""
+
+    workflow_type: str
+    workflow_id: str
+    status: str  # completed, failed, cancelled
+    project_root: str
+    beads_issue_id: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize for logging and context injection."""
+        return asdict(self)
+
+    def to_env(self) -> dict[str, str]:
+        """Environment variables for hook execution."""
+        d: dict[str, str] = {
+            "TAPPS_WORKFLOW_TYPE": self.workflow_type,
+            "TAPPS_WORKFLOW_ID": self.workflow_id,
+            "TAPPS_WORKFLOW_STATUS": self.status,
+            "TAPPS_PROJECT_ROOT": self.project_root,
+        }
+        if self.beads_issue_id:
+            d["TAPPS_BEADS_ISSUE_ID"] = self.beads_issue_id
+        return d

tapps_agents/hooks/executor.py

@@ -0,0 +1,128 @@
+"""
+Hook executor: run hook shell commands with TAPPS_* env vars, timeout, and capture.
+
+Runs hooks synchronously; captures stdout/stderr; configurable timeout (default 30s).
+Non-zero exit is logged and optionally fails the workflow when fail_on_error is True.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import HookDefinition
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TIMEOUT_SECONDS = 30
+
+
+@dataclass
+class HookResult:
+    """Result of running a single hook."""
+
+    stdout: str
+    stderr: str
+    returncode: int
+    timed_out: bool
+    hook_name: str
+
+    @property
+    def success(self) -> bool:
+        """True if hook completed without timeout and returncode 0."""
+        return not self.timed_out and self.returncode == 0
+
+
+def _substitute_placeholders(command: str, env: dict[str, str]) -> str:
+    """Replace {name} in command with env value; names are lower-case env keys."""
+    result = command
+    for key, value in env.items():
+        # Support both {TAPPS_FILE_PATH} and {file_path} style
+        placeholder = "{" + key + "}"
+        if placeholder in result:
+            result = result.replace(placeholder, value)
+        # Snake-case style: TAPPS_FILE_PATH -> file_path
+        snake = key.replace("TAPPS_", "").lower()
+        if "{" + snake + "}" in result:
+            result = result.replace("{" + snake + "}", value)
+    return result
+
+
+def run_hook(
+    hook: HookDefinition,
+    env: dict[str, str],
+    *,
+    timeout_seconds: int | None = None,
+    project_root: Path | None = None,
+) -> HookResult:
+    """
+    Execute a hook's shell command with the given environment.
+
+    Args:
+        hook: Hook definition (name, command, fail_on_error).
+        env: Environment variables for the process (e.g. TAPPS_FILE_PATH, TAPPS_PROMPT).
+            Merged over current process env; passed to the subprocess.
+        timeout_seconds: Max run time in seconds; default DEFAULT_TIMEOUT_SECONDS.
+        project_root: Optional project root; cwd for the subprocess when set.
+
+    Returns:
+        HookResult with stdout, stderr, returncode, timed_out, hook_name.
+    """
+    timeout_seconds = timeout_seconds if timeout_seconds is not None else DEFAULT_TIMEOUT_SECONDS
+    full_env = {**os.environ, **env}
+    command = _substitute_placeholders(hook.command, full_env)
+    cwd = Path(project_root) if project_root else None
+
+    try:
+        proc = subprocess.run(
+            command,
+            shell=True,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            env=full_env,
+            cwd=cwd,
+            timeout=timeout_seconds,
+        )
+        stdout = proc.stdout or ""
+        stderr = proc.stderr or ""
+        if stderr.strip():
+            logger.warning("Hook %s stderr: %s", hook.name, stderr.strip())
+        if proc.returncode != 0:
+            logger.error(
+                "Hook %s exited with code %d: %s",
+                hook.name,
+                proc.returncode,
+                stderr.strip() or stdout.strip() or "(no output)",
+            )
+        return HookResult(
+            stdout=stdout,
+            stderr=stderr,
+            returncode=proc.returncode,
+            timed_out=False,
+            hook_name=hook.name,
+        )
+    except subprocess.TimeoutExpired as e:
+        logger.error("Hook %s timed out after %s seconds", hook.name, timeout_seconds)
+        stdout = (e.stdout or b"").decode("utf-8", errors="replace") if e.stdout else ""
+        stderr = (e.stderr or b"").decode("utf-8", errors="replace") if e.stderr else ""
+        return HookResult(
+            stdout=stdout,
+            stderr=stderr + f"\n(Hook timed out after {timeout_seconds}s)",
+            returncode=-1,
+            timed_out=True,
+            hook_name=hook.name,
+        )
+    except Exception as e:
+        logger.exception("Hook %s failed: %s", hook.name, e)
+        return HookResult(
+            stdout="",
+            stderr=str(e),
+            returncode=-1,
+            timed_out=False,
+            hook_name=hook.name,
+        )