LCORE-1958: Fix duplicate A2A operationIds and OpenAPI response metadata

Separate GET/POST operationId values on /a2a, tighten route summaries and
descriptions for the spec, and fix Responses streaming OpenAPI (200 text/event-
stream: drop invalid sibling description; clarify JSON success description).
Regenerate docs/openapi.json for those paths only (no global tag list yet).

Author: syedriko

docs/openapi.json

@@ -9205,7 +9205,7 @@
                 },
                 "responses": {
                     "200": {
-                        "description": "Successful response",
+                        "description": "Successful response. For `text/event-stream`, the body is a Server-Sent Events stream.",
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -9262,8 +9262,7 @@
                                 "schema": {
                                     "type": "string"
                                 },
-                                "example": "event: response.created\ndata: {\"type\":\"response.created\",\"sequence_number\":0,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"in_progress\",\"model\":\"openai/gpt-4o-mini\",\"output\":[],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{},\"output_text\":\"\"}}\n\nevent: response.output_item.added\ndata: {\"type\":\"response.output_item.added\",\"sequence_number\":1,\"response_id\":\"resp_abc\",\"output_index\":0,\"item\":{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"in_progress\",\"role\":\"assistant\",\"content\":[]}}\n\n...\n\nevent: response.completed\ndata: {\"type\":\"response.completed\",\"sequence_number\":30,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"completed\",\"model\":\"openai/gpt-4o-mini\",\"output\":[{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"completed\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Hello! How can I help?\",\"annotations\":[]}]}],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"usage\":{\"input_tokens\":10,\"output_tokens\":6,\"total_tokens\":16,\"input_tokens_details\":{\"cached_tokens\":0},\"output_tokens_details\":{\"reasoning_tokens\":0}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{\"daily\":1000,\"monthly\":50000},\"output_text\":\"Hello! How can I help?\"}}\n\ndata: [DONE]\n\n",
-                                "description": "SSE stream of events"
+                                "example": "event: response.created\ndata: {\"type\":\"response.created\",\"sequence_number\":0,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"in_progress\",\"model\":\"openai/gpt-4o-mini\",\"output\":[],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{},\"output_text\":\"\"}}\n\nevent: response.output_item.added\ndata: {\"type\":\"response.output_item.added\",\"sequence_number\":1,\"response_id\":\"resp_abc\",\"output_index\":0,\"item\":{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"in_progress\",\"role\":\"assistant\",\"content\":[]}}\n\n...\n\nevent: response.completed\ndata: {\"type\":\"response.completed\",\"sequence_number\":30,\"response\":{\"id\":\"resp_abc\",\"object\":\"response\",\"created_at\":1704067200,\"status\":\"completed\",\"model\":\"openai/gpt-4o-mini\",\"output\":[{\"id\":\"msg_abc\",\"type\":\"message\",\"status\":\"completed\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"Hello! How can I help?\",\"annotations\":[]}]}],\"store\":true,\"text\":{\"format\":{\"type\":\"text\"}},\"usage\":{\"input_tokens\":10,\"output_tokens\":6,\"total_tokens\":16,\"input_tokens_details\":{\"cached_tokens\":0},\"output_tokens_details\":{\"reasoning_tokens\":0}},\"conversation\":\"0d21ba731f21f798dc9680125d5d6f49\",\"available_quotas\":{\"daily\":1000,\"monthly\":50000},\"output_text\":\"Hello! How can I help?\"}}\n\ndata: [DONE]\n\n"
                             }
                         }
                     },
@@ -10600,15 +10599,30 @@
                 "tags": [
                     "a2a"
                 ],
-                "summary": "Handle A2A Jsonrpc",
-                "description": "Handle A2A JSON-RPC requests following the A2A protocol specification.\n\nThis endpoint uses the DefaultRequestHandler from the A2A SDK to handle\nall JSON-RPC requests including message/send, message/stream, etc.\n\nThe A2A SDK application is created per-request to include authentication\ncontext while still leveraging FastAPI's authorization middleware.\n\nAutomatically detects streaming requests (message/stream JSON-RPC method)\nand returns a StreamingResponse to enable real-time chunk delivery.\n\nArgs:\n    request: FastAPI request object\n    auth: Authentication tuple\n    mcp_headers: MCP headers for context propagation\n\nReturns:\n    JSON-RPC response or streaming response",
+                "summary": "Handle A2A JSON-RPC GET",
+                "description": "Handle GET on /a2a for A2A JSON-RPC requests following the A2A protocol specification.",
                 "operationId": "handle_a2a_jsonrpc_a2a_get",
                 "responses": {
                     "200": {
-                        "description": "Successful Response",
+                        "description": "Successful response: buffered JSON-RPC or HTTP payload for non-streaming calls, or a Server-Sent Events stream when the JSON-RPC method is message/stream.",
                         "content": {
                             "application/json": {
-                                "schema": {}
+                                "schema": {
+                                    "type": "object",
+                                    "description": "JSON-RPC 2.0 response or A2A-over-HTTP payload"
+                                },
+                                "example": {
+                                    "jsonrpc": "2.0",
+                                    "id": "1",
+                                    "result": {}
+                                }
+                            },
+                            "text/event-stream": {
+                                "schema": {
+                                    "type": "string",
+                                    "format": "text/event-stream"
+                                },
+                                "example": "data: {\"jsonrpc\":\"2.0\",\"id\":\"1\",\"result\":{}}\n\n"
                             }
                         }
                     }
@@ -10618,15 +10632,30 @@
                 "tags": [
                     "a2a"
                 ],
-                "summary": "Handle A2A Jsonrpc",
-                "description": "Handle A2A JSON-RPC requests following the A2A protocol specification.\n\nThis endpoint uses the DefaultRequestHandler from the A2A SDK to handle\nall JSON-RPC requests including message/send, message/stream, etc.\n\nThe A2A SDK application is created per-request to include authentication\ncontext while still leveraging FastAPI's authorization middleware.\n\nAutomatically detects streaming requests (message/stream JSON-RPC method)\nand returns a StreamingResponse to enable real-time chunk delivery.\n\nArgs:\n    request: FastAPI request object\n    auth: Authentication tuple\n    mcp_headers: MCP headers for context propagation\n\nReturns:\n    JSON-RPC response or streaming response",
-                "operationId": "handle_a2a_jsonrpc_a2a_get",
+                "summary": "Handle A2A JSON-RPC POST",
+                "description": "Handle POST on /a2a for A2A JSON-RPC requests following the A2A protocol specification.",
+                "operationId": "handle_a2a_jsonrpc_a2a_post",
                 "responses": {
                     "200": {
-                        "description": "Successful Response",
+                        "description": "Successful response: buffered JSON-RPC or HTTP payload for non-streaming calls, or a Server-Sent Events stream when the JSON-RPC method is message/stream.",
                         "content": {
                             "application/json": {
-                                "schema": {}
+                                "schema": {
+                                    "type": "object",
+                                    "description": "JSON-RPC 2.0 response or A2A-over-HTTP payload"
+                                },
+                                "example": {
+                                    "jsonrpc": "2.0",
+                                    "id": "1",
+                                    "result": {}
+                                }
+                            },
+                            "text/event-stream": {
+                                "schema": {
+                                    "type": "string",
+                                    "format": "text/event-stream"
+                                },
+                                "example": "data: {\"jsonrpc\":\"2.0\",\"id\":\"1\",\"result\":{}}\n\n"
                             }
                         }
                     }

src/app/endpoints/a2a.py

@@ -36,6 +36,7 @@
 from starlette.responses import Response, StreamingResponse
 
 from a2a_storage import A2AContextStore, A2AStorageFactory
+from app.endpoints.a2a_openapi import a2a_jsonrpc_responses
 from authentication import get_auth_dependency
 from authentication.interface import AuthTuple
 from authorization.middleware import authorize
@@ -692,12 +693,94 @@ async def _create_a2a_app(
     return a2a_app.build()
 
 
-@router.api_route("/a2a", methods=["GET", "POST"], response_model=None)
+@router.get(
+    "/a2a",
+    response_model=None,
+    responses=a2a_jsonrpc_responses,
+    operation_id="handle_a2a_jsonrpc_a2a_get",
+    summary="Handle A2A JSON-RPC GET",
+    description=(
+        "Handle GET on /a2a for A2A JSON-RPC requests following the A2A protocol specification."
+    ),
+)
+@authorize(Action.A2A_JSONRPC)
+async def handle_a2a_jsonrpc_get(
+    request: Request,
+    auth: Annotated[AuthTuple, Depends(auth_dependency)],
+    mcp_headers: McpHeaders = Depends(mcp_headers_dependency),
+) -> Response | StreamingResponse:
+    """Serve A2A JSON-RPC over HTTP GET on ``/a2a``.
+
+    Thin wrapper that delegates to ``_handle_a2a_jsonrpc`` so GET and POST share
+    the same processing path while keeping distinct OpenAPI operation metadata.
+
+    Args:
+        request: Incoming ASGI/FastAPI request (body, scope, headers).
+        auth: Resolved authentication tuple from ``auth_dependency`` (user
+            identity and bearer token used to build the per-request A2A app).
+        mcp_headers: MCP-related headers from ``mcp_headers_dependency``, forwarded
+            into the A2A executor for downstream tool/context propagation.
+
+    Returns:
+        ``Response`` with the full buffered JSON-RPC (or HTTP) payload when the
+        request is non-streaming, or ``StreamingResponse`` (SSE) when the
+        JSON-RPC method is ``message/stream`` and chunks are streamed to the
+        client. Error conditions are generally expressed as JSON-RPC or HTTP
+        responses rather than by raising from this wrapper.
+
+    Raises:
+        HTTPException: If authentication or ``@authorize`` rejects the request
+            before or while entering the handler chain.
+    """
+    return await _handle_a2a_jsonrpc(request, auth, mcp_headers)
+
+
+@router.post(
+    "/a2a",
+    response_model=None,
+    responses=a2a_jsonrpc_responses,
+    operation_id="handle_a2a_jsonrpc_a2a_post",
+    summary="Handle A2A JSON-RPC POST",
+    description=(
+        "Handle POST on /a2a for A2A JSON-RPC requests following the A2A protocol specification."
+    ),
+)
 @authorize(Action.A2A_JSONRPC)
-async def handle_a2a_jsonrpc(  # pylint: disable=too-many-locals,too-many-statements
+async def handle_a2a_jsonrpc_post(
     request: Request,
     auth: Annotated[AuthTuple, Depends(auth_dependency)],
     mcp_headers: McpHeaders = Depends(mcp_headers_dependency),
+) -> Response | StreamingResponse:
+    """Serve A2A JSON-RPC over HTTP POST on ``/a2a``.
+
+    Thin wrapper that delegates to ``_handle_a2a_jsonrpc`` so GET and POST share
+    the same processing path while keeping distinct OpenAPI operation metadata.
+
+    Args:
+        request: Incoming ASGI/FastAPI request (body, scope, headers).
+        auth: Resolved authentication tuple from ``auth_dependency`` (user
+            identity and bearer token used to build the per-request A2A app).
+        mcp_headers: MCP-related headers from ``mcp_headers_dependency``, forwarded
+            into the A2A executor for downstream tool/context propagation.
+
+    Returns:
+        ``Response`` with the full buffered JSON-RPC (or HTTP) payload when the
+        request is non-streaming, or ``StreamingResponse`` (SSE) when the
+        JSON-RPC method is ``message/stream`` and chunks are streamed to the
+        client. Error conditions are generally expressed as JSON-RPC or HTTP
+        responses rather than by raising from this wrapper.
+
+    Raises:
+        HTTPException: If authentication or ``@authorize`` rejects the request
+            before or while entering the handler chain.
+    """
+    return await _handle_a2a_jsonrpc(request, auth, mcp_headers)
+
+
+async def _handle_a2a_jsonrpc(  # pylint: disable=too-many-locals,too-many-statements
+    request: Request,
+    auth: AuthTuple,
+    mcp_headers: McpHeaders,
 ) -> Response | StreamingResponse:
     """
     Handle A2A JSON-RPC requests following the A2A protocol specification.

src/app/endpoints/a2a_openapi.py

@@ -0,0 +1,32 @@
+"""OpenAPI-only metadata for A2A JSON-RPC routes."""
+
+from typing import Any, Final
+
+from constants import MEDIA_TYPE_EVENT_STREAM, MEDIA_TYPE_JSON
+
+# 200 may be buffered JSON-RPC (application/json) or SSE (text/event-stream).
+a2a_jsonrpc_responses: Final[dict[int | str, dict[str, Any]]] = {
+    200: {
+        "description": "Successful response",
+        "content": {
+            MEDIA_TYPE_JSON: {
+                "schema": {
+                    "type": "object",
+                    "description": "JSON-RPC 2.0 response or A2A-over-HTTP payload",
+                },
+                "example": {"jsonrpc": "2.0", "id": "1", "result": {}},
+            },
+            MEDIA_TYPE_EVENT_STREAM: {
+                "schema": {
+                    "type": "string",
+                    "description": (
+                        "Server-Sent Events stream when "
+                        "the JSON-RPC method is message/stream"
+                    ),
+                    "format": MEDIA_TYPE_EVENT_STREAM,
+                },
+                "example": 'data: {"jsonrpc":"2.0","id":"1","result":{}}\n\n',
+            },
+        },
+    },
+}

src/models/responses.py

@@ -1681,7 +1681,6 @@ def openapi_response(cls) -> dict[str, Any]:
             "application/json": {"example": json_example} if json_example else {},
             "text/event-stream": {
                 "schema": {"type": "string"},
-                "description": "SSE stream of events",
                 "example": sse_example,
             },
         }