@jaguilar87/gaia 5.0.0-rc.2

package/dist/gaia-ops/hooks/modules/context/anchor_tracker.py

@@ -0,0 +1,317 @@
+"""
+Context anchor hit tracking for project context effectiveness measurement.
+
+Extracts "anchors" (paths, names, IDs) from injected project context and checks
+whether the agent's early tool calls reference them. This measures whether agents
+use injected context as search anchors versus discovering on their own.
+
+Provides:
+    - extract_anchors(): Extract searchable anchors from a context payload
+    - save_anchors(): Persist anchors to a session-scoped temp file
+    - load_anchors(): Load persisted anchors for a session
+    - extract_tool_calls_from_transcript(): Parse early tool calls from JSONL transcript
+    - compute_anchor_hits(): Compare tool call args against anchors
+"""
+
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+
+logger = logging.getLogger(__name__)
+
+# How many early tool calls to check
+MAX_TOOL_CALLS_TO_CHECK = 5
+
+# Tool types that have inspectable path/keyword arguments
+TRACKABLE_TOOLS = {"Glob", "Grep", "Read", "Bash"}
+
+# Minimum anchor length to avoid false-positive matches on short strings
+MIN_ANCHOR_LENGTH = 4
+
+
+def _anchors_dir() -> Path:
+    """Return the directory for anchor temp files."""
+    return Path("/tmp/gaia-context-anchors")
+
+
+def extract_anchors(context_payload: Dict[str, Any]) -> Set[str]:
+    """Extract searchable anchor strings from a context payload.
+
+    Walks the project knowledge sections and collects values from fields that
+    are likely to appear in agent tool calls: paths, names, IDs, clusters,
+    regions, namespaces, service accounts.
+
+    Args:
+        context_payload: The full context JSON payload injected into agent prompt.
+
+    Returns:
+        Set of anchor strings (paths, names, identifiers).
+    """
+    anchors: Set[str] = set()
+    contract = context_payload.get("project_knowledge", {})
+
+    # Anchor-worthy field name patterns
+    anchor_fields = re.compile(
+        r"(path|name|cluster|project|region|namespace|service|image|"
+        r"base_path|config_path|module_path|repository|bucket|sa$|"
+        r"service_account|pod_name|terragrunt_path)",
+        re.IGNORECASE,
+    )
+
+    def _walk(obj: Any, depth: int = 0) -> None:
+        if depth > 10:
+            return
+        if isinstance(obj, dict):
+            for key, value in obj.items():
+                if isinstance(value, str) and value and anchor_fields.search(key):
+                    # Normalize: strip leading ./ for path matching
+                    clean = value.lstrip("./")
+                    if len(clean) >= MIN_ANCHOR_LENGTH:
+                        anchors.add(clean)
+                elif isinstance(value, (dict, list)):
+                    _walk(value, depth + 1)
+        elif isinstance(obj, list):
+            for item in obj:
+                _walk(item, depth + 1)
+
+    _walk(contract)
+
+    # Also extract from top-level metadata
+    metadata = context_payload.get("metadata", {})
+    for key in ("project_id", "cluster_name", "region"):
+        val = metadata.get(key)
+        if isinstance(val, str) and len(val) >= MIN_ANCHOR_LENGTH:
+            anchors.add(val)
+
+    return anchors
+
+
+def save_anchors(session_id: str, agent_type: str, anchors: Set[str]) -> Optional[Path]:
+    """Persist anchors to a session+agent-scoped temp file.
+
+    Args:
+        session_id: Current session identifier.
+        agent_type: Agent name (e.g. "terraform-architect").
+        anchors: Set of anchor strings to save.
+
+    Returns:
+        Path to the saved file, or None on failure.
+    """
+    if not anchors:
+        return None
+
+    try:
+        anchor_dir = _anchors_dir()
+        anchor_dir.mkdir(parents=True, exist_ok=True)
+
+        safe_session = re.sub(r"[^a-zA-Z0-9_-]", "_", session_id or "unknown")[:32]
+        safe_agent = re.sub(r"[^a-zA-Z0-9_-]", "_", agent_type or "unknown")[:32]
+        anchor_file = anchor_dir / f"{safe_session}-{safe_agent}.json"
+
+        anchor_file.write_text(json.dumps(sorted(anchors)))
+        logger.debug(
+            "Saved %d anchors for %s/%s -> %s",
+            len(anchors), session_id, agent_type, anchor_file,
+        )
+        return anchor_file
+    except Exception as e:
+        logger.debug("Failed to save anchors: %s", e)
+        return None
+
+
+def load_anchors(session_id: str, agent_type: str) -> Set[str]:
+    """Load persisted anchors for a session+agent.
+
+    Args:
+        session_id: Current session identifier.
+        agent_type: Agent name.
+
+    Returns:
+        Set of anchor strings, or empty set if not found.
+    """
+    try:
+        safe_session = re.sub(r"[^a-zA-Z0-9_-]", "_", session_id or "unknown")[:32]
+        safe_agent = re.sub(r"[^a-zA-Z0-9_-]", "_", agent_type or "unknown")[:32]
+        anchor_file = _anchors_dir() / f"{safe_session}-{safe_agent}.json"
+
+        if not anchor_file.exists():
+            return set()
+
+        data = json.loads(anchor_file.read_text())
+        return set(data) if isinstance(data, list) else set()
+    except Exception as e:
+        logger.debug("Failed to load anchors: %s", e)
+        return set()
+
+
+def extract_tool_calls_from_transcript(
+    transcript_path: str,
+    max_calls: int = MAX_TOOL_CALLS_TO_CHECK,
+) -> List[Dict[str, Any]]:
+    """Extract the first N trackable tool calls from a Claude Code transcript JSONL.
+
+    Claude Code transcripts contain tool_use entries in the assistant messages
+    (content blocks with type "tool_use").
+
+    Args:
+        transcript_path: Path to the transcript JSONL file.
+        max_calls: Maximum number of tool calls to extract.
+
+    Returns:
+        List of dicts with keys: tool_name, arguments (dict), call_index (1-based).
+    """
+    if not transcript_path:
+        return []
+
+    try:
+        path = Path(transcript_path).expanduser()
+        if not path.exists():
+            return []
+
+        tool_calls: List[Dict[str, Any]] = []
+        call_index = 0
+
+        for line in path.read_text().strip().splitlines():
+            if not line.strip():
+                continue
+            if call_index >= max_calls:
+                break
+
+            try:
+                entry = json.loads(line)
+                msg = entry.get("message", entry)
+
+                if msg.get("role") != "assistant":
+                    continue
+
+                content = msg.get("content", [])
+                if not isinstance(content, list):
+                    continue
+
+                for block in content:
+                    if call_index >= max_calls:
+                        break
+                    if not isinstance(block, dict):
+                        continue
+                    if block.get("type") != "tool_use":
+                        continue
+
+                    tool_name = block.get("name", "")
+                    if tool_name not in TRACKABLE_TOOLS:
+                        continue
+
+                    call_index += 1
+                    tool_calls.append({
+                        "tool_name": tool_name,
+                        "arguments": block.get("input", {}),
+                        "call_index": call_index,
+                    })
+
+            except (json.JSONDecodeError, TypeError):
+                continue
+
+        return tool_calls
+
+    except Exception as e:
+        logger.debug("Failed to extract tool calls from transcript: %s", e)
+        return []
+
+
+def _extract_searchable_text(tool_name: str, arguments: Dict[str, Any]) -> str:
+    """Extract the searchable text from a tool call's arguments.
+
+    Returns a single string containing all path/keyword-relevant arguments
+    concatenated for substring matching.
+    """
+    parts: List[str] = []
+
+    if tool_name == "Glob":
+        parts.append(arguments.get("pattern", ""))
+        parts.append(arguments.get("path", ""))
+    elif tool_name == "Grep":
+        parts.append(arguments.get("pattern", ""))
+        parts.append(arguments.get("path", ""))
+        parts.append(arguments.get("glob", ""))
+    elif tool_name == "Read":
+        parts.append(arguments.get("file_path", ""))
+    elif tool_name == "Bash":
+        parts.append(arguments.get("command", ""))
+
+    return " ".join(p for p in parts if p)
+
+
+def compute_anchor_hits(
+    tool_calls: List[Dict[str, Any]],
+    anchors: Set[str],
+) -> Dict[str, Any]:
+    """Compare tool call arguments against known anchors.
+
+    For each tool call, checks if any anchor appears as a substring in the
+    tool's searchable arguments. This is a lightweight prefix/substring match.
+
+    Args:
+        tool_calls: List from extract_tool_calls_from_transcript().
+        anchors: Set of anchor strings from extract_anchors().
+
+    Returns:
+        Dict with hit tracking data.
+    """
+    if not tool_calls or not anchors:
+        return {
+            "total_checked": len(tool_calls),
+            "hits": 0,
+            "hit_rate": 0.0,
+            "details": [],
+        }
+
+    details: List[Dict[str, Any]] = []
+    hits = 0
+
+    for call in tool_calls:
+        searchable = _extract_searchable_text(call["tool_name"], call["arguments"])
+        matched_anchor: Optional[str] = None
+
+        if searchable:
+            for anchor in anchors:
+                if anchor in searchable:
+                    matched_anchor = anchor
+                    break
+
+        is_hit = matched_anchor is not None
+        if is_hit:
+            hits += 1
+
+        details.append({
+            "call_index": call["call_index"],
+            "tool": call["tool_name"],
+            "anchor": matched_anchor,
+            "hit": is_hit,
+        })
+
+    total = len(tool_calls)
+    return {
+        "total_checked": total,
+        "hits": hits,
+        "hit_rate": round(hits / total, 2) if total > 0 else 0.0,
+        "details": details,
+    }
+
+
+def cleanup_anchors(session_id: str, agent_type: str) -> None:
+    """Remove the anchor temp file after use.
+
+    Args:
+        session_id: Current session identifier.
+        agent_type: Agent name.
+    """
+    try:
+        safe_session = re.sub(r"[^a-zA-Z0-9_-]", "_", session_id or "unknown")[:32]
+        safe_agent = re.sub(r"[^a-zA-Z0-9_-]", "_", agent_type or "unknown")[:32]
+        anchor_file = _anchors_dir() / f"{safe_session}-{safe_agent}.json"
+        if anchor_file.exists():
+            anchor_file.unlink()
+            logger.debug("Cleaned up anchor file: %s", anchor_file)
+    except Exception as e:
+        logger.debug("Failed to cleanup anchors: %s", e)

package/dist/gaia-ops/hooks/modules/context/compact_context_builder.py

@@ -0,0 +1,218 @@
+"""Compact context builder for post-compaction re-injection.
+
+Builds a lightweight context summary from session data sources.
+Each source is independent and fail-safe.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime
+from pathlib import Path
+
+from ..core.paths import get_plugin_data_dir
+
+logger = logging.getLogger(__name__)
+
+# Defaults
+DEFAULT_MAX_SNAPSHOTS = 5
+DEFAULT_ANOMALY_WINDOW_HOURS = 1
+DEFAULT_MAX_EVENTS = 5
+
+
+def build_compact_context(
+    *,
+    max_snapshots: int = DEFAULT_MAX_SNAPSHOTS,
+    anomaly_window_hours: int = DEFAULT_ANOMALY_WINDOW_HOURS,
+    max_events: int = DEFAULT_MAX_EVENTS,
+) -> str:
+    """Build compact context for post-compaction re-injection.
+
+    Returns a markdown string with 4 blocks:
+    1. Orchestrator identity reminder
+    2. Session activity summary (from run-snapshots.jsonl)
+    3. Active anomalies (from anomalies.jsonl)
+    4. Recent session events (from context.json)
+
+    Each block is independent — if a source fails, the others still produce output.
+    """
+    blocks = []
+
+    # Block 1: Orchestrator identity (always present, static)
+    blocks.append(_build_identity_block())
+
+    # Block 2: Session activity from run-snapshots.jsonl
+    activity = _build_activity_block(max_snapshots)
+    if activity:
+        blocks.append(activity)
+
+    # Block 3: Active anomalies from anomalies.jsonl
+    anomalies = _build_anomalies_block(anomaly_window_hours)
+    if anomalies:
+        blocks.append(anomalies)
+
+    # Block 4: Recent events from context.json
+    events = _build_events_block(max_events)
+    if events:
+        blocks.append(events)
+
+    return "\n\n".join(blocks)
+
+
+def _build_identity_block() -> str:
+    """Minimal post-compaction identity reminder.
+
+    Full identity lives in agents/gaia-orchestrator.md and is injected at
+    session start.  This block only restores the core posture after context
+    compaction — it intentionally does NOT list specific agents because
+    the agent roster can change and a stale list causes drift.
+    """
+    return (
+        "# Post-Compaction Context Refresh\n\n"
+        "You are the orchestrator. Dispatch work via Agent, resume agents via "
+        "SendMessage(to: agentId), get user approval via AskUserQuestion."
+    )
+
+
+def _build_activity_block(max_snapshots: int) -> str | None:
+    """Build session activity summary from run-snapshots.jsonl."""
+    snapshots_path = (
+        get_plugin_data_dir() / "project-context" / "workflow-episodic-memory" / "run-snapshots.jsonl"
+    )
+    if not snapshots_path.exists():
+        return None
+
+    try:
+        lines = snapshots_path.read_text().splitlines()
+        # Take last N lines
+        recent = lines[-max_snapshots:] if len(lines) > max_snapshots else lines
+
+        entries = []
+        for line in recent:
+            if not line.strip():
+                continue
+            try:
+                snap = json.loads(line)
+                agent = snap.get("agent", "unknown")
+                status = snap.get("plan_status", "unknown")
+                prompt = snap.get("prompt", "")[:80]
+                cmd_count = snap.get("commands_executed_count", 0)
+                entries.append(f"- {agent} → {status} ({prompt}, {cmd_count} commands)")
+            except json.JSONDecodeError:
+                continue
+
+        if not entries:
+            return None
+
+        return "## Session Activity\n" + "\n".join(entries)
+
+    except Exception as e:
+        logger.debug("Failed to build activity block (non-fatal): %s", e)
+        return None
+
+
+def _build_anomalies_block(window_hours: int) -> str | None:
+    """Build active anomalies summary from anomalies.jsonl."""
+    anomaly_path = (
+        get_plugin_data_dir() / "project-context" / "workflow-episodic-memory" / "anomalies.jsonl"
+    )
+    if not anomaly_path.exists():
+        return None
+
+    try:
+        lines = anomaly_path.read_text().splitlines()[-20:]
+        cutoff = datetime.now().timestamp() - (window_hours * 3600)
+
+        critical_types: list[str] = []
+        warning_types: list[str] = []
+
+        for line in lines:
+            if not line.strip():
+                continue
+            try:
+                entry = json.loads(line)
+                ts = entry.get("timestamp", "")
+                if ts:
+                    try:
+                        entry_time = datetime.fromisoformat(ts).timestamp()
+                        if entry_time < cutoff:
+                            continue
+                    except (ValueError, TypeError):
+                        continue
+
+                for anomaly in entry.get("anomalies", []):
+                    severity = anomaly.get("severity", "")
+                    atype = anomaly.get("type", "unknown")
+                    if severity == "critical":
+                        critical_types.append(atype)
+                    elif severity == "warning":
+                        warning_types.append(atype)
+            except json.JSONDecodeError:
+                continue
+
+        if not critical_types and not warning_types:
+            return None
+
+        parts = []
+        if critical_types:
+            unique = sorted(set(critical_types))
+            parts.append(f"- {len(critical_types)} critical: {', '.join(unique)}")
+        if warning_types:
+            unique = sorted(set(warning_types))
+            parts.append(f"- {len(warning_types)} warning: {', '.join(unique)}")
+
+        return "## Active Anomalies\n" + "\n".join(parts)
+
+    except Exception as e:
+        logger.debug("Failed to build anomalies block (non-fatal): %s", e)
+        return None
+
+
+def _build_events_block(max_events: int) -> str | None:
+    """Build recent events summary from session context.json."""
+    context_path = Path(".claude/session/active/context.json")
+    if not context_path.exists():
+        return None
+
+    try:
+        with open(context_path) as f:
+            context = json.load(f)
+
+        events = context.get("critical_events", [])
+        if not events:
+            return None
+
+        # Take last N events
+        recent = events[-max_events:]
+
+        lines = []
+        for event in recent:
+            etype = event.get("event_type", "")
+            ts = event.get("timestamp", "")[:16]
+
+            if etype == "git_commit":
+                msg = event.get("commit_message", "")
+                hash_val = event.get("commit_hash", "")[:7]
+                if hash_val and msg:
+                    lines.append(f"- [{ts}] Commit {hash_val}: {msg}")
+            elif etype == "git_push":
+                branch = event.get("branch", "")
+                if branch:
+                    lines.append(f"- [{ts}] Pushed to {branch}")
+            elif etype == "file_modifications":
+                count = event.get("modification_count", 0)
+                if count:
+                    lines.append(f"- [{ts}] Modified {count} files")
+            elif etype == "infrastructure_change":
+                cmd = event.get("command", "")
+                if cmd:
+                    lines.append(f"- [{ts}] Infrastructure: {cmd}")
+
+        if not lines:
+            return None
+
+        return "## Recent Events\n" + "\n".join(lines)
+
+    except Exception as e:
+        logger.debug("Failed to build events block (non-fatal): %s", e)
+        return None

package/dist/gaia-ops/hooks/modules/context/context_freshness.py

@@ -0,0 +1,145 @@
+"""
+Context freshness checker for SessionStart hook.
+
+Determines whether project-context.json is fresh enough to skip a rescan.
+Uses metadata.scan_config.last_scan (preferred) or file mtime as fallback.
+
+Public API:
+    - check_freshness(project_root: Path) -> FreshnessResult
+"""
+
+import json
+import logging
+import os
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Optional
+
+from ..core.paths import find_claude_dir
+
+logger = logging.getLogger(__name__)
+
+# Context freshness threshold (hours) -- env var overrides default
+DEFAULT_FRESHNESS_HOURS = 24
+
+
+@dataclass(frozen=True)
+class FreshnessResult:
+    """Result of a context freshness check."""
+
+    is_fresh: bool
+    reason: str
+    age_hours: float = 0.0
+
+
+def _get_context_path() -> Path:
+    """Return path to project-context.json."""
+    claude_dir = find_claude_dir()
+    return claude_dir / "project-context" / "project-context.json"
+
+
+def _read_staleness_from_context(context_path: Path) -> Optional[int]:
+    """Read staleness_hours from metadata.scan_config in the context file.
+
+    Returns None if the file cannot be read or the field is absent.
+    """
+    if not context_path.is_file():
+        return None
+    try:
+        with open(context_path, "r") as f:
+            data = json.load(f)
+        return (
+            int(
+                data.get("metadata", {})
+                .get("scan_config", {})
+                .get("staleness_hours", 0)
+            )
+            or None
+        )
+    except (json.JSONDecodeError, OSError, ValueError, TypeError):
+        return None
+
+
+def _get_effective_threshold() -> int:
+    """Determine the effective freshness threshold in hours."""
+    return int(
+        os.environ.get(
+            "GAIA_SCAN_STALENESS_HOURS",
+            os.environ.get("CONTEXT_FRESHNESS_HOURS", str(DEFAULT_FRESHNESS_HOURS)),
+        )
+    )
+
+
+def check_freshness(project_root: Path = None) -> FreshnessResult:
+    """Check if project-context.json exists and is fresh (< threshold).
+
+    Args:
+        project_root: Unused, kept for API compatibility. Context path
+            is resolved via find_claude_dir().
+
+    Returns:
+        FreshnessResult with is_fresh, reason, and age_hours.
+    """
+    context_path = _get_context_path()
+
+    if not context_path.exists():
+        logger.info("project-context.json not found at %s", context_path)
+        return FreshnessResult(is_fresh=False, reason="missing", age_hours=0.0)
+
+    # Determine effective threshold: env var > context file > default
+    effective_hours = _get_effective_threshold()
+    ctx_hours = _read_staleness_from_context(context_path)
+    if ctx_hours and not os.environ.get("GAIA_SCAN_STALENESS_HOURS"):
+        effective_hours = ctx_hours
+
+    try:
+        # Try metadata.scan_config.last_scan first (more accurate)
+        with open(context_path, "r") as f:
+            data = json.load(f)
+        last_scan = data.get("metadata", {}).get("scan_config", {}).get("last_scan")
+
+        if last_scan:
+            scan_dt = datetime.fromisoformat(last_scan)
+            now = datetime.now(timezone.utc)
+            age = now - scan_dt
+            age_hours = age.total_seconds() / 3600.0
+            threshold = timedelta(hours=effective_hours)
+
+            if age > threshold:
+                logger.info(
+                    "project-context.json is stale (last_scan age: %s, threshold: %sh)",
+                    age,
+                    effective_hours,
+                )
+                return FreshnessResult(
+                    is_fresh=False, reason="stale", age_hours=age_hours
+                )
+
+            logger.debug("project-context.json is fresh (last_scan age: %s)", age)
+            return FreshnessResult(
+                is_fresh=True, reason="fresh", age_hours=age_hours
+            )
+
+        # Fallback: use file mtime
+        mtime = datetime.fromtimestamp(context_path.stat().st_mtime)
+        age = datetime.now() - mtime
+        age_hours = age.total_seconds() / 3600.0
+        threshold = timedelta(hours=effective_hours)
+
+        if age > threshold:
+            logger.info(
+                "project-context.json is stale (mtime age: %s, threshold: %sh)",
+                age,
+                effective_hours,
+            )
+            return FreshnessResult(
+                is_fresh=False, reason="stale", age_hours=age_hours
+            )
+
+        logger.debug("project-context.json is fresh (mtime age: %s)", age)
+        return FreshnessResult(is_fresh=True, reason="fresh", age_hours=age_hours)
+
+    except Exception as e:
+        logger.warning("Error checking context freshness: %s", e)
+        return FreshnessResult(is_fresh=False, reason="error", age_hours=0.0)