hanzo-mcp 0.6.13__py3-none-any.whl → 0.7.1__py3-none-any.whl

hanzo_mcp/tools/agent/clarification_protocol.py

@@ -0,0 +1,220 @@
+"""Clarification protocol for agent-to-mainloop communication.
+
+This module provides a protocol for agents to request clarification
+from the main loop without human intervention.
+"""
+
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+from enum import Enum
+
+
+class ClarificationType(Enum):
+    """Types of clarification requests."""
+    AMBIGUOUS_INSTRUCTION = "ambiguous_instruction"
+    MISSING_CONTEXT = "missing_context"
+    MULTIPLE_OPTIONS = "multiple_options"
+    CONFIRMATION_NEEDED = "confirmation_needed"
+    ADDITIONAL_INFO = "additional_info"
+
+
+@dataclass
+class ClarificationRequest:
+    """A request for clarification from an agent."""
+    
+    agent_id: str
+    request_type: ClarificationType
+    question: str
+    context: Dict[str, Any]
+    options: Optional[List[str]] = None
+    
+    def to_json(self) -> str:
+        """Convert to JSON for transport."""
+        return json.dumps({
+            "agent_id": self.agent_id,
+            "request_type": self.request_type.value,
+            "question": self.question,
+            "context": self.context,
+            "options": self.options
+        })
+    
+    @classmethod
+    def from_json(cls, data: str) -> "ClarificationRequest":
+        """Create from JSON string."""
+        obj = json.loads(data)
+        return cls(
+            agent_id=obj["agent_id"],
+            request_type=ClarificationType(obj["request_type"]),
+            question=obj["question"],
+            context=obj["context"],
+            options=obj.get("options")
+        )
+
+
+@dataclass
+class ClarificationResponse:
+    """A response to a clarification request."""
+    
+    request_id: str
+    answer: str
+    additional_context: Optional[Dict[str, Any]] = None
+    
+    def to_json(self) -> str:
+        """Convert to JSON for transport."""
+        return json.dumps({
+            "request_id": self.request_id,
+            "answer": self.answer,
+            "additional_context": self.additional_context
+        })
+
+
+class ClarificationHandler:
+    """Handles clarification requests from agents."""
+    
+    def __init__(self):
+        self.pending_requests: Dict[str, ClarificationRequest] = {}
+        self.request_counter = 0
+    
+    def create_request(
+        self,
+        agent_id: str,
+        request_type: ClarificationType,
+        question: str,
+        context: Dict[str, Any],
+        options: Optional[List[str]] = None
+    ) -> str:
+        """Create a new clarification request.
+        
+        Returns:
+            Request ID for tracking
+        """
+        request = ClarificationRequest(
+            agent_id=agent_id,
+            request_type=request_type,
+            question=question,
+            context=context,
+            options=options
+        )
+        
+        request_id = f"clarify_{self.request_counter}"
+        self.request_counter += 1
+        self.pending_requests[request_id] = request
+        
+        return request_id
+    
+    def handle_request(self, request: ClarificationRequest) -> ClarificationResponse:
+        """Handle a clarification request automatically.
+        
+        This method implements automatic clarification resolution
+        based on context and common patterns.
+        """
+        request_id = f"clarify_{len(self.pending_requests)}"
+        
+        # Handle different types of clarification
+        if request.request_type == ClarificationType.AMBIGUOUS_INSTRUCTION:
+            # Try to clarify based on context
+            if "file_path" in request.context:
+                if request.context["file_path"].endswith(".go"):
+                    answer = "For Go files, ensure you add imports in the correct format and handle both single import and import block cases."
+                elif request.context["file_path"].endswith(".py"):
+                    answer = "For Python files, add imports at the top of the file after any module docstring."
+                else:
+                    answer = "Add imports according to the language's conventions."
+            else:
+                answer = "Proceed with the most reasonable interpretation based on the context."
+        
+        elif request.request_type == ClarificationType.MISSING_CONTEXT:
+            # Provide additional context based on what's missing
+            if "import_path" in request.question.lower():
+                answer = "Use the standard import path based on the project structure. Check existing imports in similar files for patterns."
+            elif "format" in request.question.lower():
+                answer = "Match the existing code style in the file. Use the same indentation and formatting patterns."
+            else:
+                answer = "Analyze the surrounding code and project structure to infer the missing information."
+        
+        elif request.request_type == ClarificationType.MULTIPLE_OPTIONS:
+            # Choose the best option based on context
+            if request.options:
+                # Simple heuristic: choose the first option that seems most standard
+                for option in request.options:
+                    if "common" in option or "standard" in option:
+                        answer = f"Choose option: {option}"
+                        break
+                else:
+                    answer = f"Choose option: {request.options[0]}"
+            else:
+                answer = "Choose the most conventional approach based on the codebase patterns."
+        
+        elif request.request_type == ClarificationType.CONFIRMATION_NEEDED:
+            # Auto-confirm safe operations
+            if "add import" in request.question.lower():
+                answer = "Yes, proceed with adding the import."
+            elif "multi_edit" in request.question.lower():
+                answer = "Yes, use multi_edit for efficiency."
+            else:
+                answer = "Proceed if the operation is safe and reversible."
+        
+        else:  # ADDITIONAL_INFO
+            answer = "Continue with available information and make reasonable assumptions based on context."
+        
+        return ClarificationResponse(
+            request_id=request_id,
+            answer=answer,
+            additional_context={"auto_resolved": True}
+        )
+
+
+class AgentClarificationMixin:
+    """Mixin for agents to request clarification."""
+    
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.clarification_handler = ClarificationHandler()
+        self.clarification_count = 0
+        self.max_clarifications = 1  # Allow up to 1 clarification per task
+    
+    async def request_clarification(
+        self,
+        request_type: ClarificationType,
+        question: str,
+        context: Dict[str, Any],
+        options: Optional[List[str]] = None
+    ) -> str:
+        """Request clarification from the main loop.
+        
+        Args:
+            request_type: Type of clarification needed
+            question: The question to ask
+            context: Relevant context for the question
+            options: Optional list of choices
+            
+        Returns:
+            The clarification response
+            
+        Raises:
+            RuntimeError: If clarification limit exceeded
+        """
+        if self.clarification_count >= self.max_clarifications:
+            raise RuntimeError("Clarification limit exceeded")
+        
+        self.clarification_count += 1
+        
+        # Create request
+        request = ClarificationRequest(
+            agent_id=getattr(self, 'agent_id', 'unknown'),
+            request_type=request_type,
+            question=question,
+            context=context,
+            options=options
+        )
+        
+        # In real implementation, this would communicate with main loop
+        # For now, use the automatic handler
+        response = self.clarification_handler.handle_request(request)
+        
+        return response.answer
+    
+    def format_clarification_in_output(self, question: str, answer: str) -> str:
+        """Format clarification exchange for output."""
+        return f"\n🤔 Clarification needed: {question}\n✅ Resolved: {answer}\n"

hanzo_mcp/tools/agent/clarification_tool.py

@@ -0,0 +1,68 @@
+"""Clarification tool for agents to request information from main loop."""
+
+from typing import Any, Dict, List, Optional, override
+
+from hanzo_mcp.tools.common.base import BaseTool
+from mcp.server.fastmcp import Context as MCPContext
+from mcp.server import FastMCP
+
+
+class ClarificationTool(BaseTool):
+    """Tool for agents to request clarification from the main loop."""
+    
+    name = "request_clarification"
+    
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description."""
+        return """Request clarification from the main loop (not the human user).
+
+Use this when you encounter:
+- Ambiguous instructions that could be interpreted multiple ways
+- Missing context needed to complete the task
+- Multiple valid options where you need guidance
+- Operations that need confirmation before proceeding
+- Need for additional information not provided
+
+Parameters:
+- type: Type of clarification (AMBIGUOUS_INSTRUCTION, MISSING_CONTEXT, MULTIPLE_OPTIONS, CONFIRMATION_NEEDED, ADDITIONAL_INFO)
+- question: Clear, specific question to ask
+- context: Relevant context (e.g., file_path, current_operation, etc.)
+- options: Optional list of possible choices (for MULTIPLE_OPTIONS type)
+
+You can only use this ONCE per task, so make it count!
+
+Example:
+request_clarification(
+    type="MISSING_CONTEXT",
+    question="What is the correct import path for the common package?",
+    context={"file_path": "/path/to/file.go", "undefined_symbol": "common"},
+    options=["github.com/luxfi/node/common", "github.com/project/common"]
+)"""
+    
+    async def call(
+        self,
+        ctx: MCPContext,
+        type: str,
+        question: str,
+        context: Dict[str, Any],
+        options: Optional[List[str]] = None
+    ) -> str:
+        """This is a placeholder - actual implementation happens in AgentTool."""
+        # This tool is handled specially in the agent execution
+        return f"Clarification request: {question}"
+    
+    def register(self, server: FastMCP) -> None:
+        """Register the tool with the MCP server."""
+        tool_self = self
+        
+        @server.tool(name=self.name, description=self.description)
+        async def request_clarification(
+            ctx: MCPContext,
+            type: str,
+            question: str,
+            context: Dict[str, Any],
+            options: Optional[List[str]] = None
+        ) -> str:
+            return await tool_self.call(ctx, type, question, context, options)

hanzo_mcp/tools/agent/claude_cli_tool.py

@@ -0,0 +1,125 @@
+"""Claude Code CLI agent tool.
+
+This tool provides integration with the Claude Code CLI (claude command),
+allowing programmatic execution of Claude for code tasks.
+"""
+
+from typing import List, Optional, override, final
+from mcp.server import FastMCP
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_mcp.tools.agent.cli_agent_base import CLIAgentBase
+from hanzo_mcp.tools.common.permissions import PermissionManager
+from hanzo_mcp.tools.agent.code_auth import get_latest_claude_model
+
+
+@final
+class ClaudeCLITool(CLIAgentBase):
+    """Tool for executing Claude Code CLI."""
+    
+    def __init__(
+        self,
+        permission_manager: PermissionManager,
+        model: Optional[str] = None,
+        **kwargs
+    ):
+        """Initialize Claude CLI tool.
+        
+        Args:
+            permission_manager: Permission manager for access control
+            model: Optional model override (defaults to latest Sonnet)
+            **kwargs: Additional arguments
+        """
+        super().__init__(
+            permission_manager=permission_manager,
+            command_name="claude",
+            provider_name="Claude Code",
+            default_model=model or get_latest_claude_model(),
+            env_vars=["ANTHROPIC_API_KEY", "CLAUDE_API_KEY"],
+            **kwargs
+        )
+    
+    @property
+    @override
+    def name(self) -> str:
+        """Get the tool name."""
+        return "claude_cli"
+    
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description."""
+        return """Execute Claude Code CLI for advanced code tasks.
+
+This tool runs the Claude Code CLI (claude command) for code generation,
+editing, analysis, and other programming tasks. It uses the latest
+Claude 3.5 Sonnet model by default.
+
+Features:
+- Direct access to Claude's coding capabilities
+- File-aware context and editing
+- Interactive code generation
+- Supports all Claude Code CLI features
+
+Usage:
+claude_cli(prompts="Fix the bug in main.py and add tests")
+claude_cli(prompts="Refactor this class to use dependency injection", model="claude-3-opus-20240229")
+
+Requirements:
+- Claude Code CLI must be installed
+- ANTHROPIC_API_KEY or CLAUDE_API_KEY environment variable
+"""
+    
+    @override
+    def get_cli_args(self, prompt: str, **kwargs) -> List[str]:
+        """Get CLI arguments for Claude.
+        
+        Args:
+            prompt: The prompt to send
+            **kwargs: Additional arguments (model, temperature, etc.)
+            
+        Returns:
+            List of command arguments
+        """
+        args = []
+        
+        # Add model if specified
+        model = kwargs.get("model", self.default_model)
+        if model:
+            args.extend(["--model", model])
+        
+        # Add temperature if specified
+        if "temperature" in kwargs:
+            args.extend(["--temperature", str(kwargs["temperature"])])
+        
+        # Add max tokens if specified
+        if "max_tokens" in kwargs:
+            args.extend(["--max-tokens", str(kwargs["max_tokens"])])
+        
+        # Add the prompt
+        args.append(prompt)
+        
+        return args
+    
+    @override
+    def register(self, mcp_server: FastMCP) -> None:
+        """Register this tool with the MCP server."""
+        tool_self = self
+        
+        @mcp_server.tool(name=self.name, description=self.description)
+        async def claude_cli(
+            ctx: MCPContext,
+            prompts: str,
+            model: Optional[str] = None,
+            temperature: Optional[float] = None,
+            max_tokens: Optional[int] = None,
+            working_dir: Optional[str] = None,
+        ) -> str:
+            return await tool_self.call(
+                ctx,
+                prompts=prompts,
+                model=model,
+                temperature=temperature,
+                max_tokens=max_tokens,
+                working_dir=working_dir,
+            )