superqode 0.1.5__py3-none-any.whl

superqode/agents/data/stakpak.dev.toml

@@ -0,0 +1,51 @@
+# Schema defined in agent_schema.py
+# https://github.com/stakpak/stakpak
+
+identity = "stakpak.dev"
+name = "Stakpak"
+short_name = "stakpak"
+url = "https://github.com/stakpak/stakpak"
+protocol = "acp"
+author_name = "Stakpak"
+author_url = "https://github.com/stakpak"
+publisher_name = "SuperQode Team"
+publisher_url = "https://github.com/SuperagenticAI/superqode"
+type = "coding"
+description = "An ACP-compatible agent focused on providing comprehensive code assistance and collaboration features."
+tags = ["code-assistance", "collaboration", "acp"]
+run_command."*" = "stakpak --acp"
+
+help = '''
+# Stakpak
+
+**Comprehensive Code Assistance Agent**
+
+Stakpak is an ACP-compatible agent focused on providing comprehensive code assistance and collaboration features for development teams.
+
+## Key Features
+
+- **Code Assistance**: Comprehensive code analysis and suggestions
+- **Collaboration**: Team collaboration features
+- **ACP Compatible**: Full Agent Client Protocol support
+- **Extensible**: Plugin system for custom functionality
+
+## Installation
+
+Install Stakpak via pip:
+
+```bash
+pip install stakpak
+```
+
+**Requirements:**
+- Python 3.8 or higher
+- pip
+
+---
+
+**GitHub**: https://github.com/stakpak/stakpak
+'''
+
+[actions."*".install]
+command = "pip install stakpak"
+description = "Install Stakpak"

superqode/agents/data/vtcode.dev.toml

@@ -0,0 +1,51 @@
+# Schema defined in agent_schema.py
+# https://github.com/vtcode/vtcode
+
+identity = "vtcode.dev"
+name = "VT Code"
+short_name = "vtcode"
+url = "https://github.com/vtcode/vtcode"
+protocol = "acp"
+author_name = "VT Code"
+author_url = "https://github.com/vtcode"
+publisher_name = "SuperQode Team"
+publisher_url = "https://github.com/SuperagenticAI/superqode"
+type = "coding"
+description = "A versatile coding agent implementing ACP for seamless integration with compatible development environments."
+tags = ["versatile", "acp", "integration"]
+run_command."*" = "vtcode --acp"
+
+help = '''
+# VT Code
+
+**Versatile Coding Agent**
+
+VT Code is a versatile coding agent implementing ACP for seamless integration with compatible development environments.
+
+## Key Features
+
+- **Versatile**: Works with multiple development environments
+- **ACP Integration**: Full Agent Client Protocol support
+- **Seamless Integration**: Easy integration with existing workflows
+- **Cross-Platform**: Works on multiple operating systems
+
+## Installation
+
+Install VT Code ACP adapter via npm:
+
+```bash
+npm install -g vtcode-acp
+```
+
+**Requirements:**
+- Node.js (v16 or higher)
+- npm
+
+---
+
+**GitHub**: https://github.com/vtcode/vtcode
+'''
+
+[actions."*".install]
+command = "npm install -g vtcode-acp"
+description = "Install VT Code ACP adapter"

superqode/agents/discovery.py

@@ -0,0 +1,266 @@
+"""Agent discovery system for SuperQode ACP integration."""
+
+import asyncio
+from importlib.resources import files
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .schema import Agent
+
+try:
+    import tomllib
+except ImportError:
+    # Python < 3.12
+    import tomli as tomllib
+
+
+class AgentReadError(Exception):
+    """Problem reading the agents."""
+
+
+async def read_agents(include_registry: bool = False) -> dict[str, "Agent"]:
+    """Read agent information from agents/data directory with enhanced error handling.
+
+    Args:
+        include_registry: If True, merge with registry agents. Default False for backward compatibility.
+
+    Raises:
+        AgentReadError: If the files could not be read.
+
+    Returns:
+        A mapping of identity on to Agent dict.
+    """
+
+    def read_agents_sync() -> tuple[list["Agent"], list[str]]:
+        """Read agent information synchronously with error tracking.
+
+        Stored in agents/data directory.
+
+        Returns:
+            Tuple of (agents_list, warnings_list)
+        """
+        agents: list["Agent"] = []
+        warnings: list[str] = []
+
+        # Define search paths
+        search_paths = []
+
+        # Add filesystem path (primary source)
+        fs_data_dir = Path(__file__).parent / "data"
+        if fs_data_dir.exists():
+            search_paths.append(fs_data_dir)
+
+        # Try package data as secondary source
+        try:
+            package_data_path = files("superqode.agents.data")
+            # Convert to string path for Path constructor
+            package_data_path = Path(str(package_data_path))
+            if package_data_path.exists() and package_data_path not in search_paths:
+                search_paths.append(package_data_path)
+        except (ImportError, AttributeError, TypeError):
+            pass  # Package data not available
+
+        # Also check for user-defined agent directories
+        user_agent_dir = Path.home() / ".superqode" / "agents"
+        if user_agent_dir.exists():
+            search_paths.append(user_agent_dir)
+
+        if not search_paths:
+            warnings.append("No agent data directories found")
+            return agents, warnings
+
+        # Read agents from all paths
+        for search_path in search_paths:
+            try:
+                for file in search_path.iterdir():
+                    if file.name.endswith(".toml") and file.is_file():
+                        try:
+                            agent: "Agent" = tomllib.load(file.open("rb"))
+                            if agent.get("active", True):
+                                # Validate required fields
+                                required_fields = ["identity", "name", "short_name", "protocol"]
+                                missing_fields = [
+                                    field for field in required_fields if field not in agent
+                                ]
+                                if missing_fields:
+                                    warnings.append(
+                                        f"Agent {file.name}: missing required fields {missing_fields}"
+                                    )
+                                    continue
+
+                                agents.append(agent)
+                            else:
+                                warnings.append(f"Agent {agent.get('name', file.name)} is disabled")
+                        except tomllib.TOMLKitError as e:
+                            warnings.append(f"Failed to parse {file.name}: {e}")
+                        except Exception as e:
+                            warnings.append(f"Error reading {file.name}: {e}")
+            except Exception as e:
+                warnings.append(f"Error reading directory {search_path}: {e}")
+
+        return agents, warnings
+
+    agents, warnings = await asyncio.to_thread(read_agents_sync)
+
+    # Log warnings if any
+    if warnings:
+        import sys
+
+        console = sys.modules.get("rich.console", None)
+        if console:
+            from rich.console import Console
+
+            console = Console()
+            for warning in warnings:
+                console.print(f"[yellow]Warning: {warning}[/yellow]")
+
+    agent_map = {agent["identity"]: agent for agent in agents}
+
+    # Merge with registry if requested
+    if include_registry:
+        # Import here to avoid circular dependency
+        from .acp_registry import get_all_registry_agents
+
+        # Get registry agents and merge
+        registry_agents = get_all_registry_agents()
+
+        # Convert registry agents to Agent format and merge
+        for identity, metadata in registry_agents.items():
+            # Skip if already in local agents
+            if identity in agent_map:
+                continue
+
+            # Convert registry metadata to Agent format
+            agent: "Agent" = {
+                "identity": metadata["identity"],
+                "name": metadata["name"],
+                "short_name": metadata["short_name"],
+                "url": metadata["url"],
+                "protocol": "acp",
+                "author_name": metadata["author_name"],
+                "author_url": metadata["author_url"],
+                "publisher_name": "SuperQode Team",
+                "publisher_url": "https://github.com/SuperagenticAI/superqode",
+                "type": "coding",
+                "description": metadata["description"],
+                "tags": [],
+                "help": f"# {metadata['name']}\n\n{metadata['description']}\n\n## Installation\n\n{metadata['installation_instructions']}\n\nRun: `{metadata['installation_command']}`",
+                "run_command": {"*": metadata["run_command"]},
+                "actions": {
+                    "*": {
+                        "install": {
+                            "command": metadata["installation_command"],
+                            "description": f"Install {metadata['name']}",
+                        }
+                    }
+                },
+            }
+
+            agent_map[identity] = agent
+
+    if not agent_map:
+        raise AgentReadError("No valid agents found in any data directory")
+
+    return agent_map
+
+
+async def get_agent_by_identity_async(
+    identity: str, include_registry: bool = True
+) -> "Agent | None":
+    """Get a specific agent by identity (async version).
+
+    Args:
+        identity: The agent identity to look for.
+        include_registry: If True, also check registry. Default True.
+
+    Returns:
+        The agent dict if found, None otherwise.
+    """
+    agent_map = await read_agents(include_registry=include_registry)
+    return agent_map.get(identity)
+
+
+async def get_agent_by_short_name_async(
+    short_name: str, include_registry: bool = True
+) -> "Agent | None":
+    """Get a specific agent by short name (async version).
+
+    Args:
+        short_name: The agent short name to look for.
+        include_registry: If True, also check registry. Default True.
+
+    Returns:
+        The agent dict if found, None otherwise.
+    """
+    agents = await read_agents(include_registry=include_registry)
+
+    for agent in agents.values():
+        if agent.get("short_name", "").lower() == short_name.lower():
+            return agent
+
+    return None
+
+
+def get_agent_by_identity(identity: str) -> "Agent | None":
+    """Get a specific agent by identity.
+
+    Args:
+        identity: The agent identity to look for.
+
+    Returns:
+        The agent dict if found, None otherwise.
+    """
+    import asyncio
+
+    try:
+        # Try to get the current event loop
+        loop = asyncio.get_running_loop()
+        # If we're in an async context, we need to handle this differently
+        # For now, create a new event loop
+        new_loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(new_loop)
+        try:
+            agent_map = new_loop.run_until_complete(read_agents())
+            return agent_map.get(identity)
+        finally:
+            new_loop.close()
+    except RuntimeError:
+        # No running loop, safe to use asyncio.run
+        agent_map = asyncio.run(read_agents())
+        return agent_map.get(identity)
+
+
+def get_agent_by_short_name(short_name: str) -> "Agent | None":
+    """Get a specific agent by short name.
+
+    Args:
+        short_name: The agent short name to look for.
+
+    Returns:
+        The agent dict if found, None otherwise.
+    """
+    import asyncio
+
+    try:
+        # Try to get the current event loop
+        loop = asyncio.get_running_loop()
+        # If we're in an async context, we need to handle this differently
+        # For now, create a new event loop
+        new_loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(new_loop)
+        try:
+            agents = new_loop.run_until_complete(read_agents())
+            for agent in agents.values():
+                if agent.get("short_name", "").lower() == short_name.lower():
+                    return agent
+            return None
+        finally:
+            new_loop.close()
+    except RuntimeError:
+        # No running loop, safe to use asyncio.run
+        agents = asyncio.run(read_agents())
+        for agent in agents.values():
+            if agent.get("short_name", "").lower() == short_name.lower():
+                return agent
+        return None

superqode/agents/messaging.py

@@ -0,0 +1,160 @@
+"""Agent messaging utilities for direct subprocess communication."""
+
+import subprocess
+from pathlib import Path
+from typing import Tuple, Optional, Dict, Any
+
+
+def map_model_to_opencode(model_name: str) -> str:
+    """Map user-friendly model names to OpenCode model identifiers.
+
+    OpenCode expects just the model name (e.g., "glm-4.7-free"),
+    NOT the provider/model format.
+    """
+    # Map user-friendly names to OpenCode model names
+    model_mapping = {
+        "glm-4.7": "glm-4.7-free",
+        "grok-code": "grok-code",
+        "gpt-5-nano": "gpt-5-nano",
+        "big-pickle": "big-pickle",
+        "minimax-m2.1": "minimax-m2.1-free",
+        # Strip provider prefix if present
+        "opencode/glm-4.7-free": "glm-4.7-free",
+        "opencode/grok-code": "grok-code",
+        "opencode/gpt-5-nano": "gpt-5-nano",
+        "opencode/big-pickle": "big-pickle",
+        "opencode/minimax-m2.1-free": "minimax-m2.1-free",
+    }
+
+    mapped = model_mapping.get(model_name, model_name)
+
+    # Ensure the result has the opencode/ prefix
+    if not mapped.startswith("opencode/"):
+        mapped = f"opencode/{mapped}"
+
+    return mapped
+
+
+def send_message_to_agent(
+    agent: Dict[str, Any], message: str, model: Optional[str] = None, cwd: Optional[Path] = None
+) -> Tuple[bool, str, str]:
+    """
+    Send a message to an agent using subprocess.
+
+    Args:
+        agent: Agent data dictionary with 'short_name' and other metadata
+        message: The message to send to the agent
+        model: Optional model name to use (will be mapped for OpenCode)
+        cwd: Optional working directory for subprocess
+
+    Returns:
+        Tuple of (success: bool, stdout: str, stderr: str)
+    """
+    agent_name = agent.get("short_name", "unknown")
+
+    if agent_name == "opencode":
+        return _send_to_opencode(message, model, cwd)
+    else:
+        # For other agents, return not implemented
+        error_msg = f"Direct messaging not yet implemented for agent: {agent_name}"
+        return (False, "", error_msg)
+
+
+def _send_to_opencode(
+    message: str, model: Optional[str] = None, cwd: Optional[Path] = None
+) -> Tuple[bool, str, str]:
+    """
+    Send a message to OpenCode using subprocess.
+
+    Args:
+        message: The message to send
+        model: Optional model name (will be mapped to OpenCode format)
+        cwd: Optional working directory
+
+    Returns:
+        Tuple of (success: bool, stdout: str, stderr: str)
+    """
+    # Build the command
+    cmd = ["opencode", "run", message]
+
+    # Note: Not specifying model for better performance and accuracy
+    # OpenCode tends to read config files when model is specified
+
+    # Execute
+    try:
+        import subprocess as sp
+
+        result = sp.run(cmd, capture_output=True, text=True, cwd=str(cwd) if cwd else None)
+
+        success = result.returncode == 0
+        return (success, result.stdout, result.stderr)
+
+    except FileNotFoundError:
+        error_msg = "OpenCode not found. Make sure it's installed and in your PATH."
+        return (False, "", error_msg)
+    except Exception as e:
+        error_msg = f"Error running OpenCode: {e}"
+        return (False, "", error_msg)
+
+
+def send_to_role_agent(
+    agent_name: str, model: Optional[str], message: str, cwd: Optional[Path] = None
+) -> Tuple[bool, str, str]:
+    """
+    Send a message to an agent configured in a role.
+
+    This is a convenience function for role-based mode where we already know
+    the agent name and model from the role configuration.
+
+    Args:
+        agent_name: Name of the agent (e.g., "opencode")
+        model: Model to use (e.g., "glm-4.7", "grok-code")
+        message: The message to send
+        cwd: Optional working directory
+
+    Returns:
+        Tuple of (success: bool, stdout: str, stderr: str)
+    """
+    # Create a minimal agent dict
+    agent = {"short_name": agent_name}
+    return send_message_to_agent(agent, message, model, cwd)
+
+
+# Import PersonaContext for type hints (lazy import to avoid circular deps)
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from superqode.agents.persona import PersonaContext
+
+
+def wrap_message_with_persona(message: str, persona_context: Optional["PersonaContext"]) -> str:
+    """Wrap a user message with persona context.
+
+    This function prepends the persona system prompt to the user's message,
+    allowing the AI model to respond with the appropriate role context.
+
+    Args:
+        message: The original user message
+        persona_context: Optional persona context to prepend. If None or
+                        invalid, returns the original message unchanged.
+
+    Returns:
+        The wrapped message with persona context, or original if no context.
+        The format is: {system_prompt}{user_message}
+    """
+    # Handle None or invalid context gracefully
+    if persona_context is None:
+        return message
+
+    # Check if persona_context has required attributes
+    try:
+        system_prompt = persona_context.system_prompt
+        if not system_prompt:
+            return message
+    except (AttributeError, TypeError):
+        # Invalid context object, return original message
+        return message
+
+    # Combine persona context with user message
+    # The system_prompt already ends with "---\n" separator
+    return f"{system_prompt}{message}"

superqode/agents/persona.py

@@ -0,0 +1,166 @@
+"""Persona injection for role-based AI interactions.
+
+This module provides functionality to inject role-based persona context
+into messages sent to AI coding agents, enabling the model to respond
+with the appropriate expertise and personality for the configured role.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+# Import ResolvedRole type for type hints
+from superqode.config.schema import ResolvedRole
+
+
+@dataclass
+class PersonaContext:
+    """Holds the constructed persona context for a role.
+
+    Attributes:
+        role_name: The full role identifier (e.g., "DEV.FULLSTACK")
+        role_description: Brief description of the role
+        job_description: Detailed job description from YAML config
+        system_prompt: The constructed system prompt for injection
+        is_valid: True if job_description was present and non-empty
+    """
+
+    role_name: str
+    role_description: str
+    job_description: str
+    system_prompt: str
+    is_valid: bool
+
+
+def validate_job_description(job_description: Optional[str]) -> bool:
+    """Validate that a job_description is suitable for persona injection.
+
+    Args:
+        job_description: The job description string to validate
+
+    Returns:
+        True if job_description is a non-empty string (not None,
+        not empty string, not whitespace-only)
+    """
+    if job_description is None:
+        return False
+    if not isinstance(job_description, str):
+        return False
+    return len(job_description.strip()) > 0
+
+
+def truncate_job_description(job_description: str, max_length: int = 60) -> str:
+    """Truncate a job description for display purposes.
+
+    Args:
+        job_description: The job description to truncate
+        max_length: Maximum length before truncation (default 60)
+
+    Returns:
+        The original string if under max_length, otherwise truncated
+        with "..." suffix
+    """
+    if not job_description:
+        return ""
+
+    # Get first line only for preview
+    first_line = job_description.split("\n")[0].strip()
+
+    if len(first_line) <= max_length:
+        return first_line
+
+    return first_line[:max_length] + "..."
+
+
+class PersonaInjector:
+    """Constructs persona context from role configuration.
+
+    This class is responsible for building the system prompt that will
+    be injected into messages sent to AI coding agents.
+    """
+
+    # Template for full persona prompt (when job_description is available)
+    FULL_PROMPT_TEMPLATE = """[SYSTEM INSTRUCTION - MANDATORY PERSONA]
+You ARE a {role_name} on a software development team. This is your identity.
+
+Role: {role_description}
+
+Your responsibilities and expertise:
+{job_description}
+
+CRITICAL RULES:
+1. When asked "who are you" or about your identity, describe yourself as this role - NOT as an AI model.
+2. DO NOT announce your role or identity during tasks. Just do the work silently and professionally.
+3. NEVER say things like "As a {role_name}..." or "I am a {role_name}..." while working.
+4. Focus on completing tasks efficiently without self-referential statements.
+[END SYSTEM INSTRUCTION]
+
+"""
+
+    # Template for minimal persona prompt (when job_description is missing)
+    MINIMAL_PROMPT_TEMPLATE = """[SYSTEM INSTRUCTION - MANDATORY PERSONA]
+You ARE a {role_name} ({role_description}) on a software development team. This is your identity.
+
+CRITICAL RULES:
+1. When asked "who are you", describe yourself as this role - NOT as an AI model.
+2. DO NOT announce your role during tasks. Just do the work silently.
+3. NEVER say "As a {role_name}..." or "I am a {role_name}..." while working.
+[END SYSTEM INSTRUCTION]
+
+"""
+
+    def build_persona(self, mode: str, role: str, resolved_role: ResolvedRole) -> PersonaContext:
+        """Build persona context from resolved role configuration.
+
+        Args:
+            mode: The mode name (e.g., "dev", "qe")
+            role: The role name (e.g., "fullstack", "api_tester")
+            resolved_role: The ResolvedRole object from config loader
+
+        Returns:
+            PersonaContext with constructed system prompt
+        """
+        role_name = f"{mode.upper()}.{role.upper()}"
+        role_description = resolved_role.description or ""
+        job_description = resolved_role.job_description or ""
+
+        is_valid = validate_job_description(job_description)
+
+        system_prompt = self.format_system_prompt(
+            role_name=role_name,
+            role_description=role_description,
+            job_description=job_description,
+            is_valid=is_valid,
+        )
+
+        return PersonaContext(
+            role_name=role_name,
+            role_description=role_description,
+            job_description=job_description,
+            system_prompt=system_prompt,
+            is_valid=is_valid,
+        )
+
+    def format_system_prompt(
+        self, role_name: str, role_description: str, job_description: str, is_valid: bool
+    ) -> str:
+        """Format the system prompt for injection.
+
+        Args:
+            role_name: The full role identifier
+            role_description: Brief description of the role
+            job_description: Detailed job description
+            is_valid: Whether job_description is valid
+
+        Returns:
+            A formatted string suitable for prepending to user messages
+        """
+        if is_valid:
+            return self.FULL_PROMPT_TEMPLATE.format(
+                role_name=role_name,
+                role_description=role_description,
+                job_description=job_description.strip(),
+            )
+        else:
+            return self.MINIMAL_PROMPT_TEMPLATE.format(
+                role_name=role_name, role_description=role_description
+            )