@jaguilar87/gaia 5.0.0-rc1

package/dist/gaia-ops/hooks/modules/audit/workflow_recorder.py

@@ -0,0 +1,296 @@
+"""
+Workflow metrics capture and persistence.
+
+Renamed from metrics_recorder.py for clarity.
+
+Provides:
+    - get_workflow_memory_dir(): Resolve workflow memory directory
+    - record(): Build metrics dict, write to JSONL
+"""
+
+import json
+import logging
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from ..context.context_injector import build_context_telemetry_snapshot
+from ..core.paths import get_plugin_data_dir
+
+logger = logging.getLogger(__name__)
+
+
+def get_workflow_memory_dir() -> Path:
+    """
+    Get workflow memory directory path.
+
+    Resolution order:
+    1. WORKFLOW_MEMORY_BASE_PATH env var (testing override)
+    2. CLAUDE_PLUGIN_DATA / project-context / workflow-episodic-memory
+    3. .claude/project-context/workflow-episodic-memory (backward compat)
+    """
+    base_path = os.environ.get("WORKFLOW_MEMORY_BASE_PATH")
+    if base_path:
+        return Path(base_path) / "project-context" / "workflow-episodic-memory"
+    return get_plugin_data_dir() / "project-context" / "workflow-episodic-memory"
+
+
+def _append_jsonl(path: Path, payload: Dict[str, Any]) -> None:
+    """Append one JSON record per line."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "a") as f:
+        f.write(json.dumps(payload) + "\n")
+
+
+def _parse_frontmatter(text: str) -> Dict[str, Any]:
+    """Parse simple markdown frontmatter without external dependencies."""
+    if not text.startswith("---"):
+        return {}
+
+    try:
+        end = text.index("---", 3)
+    except ValueError:
+        return {}
+
+    frontmatter = text[3:end]
+    result: Dict[str, Any] = {}
+    current_key: Optional[str] = None
+    current_list: Optional[List[str]] = None
+
+    for line in frontmatter.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        if stripped.startswith("- ") and current_key and current_list is not None:
+            current_list.append(stripped[2:].strip())
+            continue
+
+        if ":" in stripped:
+            if current_key and current_list is not None:
+                result[current_key] = current_list
+
+            key, _, value = stripped.partition(":")
+            key = key.strip()
+            value = value.strip()
+
+            if value:
+                result[key] = value
+                current_key = key
+                current_list = None
+            else:
+                current_key = key
+                current_list = []
+
+    if current_key and current_list is not None:
+        result[current_key] = current_list
+
+    return result
+
+
+def _parse_tools_field(value: Any) -> List[str]:
+    """Normalize frontmatter tools into a list."""
+    if isinstance(value, list):
+        return [item for item in value if isinstance(item, str) and item.strip()]
+    if isinstance(value, str):
+        return [item.strip() for item in value.split(",") if item.strip()]
+    return []
+
+
+def _resolve_agent_file(agent_type: str) -> Optional[Path]:
+    """Resolve the markdown definition for a project agent."""
+    if not agent_type:
+        return None
+
+    candidates = [
+        Path(".claude/agents") / f"{agent_type}.md",
+        Path(__file__).resolve().parents[3] / "agents" / f"{agent_type}.md",
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def load_agent_runtime_profile(agent_type: str) -> Dict[str, Any]:
+    """Load runtime-default metadata from an agent definition file."""
+    agent_file = _resolve_agent_file(agent_type)
+    if not agent_file:
+        return {
+            "agent": agent_type or "unknown",
+            "model": "",
+            "tools": [],
+            "skills": [],
+            "skills_count": 0,
+        }
+
+    frontmatter = _parse_frontmatter(agent_file.read_text())
+    skills = frontmatter.get("skills", [])
+    if not isinstance(skills, list):
+        skills = []
+
+    return {
+        "agent": agent_type or "unknown",
+        "model": frontmatter.get("model", ""),
+        "tools": _parse_tools_field(frontmatter.get("tools", [])),
+        "skills": skills,
+        "skills_count": len(skills),
+    }
+
+
+def record_agent_skill_snapshot(
+    agent_type: str,
+    session_context: Optional[Dict[str, Any]] = None,
+    task_description: str = "",
+) -> Dict[str, Any]:
+    """Persist a historical snapshot of an agent's runtime defaults."""
+    session_context = session_context or {}
+    profile = load_agent_runtime_profile(agent_type)
+    snapshot = {
+        "timestamp": session_context.get("timestamp", datetime.now().isoformat()),
+        "session_id": session_context.get("session_id", ""),
+        "agent": profile.get("agent", agent_type or "unknown"),
+        "task_description": task_description[:200],
+        "model": profile.get("model", ""),
+        "tools": profile.get("tools", []),
+        "skills": profile.get("skills", []),
+        "skills_count": profile.get("skills_count", 0),
+    }
+
+    try:
+        _append_jsonl(get_workflow_memory_dir() / "agent-skills.jsonl", snapshot)
+    except Exception as exc:
+        logger.debug("Could not persist agent skill snapshot: %s", exc)
+
+    return snapshot
+
+
+def record(
+    task_info: Dict[str, Any],
+    agent_output: str,
+    session_context: Dict[str, Any],
+    commands_executed: Optional[List[str]] = None,
+    context_update_result: Optional[Dict[str, Any]] = None,
+    anchor_hits: Optional[Dict[str, Any]] = None,
+    transcript_analysis: Optional[Any] = None,
+    compliance_result: Optional[Any] = None,
+) -> Dict[str, Any]:
+    """
+    Capture workflow execution metrics for analysis.
+
+    Args:
+        task_info: Task metadata
+        agent_output: Output from agent execution
+        session_context: Current session context
+        commands_executed: List of commands the agent executed.
+        context_update_result: Result of context update processing.
+        anchor_hits: Context anchor hit data.
+        transcript_analysis: Optional TranscriptAnalysis from transcript_analyzer.
+            When provided, real token counts and tool metrics are added to the
+            metrics dict alongside the existing output_tokens_approx.
+        compliance_result: Optional ComplianceScore from transcript_analyzer.
+            When provided, compliance_score and compliance_grade are added.
+
+    Returns:
+        Dict with duration, exit_code, agent, tier, etc.
+    """
+    # Duration cannot be reliably measured from within this hook because
+    # it fires only at agent completion (no start timestamp available).
+    duration_ms = None
+
+    # Use exit_code from task_info (derived from AGENT_STATUS block) instead
+    # of naive text matching which gives false positives on "No errors found".
+    exit_code = task_info.get("exit_code", 0)
+
+    # Approximate token count: 4 chars per token is a reliable heuristic for LLM output
+    output_tokens_approx = len(agent_output) // 4
+
+    commands_executed = commands_executed or []
+    context_update_result = context_update_result or {}
+    context_snapshot = build_context_telemetry_snapshot(
+        task_info.get("injected_context") or {}
+    )
+    default_skills_snapshot = load_agent_runtime_profile(task_info.get("agent", "unknown"))
+
+    metrics = {
+        "timestamp": session_context["timestamp"],
+        "session_id": session_context["session_id"],
+        "task_id": task_info.get("task_id", "unknown"),
+        "agent_id": task_info.get("agent_id", "unknown"),
+        "agent": task_info.get("agent", "unknown"),
+        "tier": task_info.get("tier", "T0"),
+        "duration_ms": duration_ms,
+        "exit_code": exit_code,
+        "plan_status": task_info.get("plan_status", ""),
+        "output_length": len(agent_output),
+        "output_tokens_approx": output_tokens_approx,
+        "tags": task_info.get("tags", []),
+        "prompt": task_info.get("description", ""),  # Store for episodic
+        "commands_executed": commands_executed,
+        "commands_executed_count": len(commands_executed),
+        "context_snapshot": context_snapshot,
+        "context_updated": bool(context_update_result.get("updated", False)),
+        "context_sections_updated": context_update_result.get("sections_updated", []),
+        "context_rejected_sections": context_update_result.get("rejected", []),
+        "default_skills_snapshot": default_skills_snapshot,
+        "context_anchor_hits": anchor_hits,
+        "context_anchor_hit_rate": anchor_hits.get("hit_rate") if anchor_hits else None,
+    }
+
+    # --- Transcript-analysis enrichment (T010) ---
+    if transcript_analysis is not None:
+        metrics["input_tokens"] = transcript_analysis.input_tokens
+        metrics["cache_creation_tokens"] = transcript_analysis.cache_creation_tokens
+        metrics["cache_read_tokens"] = transcript_analysis.cache_read_tokens
+        metrics["output_tokens_real"] = transcript_analysis.output_tokens
+        metrics["duration_ms"] = transcript_analysis.duration_ms
+        metrics["tool_call_count"] = transcript_analysis.tool_call_count
+        metrics["skills_injected"] = transcript_analysis.skills_injected
+        metrics["model_used"] = transcript_analysis.model
+        metrics["api_call_count"] = transcript_analysis.api_call_count
+
+    # --- Compliance enrichment (T010) ---
+    if compliance_result is not None:
+        metrics["compliance_score"] = compliance_result.total
+        metrics["compliance_grade"] = compliance_result.grade
+
+    run_snapshot = {
+        "timestamp": metrics["timestamp"],
+        "session_id": metrics["session_id"],
+        "task_id": metrics["task_id"],
+        "agent_id": metrics["agent_id"],
+        "agent": metrics["agent"],
+        "tier": metrics["tier"],
+        "plan_status": metrics["plan_status"],
+        "context_snapshot": context_snapshot,
+        "context_updated": metrics["context_updated"],
+        "context_sections_updated": metrics["context_sections_updated"],
+        "context_rejected_sections": metrics["context_rejected_sections"],
+        "default_skills_snapshot": default_skills_snapshot,
+        "context_anchor_hits": anchor_hits,
+        "context_anchor_hit_rate": anchor_hits.get("hit_rate") if anchor_hits else None,
+    }
+
+    try:
+        workflow_memory_dir = get_workflow_memory_dir()
+        workflow_memory_dir.mkdir(parents=True, exist_ok=True)
+        _append_jsonl(workflow_memory_dir / "run-snapshots.jsonl", run_snapshot)
+    except Exception as exc:
+        logger.debug("Could not persist run telemetry snapshot: %s", exc)
+
+    # Save to workflow memory (gated behind env var; default: no write)
+    if os.environ.get("GAIA_WRITE_WORKFLOW_METRICS") == "1":
+        workflow_memory_dir = get_workflow_memory_dir()
+        workflow_memory_dir.mkdir(parents=True, exist_ok=True)
+
+        metrics_file = workflow_memory_dir / "metrics.jsonl"
+        with open(metrics_file, "a") as f:
+            f.write(json.dumps(metrics) + "\n")
+
+    logger.debug(
+        "Captured workflow metrics: %s (duration: %sms, exit: %s, commands: %s)",
+        metrics["agent"], duration_ms, exit_code, len(commands_executed),
+    )
+
+    return metrics

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

@@ -0,0 +1,11 @@
+"""
+Context Management Module
+
+This module provides tools for managing context in agent conversations:
+- context_writer: Progressive enrichment of project-context.json via CONTEXT_UPDATE blocks
+- contracts_loader: Load context contracts, detect cloud provider, merge agent permissions
+- context_injector: Core context injection subsystem for project agents
+- context_freshness: Check staleness of project-context.json for SessionStart
+"""
+
+__all__ = []

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

@@ -0,0 +1,165 @@
+"""Agentic loop state detector.
+
+Lightweight, fail-safe detection of an active agentic-loop session in the
+current working directory.  Used by UserPromptSubmit and PreCompact hooks to
+inject recovery context when the loop is running.
+
+Design constraints:
+- Non-blocking: never raises, returns empty string on failure
+- Lightweight: only file existence + small JSON reads
+- Safe: malformed or missing files are silently skipped
+- Staleness guard: states older than 24 hours are ignored
+"""
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# How old a state file can be before it's considered stale
+STALE_HOURS = 24
+
+# Candidate locations to search for loop state, relative to cwd
+_STATE_CANDIDATES = [
+    "agentic_loop_state.json",
+    "state.json",
+    "tests/agentic_loop_state.json",
+    "tests/state.json",
+]
+
+
+def _parse_state(path: Path) -> Optional[dict]:
+    """Read and parse the JSON state file.  Returns None on any error."""
+    try:
+        text = path.read_text(encoding="utf-8")
+        return json.loads(text)
+    except Exception:
+        return None
+
+
+def _is_stale(state: dict) -> bool:
+    """Return True if the state's timestamp is older than STALE_HOURS."""
+    ts = state.get("timestamp")
+    if not ts:
+        # No timestamp -- treat as fresh so we don't silently skip real state
+        return False
+    try:
+        ts_clean = ts.replace("Z", "+00:00")
+        state_time = datetime.fromisoformat(ts_clean)
+        if state_time.tzinfo is None:
+            state_time = state_time.replace(tzinfo=timezone.utc)
+        now = datetime.now(tz=timezone.utc)
+        age_hours = (now - state_time).total_seconds() / 3600
+        return age_hours > STALE_HOURS
+    except Exception:
+        return False
+
+
+def _is_agentic_loop_state(state: dict) -> bool:
+    """Return True if the state dict looks like an agentic-loop state file.
+
+    Checks for the presence of key fields that distinguish agentic-loop
+    state from unrelated state.json files (e.g., Node.js build state).
+    """
+    loop_fields = {"eval_command", "metric", "threshold", "iteration"}
+    return bool(loop_fields & state.keys())
+
+
+def find_active_loop(cwd: Optional[Path] = None) -> Optional[dict]:
+    """Search for an active agentic-loop state file.
+
+    Returns the parsed state dict if found, active (not terminal status),
+    and not stale.  Returns None otherwise.
+
+    Args:
+        cwd: Working directory to search.  Defaults to Path.cwd().
+    """
+    base = cwd or Path.cwd()
+
+    for candidate in _STATE_CANDIDATES:
+        path = base / candidate
+        if not path.exists():
+            continue
+
+        state = _parse_state(path)
+        if state is None:
+            continue
+
+        if not _is_agentic_loop_state(state):
+            continue
+
+        status = state.get("status", "")
+        if status in ("complete", "threshold_reached", "max_iterations", "stopped"):
+            logger.debug("Agentic loop at %s is terminal (status=%s), skipping", path, status)
+            continue
+
+        if _is_stale(state):
+            logger.debug("Agentic loop at %s is stale (>%dh), skipping", path, STALE_HOURS)
+            continue
+
+        logger.info("Active agentic loop found: %s (status=%s, iter=%s)", path, status, state.get("iteration"))
+        return state
+
+    return None
+
+
+def build_resume_context(cwd: Optional[Path] = None) -> str:
+    """Build the additionalContext block for an active agentic loop.
+
+    Returns an empty string if no active loop is found.
+    Silently handles all errors.
+    """
+    try:
+        state = find_active_loop(cwd)
+        if state is None:
+            return ""
+
+        iteration = state.get("iteration", "?")
+        current = state.get("current", state.get("best", "?"))
+        threshold = state.get("threshold", "?")
+        metric = state.get("metric", "metric")
+        goal = state.get("goal", "")
+
+        lines = [
+            "## Active Agentic Loop",
+        ]
+        if goal:
+            lines.append(f"Goal: {goal}")
+        lines.extend([
+            "You are in an agentic-loop session. Read state.json for your objective and progress.",
+            f"Current iteration: {iteration}, {metric}: {current}, target: {threshold}. NEVER STOP until threshold or max_iterations.",
+        ])
+
+        return "\n".join(lines)
+
+    except Exception as e:
+        logger.debug("build_resume_context failed (non-fatal): %s", e)
+        return ""
+
+
+def build_precompact_prompt(cwd: Optional[Path] = None) -> str:
+    """Build the pre-compaction instruction block for an active agentic loop.
+
+    Returns an empty string if no active loop is found.
+    Silently handles all errors.
+    """
+    try:
+        state = find_active_loop(cwd)
+        if state is None:
+            return ""
+
+        return (
+            "IMPORTANT: You are in an agentic-loop. Before context compaction:\n"
+            "1. Write continue.md with: completed work, remaining steps, current iteration, decisions made, next action\n"
+            "2. Update state.json with current progress\n"
+            "3. Update worklog.md with latest run if not already logged\n"
+            "Do this NOW before your context is compacted."
+        )
+
+    except Exception as e:
+        logger.debug("build_precompact_prompt failed (non-fatal): %s", e)
+        return ""