gobby 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

gobby/mcp_proxy/services/recommendation.py

@@ -7,13 +7,30 @@ import logging
 from typing import TYPE_CHECKING, Any, Literal
 
 if TYPE_CHECKING:
-    from gobby.config.app import RecommendToolsConfig
+    from gobby.config.features import RecommendToolsConfig
+from gobby.prompts import PromptLoader
 
 logger = logging.getLogger("gobby.mcp.server")
 
 # Search mode type
 SearchMode = Literal["llm", "semantic", "hybrid"]
 
+DEFAULT_HYBRID_RERANK_PROMPT = """Re-rank the following tools for the task: "{task_description}"
+
+Candidates:
+{candidate_list}
+
+Select the best {top_k} tools. Return JSON:
+{{"recommendations": [{{"server": "...", "tool": "...", "reason": "..."}}]}}"""
+
+DEFAULT_LLM_PROMPT = """Recommend tools for the task: "{task_description}"
+
+Available Servers:
+{available_servers}
+
+Return JSON:
+{{"recommendations": [{{"server": "...", "tool": "...", "reason": "..."}}]}}"""
+
 
 class RecommendationService:
     """Service for recommending tools."""
@@ -31,12 +48,17 @@ class RecommendationService:
         self._semantic_search = semantic_search
         self._project_id = project_id
         self._config = config
+        self._loader = PromptLoader()
+        self._loader.register_fallback(
+            "features/recommend_hybrid", lambda: DEFAULT_HYBRID_RERANK_PROMPT
+        )
+        self._loader.register_fallback("features/recommend_llm", lambda: DEFAULT_LLM_PROMPT)
 
     def _get_config(self) -> RecommendToolsConfig:
         """Get config with fallback to defaults."""
         if self._config is not None:
             return self._config
-        from gobby.config.app import RecommendToolsConfig
+        from gobby.config.features import RecommendToolsConfig
 
         return RecommendToolsConfig()
 
@@ -153,11 +175,16 @@ class RecommendationService:
                 for c in candidates
             )
 
-            prompt = config.hybrid_rerank_prompt.format(
-                task_description=task_description,
-                candidate_list=candidate_list,
-                top_k=top_k,
-            )
+            prompt_path = config.hybrid_rerank_prompt_path or "features/recommend_hybrid"
+            context = {
+                "task_description": task_description,
+                "candidate_list": candidate_list,
+                "top_k": top_k,
+            }
+            try:
+                prompt = self._loader.render(prompt_path, context)
+            except Exception:
+                prompt = DEFAULT_HYBRID_RERANK_PROMPT.format(**context)
 
             provider = self._llm_service.get_default_provider()
             response = await provider.generate_text(prompt)
@@ -191,10 +218,15 @@ class RecommendationService:
             config = self._get_config()
             available_servers = self._mcp_manager.get_available_servers()
 
-            prompt = config.llm_prompt.format(
-                task_description=task_description,
-                available_servers=", ".join(available_servers),
-            )
+            prompt_path = config.llm_prompt_path or "features/recommend_llm"
+            context = {
+                "task_description": task_description,
+                "available_servers": ", ".join(available_servers),
+            }
+            try:
+                prompt = self._loader.render(prompt_path, context)
+            except Exception:
+                prompt = DEFAULT_LLM_PROMPT.format(**context)
 
             provider = self._llm_service.get_default_provider()
             response = await provider.generate_text(prompt)

gobby/mcp_proxy/services/tool_proxy.py

@@ -4,7 +4,7 @@ import logging
 from typing import TYPE_CHECKING, Any
 
 from gobby.mcp_proxy.manager import MCPClientManager
-from gobby.mcp_proxy.models import MCPError
+from gobby.mcp_proxy.models import MCPError, ToolProxyErrorCode
 
 if TYPE_CHECKING:
     from gobby.mcp_proxy.services.fallback import ToolFallbackResolver
@@ -74,6 +74,70 @@ class ToolProxyService:
 
         return errors
 
+    def _is_argument_error(self, error_message: str) -> bool:
+        """Detect if error message suggests invalid arguments.
+
+        Used to determine whether to include tool schema in error response
+        to help the caller self-correct.
+        """
+        indicators = [
+            "parameter",
+            "argument",
+            "required",
+            "missing",
+            "invalid",
+            "unknown",
+            "expected",
+            "type error",
+            "validation",
+            "schema",
+            "property",
+            "field",
+            "400",
+            "422",
+            "-32602",  # JSON-RPC invalid params error code
+        ]
+        error_lower = error_message.lower()
+        return any(indicator in error_lower for indicator in indicators)
+
+    def _classify_error(self, error_message: str, exception: Exception) -> str:
+        """Classify an error into a structured error code.
+
+        Used to provide structured error codes that consumers can rely on
+        instead of fragile string matching.
+
+        Args:
+            error_message: The error message string
+            exception: The original exception
+
+        Returns:
+            ToolProxyErrorCode value as string
+        """
+        error_lower = error_message.lower()
+
+        # Check for server not found/configured errors
+        if "server" in error_lower:
+            if "not found" in error_lower:
+                return ToolProxyErrorCode.SERVER_NOT_FOUND.value
+            if "not configured" in error_lower:
+                return ToolProxyErrorCode.SERVER_NOT_CONFIGURED.value
+
+        # Check for tool not found
+        if "tool" in error_lower and "not found" in error_lower:
+            return ToolProxyErrorCode.TOOL_NOT_FOUND.value
+
+        # Check for argument/validation errors
+        if self._is_argument_error(error_message):
+            return ToolProxyErrorCode.INVALID_ARGUMENTS.value
+
+        # Check for connection errors
+        connection_indicators = ["connection", "timeout", "refused", "unreachable", "circuit"]
+        if any(ind in error_lower for ind in connection_indicators):
+            return ToolProxyErrorCode.CONNECTION_ERROR.value
+
+        # Default to execution error
+        return ToolProxyErrorCode.EXECUTION_ERROR.value
+
     async def list_tools(
         self,
         server_name: str,
@@ -193,10 +257,26 @@ class ToolProxyService:
             response: dict[str, Any] = {
                 "success": False,
                 "error": error_message,
+                "error_code": self._classify_error(error_message, e),
                 "server_name": server_name,
                 "tool_name": tool_name,
             }
 
+            # Enrich with schema if error looks like an argument validation error
+            if self._is_argument_error(error_message):
+                try:
+                    schema_result = await self.get_tool_schema(server_name, tool_name)
+                    if schema_result.get("success"):
+                        input_schema = schema_result.get("tool", {}).get("inputSchema", {})
+                        if input_schema:
+                            response["hint"] = (
+                                "This appears to be an argument error. "
+                                "Schema provided for self-correction."
+                            )
+                            response["schema"] = input_schema
+                except Exception as schema_error:
+                    logger.debug(f"Could not fetch schema for error enrichment: {schema_error}")
+
             # Get fallback suggestions if resolver is available
             if self._fallback_resolver:
                 try:

gobby/mcp_proxy/stdio.py

@@ -22,6 +22,7 @@ from gobby.mcp_proxy.daemon_control import (
     start_daemon_process,
     stop_daemon_process,
 )
+from gobby.mcp_proxy.instructions import build_gobby_instructions
 from gobby.mcp_proxy.registries import setup_internal_registries
 
 __all__ = [
@@ -264,7 +265,7 @@ def create_stdio_mcp_server() -> FastMCP:
     _ = setup_internal_registries(config, session_manager, memory_manager)
 
     # Initialize MCP server and daemon proxy
-    mcp = FastMCP("gobby")
+    mcp = FastMCP("gobby", instructions=build_gobby_instructions())
     proxy = DaemonProxy(config.daemon_port)
 
     register_proxy_tools(mcp, proxy)

gobby/mcp_proxy/tools/__init__.py

@@ -7,7 +7,6 @@ Provides factory functions for creating tool registries.
 # Main task registry (facade that merges all task-related registries)
 # Extracted task module registries (for direct use or testing)
 from gobby.mcp_proxy.tools.task_dependencies import create_dependency_registry
-from gobby.mcp_proxy.tools.task_expansion import create_expansion_registry
 from gobby.mcp_proxy.tools.task_github import create_github_sync_registry
 from gobby.mcp_proxy.tools.task_readiness import create_readiness_registry
 from gobby.mcp_proxy.tools.task_sync import create_sync_registry
@@ -19,7 +18,6 @@ __all__ = [
     "create_task_registry",
     # Extracted registries
     "create_dependency_registry",
-    "create_expansion_registry",
     "create_github_sync_registry",
     "create_readiness_registry",
     "create_sync_registry",

gobby/mcp_proxy/tools/agent_messaging.py

@@ -0,0 +1,317 @@
+"""
+Inter-agent messaging tools for the gobby-agents MCP server.
+
+Provides messaging capabilities between parent and child sessions:
+- send_to_parent: Child sends message to its parent session
+- send_to_child: Parent sends message to a specific child
+- poll_messages: Check for incoming messages
+- mark_message_read: Mark a message as read
+- broadcast_to_children: Send message to all running children
+
+These tools resolve session relationships from RunningAgentRegistry.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from gobby.agents.registry import RunningAgentRegistry
+    from gobby.mcp_proxy.tools.internal import InternalToolRegistry
+    from gobby.storage.inter_session_messages import InterSessionMessageManager
+
+logger = logging.getLogger(__name__)
+
+
+def add_messaging_tools(
+    registry: InternalToolRegistry,
+    message_manager: InterSessionMessageManager,
+    agent_registry: RunningAgentRegistry,
+) -> None:
+    """
+    Add inter-agent messaging tools to an existing registry.
+
+    Args:
+        registry: The InternalToolRegistry to add tools to (typically gobby-agents)
+        message_manager: InterSessionMessageManager for persisting messages
+        agent_registry: RunningAgentRegistry for resolving parent/child relationships
+    """
+
+    @registry.tool(
+        name="send_to_parent",
+        description="Send a message from a child session to its parent session.",
+    )
+    async def send_to_parent(
+        session_id: str,
+        content: str,
+        priority: str = "normal",
+    ) -> dict[str, Any]:
+        """
+        Send a message to the parent session.
+
+        Use this when a child agent needs to communicate status, results,
+        or requests back to its parent session.
+
+        Args:
+            session_id: The current (child) session ID
+            content: Message content to send
+            priority: Message priority ("normal" or "urgent")
+
+        Returns:
+            Dict with success status and message details
+        """
+        try:
+            # Find the running agent to get parent relationship
+            agent = agent_registry.get_by_session(session_id)
+            if not agent:
+                return {
+                    "success": False,
+                    "error": f"Session {session_id} not found in running agent registry",
+                }
+
+            parent_session_id = agent.parent_session_id
+            if not parent_session_id:
+                return {
+                    "success": False,
+                    "error": "No parent session found for this agent",
+                }
+
+            # Create the message
+            msg = message_manager.create_message(
+                from_session=session_id,
+                to_session=parent_session_id,
+                content=content,
+                priority=priority,
+            )
+
+            logger.info(f"Message sent from {session_id} to parent {parent_session_id}: {msg.id}")
+
+            return {
+                "success": True,
+                "message": msg.to_dict(),
+                "parent_session_id": parent_session_id,
+            }
+
+        except Exception as e:
+            logger.error(f"Failed to send message to parent: {e}")
+            return {
+                "success": False,
+                "error": str(e),
+            }
+
+    @registry.tool(
+        name="send_to_child",
+        description="Send a message from a parent session to a specific child session.",
+    )
+    async def send_to_child(
+        parent_session_id: str,
+        child_session_id: str,
+        content: str,
+        priority: str = "normal",
+    ) -> dict[str, Any]:
+        """
+        Send a message to a child session.
+
+        Use this when a parent agent needs to communicate instructions,
+        updates, or coordination messages to a spawned child.
+
+        Args:
+            parent_session_id: The parent session ID (sender)
+            child_session_id: The child session ID (recipient)
+            content: Message content to send
+            priority: Message priority ("normal" or "urgent")
+
+        Returns:
+            Dict with success status and message details
+        """
+        try:
+            # Verify the child exists and belongs to this parent
+            child_agent = agent_registry.get_by_session(child_session_id)
+            if not child_agent:
+                return {
+                    "success": False,
+                    "error": f"Child session {child_session_id} not found in running agent registry",
+                }
+
+            if child_agent.parent_session_id != parent_session_id:
+                return {
+                    "success": False,
+                    "error": (
+                        f"Session {child_session_id} is not a child of {parent_session_id}. "
+                        f"Actual parent: {child_agent.parent_session_id}"
+                    ),
+                }
+
+            # Create the message
+            msg = message_manager.create_message(
+                from_session=parent_session_id,
+                to_session=child_session_id,
+                content=content,
+                priority=priority,
+            )
+
+            logger.info(
+                f"Message sent from {parent_session_id} to child {child_session_id}: {msg.id}"
+            )
+
+            return {
+                "success": True,
+                "message": msg.to_dict(),
+            }
+
+        except Exception as e:
+            logger.error(f"Failed to send message to child: {e}")
+            return {
+                "success": False,
+                "error": str(e),
+            }
+
+    @registry.tool(
+        name="poll_messages",
+        description="Poll for messages sent to this session.",
+    )
+    async def poll_messages(
+        session_id: str,
+        unread_only: bool = True,
+    ) -> dict[str, Any]:
+        """
+        Poll for incoming messages.
+
+        Check for messages sent to this session from parent or child sessions.
+        By default, returns only unread messages.
+
+        Args:
+            session_id: The session ID to check messages for
+            unread_only: If True, only return unread messages (default: True)
+
+        Returns:
+            Dict with success status and list of messages
+        """
+        try:
+            messages = message_manager.get_messages(
+                to_session=session_id,
+                unread_only=unread_only,
+            )
+
+            return {
+                "success": True,
+                "messages": [msg.to_dict() for msg in messages],
+                "count": len(messages),
+            }
+
+        except Exception as e:
+            logger.error(f"Failed to poll messages: {e}")
+            return {
+                "success": False,
+                "error": str(e),
+            }
+
+    @registry.tool(
+        name="mark_message_read",
+        description="Mark a message as read.",
+    )
+    async def mark_message_read(
+        message_id: str,
+    ) -> dict[str, Any]:
+        """
+        Mark a message as read.
+
+        After processing a message, mark it as read so it won't appear
+        in subsequent poll_messages calls with unread_only=True.
+
+        Args:
+            message_id: The message ID to mark as read
+
+        Returns:
+            Dict with success status and updated message
+        """
+        try:
+            msg = message_manager.mark_read(message_id)
+
+            return {
+                "success": True,
+                "message": msg.to_dict(),
+            }
+
+        except ValueError:
+            return {
+                "success": False,
+                "error": f"Message not found: {message_id}",
+            }
+        except Exception as e:
+            logger.error(f"Failed to mark message as read: {e}")
+            return {
+                "success": False,
+                "error": str(e),
+            }
+
+    @registry.tool(
+        name="broadcast_to_children",
+        description="Broadcast a message to all running child sessions.",
+    )
+    async def broadcast_to_children(
+        parent_session_id: str,
+        content: str,
+        priority: str = "normal",
+    ) -> dict[str, Any]:
+        """
+        Broadcast a message to all running children.
+
+        Send the same message to all child sessions spawned by this parent.
+        Useful for coordination or shutdown signals.
+
+        Args:
+            parent_session_id: The parent session ID
+            content: Message content to broadcast
+            priority: Message priority ("normal" or "urgent")
+
+        Returns:
+            Dict with success status and count of messages sent
+        """
+        try:
+            children = agent_registry.list_by_parent(parent_session_id)
+
+            if not children:
+                return {
+                    "success": True,
+                    "sent_count": 0,
+                    "message": "No running children found",
+                }
+
+            sent_count = 0
+            errors = []
+
+            for child in children:
+                try:
+                    message_manager.create_message(
+                        from_session=parent_session_id,
+                        to_session=child.session_id,
+                        content=content,
+                        priority=priority,
+                    )
+                    sent_count += 1
+                except Exception as e:
+                    errors.append(f"{child.session_id}: {e}")
+
+            result: dict[str, Any] = {
+                "success": True,
+                "sent_count": sent_count,
+                "total_children": len(children),
+            }
+
+            if errors:
+                result["errors"] = errors
+
+            logger.info(
+                f"Broadcast from {parent_session_id} sent to {sent_count}/{len(children)} children"
+            )
+
+            return result
+
+        except Exception as e:
+            logger.error(f"Failed to broadcast to children: {e}")
+            return {
+                "success": False,
+                "error": str(e),
+            }