ref-agents 1.0.0__py3-none-any.whl

ref_agents/tools/context_manager.py

@@ -0,0 +1,550 @@
+"""Context Persistence Manager for REF.
+
+This module provides hierarchical context storage across sessions:
+- Story level: Decisions, blockers, patterns for a single story
+- Epic level: Shared patterns across related stories
+- Project level: Long-term conventions and recurring fixes
+
+Context is stored as JSONL files in ref-reports/context/ directory.
+"""
+
+import json
+from dataclasses import asdict, dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+from ref_agents.utils.git_utils import get_current_user_id, get_ref_reports_dir
+
+logger = structlog.get_logger(__name__)
+
+# Default limits for context injection
+DEFAULT_LIMITS = {
+    "story": 10,
+    "epic": 5,
+    "project": 3,
+}
+
+# Max content length per entry type (chars). Enforced at write time.
+# NOTE: Agents must summarise to one sentence before storing — rationale belongs in ADRs/CODE_MAP.
+MAX_CONTENT_LENGTH: dict[str, int] = {
+    "decision": 200,
+    "pattern": 200,
+    "blocker": 150,
+    "note": 100,
+}
+
+
+@dataclass
+class ContextEntry:
+    """Single context entry.
+
+    Attributes:
+        timestamp: ISO format timestamp.
+        entry_type: decision, blocker, pattern, or note.
+        content: Human-readable description.
+        user: Who created the entry.
+        metadata: Optional additional data.
+    """
+
+    timestamp: str
+    entry_type: str
+    content: str
+    user: str
+    metadata: dict[str, Any] | None = None
+
+
+class ContextManager:
+    """Manages hierarchical context persistence.
+
+    Attributes:
+        root: Root directory for context files.
+        limits: Max entries to load per layer.
+    """
+
+    def __init__(
+        self,
+        root: Path | None = None,
+        limits: dict[str, int] | None = None,
+    ) -> None:
+        """Initialize context manager.
+
+        Args:
+            root: Context storage directory. Defaults to {project_root}/.ref_cache/context/.
+            limits: Max entries per layer. Defaults to story=10, epic=5, project=3.
+
+        Raises:
+            RuntimeError: If project root cannot be determined.
+        """
+        if root is None:
+            root = get_ref_reports_dir() / "context"
+        self.root = root
+        self.limits = limits or DEFAULT_LIMITS
+
+    def _get_file_path(self, layer: str, identifier: str | None = None) -> Path:
+        """Get file path for a context layer.
+
+        Args:
+            layer: One of 'story', 'epic', 'project', or 'incident'.
+            identifier: Story/epic/incident ID. Required for story/epic/incident, ignored for project.
+
+        Returns:
+            Path to the JSONL file.
+
+        Raises:
+            ValueError: If layer is invalid or identifier missing for story/epic.
+        """
+        if layer == "project":
+            return self.root / "project.jsonl"
+        elif layer in ("story", "epic", "incident"):
+            if not identifier:
+                raise ValueError(f"{layer} layer requires identifier")
+            return self.root / f"{layer}_{identifier}.jsonl"
+        else:
+            raise ValueError(
+                f"Invalid layer: {layer}. Use story, epic, project, or incident."
+            )
+
+    def _ensure_dir(self) -> None:
+        """Create context directory if it doesn't exist."""
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def add_entry(  # noqa: PLR0913  # TECH_DEBT: refactor to TypedDict — STORY-046
+        self,
+        layer: str,
+        entry_type: str,
+        content: str,
+        identifier: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> ContextEntry:
+        """Add a context entry.
+
+        Args:
+            layer: One of 'story', 'epic', or 'project'.
+            entry_type: Type of entry (decision, blocker, pattern, note).
+            content: Human-readable description.
+            identifier: Story/epic ID. Required for story/epic layers.
+            metadata: Optional additional data.
+
+        Returns:
+            The created ContextEntry.
+
+        Raises:
+            ValueError: If layer invalid or identifier missing.
+        """
+        self._ensure_dir()
+        file_path = self._get_file_path(layer, identifier)
+
+        max_len = MAX_CONTENT_LENGTH.get(entry_type, 200)
+        if len(content) > max_len:
+            raise ValueError(
+                f"Content too long ({len(content)} chars, max {max_len} for '{entry_type}'). "
+                "Summarise to one sentence and retry."
+            )
+
+        entry = ContextEntry(
+            timestamp=datetime.now().isoformat(),
+            entry_type=entry_type,
+            content=content,
+            user=get_current_user_id(),
+            metadata=metadata,
+        )
+
+        try:
+            with open(file_path, "a", encoding="utf-8") as f:
+                f.write(json.dumps(asdict(entry)) + "\n")
+
+            logger.info(
+                "context_entry_added",
+                layer=layer,
+                entry_type=entry_type,
+                identifier=identifier,
+            )
+        except OSError as e:
+            logger.error("context_write_failed", error=str(e), path=str(file_path))
+            raise
+
+        # Auto-sync to context graph (non-blocking — JSONL write already succeeded)
+        self._sync_to_graph(entry, identifier)
+
+        return entry
+
+    def _sync_to_graph(self, entry: ContextEntry, identifier: str | None) -> None:
+        """Mirror a JSONL entry as a context graph node.
+
+        Args:
+            entry: The entry that was just persisted.
+            identifier: Story/epic ID if applicable.
+        """
+        try:
+            from datetime import datetime, timezone
+
+            from ref_agents.tools.context_graph import ContextNode, get_context_graph
+
+            # Map JSONL entry types → valid ContextGraph node types.
+            # "blocker" and "note" are not valid NodeType values; remap them.
+            _ENTRY_TYPE_MAP: dict[str, str] = {
+                "blocker": "issue",
+                "note": "decision",
+                "pattern": "pattern",
+                "decision": "decision",
+            }
+            node_type = _ENTRY_TYPE_MAP.get(entry.entry_type, "decision")
+
+            graph = get_context_graph()
+            ts = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S%f")
+            node_id = f"{node_type}-{ts}"
+
+            node = ContextNode(
+                id=node_id,
+                node_type=node_type,  # type: ignore[arg-type]
+                content=entry.content,
+                story_id=identifier or "",
+                origin="context",
+                metadata={"user": entry.user, **(entry.metadata or {})},
+            )
+            graph.add_node(node)
+            graph.save()
+        except (OSError, ValueError) as e:
+            # Non-blocking: JSONL is source of truth; graph sync failure is recoverable
+            logger.warning("context_graph_sync_failed", error=str(e))
+
+    def get_entries(
+        self,
+        layer: str,
+        identifier: str | None = None,
+        limit: int | None = None,
+        ttl_by_type: dict[str, int] | None = None,
+    ) -> list[ContextEntry]:
+        """Get context entries for a layer.
+
+        Args:
+            layer: One of 'story', 'epic', or 'project'.
+            identifier: Story/epic ID. Required for story/epic layers.
+            limit: Max entries to return (most recent). Defaults to layer limit.
+            ttl_by_type: Optional dict of entry_type -> max age in days.
+                Only types listed are evicted; omitted types are always kept.
+                Example: {"note": 3} evicts note entries older than 3 days.
+
+        Returns:
+            List of ContextEntry objects, most recent first.
+        """
+        try:
+            file_path = self._get_file_path(layer, identifier)
+        except ValueError:
+            return []
+
+        if not file_path.exists():
+            return []
+
+        entries: list[ContextEntry] = []
+        try:
+            with open(file_path, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if line:
+                        data = json.loads(line)
+                        entries.append(ContextEntry(**data))
+        except (OSError, json.JSONDecodeError) as e:
+            logger.warning("context_read_failed", error=str(e), path=str(file_path))
+            return []
+
+        if ttl_by_type:
+            now = datetime.now()
+            kept: list[ContextEntry] = []
+            for entry in entries:
+                max_age = ttl_by_type.get(entry.entry_type)
+                if max_age is None:
+                    kept.append(entry)
+                else:
+                    try:
+                        age_days = (now - datetime.fromisoformat(entry.timestamp)).days
+                        if age_days <= max_age:
+                            kept.append(entry)
+                    except ValueError:
+                        kept.append(entry)  # unparseable timestamp → keep
+            entries = kept
+
+        max_entries = limit or self.limits.get(layer, 10)
+        return entries[-max_entries:][::-1]  # Reverse for most recent first
+
+    def get_combined_context(
+        self,
+        story_id: str | None = None,
+        epic_id: str | None = None,
+    ) -> dict[str, list[ContextEntry]]:
+        """Get combined context from all applicable layers.
+
+        Applies TTL eviction for 'note' entries (3-day TTL). All other types
+        (decision, pattern, blocker) are permanent — required for cross-agent handoff.
+
+        Args:
+            story_id: Current story ID (optional).
+            epic_id: Current epic ID (optional).
+
+        Returns:
+            Dict with 'project', 'epic', 'story' keys containing entries.
+        """
+        # NOTE: note TTL=3 days — ephemeral observations; decision/pattern/blocker: permanent
+        _note_ttl: dict[str, int] = {"note": 3}
+
+        result: dict[str, list[ContextEntry]] = {
+            "project": self.get_entries("project", ttl_by_type=_note_ttl),
+            "epic": [],
+            "story": [],
+        }
+
+        if epic_id:
+            result["epic"] = self.get_entries("epic", epic_id, ttl_by_type=_note_ttl)
+
+        if story_id:
+            result["story"] = self.get_entries("story", story_id, ttl_by_type=_note_ttl)
+
+        return result
+
+    def format_for_prompt(
+        self,
+        story_id: str | None = None,
+        epic_id: str | None = None,
+    ) -> str:
+        """Format context for injection into agent prompts.
+
+        Args:
+            story_id: Current story ID (optional).
+            epic_id: Current epic ID (optional).
+
+        Returns:
+            Formatted markdown string for prompt injection.
+        """
+        context = self.get_combined_context(story_id, epic_id)
+
+        total_entries = sum(len(v) for v in context.values())
+        if total_entries == 0:
+            return ""
+
+        lines: list[str] = [
+            "\n--- SESSION CONTEXT (from previous sessions) ---\n",
+        ]
+
+        # Project context
+        if context["project"]:
+            lines.append("**📁 Project Conventions:**")
+            for entry in context["project"]:
+                lines.append(f"• [{entry.entry_type}] {entry.content}")
+            lines.append("")
+
+        # Epic context
+        if context["epic"]:
+            lines.append(f"**📦 Epic ({epic_id}) Patterns:**")
+            for entry in context["epic"]:
+                lines.append(f"• [{entry.entry_type}] {entry.content}")
+            lines.append("")
+
+        # Story context
+        if context["story"]:
+            lines.append(f"**📝 Story ({story_id}) History:**")
+            for entry in context["story"]:
+                lines.append(f"• [{entry.entry_type}] {entry.content} ({entry.user})")
+            lines.append("")
+
+        lines.append("--- END CONTEXT ---\n")
+
+        result = "\n".join(lines)
+        logger.warning(
+            "context_injected",
+            story_id=story_id,
+            epic_id=epic_id,
+            entries=total_entries,
+            bytes=len(result.encode()),
+        )
+        return result
+
+    def prune(
+        self,
+        layer: str,
+        identifier: str | None = None,
+        keep: int = 20,
+    ) -> int:
+        """Prune old entries from a context file.
+
+        Args:
+            layer: One of 'story', 'epic', or 'project'.
+            identifier: Story/epic ID. Required for story/epic layers.
+            keep: Number of most recent entries to keep.
+
+        Returns:
+            Number of entries removed.
+        """
+        file_path = self._get_file_path(layer, identifier)
+
+        if not file_path.exists():
+            return 0
+
+        entries: list[str] = []
+        try:
+            with open(file_path, "r", encoding="utf-8") as f:
+                entries = [line.strip() for line in f if line.strip()]
+        except OSError as e:
+            logger.error("context_prune_read_failed", error=str(e))
+            return 0
+
+        if len(entries) <= keep:
+            return 0
+
+        removed = len(entries) - keep
+        kept_entries = entries[-keep:]
+
+        try:
+            with open(file_path, "w", encoding="utf-8") as f:
+                for entry in kept_entries:
+                    f.write(entry + "\n")
+
+            logger.info(
+                "context_pruned",
+                layer=layer,
+                identifier=identifier,
+                removed=removed,
+            )
+        except OSError as e:
+            logger.error("context_prune_write_failed", error=str(e))
+            return 0
+
+        return removed
+
+    def clear(self, layer: str, identifier: str | None = None) -> bool:
+        """Clear all entries for a context layer.
+
+        Args:
+            layer: One of 'story', 'epic', or 'project'.
+            identifier: Story/epic ID. Required for story/epic layers.
+
+        Returns:
+            True if cleared successfully, False otherwise.
+        """
+        file_path = self._get_file_path(layer, identifier)
+
+        if not file_path.exists():
+            return True
+
+        try:
+            file_path.unlink()
+            logger.info("context_cleared", layer=layer, identifier=identifier)
+            return True
+        except OSError as e:
+            logger.error("context_clear_failed", error=str(e))
+            return False
+
+
+# Convenience functions for tool integration
+
+# Valid actions for manage_context
+CONTEXT_ACTIONS = ("add", "get", "clear")
+
+
+def manage_context(  # noqa: PLR0913  # TECH_DEBT: refactor to TypedDict — STORY-046
+    action: str,
+    layer: str = "",
+    entry_type: str = "",
+    content: str = "",
+    identifier: str = "",
+    story_id: str = "",
+    epic_id: str = "",
+) -> str:
+    """Unified context management tool.
+
+    Args:
+        action: One of: add, get, clear.
+        layer: Context layer (story, epic, project) - for add/clear.
+        entry_type: Type: decision, blocker, pattern, note - for add.
+        content: Description of the context - for add.
+        identifier: Story/epic ID - for add/clear (required for story/epic layers).
+        story_id: Current story ID - for get.
+        epic_id: Current epic ID - for get.
+
+    Returns:
+        Success/error message or formatted context.
+    """
+    if action not in CONTEXT_ACTIONS:
+        return f"❌ Invalid action. Use: {', '.join(CONTEXT_ACTIONS)}"
+
+    manager = ContextManager()
+
+    if action == "add":
+        if not layer:
+            return "❌ 'layer' required for add action"
+        if not entry_type:
+            return "❌ 'entry_type' required for add action"
+        if not content:
+            return "❌ 'content' required for add action"
+
+        try:
+            entry = manager.add_entry(
+                layer, entry_type, content, identifier if identifier else None
+            )
+            return f"✅ Context added: [{entry.entry_type}] {entry.content}"
+        except ValueError as e:
+            return f"❌ Error: {e}"
+        except OSError as e:
+            return f"❌ Failed to save: {e}"
+
+    if action == "get":
+        formatted = manager.format_for_prompt(
+            story_id if story_id else None,
+            epic_id if epic_id else None,
+        )
+        if not formatted:
+            return "📭 No context found for this session."
+        return formatted
+
+    else:  # action == "clear"
+        if not layer:
+            return "❌ 'layer' required for clear action"
+        try:
+            success = manager.clear(layer, identifier if identifier else None)
+            if success:
+                return f"✅ Context cleared for {layer}"
+            return f"❌ Failed to clear context for {layer}"
+        except ValueError as e:
+            return f"❌ Error: {e}"
+
+
+# Backward compatibility wrappers for tests and server.py
+def add_context(
+    layer: str,
+    entry_type: str,
+    content: str,
+    identifier: str = "",
+) -> str:
+    """Add context entry (backward compatibility wrapper).
+
+    Args:
+        layer: Context layer (story, epic, project).
+        entry_type: Type: decision, blocker, pattern, note.
+        content: Description of the context.
+        identifier: Story/epic ID (required for story/epic layers).
+
+    Returns:
+        Success/error message.
+    """
+    return manage_context(
+        action="add",
+        layer=layer,
+        entry_type=entry_type,
+        content=content,
+        identifier=identifier,
+    )
+
+
+def get_context(story_id: str = "", epic_id: str = "") -> str:
+    """Get formatted context (backward compatibility wrapper).
+
+    Args:
+        story_id: Current story ID.
+        epic_id: Current epic ID.
+
+    Returns:
+        Formatted context string or empty message.
+    """
+    return manage_context(action="get", story_id=story_id, epic_id=epic_id)

ref_agents/tools/context_tools.py

@@ -0,0 +1,121 @@
+from datetime import datetime, timezone
+from pathlib import Path
+
+import structlog
+
+from ref_agents.constants import Status, AVAILABLE_AGENTS
+from ref_agents.session import SessionManager
+from ref_agents.tools import codemap
+
+logger = structlog.get_logger(__name__)
+
+
+def _format_available_agents_numbered() -> str:
+    """Private helper to format agent list as numbered list for activation."""
+    output = "🚀 REF (Relay Engineering Framework) - Agent Selection\n\n"
+    output += "Please select your agent by entering the corresponding number:\n\n"
+
+    agents_list = list(AVAILABLE_AGENTS.items())
+    for idx, (agent, desc) in enumerate(agents_list, start=1):
+        output += f"{idx}. {desc}\n"
+        output += f"   (Agent: `{agent}`)\n\n"
+
+    output += f"Enter the number (1-{len(agents_list)}) to activate your agent."
+    return output
+
+
+def set_project_root_impl(path: str) -> str:
+    """Implementation of set_project_root tool."""
+    p = Path(path).resolve()
+    if not p.exists():
+        return f"{Status.ERROR} Directory {path} does not exist"
+
+    SessionManager.get().project_root = p
+    logger.info("project_root_set", path=str(p))
+
+    return f"{Status.SUCCESS} Project root set to: `{p}`"
+
+
+def identify_agent_impl(context_history: str = "") -> str:
+    """Implementation of identify_agent tool."""
+    active_agent = SessionManager.get().active_agent
+
+    if active_agent:
+        return f"{Status.SUCCESS} Agent is active: `{active_agent}`. Proceed with REF Protocol."
+
+    agents_output = _format_available_agents_numbered()
+
+    return (
+        "⛔ STOP. No REF Agent is active.\n"
+        "You MUST ask the user:\n\n"
+        f"{agents_output}\n\n"
+        'Once they answer, call agent(action="activate", name=agent_name) or agent(action="activate", name=number).'
+    )
+
+
+def find_project_root() -> Path | None:
+    """Find the project root by looking for CODE_MAP.md.
+    Prioritizes session state -> CWD traversal.
+    """
+    # 1. Prioritize session state
+    root = SessionManager.get().project_root
+    if root:
+        return root
+
+    # 2. Fallback to CWD traversal
+    current = Path.cwd()
+    for path in [current, *current.parents]:
+        if (path / "CODE_MAP.md").exists():
+            return path
+    return None
+
+
+def generate_codemap_wrapper(directory: str) -> str:
+    """Wrapper that also sets project root context and creates context graph node."""
+    result = codemap.generate_codemap_tool(directory)
+
+    # Auto-set project root if successful
+    if "Generated" in result or "exists" in result:
+        p = Path(directory).resolve()
+        if p.exists():
+            SessionManager.get().project_root = p
+            logger.info("project_root_auto_set", path=str(p))
+
+            # Create context graph node for CODE_MAP generation
+            try:
+                from ref_agents.tools.context_graph import (
+                    ContextNode,
+                    get_context_graph,
+                )
+
+                active_agent = SessionManager.get().active_agent
+                graph = get_context_graph(p)
+                ts = datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
+                node_id = f"decision-{ts}"
+
+                content = f"Generated CODE_MAP.md for {p.name}"
+                node = ContextNode(
+                    id=node_id,
+                    node_type="decision",
+                    content=content,
+                    metadata={"directory": str(p), "agent": active_agent or "unknown"},
+                )
+                graph.add_node(node)
+
+                # Link to most recent agent_session if available
+                agent_sessions = graph.get_nodes_by_type("agent_session")
+                if agent_sessions:
+                    latest_session = max(agent_sessions, key=lambda n: n.timestamp)
+                    graph.add_edge(node_id, latest_session.id, "discovered_by")
+
+                graph.save()
+                logger.info(
+                    "codemap_decision_node_created", node_id=node_id, directory=str(p)
+                )
+            except (OSError, ValueError, ImportError) as e:
+                # Non-blocking: log error but don't fail codemap generation
+                logger.warning(
+                    "context_graph_node_failed", operation="codemap", error=str(e)
+                )
+
+    return result