agentfluent 0.1.0__py3-none-any.whl

agentfluent/config/scanner.py

@@ -0,0 +1,146 @@
+"""Agent definition scanner and parser.
+
+Discovers and parses agent `.md` files from user and project scopes.
+Agent definitions use YAML frontmatter followed by a markdown prompt body.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from agentfluent.config.models import AgentConfig, Scope
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_USER_AGENTS_DIR = Path.home() / ".claude" / "agents"
+
+
+def _parse_frontmatter(content: str) -> tuple[dict[str, Any], str]:
+    """Split a markdown file into YAML frontmatter and body.
+
+    Expects the format:
+        ---
+        yaml content
+        ---
+        markdown body
+
+    Returns (frontmatter_dict, body_string). If no valid frontmatter
+    is found, returns ({}, full_content).
+    """
+    content = content.strip()
+    if not content.startswith("---"):
+        return {}, content
+
+    # Find the closing ---
+    end_idx = content.find("---", 3)
+    if end_idx == -1:
+        return {}, content
+
+    yaml_str = content[3:end_idx].strip()
+    body = content[end_idx + 3:].strip()
+
+    try:
+        frontmatter = yaml.safe_load(yaml_str)
+    except yaml.YAMLError:
+        return {}, content
+
+    if not isinstance(frontmatter, dict):
+        return {}, content
+
+    return frontmatter, body
+
+
+def _to_string_list(value: Any) -> list[str]:
+    """Coerce a frontmatter value to a list of strings."""
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return [str(item) for item in value]
+    if isinstance(value, str):
+        return [value]
+    return []
+
+
+def parse_agent_file(path: Path, scope: Scope) -> AgentConfig | None:
+    """Parse a single agent definition `.md` file.
+
+    Returns None if the file cannot be read. Files without valid
+    frontmatter are still returned with a warning.
+    """
+    try:
+        content = path.read_text(encoding="utf-8")
+    except OSError:
+        logger.warning("Cannot read agent file: %s", path)
+        return None
+
+    frontmatter, body = _parse_frontmatter(content)
+
+    if not frontmatter:
+        logger.warning("No valid YAML frontmatter in: %s", path.name)
+
+    name = frontmatter.get("name") or path.stem
+
+    return AgentConfig(
+        name=name,
+        file_path=path.resolve(),
+        scope=scope,
+        description=str(frontmatter.get("description", "")),
+        model=frontmatter.get("model"),
+        prompt_body=body,
+        tools=_to_string_list(frontmatter.get("tools")),
+        disallowed_tools=_to_string_list(frontmatter.get("disallowedTools")),
+        mcp_servers=_to_string_list(frontmatter.get("mcpServers")),
+        hooks=frontmatter.get("hooks") or {},
+        skills=_to_string_list(frontmatter.get("skills")),
+        memory=frontmatter.get("memory"),
+        isolation=frontmatter.get("isolation"),
+        color=frontmatter.get("color"),
+        raw_frontmatter=frontmatter,
+    )
+
+
+def _scan_directory(agents_dir: Path, scope: Scope) -> list[AgentConfig]:
+    """Scan a directory for agent `.md` files."""
+    if not agents_dir.is_dir():
+        return []
+
+    agents: list[AgentConfig] = []
+    for entry in sorted(agents_dir.iterdir()):
+        if entry.is_file() and entry.suffix == ".md":
+            agent = parse_agent_file(entry, scope)
+            if agent is not None:
+                agents.append(agent)
+    return agents
+
+
+def scan_agents(
+    scope: str = "all",
+    *,
+    user_path: Path | None = None,
+    project_path: Path | None = None,
+) -> list[AgentConfig]:
+    """Discover and parse agent definition files.
+
+    Args:
+        scope: Which locations to scan -- "user", "project", or "all".
+        user_path: Override for user agents directory. Defaults to ~/.claude/agents/.
+        project_path: Override for project agents directory. Defaults to .claude/agents/.
+
+    Returns:
+        List of parsed AgentConfig objects, sorted by scope then name.
+    """
+    agents: list[AgentConfig] = []
+
+    if scope in ("user", "all"):
+        user_dir = user_path or DEFAULT_USER_AGENTS_DIR
+        agents.extend(_scan_directory(user_dir, Scope.USER))
+
+    if scope in ("project", "all"):
+        project_dir = project_path or (Path.cwd() / ".claude" / "agents")
+        agents.extend(_scan_directory(project_dir, Scope.PROJECT))
+
+    return agents

agentfluent/config/scoring.py

@@ -0,0 +1,299 @@
+"""Agent configuration scoring rubric.
+
+Scores agent definitions against best practices across four dimensions.
+Rule-based scoring (no LLM). Weights and thresholds are configurable.
+"""
+
+from __future__ import annotations
+
+import re
+
+from agentfluent.config.models import (
+    AgentConfig,
+    ConfigRecommendation,
+    ConfigScore,
+    Severity,
+)
+
+# Read-only tools suggest simpler tasks where cheaper models suffice
+READ_ONLY_TOOLS: frozenset[str] = frozenset({
+    "Read", "Glob", "Grep", "WebFetch", "WebSearch",
+})
+
+# Action verbs that indicate a well-described agent purpose
+ACTION_VERBS: frozenset[str] = frozenset({
+    "analyze", "build", "check", "create", "debug", "deploy", "design",
+    "evaluate", "extract", "fix", "generate", "implement", "investigate",
+    "manage", "monitor", "optimize", "plan", "refactor", "review",
+    "scan", "search", "test", "translate", "validate", "verify", "write",
+})
+
+# Expensive models that may be overkill for simple tasks
+EXPENSIVE_MODELS: frozenset[str] = frozenset({
+    "claude-opus-4-6", "claude-opus-4-5-20251101",
+})
+
+# Patterns suggesting structured prompt sections
+SECTION_PATTERN = re.compile(r"^#{1,3}\s+", re.MULTILINE)
+
+# Keywords suggesting error handling guidance
+ERROR_KEYWORDS: frozenset[str] = frozenset({
+    "error", "fail", "exception", "fallback", "retry", "graceful",
+    "handle", "recover", "warning",
+})
+
+# Keywords suggesting success criteria
+SUCCESS_KEYWORDS: frozenset[str] = frozenset({
+    "success", "complete", "done", "finish", "output", "return",
+    "produce", "deliver", "result", "criteria",
+})
+
+
+
+def _score_description(config: AgentConfig) -> tuple[int, list[ConfigRecommendation]]:
+    """Score the agent description quality (0-25)."""
+    score = 0
+    recs: list[ConfigRecommendation] = []
+    desc = config.description.strip()
+
+    # Present (5 pts)
+    if desc:
+        score += 5
+    else:
+        recs.append(ConfigRecommendation(
+            dimension="description",
+            severity=Severity.CRITICAL,
+            message="Agent has no description.",
+            suggested_action="Add a description that explains when to invoke this agent.",
+        ))
+        return score, recs
+
+    # Length >= 20 chars (5 pts)
+    if len(desc) >= 20:
+        score += 5
+    else:
+        recs.append(ConfigRecommendation(
+            dimension="description",
+            severity=Severity.WARNING,
+            message=f"Description is only {len(desc)} characters.",
+            current_value=desc[:50],
+            suggested_action="Expand the description to at least 20 characters.",
+        ))
+
+    # Contains action verbs (5 pts)
+    desc_lower = desc.lower()
+    if any(v in desc_lower for v in ACTION_VERBS):
+        score += 5
+    else:
+        recs.append(ConfigRecommendation(
+            dimension="description",
+            severity=Severity.INFO,
+            message="Description lacks action verbs.",
+            current_value=desc[:80],
+            suggested_action="Include verbs like 'review', 'analyze', 'create' to clarify purpose.",
+        ))
+
+    # Specific to task -- more than 50 chars suggests specificity (5 pts)
+    if len(desc) >= 50:
+        score += 5
+    else:
+        recs.append(ConfigRecommendation(
+            dimension="description",
+            severity=Severity.INFO,
+            message="Description could be more specific.",
+            current_value=desc[:80],
+            suggested_action="Add details about what tasks this agent handles and when to use it.",
+        ))
+
+    # Distinguishes from other agents -- mentions "Do NOT" or exclusions (5 pts)
+    if "not" in desc_lower or "don't" in desc_lower or "skip" in desc_lower:
+        score += 5
+
+    return score, recs
+
+
+def _score_tool_restrictions(config: AgentConfig) -> tuple[int, list[ConfigRecommendation]]:
+    """Score tool access restrictions (0-25).
+
+    Awards points for having explicit tool restrictions (both allowlist
+    and denylist), which is a best practice for agent safety.
+    """
+    score = 0
+    recs: list[ConfigRecommendation] = []
+
+    has_allowlist = len(config.tools) > 0
+    has_denylist = len(config.disallowed_tools) > 0
+
+    # Has an allowlist (10 pts)
+    if has_allowlist:
+        score += 10
+    else:
+        recs.append(ConfigRecommendation(
+            dimension="tool_restrictions",
+            severity=Severity.WARNING,
+            message="No tools allowlist defined.",
+            suggested_action="Add a 'tools' list to restrict which tools the agent can use.",
+        ))
+
+    # Has a denylist (5 pts)
+    if has_denylist:
+        score += 5
+
+    # Has either restriction (5 pts bonus for having any restriction at all)
+    if has_allowlist or has_denylist:
+        score += 5
+    else:
+        recs.append(ConfigRecommendation(
+            dimension="tool_restrictions",
+            severity=Severity.CRITICAL,
+            message="Agent has no tool restrictions at all.",
+            suggested_action=(
+                "Add 'tools' (allowlist) and/or 'disallowedTools' (denylist) "
+                "to control agent capabilities."
+            ),
+        ))
+
+    # Has MCP server awareness (5 pts) -- shows intentional integration config
+    if config.mcp_servers:
+        score += 5
+
+    return score, recs
+
+
+def _score_model_selection(config: AgentConfig) -> tuple[int, list[ConfigRecommendation]]:
+    """Score model selection (0-25).
+
+    Awards points for specifying a model and flags clearly mismatched
+    model-task combinations.
+    """
+    score = 0
+    recs: list[ConfigRecommendation] = []
+
+    # Model is specified (10 pts)
+    if config.model:
+        score += 10
+    else:
+        recs.append(ConfigRecommendation(
+            dimension="model_selection",
+            severity=Severity.WARNING,
+            message="No model specified -- defaults will be used.",
+            suggested_action="Specify a model to control cost and capability.",
+        ))
+        return score, recs
+
+    # Model-task complexity heuristic (15 pts)
+    # Only flag clearly wrong: expensive model + ALL tools are read-only
+    tools_set = set(config.tools)
+    all_read_only = tools_set and tools_set.issubset(READ_ONLY_TOOLS)
+
+    if config.model in EXPENSIVE_MODELS and all_read_only:
+        score += 5
+        recs.append(ConfigRecommendation(
+            dimension="model_selection",
+            severity=Severity.INFO,
+            message=f"Using {config.model} with only read-only tools.",
+            current_value=config.model,
+            suggested_action=(
+                "Consider a cheaper model (Sonnet/Haiku) if the task is "
+                "primarily reading and searching."
+            ),
+        ))
+    else:
+        score += 15
+
+    return score, recs
+
+
+def _score_prompt_body(config: AgentConfig) -> tuple[int, list[ConfigRecommendation]]:
+    """Score prompt body quality (0-25)."""
+    score = 0
+    recs: list[ConfigRecommendation] = []
+    body = config.prompt_body.strip()
+
+    # Present and non-empty (5 pts)
+    if body:
+        score += 5
+    else:
+        recs.append(ConfigRecommendation(
+            dimension="prompt_body",
+            severity=Severity.CRITICAL,
+            message="Agent has no prompt body.",
+            suggested_action="Add a prompt body with instructions for the agent.",
+        ))
+        return score, recs
+
+    # Length >= 100 chars (5 pts)
+    if len(body) >= 100:
+        score += 5
+    else:
+        recs.append(ConfigRecommendation(
+            dimension="prompt_body",
+            severity=Severity.WARNING,
+            message=f"Prompt body is only {len(body)} characters.",
+            suggested_action="Expand the prompt to at least 100 characters with instructions.",
+        ))
+
+    # Has structured sections (5 pts)
+    if SECTION_PATTERN.search(body):
+        score += 5
+    else:
+        recs.append(ConfigRecommendation(
+            dimension="prompt_body",
+            severity=Severity.INFO,
+            message="Prompt body has no markdown sections.",
+            suggested_action="Add ## sections to organize the prompt (e.g., responsibilities).",
+        ))
+
+    # Mentions error handling (5 pts)
+    body_lower = body.lower()
+    if any(kw in body_lower for kw in ERROR_KEYWORDS):
+        score += 5
+    else:
+        recs.append(ConfigRecommendation(
+            dimension="prompt_body",
+            severity=Severity.INFO,
+            message="Prompt body doesn't mention error handling.",
+            suggested_action="Add guidance for how the agent should handle errors or failures.",
+        ))
+
+    # Defines success criteria (5 pts)
+    if any(kw in body_lower for kw in SUCCESS_KEYWORDS):
+        score += 5
+    else:
+        recs.append(ConfigRecommendation(
+            dimension="prompt_body",
+            severity=Severity.INFO,
+            message="Prompt body doesn't define success criteria.",
+            suggested_action="Add criteria for what constitutes a successful outcome.",
+        ))
+
+    return score, recs
+
+
+
+def score_agent(config: AgentConfig) -> ConfigScore:
+    """Score an agent configuration against the best-practices rubric.
+
+    Four dimensions, each 0-25 points, for a total of 0-100.
+    """
+    all_recs: list[ConfigRecommendation] = []
+    dimension_scores: dict[str, int] = {}
+
+    for dimension_name, scorer in [
+        ("description", _score_description),
+        ("tool_restrictions", _score_tool_restrictions),
+        ("model_selection", _score_model_selection),
+        ("prompt_body", _score_prompt_body),
+    ]:
+        dim_score, dim_recs = scorer(config)
+        dimension_scores[dimension_name] = dim_score
+        all_recs.extend(dim_recs)
+
+    overall = sum(dimension_scores.values())
+
+    return ConfigScore(
+        agent_name=config.name,
+        overall_score=overall,
+        dimension_scores=dimension_scores,
+        recommendations=all_recs,
+    )

agentfluent/core/discovery.py

@@ -0,0 +1,158 @@
+"""Project and session discovery from ~/.claude/projects/."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+
+DEFAULT_PROJECTS_DIR = Path.home() / ".claude" / "projects"
+
+
+@dataclass
+class SessionInfo:
+    """Metadata for a single JSONL session file."""
+
+    filename: str
+    path: Path
+    size_bytes: int
+    modified: datetime
+    subagent_count: int = 0
+    """Number of subagent trace files in <session-uuid>/subagents/."""
+
+
+@dataclass
+class ProjectInfo:
+    """Metadata for a discovered project directory."""
+
+    slug: str
+    """Directory name as-is (e.g., '-home-fdpearce-Documents-Projects-git-codefluent')."""
+
+    display_name: str
+    """Human-friendly name derived from slug (e.g., 'codefluent')."""
+
+    path: Path
+    session_count: int = 0
+    total_size_bytes: int = 0
+    earliest_session: datetime | None = None
+    latest_session: datetime | None = None
+    sessions: list[SessionInfo] = field(default_factory=list)
+
+
+def slug_to_display_name(slug: str) -> str:
+    """Convert a dash-encoded project directory name to a human-friendly name.
+
+    The directory format is: -home-user-path-to-project
+    We take the last path segment as the display name.
+    """
+    # Remove leading dash and split
+    parts = slug.lstrip("-").split("-")
+    # The last segment is typically the project name
+    # For paths like -home-fdpearce-Documents-Projects-git-codefluent -> codefluent
+    return parts[-1] if parts else slug
+
+
+def _count_subagent_files(session_path: Path) -> int:
+    """Count subagent JSONL files for a session.
+
+    Subagent traces live at: <session-uuid>/subagents/agent-<agentId>.jsonl
+    where <session-uuid> is a directory named the same as the session file (minus .jsonl).
+    """
+    session_dir = session_path.parent / session_path.stem
+    subagents_dir = session_dir / "subagents"
+    if not subagents_dir.is_dir():
+        return 0
+    return sum(1 for f in subagents_dir.iterdir() if f.suffix == ".jsonl")
+
+
+def discover_sessions(project_path: Path) -> list[SessionInfo]:
+    """Discover all JSONL session files within a project directory.
+
+    Returns session metadata sorted by modification time (newest first).
+    Only top-level .jsonl files are returned; subagent files are counted but not listed.
+    """
+    sessions: list[SessionInfo] = []
+
+    if not project_path.is_dir():
+        return sessions
+
+    for entry in project_path.iterdir():
+        if entry.is_file() and entry.suffix == ".jsonl":
+            stat = entry.stat()
+            sessions.append(
+                SessionInfo(
+                    filename=entry.name,
+                    path=entry,
+                    size_bytes=stat.st_size,
+                    modified=datetime.fromtimestamp(stat.st_mtime, tz=UTC),
+                    subagent_count=_count_subagent_files(entry),
+                )
+            )
+
+    sessions.sort(key=lambda s: s.modified, reverse=True)
+    return sessions
+
+
+def discover_projects(base_path: Path | None = None) -> list[ProjectInfo]:
+    """Discover all projects in the Claude projects directory.
+
+    Args:
+        base_path: Override for the projects directory. Defaults to ~/.claude/projects/.
+
+    Returns:
+        List of ProjectInfo sorted by latest session (newest first).
+
+    Raises:
+        FileNotFoundError: If the base path does not exist.
+    """
+    projects_dir = base_path or DEFAULT_PROJECTS_DIR
+
+    if not projects_dir.exists():
+        msg = f"Projects directory not found: {projects_dir}"
+        raise FileNotFoundError(msg)
+
+    projects: list[ProjectInfo] = []
+
+    for entry in sorted(projects_dir.iterdir()):
+        if not entry.is_dir():
+            continue
+        # Skip hidden directories and non-project entries
+        if entry.name.startswith("."):
+            continue
+
+        sessions = discover_sessions(entry)
+
+        total_size = sum(s.size_bytes for s in sessions)
+        earliest = min((s.modified for s in sessions), default=None)
+        latest = max((s.modified for s in sessions), default=None)
+
+        projects.append(
+            ProjectInfo(
+                slug=entry.name,
+                display_name=slug_to_display_name(entry.name),
+                path=entry,
+                session_count=len(sessions),
+                total_size_bytes=total_size,
+                earliest_session=earliest,
+                latest_session=latest,
+                sessions=sessions,
+            )
+        )
+
+    # Sort by latest session, projects with no sessions last
+    projects.sort(
+        key=lambda p: p.latest_session or datetime.min.replace(tzinfo=UTC),
+        reverse=True,
+    )
+    return projects
+
+
+def find_project(slug_or_name: str, base_path: Path | None = None) -> ProjectInfo | None:
+    """Find a project by slug or display name.
+
+    Matches against both the full slug and the derived display name (case-insensitive).
+    """
+    for project in discover_projects(base_path):
+        if project.slug == slug_or_name or project.display_name.lower() == slug_or_name.lower():
+            return project
+    return None