autobyteus 1.2.0__py3-none-any.whl → 1.2.3__py3-none-any.whl

autobyteus/rpc/protocol.py

@@ -1,244 +0,0 @@
-# file: autobyteus/autobyteus/rpc/protocol.py
-import logging
-from enum import Enum
-from typing import Optional, Dict, Any, List, Union
-from pydantic import BaseModel, Field, validator
-import uuid
-
-logger = logging.getLogger(__name__)
-
-class MessageType(str, Enum):
-    """Type of the ProtocolMessage."""
-    REQUEST = "request"
-    RESPONSE = "response"
-    ERROR = "error"
-    EVENT = "event"  # For server-pushed events, e.g., via SSE
-
-class RequestType(str, Enum):
-    """Specific method/type for a 'request' message."""
-    DISCOVER_CAPABILITIES = "discover_capabilities"
-    INVOKE_METHOD = "invoke_method"
-    REQUEST_STREAM_DOWNLOAD = "request_stream_download" # New request type for stream download
-    # Other specific control messages can be added here
-
-class ResponseType(str, Enum):
-    """Specific type for a 'response' message, often mirroring RequestType."""
-    CAPABILITIES_RESPONSE = "capabilities_response"
-    METHOD_RESULT = "method_result"
-    ACKNOWLEDGEMENT = "acknowledgement" # Generic ack
-    STREAM_DOWNLOAD_READY = "stream_download_ready" # New response type for stream download
-
-class EventType(str, Enum):
-    """Specific type for an 'event' message (server-pushed)."""
-    AGENT_OUTPUT_CHUNK = "agent_output_chunk"
-    AGENT_FINAL_MESSAGE = "agent_final_message"
-    AGENT_STATUS_UPDATE = "agent_status_update"
-    TOOL_LOG_ENTRY = "tool_log_entry"
-    # Other event types
-
-class ErrorCode(Enum):
-    """Standard error codes for RPC communication."""
-    PARSE_ERROR = -32700
-    INVALID_REQUEST = -32600
-    METHOD_NOT_FOUND = -32601
-    INVALID_PARAMS = -32602
-    INTERNAL_ERROR = -32603
-    # Custom server errors: -32000 to -32099
-    SERVER_ERROR_AGENT_PROCESSING_FAILED = -32000
-    SERVER_ERROR_CAPABILITY_DISCOVERY_FAILED = -32001
-    SERVER_ERROR_UNAUTHORIZED = -32002 # If auth is added
-    SERVER_ERROR_TIMEOUT = -32003
-    SERVER_ERROR_STREAM_PREPARATION_FAILED = -32004 # For stream download errors
-    SERVER_ERROR_STREAM_NOT_FOUND = -32005 # If stream_id is invalid
-
-class ErrorDetails(BaseModel):
-    """Structure for error details within a ProtocolMessage."""
-    code: Union[ErrorCode, int] # Allow standard ErrorCode or custom int
-    message: str
-    data: Optional[Any] = None # Optional additional error data
-
-    @validator('code', pre=True)
-    def _validate_code(cls, v):
-        if isinstance(v, ErrorCode):
-            return v.value # Store the integer value of the enum
-        if isinstance(v, int):
-            return v
-        raise ValueError("Error code must be an ErrorCode enum member or an integer.")
-
-class ProtocolMessage(BaseModel):
-    """
-    Defines the structure for all RPC communications.
-    Based on JSON-RPC 2.0 concepts but adapted for AutoByteUs needs.
-    """
-    # Common fields for all message types
-    type: MessageType = Field(..., description="The main type of the message (request, response, error, event).")
-    id: Optional[str] = Field(default=None, description="Correlation ID for requests/responses. Can be string or number, UUID for simplicity here.")
-
-    # Fields specific to 'request' type
-    method: Optional[Union[RequestType, str]] = Field(default=None, description="Method name for 'request' type (e.g., 'discover_capabilities', 'invoke_method', or a custom agent method name).")
-    params: Optional[Dict[str, Any]] = Field(default=None, description="Parameters for the method in 'request' type.")
-
-    # Fields specific to 'response' type
-    result: Optional[Any] = Field(default=None, description="Payload of a successful 'response'.")
-    response_type: Optional[ResponseType] = Field(default=None, description="Specific type of a 'response', e.g., 'capabilities_response'.")
-
-
-    # Fields specific to 'error' type (when type is MessageType.ERROR)
-    error: Optional[ErrorDetails] = Field(default=None, description="Error details if the message type is 'error'.")
-
-    # Fields specific to 'event' type (server-pushed)
-    event_type: Optional[Union[EventType, str]] = Field(default=None, description="Specific type of 'event' (server-pushed).")
-    payload: Optional[Dict[str, Any]] = Field(default=None, description="Data payload for an 'event'.")
-    
-    # Auto-generated fields (optional, can be added by sender if needed)
-    # timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
-
-    class Config:
-        use_enum_values = True # Serialize enums to their values
-        validate_assignment = True
-
-    @validator('id', pre=True, always=True)
-    def set_default_id_for_requests(cls, v, values):
-        # Ensure requests have an ID, generate if not provided
-        if values.get('type') == MessageType.REQUEST and v is None:
-            return str(uuid.uuid4())
-        return v
-    
-    @validator('error')
-    def check_error_for_error_type(cls, v, values):
-        if values.get('type') == MessageType.ERROR and v is None:
-            raise ValueError("Field 'error' is required when message 'type' is ERROR.")
-        if values.get('type') != MessageType.ERROR and v is not None:
-            raise ValueError("Field 'error' should only be present when message 'type' is ERROR.")
-        return v
-
-    @validator('result')
-    def check_result_for_response_type(cls, v, values):
-        if values.get('type') == MessageType.RESPONSE and values.get('error') is not None:
-            raise ValueError("Fields 'result' and 'error' must not coexist in a RESPONSE message.")
-        if values.get('type') == MessageType.RESPONSE and v is None and values.get('error') is None:
-            # Allow responses with null result explicitly if that's valid (e.g. for simple ack)
-            # This validation might be too strict depending on use case.
-            # For now, permit null result for acknowledgements and stream_download_ready (which will be populated by server handler)
-            if values.get('response_type') not in [ResponseType.ACKNOWLEDGEMENT, ResponseType.STREAM_DOWNLOAD_READY]:
-                 logger.debug("Field 'result' is None for a non-acknowledgement/non-stream_download_ready RESPONSE message.")
-        return v
-        
-    @validator('method', 'params')
-    def check_request_fields(cls, v, field, values):
-        if values.get('type') == MessageType.REQUEST and v is None and field.name == 'method':
-            raise ValueError(f"Field '{field.name}' is required when message 'type' is REQUEST.")
-        if values.get('type') != MessageType.REQUEST and v is not None:
-            raise ValueError(f"Field '{field.name}' should only be present when message 'type' is REQUEST.")
-        return v
-
-    @validator('event_type', 'payload')
-    def check_event_fields(cls, v, field, values):
-        if values.get('type') == MessageType.EVENT and v is None and field.name == 'event_type':
-            raise ValueError(f"Field 'event_type' is required when message 'type' is EVENT.")
-        # Payload can be optional even for event type
-        if values.get('type') != MessageType.EVENT and v is not None:
-            raise ValueError(f"Field '{field.name}' should only be present when message 'type' is EVENT.")
-        return v
-
-    def to_json_str(self) -> str:
-        """Serializes the ProtocolMessage to a JSON string."""
-        return self.model_dump_json(exclude_none=True)
-
-    @classmethod
-    def from_json_str(cls, json_str: str) -> 'ProtocolMessage':
-        """Deserializes a ProtocolMessage from a JSON string."""
-        return cls.model_validate_json(json_str)
-
-    # Factory methods for convenience
-    @classmethod
-    def create_request(cls, method: Union[RequestType, str], params: Optional[Dict[str, Any]] = None, id: Optional[str] = None) -> 'ProtocolMessage':
-        return cls(type=MessageType.REQUEST, method=method, params=params or {}, id=id or str(uuid.uuid4()))
-
-    @classmethod
-    def create_response(cls, id: str, result: Any, response_type: Optional[ResponseType] = ResponseType.METHOD_RESULT) -> 'ProtocolMessage':
-        return cls(type=MessageType.RESPONSE, id=id, result=result, response_type=response_type)
-
-    @classmethod
-    def create_error_response(cls, id: Optional[str], code: Union[ErrorCode, int], message: str, data: Optional[Any] = None) -> 'ProtocolMessage':
-        actual_code = code.value if isinstance(code, ErrorCode) else code
-        return cls(type=MessageType.ERROR, id=id, error=ErrorDetails(code=actual_code, message=message, data=data))
-
-    @classmethod
-    def create_event(cls, event_type: Union[EventType, str], payload: Optional[Dict[str, Any]] = None) -> 'ProtocolMessage':
-        return cls(type=MessageType.EVENT, event_type=event_type, payload=payload or {})
-
-
-if __name__ == "__main__": # pragma: no cover
-    # Example Usage
-    logging.basicConfig(level=logging.DEBUG)
-
-    # Request
-    cap_request = ProtocolMessage.create_request(RequestType.DISCOVER_CAPABILITIES)
-    logger.info(f"Capability Request: {cap_request.to_json_str()}")
-
-    invoke_request_params = {"tool_name": "calculator", "args": {"operation": "add", "a": 5, "b": 3}}
-    invoke_request = ProtocolMessage.create_request(RequestType.INVOKE_METHOD, params=invoke_request_params)
-    logger.info(f"Invoke Request: {invoke_request.to_json_str()}")
-    
-    custom_invoke_req = ProtocolMessage.create_request("custom_agent_method", params={"input_data": "hello"})
-    logger.info(f"Custom Invoke Request: {custom_invoke_req.to_json_str()}")
-
-    stream_download_req = ProtocolMessage.create_request(RequestType.REQUEST_STREAM_DOWNLOAD, params={"resource_id": "large_file.dat"})
-    logger.info(f"Stream Download Request: {stream_download_req.to_json_str()}")
-
-    # Response
-    cap_response_result = {"agent_id": "server_agent_001", "capabilities": ["post_inter_agent_message", "get_status"]}
-    cap_response = ProtocolMessage.create_response(id=cap_request.id, result=cap_response_result, response_type=ResponseType.CAPABILITIES_RESPONSE)
-    logger.info(f"Capability Response: {cap_response.to_json_str()}")
-
-    invoke_response_result = {"output": 8}
-    invoke_response = ProtocolMessage.create_response(id=invoke_request.id, result=invoke_response_result)
-    logger.info(f"Invoke Response: {invoke_response.to_json_str()}")
-
-    ack_response = ProtocolMessage.create_response(id=custom_invoke_req.id, result=None, response_type=ResponseType.ACKNOWLEDGEMENT)
-    logger.info(f"Ack Response: {ack_response.to_json_str()}")
-
-    stream_download_ready_result = {"stream_id": "uuid-for-stream", "metadata": {"filename": "large_file.dat", "size": 1024000}}
-    # Note: download_url would be added by SseServerHandler before sending to client
-    stream_download_ready_resp = ProtocolMessage.create_response(id=stream_download_req.id, result=stream_download_ready_result, response_type=ResponseType.STREAM_DOWNLOAD_READY)
-    logger.info(f"Stream Download Ready Response (initial): {stream_download_ready_resp.to_json_str()}")
-
-
-    # Error Response
-    error_resp = ProtocolMessage.create_error_response(id=invoke_request.id, code=ErrorCode.METHOD_NOT_FOUND, message="Method not supported by agent.")
-    logger.info(f"Error Response: {error_resp.to_json_str()}")
-    
-    parse_error_resp = ProtocolMessage.create_error_response(id=None, code=ErrorCode.PARSE_ERROR, message="Invalid JSON received.")
-    logger.info(f"Parse Error Response (no ID): {parse_error_resp.to_json_str()}")
-
-    stream_error_resp = ProtocolMessage.create_error_response(
-        id=stream_download_req.id,
-        code=ErrorCode.SERVER_ERROR_STREAM_PREPARATION_FAILED,
-        message="Agent failed to prepare the stream for resource 'large_file.dat'."
-    )
-    logger.info(f"Stream Preparation Error Response: {stream_error_resp.to_json_str()}")
-
-    # Event
-    status_event = ProtocolMessage.create_event(EventType.AGENT_STATUS_UPDATE, payload={"status": "running"})
-    logger.info(f"Status Event: {status_event.to_json_str()}")
-    
-    # Test validation
-    try:
-        invalid_msg = ProtocolMessage(type=MessageType.REQUEST) # Missing method
-    except ValueError as e:
-        logger.error(f"Validation Error: {e}")
-
-    try:
-        invalid_error_msg = ProtocolMessage(type=MessageType.ERROR, id="123") # Missing error field
-    except ValueError as e:
-        logger.error(f"Validation Error: {e}")
-
-    try:
-        error_details_invalid_code = ErrorDetails(code="INVALID_CODE_STR", message="test")
-    except ValueError as e:
-        logger.error(f"Validation Error (ErrorDetails): {e}")
-    
-    error_details_valid_int_code = ErrorDetails(code=-32050, message="Custom server error")
-    logger.info(f"ErrorDetails with int code: {error_details_valid_int_code.model_dump_json()}")
-    assert error_details_valid_int_code.code == -32050

autobyteus/rpc/server/__init__.py

@@ -1,20 +0,0 @@
-# file: autobyteus/autobyteus/rpc/server/__init__.py
-"""
-Server-side components for the AutoByteUs RPC framework.
-These components enable an AgentRuntime to expose its capabilities remotely.
-"""
-from .base_method_handler import BaseMethodHandler
-from .method_handlers import DiscoverCapabilitiesHandler, InvokeMethodHandler, InitiateStreamDownloadHandler # Added InitiateStreamDownloadHandler
-from .stdio_server_handler import StdioServerHandler
-from .sse_server_handler import SseServerHandler 
-from .agent_server_endpoint import AgentServerEndpoint
-
-__all__ = [
-    "BaseMethodHandler",
-    "DiscoverCapabilitiesHandler",
-    "InvokeMethodHandler",
-    "InitiateStreamDownloadHandler", # Added InitiateStreamDownloadHandler
-    "StdioServerHandler",
-    "SseServerHandler", 
-    "AgentServerEndpoint",
-]

autobyteus/rpc/server/agent_server_endpoint.py

@@ -1,181 +0,0 @@
-# file: autobyteus/autobyteus/rpc/server/agent_server_endpoint.py
-import asyncio
-import logging
-from typing import Optional, Dict, Union
-
-from autobyteus.rpc.config import AgentServerConfig
-from autobyteus.rpc.transport_type import TransportType
-from autobyteus.rpc.protocol import RequestType
-from autobyteus.agent.agent import Agent 
-from .base_method_handler import BaseMethodHandler
-from .method_handlers import DiscoverCapabilitiesHandler, InvokeMethodHandler, InitiateStreamDownloadHandler # Added InitiateStreamDownloadHandler
-from .stdio_server_handler import StdioServerHandler
-from .sse_server_handler import SseServerHandler
-
-logger = logging.getLogger(__name__)
-
-class AgentServerEndpoint:
-    """
-    Manages the server-side RPC endpoint.
-    It can serve a single Agent or a dictionary of multiple Agents (for SSE).
-    It initializes and controls transport-specific handlers.
-    """
-
-    def __init__(self, agent_or_agents: Union[Agent, Dict[str, Agent]]):
-        """
-        Initializes the AgentServerEndpoint.
-
-        Args:
-            agent_or_agents: Either a single Agent instance to serve, or a dictionary
-                             mapping server-routable agent IDs to Agent instances
-                             (primarily for multi-agent SSE hosting).
-        """
-        if not isinstance(agent_or_agents, (Agent, dict)):
-            raise TypeError("AgentServerEndpoint requires an Agent instance or a Dict[str, Agent].")
-        if isinstance(agent_or_agents, dict) and not all(isinstance(k, str) and isinstance(v, Agent) for k, v in agent_or_agents.items()):
-            raise TypeError("If agent_or_agents is a dict, keys must be strings and values must be Agent instances.")
-
-        self._served_entity: Union[Agent, Dict[str, Agent]] = agent_or_agents
-        self._config: Optional[AgentServerConfig] = None
-        
-        # Initialize method handlers
-        # These handlers are stateless and can be reused.
-        # For stateful handlers, they might need to be instantiated per request or per agent context.
-        self._method_handlers: Dict[Union[RequestType, str], BaseMethodHandler] = {
-            RequestType.DISCOVER_CAPABILITIES: DiscoverCapabilitiesHandler(),
-            RequestType.INVOKE_METHOD: InvokeMethodHandler(),
-            RequestType.REQUEST_STREAM_DOWNLOAD: InitiateStreamDownloadHandler(), # Added handler for stream download
-        }
-        
-        self._stdio_handler: Optional[StdioServerHandler] = None
-        self._stdio_task: Optional[asyncio.Task] = None
-        
-        self._sse_handler: Optional[SseServerHandler] = None
-        self._sse_server_task: Optional[asyncio.Task] = None # For the aiohttp server itself
-
-        self._is_running: bool = False
-        
-        if isinstance(self._served_entity, Agent):
-            logger.info(f"AgentServerEndpoint initialized for single agent '{self._served_entity.agent_id}'.")
-        else: # Dict[str, Agent]
-            agent_ids_served = list(self._served_entity.keys())
-            logger.info(f"AgentServerEndpoint initialized to serve multiple agents: {agent_ids_served}.")
-
-
-    @property
-    def is_running(self) -> bool:
-        return self._is_running
-
-    async def start(self, config: AgentServerConfig) -> None:
-        if self._is_running:
-            served_id = self._served_entity.agent_id if isinstance(self._served_entity, Agent) else "multiple agents"
-            logger.warning(f"AgentServerEndpoint for '{served_id}' is already running. Ignoring start request.")
-            return
-
-        if not isinstance(config, AgentServerConfig):
-            raise TypeError("AgentServerConfig instance required to start AgentServerEndpoint.")
-        
-        self._config = config
-        served_id_log = self._served_entity.agent_id if isinstance(self._served_entity, Agent) else f"multiple agents ({list(self._served_entity.keys())})" # type: ignore
-        logger.info(f"AgentServerEndpoint for '{served_id_log}' starting with config '{config.server_id}' (Transport: {config.transport_type.value}).")
-
-        if self._config.transport_type == TransportType.STDIO:
-            if not isinstance(self._served_entity, Agent):
-                raise ValueError("STDIO transport currently supports serving only a single Agent instance.")
-            single_agent_for_stdio: Agent = self._served_entity
-
-            if not self._stdio_handler: # Create handler if it doesn't exist
-                self._stdio_handler = StdioServerHandler(single_agent_for_stdio, self._method_handlers) 
-            
-            # Ensure task is not already running or is completed
-            if self._stdio_task and not self._stdio_task.done():
-                 logger.warning(f"Stdio task for agent '{single_agent_for_stdio.agent_id}' seems to be already running. Not restarting.")
-            else:
-                self._stdio_task = asyncio.create_task(
-                    self._stdio_handler.listen_and_dispatch(),
-                    name=f"stdio_server_endpoint_{single_agent_for_stdio.agent_id}"
-                )
-            logger.info(f"Stdio transport for agent '{single_agent_for_stdio.agent_id}' started via StdioServerHandler.")
-        
-        elif self._config.transport_type == TransportType.SSE:
-            agents_for_sse: Dict[str, Agent]
-            if isinstance(self._served_entity, Agent):
-                agents_for_sse = {self._served_entity.agent_id: self._served_entity}
-                logger.info(f"Serving single agent '{self._served_entity.agent_id}' via SSE under its own agent_id as the server key.")
-            elif isinstance(self._served_entity, dict):
-                agents_for_sse = self._served_entity
-            else: 
-                 raise ValueError("Invalid _served_entity type for SSE transport.")
-
-
-            if not self._sse_handler: # Create handler if it doesn't exist
-                self._sse_handler = SseServerHandler(agents_for_sse, self._method_handlers)
-            
-            if self._sse_server_task and not self._sse_server_task.done():
-                logger.warning("SSE server task seems to be already running. Not restarting.")
-            else:
-                # SseServerHandler.start_server is a blocking call that runs the aiohttp server.
-                # It should be run in a task that this endpoint manages.
-                self._sse_server_task = asyncio.create_task(
-                    self._sse_handler.start_server(config), 
-                    name=f"sse_server_endpoint_manager" 
-                )
-            logger.info(f"SSE transport starting via SseServerHandler for agents: {list(agents_for_sse.keys())}.")
-
-        else:
-            logger.error(f"Unsupported transport type '{self._config.transport_type}' in AgentServerEndpoint.")
-            self._config = None # Reset config if start fails for this reason
-            raise NotImplementedError(f"Transport type '{self._config.transport_type}' not implemented.")
-
-        self._is_running = True
-        logger.info(f"AgentServerEndpoint for '{served_id_log}' started successfully.")
-
-    async def stop(self) -> None:
-        served_id_log = self._served_entity.agent_id if isinstance(self._served_entity, Agent) else f"multiple agents ({list(self._served_entity.keys())})" # type: ignore
-        if not self._is_running:
-            logger.warning(f"AgentServerEndpoint for '{served_id_log}' is not running. Ignoring stop request.")
-            return
-
-        logger.info(f"AgentServerEndpoint for '{served_id_log}' stopping...")
-
-        # Stop transport-specific handlers/tasks
-        if self._config and self._config.transport_type == TransportType.STDIO:
-            if self._stdio_handler: # StdioServerHandler manages its own _running flag
-                self._stdio_handler.stop() # Signal handler to stop listening
-            if self._stdio_task and not self._stdio_task.done():
-                self._stdio_task.cancel() # Cancel the listen_and_dispatch task
-                try: await self._stdio_task
-                except asyncio.CancelledError: logger.info(f"Stdio task for endpoint for '{served_id_log}' cancelled.")
-                except Exception as e: logger.error(f"Error awaiting stdio_task during stop: {e}", exc_info=True)
-            self._stdio_task = None
-            # self._stdio_handler = None # Handler can be reused if started again
-            logger.info(f"Stdio transport for endpoint '{served_id_log}' stopped.")
-
-        elif self._config and self._config.transport_type == TransportType.SSE:
-            if self._sse_handler: # SseServerHandler has its own stop_server method
-                await self._sse_handler.stop_server() 
-            if self._sse_server_task and not self._sse_server_task.done():
-                # The sse_handler.stop_server() should ideally cause the task awaiting sse_handler.start_server() to complete.
-                # If start_server is not designed to unblock on stop_server, cancellation might be needed.
-                # Assuming start_server will handle cleanup and exit gracefully when stop_server is called.
-                # If not, explicit cancellation might be required here.
-                try: 
-                    # Give some time for graceful shutdown initiated by stop_server()
-                    await asyncio.wait_for(self._sse_server_task, timeout=5.0)
-                except asyncio.TimeoutError:
-                    logger.warning(f"Timeout waiting for SSE server task for '{served_id_log}' to complete. Cancelling.")
-                    self._sse_server_task.cancel()
-                    try: await self._sse_server_task
-                    except asyncio.CancelledError: logger.info(f"SSE server task for endpoint '{served_id_log}' cancelled.")
-                except asyncio.CancelledError: # If already cancelled by internal logic
-                     logger.info(f"SSE server task for endpoint '{served_id_log}' was already cancelled.")
-                except Exception as e: logger.error(f"Error awaiting sse_server_task during stop: {e}", exc_info=True)
-            
-            self._sse_server_task = None
-            # self._sse_handler = None # Handler can be reused
-            logger.info(f"SSE transport for endpoint '{served_id_log}' stopped.")
-
-        self._is_running = False
-        self._config = None # Clear current config
-        logger.info(f"AgentServerEndpoint for '{served_id_log}' stopped successfully.")
-

autobyteus/rpc/server/base_method_handler.py

@@ -1,40 +0,0 @@
-# file: autobyteus/autobyteus/rpc/server/base_method_handler.py
-import logging
-from abc import ABC, abstractmethod
-from typing import Optional, Dict, Any, TYPE_CHECKING
-
-from autobyteus.rpc.protocol import ProtocolMessage
-
-if TYPE_CHECKING:
-    from autobyteus.agent.agent import Agent # Changed from AgentRuntime to Agent
-
-logger = logging.getLogger(__name__)
-
-class BaseMethodHandler(ABC):
-    """
-    Abstract base class for handlers of specific RPC methods on the Agent Server.
-    """
-
-    @abstractmethod
-    async def handle(self,
-                     request_id: Optional[str],
-                     params: Optional[Dict[str, Any]],
-                     agent: 'Agent') -> ProtocolMessage: # Changed from runtime: AgentRuntime to agent: Agent
-        """
-        Handles an RPC method call.
-
-        Args:
-            request_id: The ID of the incoming request message. Used for the response.
-            params: The parameters provided with the RPC method call.
-            agent: The Agent instance being served. This provides access to the
-                   agent's public API, context, queues, status, etc.
-
-        Returns:
-            A ProtocolMessage representing the response (success or error) to be sent
-            back to the client.
-        """
-        raise NotImplementedError
-
-    def __repr__(self) -> str:
-        return f"<{self.__class__.__name__}>"
-