asap-protocol 0.5.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

asap/examples/websocket_concept.py

@@ -0,0 +1,129 @@
+"""WebSocket concept for ASAP protocol (not implemented).
+
+This module describes how WebSocket support would work with ASAP.
+No WebSocket server or client is implemented here; the protocol currently
+uses HTTP + JSON-RPC. This file is for documentation and design reference.
+
+Concept:
+    - Manifest Endpoint can expose an optional "events" URL (wss://...).
+    - Same Envelope format: clients send and receive Envelopes as JSON over the wire.
+    - Use cases: streaming task updates, real-time notifications, low-latency duplex.
+
+Pseudocode (server side):
+    1. Accept WebSocket connection at e.g. /asap/events.
+    2. Optional: validate Bearer token from query or first message.
+    3. Loop: receive JSON message -> parse as Envelope -> dispatch to handler
+       -> optional: send response Envelope(s) back (e.g. task.update, task.response).
+    4. On disconnect or error, close connection.
+
+Pseudocode (client side):
+    1. Connect to wss://agent.example.com/asap/events (from manifest.endpoints.events).
+    2. Send Envelope as JSON: json.dumps(envelope.model_dump()).
+    3. Loop: receive JSON -> parse Envelope -> handle (e.g. task.update, task.response).
+    4. Optional: ping/pong for keepalive; reconnect with backoff on disconnect.
+
+Message framing:
+    - One Envelope per WebSocket text message (JSON).
+    - Binary frames could carry compressed or binary-serialized Envelopes (future).
+
+Run:
+    uv run python -m asap.examples.websocket_concept
+"""
+
+from __future__ import annotations
+
+import argparse
+from typing import Sequence
+
+from asap.models.entities import Endpoint
+from asap.observability import get_logger
+
+logger = get_logger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Pseudocode: how a WebSocket server would integrate (NOT IMPLEMENTED)
+# ---------------------------------------------------------------------------
+#
+# async def websocket_asap_endpoint(websocket: WebSocket) -> None:
+#     await websocket.accept()
+#     # Optional: require auth via query param or first message
+#     # token = websocket.query_params.get("token") or await read_first_message()
+#     # agent_id = token_validator(token); if not agent_id: await websocket.close(4001)
+#     try:
+#         while True:
+#             data = await websocket.receive_text()
+#             envelope_dict = json.loads(data)
+#             envelope = Envelope.model_validate(envelope_dict)
+#             # Dispatch same as HTTP: handler = registry.get(envelope.payload_type)
+#             # response_envelopes = await handler(envelope)
+#             # for resp in response_envelopes:
+#             #     await websocket.send_text(json.dumps(resp.model_dump()))
+#     except WebSocketDisconnect:
+#         pass
+#     finally:
+#         await websocket.close()
+#
+# # In FastAPI: @app.websocket("/asap/events"); def events(ws: WebSocket): asyncio.run(websocket_asap_endpoint(ws))
+# ---------------------------------------------------------------------------
+
+# ---------------------------------------------------------------------------
+# Pseudocode: how a WebSocket client would integrate (NOT IMPLEMENTED)
+# ---------------------------------------------------------------------------
+#
+# async def send_envelope_over_websocket(ws: ClientSession, envelope: Envelope) -> None:
+#     await ws.send_str(json.dumps(envelope.model_dump()))
+#
+# async def receive_envelope(ws: ClientSession) -> Envelope | None:
+#     msg = await ws.receive()
+#     if msg.type == aiohttp.WSMsgType.TEXT:
+#         return Envelope.model_validate(json.loads(msg.data))
+#     return None
+#
+# # Client gets events URL from manifest: manifest.endpoints.events (wss://...)
+# ---------------------------------------------------------------------------
+
+
+def get_events_endpoint_concept() -> str:
+    """Return the optional WebSocket events URL from an Endpoint (concept).
+
+    In a real implementation, the agent manifest would expose
+    endpoints.events (e.g. wss://agent.example.com/asap/events) for
+    WebSocket connections. HTTP remains the primary transport.
+
+    Returns:
+        Example events URL string for documentation.
+    """
+    endpoint = Endpoint(
+        asap="https://api.example.com/asap",
+        events="wss://api.example.com/asap/events",
+    )
+    return endpoint.events or ""
+
+
+def run_demo() -> None:
+    """Print/log the WebSocket concept summary (no implementation)."""
+    events_url = get_events_endpoint_concept()
+    logger.info(
+        "asap.websocket_concept.summary",
+        message="WebSocket support is not implemented; same Envelope format would be used over WS",
+        example_events_url=events_url,
+    )
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    """Parse command-line arguments for the WebSocket concept demo."""
+    parser = argparse.ArgumentParser(
+        description="WebSocket concept for ASAP (comments/pseudocode only, not implemented)."
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Run the WebSocket concept demo (documentation only)."""
+    parse_args(argv)
+    run_demo()
+
+
+if __name__ == "__main__":
+    main()

asap/mcp/__init__.py

@@ -0,0 +1,43 @@
+"""Model Context Protocol (MCP) integration for ASAP.
+
+Implements MCP spec 2025-11-25: JSON-RPC 2.0 over stdio (or other transports),
+with support for initialize, tools/list, and tools/call.
+
+Example:
+    >>> from asap.mcp import MCPServer
+    >>> server = MCPServer(name="my-server", version="1.0.0")
+    >>> server.register_tool("echo", lambda message: message, {"type": "object", "properties": {"message": {"type": "string"}}})
+    >>> # asyncio.run(server.run_stdio())
+"""
+
+from asap.mcp.client import MCPClient
+from asap.mcp.protocol import (
+    MCP_PROTOCOL_VERSION,
+    CallToolRequestParams,
+    CallToolResult,
+    InitializeRequestParams,
+    InitializeResult,
+    JSONRPCError,
+    JSONRPCRequest,
+    JSONRPCResponse,
+    ListToolsResult,
+    TextContent,
+    Tool,
+)
+from asap.mcp.server import MCPServer
+
+__all__ = [
+    "MCPClient",
+    "MCPServer",
+    "MCP_PROTOCOL_VERSION",
+    "CallToolRequestParams",
+    "CallToolResult",
+    "InitializeRequestParams",
+    "InitializeResult",
+    "JSONRPCError",
+    "JSONRPCRequest",
+    "JSONRPCResponse",
+    "ListToolsResult",
+    "TextContent",
+    "Tool",
+]

asap/mcp/client.py

@@ -0,0 +1,224 @@
+"""MCP client implementation (spec 2025-11-25).
+
+Connects to an MCP server over stdio (subprocess) or provides a transport
+abstraction for sending requests and receiving responses.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, Literal, cast
+
+from asap.mcp.protocol import (
+    MCP_PROTOCOL_VERSION,
+    CallToolRequestParams,
+    CallToolResult,
+    Implementation,
+    InitializeRequestParams,
+    InitializeResult,
+    ListToolsResult,
+    Tool,
+)
+from asap.observability import get_logger
+
+logger = get_logger(__name__)
+
+
+class MCPClient:
+    """MCP client with stdio transport.
+
+    Connects to an MCP server process via stdin/stdout, performs
+    initialize handshake, then supports tools/list and tools/call.
+    """
+
+    def __init__(
+        self,
+        server_command: list[str],
+        *,
+        name: str = "asap-mcp-client",
+        version: str = "1.0.0",
+        receive_timeout: float | None = 60.0,
+        request_id_type: Literal["int", "str"] = "str",
+    ) -> None:
+        """Initialize the client.
+
+        Args:
+            server_command: Command and args to start the server (e.g. ["python", "-m", "asap.mcp.server_runner"]).
+            name: Client name for initialize.
+            version: Client version for initialize.
+            receive_timeout: Seconds to wait for a response (None = no timeout).
+            request_id_type: Request id type for JSON-RPC id field ("int" or "str").
+        """
+        self._server_command = server_command
+        self._client_info = Implementation(name=name, version=version)
+        self._receive_timeout = receive_timeout
+        self._process: asyncio.subprocess.Process | None = None
+        self._initialized = False
+        self._request_id = 0
+        self._use_str_ids = request_id_type == "str"
+        self._init_result: InitializeResult | None = None
+
+    def _next_id(self) -> str | int:
+        self._request_id += 1
+        return str(self._request_id) if self._use_str_ids else self._request_id
+
+    async def _send(self, payload: dict[str, Any]) -> None:
+        """Send one JSON-RPC message (request or notification) to server stdin."""
+        if self._process is None or self._process.stdin is None:
+            raise RuntimeError("Not connected; call connect() first")
+        line = json.dumps(payload) + "\n"
+        self._process.stdin.write(line.encode("utf-8"))
+        await self._process.stdin.drain()
+
+    async def _receive(self) -> dict[str, Any] | None:
+        """Read one JSON-RPC response from server stdout."""
+        if self._process is None or self._process.stdout is None:
+            raise RuntimeError("Not connected; call connect() first")
+        read_coro = self._process.stdout.readline()
+        if self._receive_timeout is not None:
+            try:
+                raw_line = await asyncio.wait_for(read_coro, timeout=self._receive_timeout)
+            except asyncio.TimeoutError:
+                raise RuntimeError(f"No response within {self._receive_timeout}s") from None
+        else:
+            raw_line = await read_coro
+        if not raw_line:
+            return None
+        line = raw_line.decode("utf-8").rstrip("\n\r")
+        if not line:
+            return None
+        try:
+            data = json.loads(line)
+            if not isinstance(data, dict):
+                return None
+            return cast("dict[str, Any]", data)
+        except json.JSONDecodeError as e:
+            logger.warning("mcp.client.parse_error", error=str(e))
+            return None
+
+    async def connect(self) -> InitializeResult:
+        """Start the server process and perform initialize handshake.
+
+        Returns:
+            InitializeResult from the server.
+
+        Raises:
+            RuntimeError: If already connected or server fails to respond.
+        """
+        if self._process is not None:
+            raise RuntimeError("Already connected")
+        self._process = await asyncio.create_subprocess_exec(
+            *self._server_command,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        if self._process.stdin is None or self._process.stdout is None:
+            raise RuntimeError("Failed to get server stdin/stdout")
+
+        req_id = self._next_id()
+        init_req = {
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "method": "initialize",
+            "params": InitializeRequestParams(
+                protocolVersion=MCP_PROTOCOL_VERSION,
+                capabilities={},
+                clientInfo=self._client_info,
+            ).model_dump(by_alias=True, exclude_none=True),
+        }
+        await self._send(init_req)
+        raw = await self._receive()
+        if raw is None:
+            raise RuntimeError("No response to initialize")
+        if "error" in raw:
+            err = raw["error"]
+            raise RuntimeError(f"Initialize failed: {err.get('message', err)}")
+        self._init_result = InitializeResult.model_validate(raw["result"])
+        self._initialized = True
+
+        await self._send(
+            {
+                "jsonrpc": "2.0",
+                "method": "notifications/initialized",
+            }
+        )
+        return self._init_result
+
+    async def list_tools(self) -> list[Tool]:
+        """Request the list of tools from the server.
+
+        Returns:
+            List of Tool definitions.
+        """
+        if not self._initialized:
+            raise RuntimeError("Not initialized; call connect() first")
+        req_id = self._next_id()
+        await self._send(
+            {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "method": "tools/list",
+                "params": {},
+            }
+        )
+        raw = await self._receive()
+        if raw is None:
+            raise RuntimeError("No response to tools/list")
+        if "error" in raw:
+            err = raw["error"]
+            raise RuntimeError(f"tools/list failed: {err.get('message', err)}")
+        result = ListToolsResult(**raw["result"])
+        return result.tools
+
+    async def call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> CallToolResult:
+        """Invoke a tool by name with the given arguments.
+
+        Args:
+            name: Tool name (as returned by list_tools).
+            arguments: Tool arguments (keyword dict).
+
+        Returns:
+            CallToolResult with content and is_error.
+        """
+        if not self._initialized:
+            raise RuntimeError("Not initialized; call connect() first")
+        req_id = self._next_id()
+        params = CallToolRequestParams(name=name, arguments=arguments or {})
+        await self._send(
+            {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "method": "tools/call",
+                "params": params.model_dump(by_alias=True),
+            }
+        )
+        raw = await self._receive()
+        if raw is None:
+            raise RuntimeError("No response to tools/call")
+        if "error" in raw:
+            err = raw["error"]
+            return CallToolResult(
+                content=[{"type": "text", "text": err.get("message", str(err))}],
+                isError=True,
+            )
+        return CallToolResult.model_validate(raw["result"])
+
+    async def disconnect(self) -> None:
+        """Close the connection to the server (and terminate the process)."""
+        if self._process is not None:
+            if self._process.stdin:
+                self._process.stdin.close()
+                await self._process.stdin.wait_closed()
+            self._process.terminate()
+            await self._process.wait()
+            self._process = None
+        self._initialized = False
+
+    async def __aenter__(self) -> MCPClient:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.disconnect()

asap/mcp/protocol.py

@@ -0,0 +1,179 @@
+"""MCP protocol types (spec 2025-11-25).
+
+JSON-RPC 2.0 and MCP message types for initialize, tools/list, and tools/call.
+Models use extra="ignore" for forward compatibility with future spec fields.
+"""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# Protocol version supported by this implementation
+MCP_PROTOCOL_VERSION = "2025-11-25"
+
+# JSON-RPC 2.0 standard error codes
+PARSE_ERROR = -32700
+INVALID_REQUEST = -32600
+METHOD_NOT_FOUND = -32601
+INVALID_PARAMS = -32602
+INTERNAL_ERROR = -32603
+
+
+def _mcp_model_config() -> ConfigDict:
+    """Pydantic config for MCP models: allow extra fields for forward compatibility."""
+    return ConfigDict(extra="ignore", populate_by_name=True)
+
+
+# --- JSON-RPC 2.0 ---
+
+
+class JSONRPCError(BaseModel):
+    """JSON-RPC 2.0 error object."""
+
+    model_config = _mcp_model_config()
+
+    code: int = Field(description="Error code (integer)")
+    message: str = Field(description="Short error description")
+    data: Any = Field(default=None, description="Optional additional data")
+
+
+class JSONRPCRequest(BaseModel):
+    """JSON-RPC 2.0 request (has id, expects response)."""
+
+    model_config = _mcp_model_config()
+
+    jsonrpc: Literal["2.0"] = Field(default="2.0")
+    id: str | int = Field(description="Request id (must not be null)")
+    method: str = Field(description="Method name")
+    params: dict[str, Any] | None = Field(default=None)
+
+
+class JSONRPCResponse(BaseModel):
+    """JSON-RPC 2.0 success response."""
+
+    model_config = _mcp_model_config()
+
+    jsonrpc: Literal["2.0"] = Field(default="2.0")
+    id: str | int = Field(description="Same id as request")
+    result: dict[str, Any] = Field(description="Result payload")
+
+
+class JSONRPCErrorResponse(BaseModel):
+    """JSON-RPC 2.0 error response."""
+
+    model_config = _mcp_model_config()
+
+    jsonrpc: Literal["2.0"] = Field(default="2.0")
+    id: str | int | None = Field(description="Same id as request, or null")
+    error: JSONRPCError = Field(description="Error object")
+
+
+class JSONRPCNotification(BaseModel):
+    """JSON-RPC 2.0 notification (no id, no response)."""
+
+    model_config = _mcp_model_config()
+
+    jsonrpc: Literal["2.0"] = Field(default="2.0")
+    method: str = Field(description="Method name")
+    params: dict[str, Any] | None = Field(default=None)
+
+
+# --- Implementation (clientInfo / serverInfo) ---
+
+
+class Implementation(BaseModel):
+    """MCP implementation info (client or server)."""
+
+    model_config = _mcp_model_config()
+
+    name: str = Field(description="Programmatic name")
+    version: str = Field(description="Version string")
+    title: str | None = Field(default=None, description="Human-readable title")
+    description: str | None = Field(default=None)
+    icons: list[dict[str, Any]] | None = Field(default=None)
+    website_url: str | None = Field(default=None, alias="websiteUrl")
+
+
+# --- Initialize ---
+
+
+class InitializeRequestParams(BaseModel):
+    """Params for initialize request."""
+
+    model_config = _mcp_model_config()
+
+    protocol_version: str = Field(alias="protocolVersion")
+    capabilities: dict[str, Any] = Field(default_factory=dict)
+    client_info: Implementation = Field(alias="clientInfo")
+
+
+class InitializeResult(BaseModel):
+    """Result of initialize (server response)."""
+
+    model_config = _mcp_model_config()
+
+    protocol_version: str = Field(alias="protocolVersion", default=MCP_PROTOCOL_VERSION)
+    capabilities: dict[str, Any] = Field(default_factory=dict)
+    server_info: Implementation = Field(alias="serverInfo")
+    instructions: str | None = Field(default=None)
+
+
+# --- Tools ---
+
+
+class Tool(BaseModel):
+    """MCP tool definition (tools/list item)."""
+
+    model_config = _mcp_model_config()
+
+    name: str = Field(description="Unique tool name")
+    description: str = Field(description="Human-readable description")
+    input_schema: dict[str, Any] = Field(
+        alias="inputSchema",
+        description="JSON Schema for parameters (object, not null)",
+    )
+    title: str | None = Field(default=None)
+    icons: list[dict[str, Any]] | None = Field(default=None)
+    output_schema: dict[str, Any] | None = Field(default=None, alias="outputSchema")
+    annotations: dict[str, Any] | None = Field(default=None)
+
+
+class TextContent(BaseModel):
+    """Text content item in tool result."""
+
+    model_config = _mcp_model_config()
+
+    type: Literal["text"] = Field(default="text")
+    text: str = Field(description="Text content")
+    annotations: dict[str, Any] | None = Field(default=None)
+
+
+class CallToolRequestParams(BaseModel):
+    """Params for tools/call request."""
+
+    model_config = _mcp_model_config()
+
+    name: str = Field(description="Tool name")
+    arguments: dict[str, Any] = Field(default_factory=dict, description="Tool arguments")
+
+
+class CallToolResult(BaseModel):
+    """Result of tools/call (content + isError)."""
+
+    model_config = _mcp_model_config()
+
+    content: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description="Content blocks (e.g. TextContent)",
+    )
+    is_error: bool = Field(default=False, alias="isError")
+    structured_content: dict[str, Any] | None = Field(default=None, alias="structuredContent")
+
+
+class ListToolsResult(BaseModel):
+    """Result of tools/list."""
+
+    model_config = _mcp_model_config()
+
+    tools: list[Tool] = Field(default_factory=list)
+    next_cursor: str | None = Field(default=None, alias="nextCursor")