@pennyfarthing/core 11.3.3 → 11.3.4

package/pennyfarthing-dist/pf/prime/session.py

@@ -0,0 +1,183 @@
+"""
+Session registration for Prime v2.
+
+Manages agent session files in .session/agents/ for multi-session support.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import uuid
+from pathlib import Path
+
+from pf.common.config import get_project_root
+from pf.prime.models import SessionInfo
+
+
+def get_agents_dir(project_root: Path) -> Path:
+    """Get the agents session directory.
+
+    Args:
+        project_root: Project root path
+
+    Returns:
+        Path to .session/agents/
+    """
+    return project_root / ".session" / "agents"
+
+
+def register_session(
+    agent_name: str,
+    session_id: str | None = None,
+    project_root: Path | None = None,
+) -> SessionInfo:
+    """Register an agent session.
+
+    Creates a session file in .session/agents/{session_id} containing
+    the agent name. If no session_id is provided, generates a new UUID.
+
+    Args:
+        agent_name: Name of the agent to register
+        session_id: Optional session ID (generated if not provided)
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        SessionInfo with session details
+    """
+    root = project_root or get_project_root()
+    agents_dir = get_agents_dir(root)
+
+    # Create agents directory if needed
+    agents_dir.mkdir(parents=True, exist_ok=True)
+
+    # Generate session ID if not provided
+    if not session_id:
+        # Check SESSION_ID environment variable first
+        session_id = os.environ.get("SESSION_ID")
+        if not session_id:
+            session_id = str(uuid.uuid4())
+
+    # Write agent file
+    session_file = agents_dir / session_id
+    session_file.write_text(agent_name)
+
+    return SessionInfo(
+        session_id=session_id,
+        agent_name=agent_name,
+        file_path=str(session_file),
+    )
+
+
+def cleanup_old_sessions(project_root: Path | None = None, max_age_days: int = 7) -> int:
+    """Remove stale session files.
+
+    Deletes session files older than max_age_days.
+
+    Args:
+        project_root: Project root path (auto-detected if not provided)
+        max_age_days: Maximum age in days before cleanup
+
+    Returns:
+        Number of files removed
+    """
+    root = project_root or get_project_root()
+    agents_dir = get_agents_dir(root)
+
+    if not agents_dir.is_dir():
+        return 0
+
+    cutoff = time.time() - (max_age_days * 86400)
+    removed = 0
+
+    for session_file in agents_dir.iterdir():
+        if session_file.is_file():
+            try:
+                if session_file.stat().st_mtime < cutoff:
+                    session_file.unlink()
+                    removed += 1
+            except OSError:
+                pass
+
+    return removed
+
+
+def get_session_agent(
+    session_id: str,
+    project_root: Path | None = None,
+) -> str | None:
+    """Get the agent name for a session.
+
+    Args:
+        session_id: Session ID to look up
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        Agent name, or None if session not found
+    """
+    root = project_root or get_project_root()
+    session_file = get_agents_dir(root) / session_id
+
+    if not session_file.is_file():
+        return None
+
+    return session_file.read_text().strip()
+
+
+def unregister_session(
+    session_id: str,
+    project_root: Path | None = None,
+) -> bool:
+    """Unregister an agent session.
+
+    Removes the session file.
+
+    Args:
+        session_id: Session ID to unregister
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        True if session was removed, False if not found
+    """
+    root = project_root or get_project_root()
+    session_file = get_agents_dir(root) / session_id
+
+    if not session_file.is_file():
+        return False
+
+    try:
+        session_file.unlink()
+        return True
+    except OSError:
+        return False
+
+
+def list_sessions(project_root: Path | None = None) -> list[SessionInfo]:
+    """List all active sessions.
+
+    Args:
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        List of SessionInfo for all active sessions
+    """
+    root = project_root or get_project_root()
+    agents_dir = get_agents_dir(root)
+
+    if not agents_dir.is_dir():
+        return []
+
+    sessions = []
+    for session_file in agents_dir.iterdir():
+        if session_file.is_file():
+            try:
+                agent_name = session_file.read_text().strip()
+                sessions.append(SessionInfo(
+                    session_id=session_file.name,
+                    agent_name=agent_name,
+                    file_path=str(session_file),
+                ))
+            except OSError:
+                pass
+
+    return sessions

package/pennyfarthing-dist/pf/prime/tiers.py

@@ -0,0 +1,214 @@
+"""Tiered context injection for Prime.
+
+Implements four context tiers based on session state:
+- FULL (~4000 tokens): First turn of new session
+- REFRESH (~600 tokens): Resumed session, same agent
+- HANDOFF (~700 tokens): Resumed session, different agent
+- MINIMAL (~200 tokens): Deep conversation (turn 3+), same agent
+
+Story: MSSCI-12797 - Python Prime Tier Support
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+
+def estimate_tokens(text: str) -> int:
+    """Estimate token count for a text string.
+
+    Uses character-based approximation (~4 characters per token) which is
+    reasonably accurate for English text with mixed code/prose content.
+
+    Args:
+        text: Text to estimate tokens for
+
+    Returns:
+        Estimated token count (0 for empty string)
+    """
+    if not text:
+        return 0
+    # Approximate: ~4 characters per token for cl100k_base encoding
+    # This is within 10% for typical agent context content
+    return max(1, len(text) // 4)
+
+
+from pf.prime.loader import (  # noqa: E402
+    load_agent_definition,
+    load_behavior_guide,
+    load_repos_topology,
+    load_session_context,
+    load_sidecars,
+    load_sprint_context,
+)
+from pf.prime.persona import (  # noqa: E402
+    format_persona_compressed,
+    get_crew_manifest,
+    get_user_title,
+    is_character_voice_enabled,
+    load_persona,
+)
+from pf.prime.workflow import detect_workflow_state  # noqa: E402
+
+
+class ContextTier(Enum):
+    """Context tier levels for session-aware injection."""
+
+    FULL = "FULL"
+    REFRESH = "REFRESH"
+    HANDOFF = "HANDOFF"
+    MINIMAL = "MINIMAL"
+
+
+def tier_from_string(value: str) -> ContextTier:
+    """Convert string to ContextTier enum.
+
+    Args:
+        value: Tier name (case-insensitive)
+
+    Returns:
+        ContextTier enum value
+
+    Raises:
+        ValueError: If value is not a valid tier name
+    """
+    normalized = value.upper()
+    try:
+        return ContextTier(normalized)
+    except ValueError:
+        valid = ", ".join(t.value for t in ContextTier)
+        raise ValueError(f"Invalid tier '{value}'. Must be one of: {valid}") from None
+
+
+def load_tier_components(
+    tier: ContextTier,
+    agent_name: str,
+    project_root: Path,
+) -> dict[str, Any]:
+    """Load components for the specified tier.
+
+    Component sets by tier:
+    - FULL: All components (workflow, agent, persona, guide, sprint, session, sidecars)
+    - REFRESH: Dynamic state only (workflow, sprint, session_header)
+    - HANDOFF: Agent essentials (workflow, agent, persona_compressed)
+    - MINIMAL: Routing only (workflow)
+
+    Args:
+        tier: Context tier level
+        agent_name: Name of the agent to load context for
+        project_root: Project root path
+
+    Returns:
+        Dict with:
+        - Component name -> content mappings
+        - "token_counts": Dict mapping component name to estimated token count
+        - "total_tokens": Sum of all component token counts
+    """
+    components: dict[str, Any] = {}
+    token_counts: dict[str, int] = {}
+
+    def add_component(name: str, content: str | Any) -> None:
+        """Add a component and track its token count."""
+        components[name] = content
+        # Estimate tokens for string content, 0 for structured data
+        if isinstance(content, str):
+            token_counts[name] = estimate_tokens(content)
+        else:
+            # For structured data (like WorkflowStatus), estimate from string repr
+            token_counts[name] = estimate_tokens(str(content))
+
+    # All tiers include workflow state
+    workflow_status = detect_workflow_state(project_root)
+    add_component("workflow_state", workflow_status)
+
+    if tier == ContextTier.MINIMAL:
+        # MINIMAL: Just workflow state
+        components["token_counts"] = token_counts
+        components["total_tokens"] = sum(token_counts.values())
+        return components
+
+    if tier == ContextTier.REFRESH:
+        # REFRESH: Dynamic state only
+        sprint_content = load_sprint_context(project_root)
+        if sprint_content:
+            add_component("sprint_context", sprint_content)
+
+        topology_content = load_repos_topology(project_root)
+        if topology_content:
+            add_component("repos_topology", topology_content)
+
+        session_result = load_session_context(project_root)
+        if session_result:
+            filename, header, _ = session_result
+            add_component("session_header", header)
+
+        components["token_counts"] = token_counts
+        components["total_tokens"] = sum(token_counts.values())
+        return components
+
+    if tier == ContextTier.HANDOFF:
+        # HANDOFF: Agent essentials for new agent
+        agent_content = load_agent_definition(agent_name, project_root)
+        if agent_content:
+            add_component("agent_definition", agent_content)
+
+        # Load compressed persona
+        if is_character_voice_enabled(project_root):
+            persona, theme = load_persona(agent_name, project_root)
+            if persona and theme:
+                compressed = format_persona_compressed(persona, theme, agent_name)
+                add_component("persona_compressed", compressed)
+
+        topology_content = load_repos_topology(project_root)
+        if topology_content:
+            add_component("repos_topology", topology_content)
+
+        components["token_counts"] = token_counts
+        components["total_tokens"] = sum(token_counts.values())
+        return components
+
+    # FULL tier: Everything
+    agent_content = load_agent_definition(agent_name, project_root)
+    if agent_content:
+        add_component("agent_definition", agent_content)
+
+    if is_character_voice_enabled(project_root):
+        persona, theme = load_persona(agent_name, project_root)
+        if persona and theme:
+            from pf.prime.persona import format_persona_output
+
+            crew = get_crew_manifest(project_root)
+            user_title = get_user_title(project_root)
+            persona_content = format_persona_output(
+                persona, theme, agent_name, crew, user_title
+            )
+            add_component("persona", persona_content)
+
+    guide_content = load_behavior_guide(project_root)
+    if guide_content:
+        add_component("behavior_guide", guide_content)
+
+    sprint_content = load_sprint_context(project_root)
+    if sprint_content:
+        add_component("sprint_context", sprint_content)
+
+    topology_content = load_repos_topology(project_root)
+    if topology_content:
+        add_component("repos_topology", topology_content)
+
+    session_result = load_session_context(project_root)
+    if session_result:
+        filename, header, assessment = session_result
+        add_component("session_header", header)
+        if assessment:
+            add_component("session_assessment", assessment)
+
+    sidecars = load_sidecars(agent_name, project_root)
+    if sidecars:
+        add_component("sidecars", sidecars)
+
+    components["token_counts"] = token_counts
+    components["total_tokens"] = sum(token_counts.values())
+    return components

package/pennyfarthing-dist/pf/prime/workflow.py

@@ -0,0 +1,317 @@
+"""
+Workflow state detection for Prime v2.
+
+Detects current workflow state by analyzing:
+- Active session files in .session/
+- Session headers for phase and workflow
+- Sprint backlog for available stories
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from pf.common.config import get_project_root
+from pf.prime.models import WorkflowState, WorkflowStatus
+
+
+def find_active_session(project_root: Path) -> Path | None:
+    """Find the active session file.
+
+    Looks in .session/ for *-session.md files, excluding context-*.md.
+    Returns the most recently modified session file.
+
+    Args:
+        project_root: Project root path
+
+    Returns:
+        Path to active session file, or None if not found
+    """
+    session_dir = project_root / ".session"
+    if not session_dir.is_dir():
+        return None
+
+    # Find *-session.md files (not context-*)
+    session_files = [
+        f for f in session_dir.glob("*-session.md")
+        if not f.name.startswith("context-")
+    ]
+
+    if not session_files:
+        return None
+
+    # Return the most recently modified one
+    return max(session_files, key=lambda f: f.stat().st_mtime)
+
+
+def parse_session_header(session_path: Path) -> dict[str, Any]:
+    """Parse session file header to extract metadata.
+
+    Looks for key: value patterns throughout the session file header sections.
+    Extracts workflow, phase, story_id, status from:
+    - ## Story Context section
+    - ## Workflow Phase section
+
+    Args:
+        session_path: Path to session file
+
+    Returns:
+        Dict with extracted metadata (workflow, phase, story_id, status)
+    """
+    content = session_path.read_text()
+    lines = content.split("\n")
+
+    result: dict[str, Any] = {}
+
+    # Extract story ID from filename (e.g., MSSCI-12419-session.md -> MSSCI-12419)
+    filename = session_path.stem
+    if filename.endswith("-session"):
+        result["story_id"] = filename[:-8]  # Remove "-session"
+
+    # Track which sections we're in (we care about Story Context and Workflow Phase)
+    in_relevant_section = True  # Start True to capture content before any ##
+
+    for line in lines:
+        # Track section headers
+        if line.startswith("## "):
+            # We care about Story Context and Workflow Phase sections
+            section_name = line[3:].strip().lower()
+            in_relevant_section = (
+                "story context" in section_name or
+                "workflow phase" in section_name or
+                "branch" in section_name
+            )
+            # Stop at assessment sections (too far down)
+            if "assessment" in section_name:
+                break
+            continue
+
+        # Only parse lines in relevant sections
+        if not in_relevant_section:
+            continue
+
+        # Look for key-value patterns
+        # Format is "**Key:** Value" (colon inside the bold)
+        # e.g., "- **Workflow:** tdd" or "- **Current Phase:** green"
+        match = re.search(r"\*\*([^*:]+):\*\*\s*(.+)", line)
+        if match:
+            key = match.group(1).lower().strip()
+            value = match.group(2).strip()
+
+            if key == "workflow":
+                result["workflow"] = value.lower()
+            elif key in ("current phase", "phase"):
+                # Extract phase name, handling "(APPROVED)" suffix
+                # Matches both "**Current Phase:**" and "**Phase:**"
+                phase_match = re.match(r"(\w+)(?:\s*\(([^)]+)\))?", value)
+                if phase_match:
+                    result["phase"] = phase_match.group(1).lower()
+                    if phase_match.group(2):
+                        result["phase_status"] = phase_match.group(2).lower()
+            elif key == "id" and "story_id" not in result:
+                result["story_id"] = value
+            elif key == "status":
+                result["status"] = value.lower()
+
+    return result
+
+
+def get_phase_owner(workflow: str, phase: str, project_root: Path) -> str | None:
+    """Look up the agent that owns a workflow phase.
+
+    Reads the workflow YAML and finds the agent for the given phase.
+
+    Args:
+        workflow: Workflow name (tdd, trivial, bdd, etc.)
+        phase: Phase name (setup, red, green, review, finish)
+        project_root: Project root path
+
+    Returns:
+        Agent name (sm, tea, dev, reviewer), or None if not found
+    """
+    workflow_path = project_root / "pennyfarthing-dist" / "workflows" / f"{workflow}.yaml"
+
+    if not workflow_path.exists():
+        # Fallback to symlinked location
+        workflow_path = project_root / ".pennyfarthing" / "workflows" / f"{workflow}.yaml"
+        if not workflow_path.exists():
+            return None
+
+    try:
+        data = yaml.safe_load(workflow_path.read_text())
+        phases = data.get("workflow", {}).get("phases", [])
+
+        for p in phases:
+            if p.get("name") == phase:
+                return p.get("agent")
+
+        return None
+    except Exception:
+        return None
+
+
+def get_backlog_count(project_root: Path) -> int:
+    """Count stories in backlog, ready, or planning status.
+
+    Args:
+        project_root: Project root path
+
+    Returns:
+        Number of stories available for work
+    """
+    # Import here to avoid circular imports
+    from pf.sprint.loader import load_sprint
+
+    sprint = load_sprint(project_root)
+    if not sprint or "epics" not in sprint:
+        return 0
+
+    count = 0
+    for epic in sprint["epics"]:
+        if not isinstance(epic, dict):
+            continue  # Skip string refs (defensive)
+        for story in epic.get("stories", []):
+            status = story.get("status", "").lower()
+            if status in ("backlog", "ready", "planning"):
+                count += 1
+
+    return count
+
+
+def detect_workflow_state(project_root: Path | None = None) -> WorkflowStatus:
+    """Detect the current workflow state.
+
+    Returns one of:
+    - FINISH_STATE: Session exists with phase=approved or review-approved
+    - IN_PROGRESS_STATE: Session exists with active phase
+    - NEW_WORK_STATE: No session and backlog has stories
+    - EMPTY_BACKLOG_STATE: No session and backlog is empty
+
+    Args:
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        WorkflowStatus with detected state and metadata
+    """
+    root = project_root or get_project_root()
+    session_file = find_active_session(root)
+
+    if session_file:
+        header = parse_session_header(session_file)
+        story_id = header.get("story_id")
+        workflow = header.get("workflow", "tdd")
+        phase = header.get("phase")
+        phase_status = header.get("phase_status", "")
+
+        # Check for finish state
+        if phase in ("approved", "review-approved", "finish"):
+            return WorkflowStatus(
+                state=WorkflowState.FINISH_STATE,
+                story_id=story_id,
+                phase=phase,
+                phase_owner="sm",
+                workflow=workflow,
+                session_file=str(session_file),
+            )
+
+        # Check if phase is approved (e.g., "REVIEW (APPROVED)")
+        if phase_status == "approved":
+            return WorkflowStatus(
+                state=WorkflowState.FINISH_STATE,
+                story_id=story_id,
+                phase=phase,
+                phase_owner="sm",
+                workflow=workflow,
+                session_file=str(session_file),
+            )
+
+        # In progress state - look up phase owner
+        owner = get_phase_owner(workflow, phase, root) if phase else None
+
+        return WorkflowStatus(
+            state=WorkflowState.IN_PROGRESS_STATE,
+            story_id=story_id,
+            phase=phase,
+            phase_owner=owner,
+            workflow=workflow,
+            session_file=str(session_file),
+        )
+
+    # No active session - check backlog
+    backlog_count = get_backlog_count(root)
+
+    if backlog_count > 0:
+        return WorkflowStatus(
+            state=WorkflowState.NEW_WORK_STATE,
+            backlog_count=backlog_count,
+        )
+
+    return WorkflowStatus(
+        state=WorkflowState.EMPTY_BACKLOG_STATE,
+    )
+
+
+def check_redirect(workflow_status: WorkflowStatus, agent_name: str) -> tuple[str, str] | None:
+    """Check if the activated agent should redirect to another agent.
+
+    Returns redirect info if:
+    - IN_PROGRESS_STATE and agent_name != phase_owner
+
+    Args:
+        workflow_status: Current workflow status
+        agent_name: Name of the activated agent
+
+    Returns:
+        Tuple of (target_agent, reason) if redirect needed, None otherwise
+    """
+    if workflow_status.state == WorkflowState.IN_PROGRESS_STATE:
+        if workflow_status.phase_owner and workflow_status.phase_owner != agent_name:
+            return (
+                workflow_status.phase_owner,
+                f"Phase '{workflow_status.phase}' is owned by '{workflow_status.phase_owner}'",
+            )
+
+    return None
+
+
+def get_phase_tandem_config(
+    workflow_name: str, phase_name: str, project_root: Path | None = None
+) -> dict[str, Any] | None:
+    """Extract tandem configuration for a specific workflow phase.
+
+    Reads the workflow YAML and returns the tandem block for the given phase,
+    or None if the phase has no tandem configuration.
+
+    Args:
+        workflow_name: Workflow name (tdd-tandem, bdd-tandem, etc.)
+        phase_name: Phase name (red, green, review, etc.)
+        project_root: Project root path (auto-detected if not provided)
+
+    Returns:
+        Dict with tandem config (partner, mode, model, token_budget, triggers, scope)
+        or None if no tandem config on this phase.
+    """
+    root = project_root or get_project_root()
+    workflow_path = root / "pennyfarthing-dist" / "workflows" / f"{workflow_name}.yaml"
+
+    if not workflow_path.exists():
+        return None
+
+    try:
+        data = yaml.safe_load(workflow_path.read_text())
+        phases = data.get("workflow", {}).get("phases", [])
+
+        for phase in phases:
+            if isinstance(phase, dict) and phase.get("name") == phase_name:
+                tandem = phase.get("tandem")
+                if isinstance(tandem, dict):
+                    return dict(tandem)
+                return None
+
+        return None
+    except Exception:
+        return None