fast-agent-mcp 0.3.13__py3-none-any.whl → 0.3.15__py3-none-any.whl

fast_agent/mcp/sse_tracking.py

@@ -0,0 +1,287 @@
+"""SSE transport wrapper that emits channel events for UI display."""
+
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any, AsyncGenerator, Callable
+from urllib.parse import parse_qs, urljoin, urlparse
+
+import anyio
+import httpx
+import mcp.types as types
+from httpx_sse import aconnect_sse
+from httpx_sse._exceptions import SSEError
+from mcp.shared._httpx_utils import McpHttpClientFactory, create_mcp_http_client
+from mcp.shared.message import SessionMessage
+
+from fast_agent.mcp.transport_tracking import ChannelEvent, ChannelName
+
+if TYPE_CHECKING:
+    from anyio.abc import TaskStatus
+    from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+
+logger = logging.getLogger(__name__)
+
+ChannelHook = Callable[[ChannelEvent], None]
+
+
+def _extract_session_id(endpoint_url: str) -> str | None:
+    parsed = urlparse(endpoint_url)
+    query_params = parse_qs(parsed.query)
+    for key in ("sessionId", "session_id", "session"):
+        values = query_params.get(key)
+        if values:
+            return values[0]
+    return None
+
+
+def _emit_channel_event(
+    channel_hook: ChannelHook | None,
+    channel: ChannelName,
+    event_type: str,
+    *,
+    message: types.JSONRPCMessage | None = None,
+    raw_event: str | None = None,
+    detail: str | None = None,
+    status_code: int | None = None,
+) -> None:
+    if channel_hook is None:
+        return
+    try:
+        channel_hook(
+            ChannelEvent(
+                channel=channel,
+                event_type=event_type,  # type: ignore[arg-type]
+                message=message,
+                raw_event=raw_event,
+                detail=detail,
+                status_code=status_code,
+            )
+        )
+    except Exception:
+        logger.debug("Channel hook raised an exception", exc_info=True)
+
+
+def _format_http_error(exc: httpx.HTTPStatusError) -> tuple[int | None, str]:
+    status_code: int | None = None
+    detail = str(exc)
+    if exc.response is not None:
+        status_code = exc.response.status_code
+        reason = exc.response.reason_phrase or ""
+        if not reason:
+            try:
+                reason = (exc.response.text or "").strip()
+            except Exception:
+                reason = ""
+        detail = f"HTTP {status_code}: {reason or 'response'}"
+    return status_code, detail
+
+
+@asynccontextmanager
+async def tracking_sse_client(
+    url: str,
+    headers: dict[str, Any] | None = None,
+    timeout: float = 5,
+    sse_read_timeout: float = 60 * 5,
+    httpx_client_factory: McpHttpClientFactory = create_mcp_http_client,
+    auth: httpx.Auth | None = None,
+    channel_hook: ChannelHook | None = None,
+) -> AsyncGenerator[
+    tuple[
+        MemoryObjectReceiveStream[SessionMessage | Exception],
+        MemoryObjectSendStream[SessionMessage],
+        Callable[[], str | None],
+    ],
+    None,
+]:
+    """
+    Client transport for SSE with channel activity tracking.
+    """
+
+    read_stream_writer, read_stream = anyio.create_memory_object_stream[SessionMessage | Exception](
+        0
+    )
+    write_stream, write_stream_reader = anyio.create_memory_object_stream[SessionMessage](0)
+
+    session_id: str | None = None
+
+    def get_session_id() -> str | None:
+        return session_id
+
+    async with anyio.create_task_group() as tg:
+        try:
+            logger.debug("Connecting to SSE endpoint: %s", url)
+            async with httpx_client_factory(
+                headers=headers,
+                auth=auth,
+                timeout=httpx.Timeout(timeout, read=sse_read_timeout),
+            ) as client:
+                connected = False
+                post_connected = False
+
+                async def sse_reader(
+                    task_status: TaskStatus[str] = anyio.TASK_STATUS_IGNORED,
+                ):
+                    try:
+                        async for sse in event_source.aiter_sse():
+                            if sse.event == "endpoint":
+                                endpoint_url = urljoin(url, sse.data)
+                                logger.debug("Received SSE endpoint URL: %s", endpoint_url)
+
+                                url_parsed = urlparse(url)
+                                endpoint_parsed = urlparse(endpoint_url)
+                                if (
+                                    url_parsed.scheme != endpoint_parsed.scheme
+                                    or url_parsed.netloc != endpoint_parsed.netloc
+                                ):
+                                    error_msg = (
+                                        "Endpoint origin does not match connection origin: "
+                                        f"{endpoint_url}"
+                                    )
+                                    logger.error(error_msg)
+                                    _emit_channel_event(
+                                        channel_hook,
+                                        "get",
+                                        "error",
+                                        detail=error_msg,
+                                    )
+                                    raise ValueError(error_msg)
+
+                                nonlocal session_id
+                                session_id = _extract_session_id(endpoint_url)
+                                task_status.started(endpoint_url)
+                            elif sse.event == "message":
+                                try:
+                                    message = types.JSONRPCMessage.model_validate_json(sse.data)
+                                except Exception as exc:
+                                    logger.exception("Error parsing server message")
+                                    _emit_channel_event(
+                                        channel_hook,
+                                        "get",
+                                        "error",
+                                        detail="Error parsing server message",
+                                    )
+                                    await read_stream_writer.send(exc)
+                                    continue
+
+                                _emit_channel_event(channel_hook, "get", "message", message=message)
+                                await read_stream_writer.send(SessionMessage(message))
+                            else:
+                                _emit_channel_event(
+                                    channel_hook,
+                                    "get",
+                                    "keepalive",
+                                    raw_event=sse.event or "keepalive",
+                                )
+                    except SSEError as sse_exc:
+                        logger.exception("Encountered SSE exception")
+                        _emit_channel_event(
+                            channel_hook,
+                            "get",
+                            "error",
+                            detail=str(sse_exc),
+                        )
+                        raise
+                    except Exception as exc:
+                        logger.exception("Error in sse_reader")
+                        _emit_channel_event(
+                            channel_hook,
+                            "get",
+                            "error",
+                            detail=str(exc),
+                        )
+                        await read_stream_writer.send(exc)
+                    finally:
+                        await read_stream_writer.aclose()
+
+                async def post_writer(endpoint_url: str):
+                    try:
+                        async with write_stream_reader:
+                            async for session_message in write_stream_reader:
+                                try:
+                                    payload = session_message.message.model_dump(
+                                        by_alias=True,
+                                        mode="json",
+                                        exclude_none=True,
+                                    )
+                                except Exception:
+                                    logger.exception("Invalid session message payload")
+                                    continue
+
+                                _emit_channel_event(
+                                    channel_hook,
+                                    "post-sse",
+                                    "message",
+                                    message=session_message.message,
+                                )
+
+                                try:
+                                    response = await client.post(endpoint_url, json=payload)
+                                    response.raise_for_status()
+                                except httpx.HTTPStatusError as exc:
+                                    status_code, detail = _format_http_error(exc)
+                                    _emit_channel_event(
+                                        channel_hook,
+                                        "post-sse",
+                                        "error",
+                                        detail=detail,
+                                        status_code=status_code,
+                                    )
+                                    raise
+                    except httpx.HTTPStatusError:
+                        logger.exception("HTTP error in post_writer")
+                    except Exception:
+                        logger.exception("Error in post_writer")
+                        _emit_channel_event(
+                            channel_hook,
+                            "post-sse",
+                            "error",
+                            detail="Error sending client message",
+                        )
+                    finally:
+                        await write_stream.aclose()
+
+                try:
+                    async with aconnect_sse(
+                        client,
+                        "GET",
+                        url,
+                    ) as event_source:
+                        try:
+                            event_source.response.raise_for_status()
+                        except httpx.HTTPStatusError as exc:
+                            status_code, detail = _format_http_error(exc)
+                            _emit_channel_event(
+                                channel_hook,
+                                "get",
+                                "error",
+                                detail=detail,
+                                status_code=status_code,
+                            )
+                            raise
+
+                        _emit_channel_event(channel_hook, "get", "connect")
+                        connected = True
+
+                        endpoint_url = await tg.start(sse_reader)
+                        _emit_channel_event(channel_hook, "post-sse", "connect")
+                        post_connected = True
+                        tg.start_soon(post_writer, endpoint_url)
+
+                        try:
+                            yield read_stream, write_stream, get_session_id
+                        finally:
+                            tg.cancel_scope.cancel()
+                except Exception:
+                    raise
+                finally:
+                    if connected:
+                        _emit_channel_event(channel_hook, "get", "disconnect")
+                    if post_connected:
+                        _emit_channel_event(channel_hook, "post-sse", "disconnect")
+        finally:
+            await read_stream_writer.aclose()
+            await read_stream.aclose()
+            await write_stream_reader.aclose()
+            await write_stream.aclose()

fast_agent/mcp/transport_tracking.py

@@ -82,6 +82,8 @@ class ChannelSnapshot(BaseModel):
     response_count: int = 0
     notification_count: int = 0
     activity_buckets: list[str] | None = None
+    activity_bucket_seconds: int | None = None
+    activity_bucket_count: int | None = None
 
 
 class TransportSnapshot(BaseModel):
@@ -95,12 +97,18 @@ class TransportSnapshot(BaseModel):
     get: ChannelSnapshot | None = None
     resumption: ChannelSnapshot | None = None
     stdio: ChannelSnapshot | None = None
+    activity_bucket_seconds: int | None = None
+    activity_bucket_count: int | None = None
 
 
 class TransportChannelMetrics:
     """Aggregates low-level channel events into user-visible metrics."""
 
-    def __init__(self) -> None:
+    def __init__(
+        self,
+        bucket_seconds: int | None = None,
+        bucket_count: int | None = None,
+    ) -> None:
         self._lock = Lock()
 
         self._post_modes: set[str] = set()
@@ -155,8 +163,22 @@ class TransportChannelMetrics:
 
         self._response_channel_by_id: dict[RequestId, ChannelName] = {}
 
-        self._history_bucket_seconds = 30
-        self._history_bucket_count = 20
+        try:
+            seconds = 30 if bucket_seconds is None else int(bucket_seconds)
+        except (TypeError, ValueError):
+            seconds = 30
+        if seconds <= 0:
+            seconds = 30
+
+        try:
+            count = 20 if bucket_count is None else int(bucket_count)
+        except (TypeError, ValueError):
+            count = 20
+        if count <= 0:
+            count = 20
+
+        self._history_bucket_seconds = seconds
+        self._history_bucket_count = count
         self._history_priority = {
             "error": 5,
             "disabled": 4,
@@ -463,6 +485,8 @@ class TransportChannelMetrics:
             last_message_summary=stats.last_summary,
             last_message_at=stats.last_at,
             activity_buckets=self._build_activity_buckets(f"post-{mode}", now),
+            activity_bucket_seconds=self._history_bucket_seconds,
+            activity_bucket_count=self._history_bucket_count,
         )
 
     def snapshot(self) -> TransportSnapshot:
@@ -503,6 +527,8 @@ class TransportChannelMetrics:
                     response_count=self._post_response_count,
                     notification_count=self._post_notification_count,
                     activity_buckets=self._merge_activity_buckets(["post-json", "post-sse"], now),
+                    activity_bucket_seconds=self._history_bucket_seconds,
+                    activity_bucket_count=self._history_bucket_count,
                 )
 
             post_json_snapshot = self._build_post_mode_snapshot("json", now)
@@ -543,6 +569,8 @@ class TransportChannelMetrics:
                     response_count=self._get_response_count,
                     notification_count=self._get_notification_count,
                     activity_buckets=self._build_activity_buckets("get", now),
+                    activity_bucket_seconds=self._history_bucket_seconds,
+                    activity_bucket_count=self._history_bucket_count,
                 )
 
             resumption_snapshot = None
@@ -555,6 +583,8 @@ class TransportChannelMetrics:
                     response_count=self._resumption_response_count,
                     notification_count=self._resumption_notification_count,
                     activity_buckets=self._build_activity_buckets("resumption", now),
+                    activity_bucket_seconds=self._history_bucket_seconds,
+                    activity_bucket_count=self._history_bucket_count,
                 )
 
             stdio_snapshot = None
@@ -588,6 +618,8 @@ class TransportChannelMetrics:
                     response_count=self._stdio_response_count,
                     notification_count=self._stdio_notification_count,
                     activity_buckets=self._build_activity_buckets("stdio", now),
+                    activity_bucket_seconds=self._history_bucket_seconds,
+                    activity_bucket_count=self._history_bucket_count,
                 )
 
             return TransportSnapshot(
@@ -597,4 +629,6 @@ class TransportChannelMetrics:
                 get=get_snapshot,
                 resumption=resumption_snapshot,
                 stdio=stdio_snapshot,
+                activity_bucket_seconds=self._history_bucket_seconds,
+                activity_bucket_count=self._history_bucket_count,
             )

fast_agent/mcp/types.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from fast_agent.interfaces import AgentProtocol
+
+if TYPE_CHECKING:
+    from fast_agent.context import Context
+    from fast_agent.mcp.mcp_aggregator import MCPAggregator
+    from fast_agent.ui.console_display import ConsoleDisplay
+
+
+@runtime_checkable
+class McpAgentProtocol(AgentProtocol, Protocol):
+    """Agent protocol with MCP-specific surface area."""
+
+    @property
+    def aggregator(self) -> MCPAggregator: ...
+
+    @property
+    def display(self) -> "ConsoleDisplay": ...
+
+    @property
+    def context(self) -> "Context | None": ...

fast_agent/resources/examples/workflows/router.py

@@ -60,6 +60,7 @@ async def main() -> None:
         await agent.interactive(agent_name="route")
         for request in SAMPLE_REQUESTS:
             await agent.route(request)
+        await agent.interactive()
 
 
 if __name__ == "__main__":

fast_agent/resources/setup/fastagent.config.yaml

@@ -15,6 +15,11 @@ default_model: gpt-5-mini.low
 # mcp_ui_output_dir: ".fast-agent/ui"  # Where to write MCP-UI HTML files (relative to CWD if not absolute)
 # mcp_ui_mode: enabled
 
+# MCP timeline display (adjust activity window/intervals in MCP UI + fast-agent check)
+mcp_timeline:
+  steps: 20 # number of timeline buckets to render
+  step_seconds: 15 # seconds per bucket (accepts values like "45s", "2m")
+
 # Logging and Console Configuration:
 logger:
   # level: "debug" | "info" | "warning" | "error"
@@ -23,13 +28,14 @@ logger:
 
   # Switch the progress display on or off
   progress_display: true
-
   # Show chat User/Assistant messages on the console
   show_chat: true
   # Show tool calls on the console
   show_tools: true
   # Truncate long tool responses on the console
   truncate_tools: true
+  # Streaming renderer for assistant responses: "markdown", "plain", or "none"
+  streaming: markdown
 
 # MCP Servers
 mcp: