spec-kitty-cli 0.12.1__py3-none-any.whl

specify_cli/orchestrator/agent_config.py

@@ -0,0 +1,224 @@
+"""Agent configuration for the orchestrator.
+
+This module manages agent configuration that is set during `spec-kitty init`
+and used by the orchestrator to select agents for implementation and review.
+
+The configuration is stored in .kittify/config.yaml under the `agents` key.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from ruamel.yaml import YAML
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class SelectionStrategy(str, Enum):
+    """Strategy for selecting agents."""
+
+    PREFERRED = "preferred"  # Use user-specified preferred agents
+    RANDOM = "random"  # Randomly select from available agents
+
+
+@dataclass
+class AgentSelectionConfig:
+    """Configuration for agent selection.
+
+    Attributes:
+        strategy: How to select agents (preferred or random)
+        preferred_implementer: Agent ID for implementation (if strategy=preferred)
+        preferred_reviewer: Agent ID for review (if strategy=preferred)
+    """
+
+    strategy: SelectionStrategy = SelectionStrategy.PREFERRED
+    preferred_implementer: str | None = None
+    preferred_reviewer: str | None = None
+
+
+@dataclass
+class AgentConfig:
+    """Full agent configuration.
+
+    Attributes:
+        available: List of agent IDs that are available for use
+        selection: Configuration for how to select agents
+    """
+
+    available: list[str] = field(default_factory=list)
+    selection: AgentSelectionConfig = field(default_factory=AgentSelectionConfig)
+
+    def select_implementer(self, exclude: str | None = None) -> str | None:
+        """Select an agent for implementation.
+
+        Args:
+            exclude: Optional agent ID to exclude from selection
+
+        Returns:
+            Selected agent ID or None if no agents available
+        """
+        candidates = [a for a in self.available if a != exclude]
+        if not candidates:
+            return None
+
+        if self.selection.strategy == SelectionStrategy.PREFERRED:
+            if self.selection.preferred_implementer in candidates:
+                return self.selection.preferred_implementer
+            # Fall back to first available
+            return candidates[0]
+        else:  # RANDOM
+            return random.choice(candidates)
+
+    def select_reviewer(self, implementer: str | None = None) -> str | None:
+        """Select an agent for review.
+
+        Prefers a different agent than the implementer for cross-review.
+
+        Args:
+            implementer: Agent that did implementation (prefer different agent)
+
+        Returns:
+            Selected agent ID or None if no agents available
+        """
+        # Prefer different agent for cross-review
+        candidates = [a for a in self.available if a != implementer]
+
+        # Fall back to same agent if no other available
+        if not candidates:
+            candidates = self.available.copy()
+
+        if not candidates:
+            return None
+
+        if self.selection.strategy == SelectionStrategy.PREFERRED:
+            if self.selection.preferred_reviewer in candidates:
+                return self.selection.preferred_reviewer
+            # Fall back to first available that's not the implementer
+            return candidates[0]
+        else:  # RANDOM
+            return random.choice(candidates)
+
+
+def load_agent_config(repo_root: Path) -> AgentConfig:
+    """Load agent configuration from .kittify/config.yaml.
+
+    Args:
+        repo_root: Repository root directory
+
+    Returns:
+        AgentConfig instance (defaults if not configured)
+    """
+    config_file = repo_root / ".kittify" / "config.yaml"
+
+    if not config_file.exists():
+        logger.warning(f"Config file not found: {config_file}")
+        return AgentConfig()
+
+    yaml = YAML()
+    yaml.preserve_quotes = True
+
+    try:
+        with open(config_file, "r") as f:
+            data = yaml.load(f) or {}
+    except Exception as e:
+        logger.error(f"Failed to load config: {e}")
+        return AgentConfig()
+
+    agents_data = data.get("agents", {})
+    if not agents_data:
+        logger.info("No agents section in config.yaml")
+        return AgentConfig()
+
+    # Parse available agents
+    available = agents_data.get("available", [])
+    if isinstance(available, str):
+        available = [available]
+
+    # Parse selection config
+    selection_data = agents_data.get("selection", {})
+    strategy_str = selection_data.get("strategy", "preferred")
+    try:
+        strategy = SelectionStrategy(strategy_str)
+    except ValueError:
+        logger.warning(f"Invalid strategy '{strategy_str}', defaulting to 'preferred'")
+        strategy = SelectionStrategy.PREFERRED
+
+    selection = AgentSelectionConfig(
+        strategy=strategy,
+        preferred_implementer=selection_data.get("preferred_implementer"),
+        preferred_reviewer=selection_data.get("preferred_reviewer"),
+    )
+
+    return AgentConfig(available=available, selection=selection)
+
+
+def save_agent_config(repo_root: Path, config: AgentConfig) -> None:
+    """Save agent configuration to .kittify/config.yaml.
+
+    Merges with existing config (preserves other sections like vcs).
+
+    Args:
+        repo_root: Repository root directory
+        config: AgentConfig to save
+    """
+    config_dir = repo_root / ".kittify"
+    config_file = config_dir / "config.yaml"
+
+    yaml = YAML()
+    yaml.preserve_quotes = True
+
+    # Load existing config or create new
+    if config_file.exists():
+        with open(config_file, "r") as f:
+            data = yaml.load(f) or {}
+    else:
+        data = {}
+        config_dir.mkdir(parents=True, exist_ok=True)
+
+    # Update agents section
+    data["agents"] = {
+        "available": config.available,
+        "selection": {
+            "strategy": config.selection.strategy.value,
+            "preferred_implementer": config.selection.preferred_implementer,
+            "preferred_reviewer": config.selection.preferred_reviewer,
+        },
+    }
+
+    # Write back
+    with open(config_file, "w") as f:
+        yaml.dump(data, f)
+
+    logger.info(f"Saved agent config to {config_file}")
+
+
+def get_configured_agents(repo_root: Path) -> list[str]:
+    """Get list of configured agents.
+
+    This is the DEFINITIVE list of available agents, set during init.
+
+    Args:
+        repo_root: Repository root directory
+
+    Returns:
+        List of agent IDs, empty if not configured
+    """
+    config = load_agent_config(repo_root)
+    return config.available
+
+
+__all__ = [
+    "SelectionStrategy",
+    "AgentSelectionConfig",
+    "AgentConfig",
+    "load_agent_config",
+    "save_agent_config",
+    "get_configured_agents",
+]

specify_cli/orchestrator/agents/__init__.py

@@ -0,0 +1,170 @@
+"""Agent invokers for the orchestrator.
+
+This subpackage contains implementations of AgentInvoker for each supported
+AI coding agent. Each invoker knows how to:
+    - Build the command line for that agent
+    - Pipe prompts via stdin or file
+    - Parse output and detect success/failure
+
+Supported Agents (9 total):
+    Core (WP02):
+    - claude-code: Claude Code (Anthropic)
+    - codex: GitHub Codex
+    - copilot: GitHub Copilot
+    - gemini: Google Gemini
+
+    Additional (WP03):
+    - qwen: Qwen Code
+    - opencode: OpenCode
+    - kilocode: Kilocode
+    - augment: Augment Code (auggie)
+    - cursor: Cursor (with timeout wrapper)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from specify_cli.orchestrator.agents.augment import AugmentInvoker
+from specify_cli.orchestrator.agents.base import (
+    AgentInvoker,
+    BaseInvoker,
+    InvocationResult,
+)
+from specify_cli.orchestrator.agents.claude import ClaudeInvoker
+from specify_cli.orchestrator.agents.codex import CodexInvoker
+from specify_cli.orchestrator.agents.copilot import CopilotInvoker
+from specify_cli.orchestrator.agents.cursor import CursorInvoker
+from specify_cli.orchestrator.agents.gemini import GeminiInvoker
+from specify_cli.orchestrator.agents.kilocode import KilocodeInvoker
+from specify_cli.orchestrator.agents.opencode import OpenCodeInvoker
+from specify_cli.orchestrator.agents.qwen import QwenInvoker
+
+if TYPE_CHECKING:
+    pass
+
+# Registry mapping agent IDs to invoker classes
+AGENT_REGISTRY: dict[str, type[BaseInvoker]] = {
+    "claude-code": ClaudeInvoker,
+    "codex": CodexInvoker,
+    "copilot": CopilotInvoker,
+    "gemini": GeminiInvoker,
+    "qwen": QwenInvoker,
+    "opencode": OpenCodeInvoker,
+    "kilocode": KilocodeInvoker,
+    "augment": AugmentInvoker,
+    "cursor": CursorInvoker,
+}
+
+# Aliases for user-friendly names to canonical registry names
+# These match the keys used in AI_CHOICES (core/config.py) and .kittify/config.yaml
+AGENT_ALIASES: dict[str, str] = {
+    "claude": "claude-code",  # User-facing name -> registry name
+    "auggie": "augment",      # Alternative name used in gitignore_manager
+}
+
+# Priority order for agent selection (lower index = higher priority)
+# Based on feature 019 research recommendations
+AGENT_PRIORITY_ORDER = [
+    "claude-code",
+    "codex",
+    "copilot",
+    "gemini",
+    "qwen",
+    "opencode",
+    "kilocode",
+    "augment",
+    "cursor",
+]
+
+
+def normalize_agent_id(agent_id: str) -> str:
+    """Normalize agent ID to canonical registry name.
+
+    Resolves user-friendly aliases (e.g., "claude" -> "claude-code").
+
+    Args:
+        agent_id: User-provided agent ID (may be an alias).
+
+    Returns:
+        Canonical agent ID used in AGENT_REGISTRY.
+    """
+    return AGENT_ALIASES.get(agent_id, agent_id)
+
+
+def get_invoker(agent_id: str) -> BaseInvoker:
+    """Get invoker instance for agent ID.
+
+    Args:
+        agent_id: The agent identifier (e.g., "claude-code", "codex").
+                  Aliases like "claude" are automatically resolved.
+
+    Returns:
+        Instantiated invoker for the specified agent.
+
+    Raises:
+        ValueError: If agent_id is not recognized.
+    """
+    # Resolve aliases to canonical names
+    canonical_id = normalize_agent_id(agent_id)
+
+    invoker_class = AGENT_REGISTRY.get(canonical_id)
+    if not invoker_class:
+        valid_agents = ", ".join(sorted(AGENT_REGISTRY.keys()))
+        # Include aliases in the error message for clarity
+        alias_info = ", ".join(f"{k}->{v}" for k, v in AGENT_ALIASES.items())
+        raise ValueError(
+            f"Unknown agent: {agent_id}. Valid agents: {valid_agents}. "
+            f"Aliases: {alias_info}"
+        )
+    return invoker_class()
+
+
+def detect_installed_agents() -> list[str]:
+    """Detect which agents are installed on the system.
+
+    Returns:
+        List of installed agent IDs, sorted by default priority
+        (claude-code first, cursor last).
+    """
+    installed = []
+    for agent_id, invoker_class in AGENT_REGISTRY.items():
+        invoker = invoker_class()
+        if invoker.is_installed():
+            installed.append(agent_id)
+
+    # Sort by priority order
+    return sorted(
+        installed,
+        key=lambda x: (
+            AGENT_PRIORITY_ORDER.index(x)
+            if x in AGENT_PRIORITY_ORDER
+            else 999
+        ),
+    )
+
+
+__all__ = [
+    # Protocol and base classes
+    "AgentInvoker",
+    "BaseInvoker",
+    "InvocationResult",
+    # Core invokers (WP02)
+    "ClaudeInvoker",
+    "CodexInvoker",
+    "CopilotInvoker",
+    "GeminiInvoker",
+    # Additional invokers (WP03)
+    "QwenInvoker",
+    "OpenCodeInvoker",
+    "KilocodeInvoker",
+    "AugmentInvoker",
+    "CursorInvoker",
+    # Registry and utilities
+    "AGENT_REGISTRY",
+    "AGENT_ALIASES",
+    "AGENT_PRIORITY_ORDER",
+    "get_invoker",
+    "normalize_agent_id",
+    "detect_installed_agents",
+]

specify_cli/orchestrator/agents/augment.py

@@ -0,0 +1,112 @@
+"""Augment Code invoker.
+
+Implements the AgentInvoker protocol for Augment Code CLI (auggie).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from specify_cli.orchestrator.agents.base import BaseInvoker, InvocationResult
+
+
+class AugmentInvoker(BaseInvoker):
+    """Invoker for Augment Code CLI (auggie).
+
+    Auggie uses --acp for autonomous coding prompt mode.
+    Does not support JSON output - relies on exit code only.
+    """
+
+    agent_id = "augment"
+    command = "auggie"
+    uses_stdin = False  # Prompt passed as argument
+
+    def build_command(
+        self,
+        prompt: str,
+        working_dir: Path,
+        role: str,
+    ) -> list[str]:
+        """Build Auggie command.
+
+        Args:
+            prompt: Task prompt (passed as argument).
+            working_dir: Directory for execution.
+            role: "implementation" or "review".
+
+        Returns:
+            Command arguments list.
+        """
+        cmd = [
+            "auggie",
+            "--acp",  # Autonomous coding prompt mode
+            prompt,  # Prompt as positional argument
+        ]
+
+        return cmd
+
+    def parse_output(
+        self,
+        stdout: str,
+        stderr: str,
+        exit_code: int,
+        duration_seconds: float,
+    ) -> InvocationResult:
+        """Parse Auggie output.
+
+        Auggie doesn't support JSON output, so we rely primarily
+        on exit code and parse stdout/stderr for useful information.
+        """
+        success = exit_code == 0
+
+        # No JSON output - extract what we can from text
+        files_modified = self._extract_files_from_text(stdout)
+        commits_made = []
+        errors = []
+        warnings = []
+
+        # Check stderr for errors
+        if stderr.strip():
+            if not success:
+                errors = self._extract_errors_from_output(None, stderr)
+            warnings = self._extract_warnings_from_output(None, stderr)
+
+        # Check stdout for error indicators
+        if not success and not errors:
+            stdout_lower = stdout.lower()
+            if "error" in stdout_lower or "failed" in stdout_lower:
+                error_lines = [
+                    line.strip()
+                    for line in stdout.split("\n")
+                    if "error" in line.lower() or "failed" in line.lower()
+                ]
+                errors.extend(error_lines[:3])
+
+        return InvocationResult(
+            success=success,
+            exit_code=exit_code,
+            stdout=stdout,
+            stderr=stderr,
+            duration_seconds=duration_seconds,
+            files_modified=files_modified,
+            commits_made=commits_made,
+            errors=errors,
+            warnings=warnings,
+        )
+
+    def _extract_files_from_text(self, text: str) -> list[str]:
+        """Extract file paths mentioned in unstructured text output."""
+        files = []
+        import re
+
+        # Patterns like "Created file.py", "Modified src/foo.py", etc.
+        patterns = [
+            r"(?:created|modified|updated|wrote|edited)\s+['\"]?([^\s'\"]+\.\w+)['\"]?",
+            r"(?:writing to|saving)\s+['\"]?([^\s'\"]+\.\w+)['\"]?",
+        ]
+
+        for pattern in patterns:
+            matches = re.findall(pattern, text, re.IGNORECASE)
+            files.extend(matches)
+
+        return list(set(files))