fast-agent-mcp 0.4.7__py3-none-any.whl

fast_agent/core/logging/transport.py

@@ -0,0 +1,481 @@
+"""
+Transports for the Logger module for MCP Agent, including:
+- Local + optional remote event transport
+- Async event bus
+"""
+
+import asyncio
+import json
+import traceback
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Protocol
+
+import aiohttp
+from opentelemetry import trace
+from rich import print
+from rich.json import JSON
+from rich.text import Text
+
+from fast_agent.config import LoggerSettings
+from fast_agent.core.logging.events import Event, EventFilter
+from fast_agent.core.logging.json_serializer import JSONSerializer
+from fast_agent.core.logging.listeners import EventListener, LifecycleAwareListener
+from fast_agent.ui.console import console
+
+
+class EventTransport(Protocol):
+    """
+    Pluggable interface for sending events to a remote or external system
+    (Kafka, RabbitMQ, REST, etc.).
+    """
+
+    async def send_event(self, event: Event) -> None:
+        """
+        Send an event to the external system.
+        Args:
+            event: Event to send.
+        """
+        ...
+
+
+class FilteredEventTransport(EventTransport, ABC):
+    """
+    Event transport that filters events based on a filter before sending.
+    """
+
+    def __init__(self, event_filter: EventFilter | None = None) -> None:
+        self.filter = event_filter
+
+    async def send_event(self, event: Event) -> None:
+        if not self.filter or self.filter.matches(event):
+            await self.send_matched_event(event)
+
+    @abstractmethod
+    async def send_matched_event(self, event: Event):
+        """Send an event to the external system."""
+
+
+class NoOpTransport(FilteredEventTransport):
+    """Default transport that does nothing (purely local)."""
+
+    async def send_matched_event(self, event) -> None:
+        """Do nothing."""
+        pass
+
+
+class ConsoleTransport(FilteredEventTransport):
+    """Simple transport that prints events to console."""
+
+    def __init__(self, event_filter: EventFilter | None = None) -> None:
+        super().__init__(event_filter=event_filter)
+        # Use shared console instances
+        self._serializer = JSONSerializer()
+        self.log_level_styles: dict[str, str] = {
+            "info": "bold green",
+            "debug": "dim white",
+            "warning": "bold yellow",
+            "error": "bold red",
+        }
+
+    async def send_matched_event(self, event: Event) -> None:
+        # Map log levels to styles
+        style = self.log_level_styles.get(event.type, "white")
+
+        # Use the appropriate console based on event type
+        #        output_console = error_console if event.type == "error" else console
+        output_console = console
+
+        # Create namespace without None
+        namespace = event.namespace
+        if event.name:
+            namespace = f"{namespace}.{event.name}"
+
+        log_text = Text.assemble(
+            (f"[{event.type.upper()}] ", style),
+            (f"{event.timestamp.replace(microsecond=0).isoformat()} ", "cyan"),
+            (f"{namespace} ", "magenta"),
+            (f"- {event.message}", "white"),
+        )
+        output_console.print(log_text)
+
+        # Print additional data as JSON if available
+        if event.data:
+            serialized_data = self._serializer(event.data)
+            output_console.print(JSON.from_data(serialized_data))
+
+
+class FileTransport(FilteredEventTransport):
+    """Transport that writes events to a file with proper formatting."""
+
+    def __init__(
+        self,
+        filepath: str | Path,
+        event_filter: EventFilter | None = None,
+        mode: str = "a",
+        encoding: str = "utf-8",
+    ) -> None:
+        """Initialize FileTransport.
+
+        Args:
+            filepath: Path to the log file. If relative, the current working directory will be used
+            event_filter: Optional filter for events
+            mode: File open mode ('a' for append, 'w' for write)
+            encoding: File encoding to use
+        """
+        super().__init__(event_filter=event_filter)
+        self.filepath = Path(filepath)
+        self.mode = mode
+        self.encoding = encoding
+        self._serializer = JSONSerializer()
+
+        # Create directory if it doesn't exist
+        self.filepath.parent.mkdir(parents=True, exist_ok=True)
+
+    async def send_matched_event(self, event: Event) -> None:
+        """Write matched event to log file asynchronously.
+
+        Args:
+            event: Event to write to file
+        """
+        # Format the log entry
+        namespace = event.namespace
+        if event.name:
+            namespace = f"{namespace}.{event.name}"
+
+        log_entry = {
+            "level": event.type.upper(),
+            "timestamp": event.timestamp.isoformat(),
+            "namespace": namespace,
+            "message": event.message,
+        }
+
+        # Add event data if present
+        if event.data:
+            log_entry["data"] = self._serializer(event.data)
+
+        try:
+            with open(self.filepath, mode=self.mode, encoding=self.encoding) as f:
+                # Write the log entry as compact JSON (JSONL format)
+                f.write(json.dumps(log_entry, separators=(",", ":")) + "\n")
+                f.flush()  # Ensure writing to disk
+        except IOError as e:
+            # Log error without recursion
+            print(f"Error writing to log file {self.filepath}: {e}")
+
+    async def close(self) -> None:
+        """Clean up resources if needed."""
+        pass  # File handles are automatically closed after each write
+
+    @property
+    def is_closed(self) -> bool:
+        """Check if transport is closed."""
+        return False  # Since we open/close per write
+
+
+class HTTPTransport(FilteredEventTransport):
+    """
+    Sends events to an HTTP endpoint in batches.
+    Useful for sending to remote logging services like Elasticsearch, etc.
+    """
+
+    def __init__(
+        self,
+        endpoint: str,
+        headers: dict[str, str] = None,
+        batch_size: int = 100,
+        timeout: float = 5.0,
+        event_filter: EventFilter | None = None,
+    ) -> None:
+        super().__init__(event_filter=event_filter)
+        self.endpoint = endpoint
+        self.headers = headers or {}
+        self.batch_size = batch_size
+        self.timeout = timeout
+
+        self.batch: list[Event] = []
+        self.lock = asyncio.Lock()
+        self._session: aiohttp.ClientSession | None = None
+        self._serializer = JSONSerializer()
+
+    async def start(self) -> None:
+        """Initialize HTTP session."""
+        if not self._session:
+            self._session = aiohttp.ClientSession(
+                headers=self.headers, timeout=aiohttp.ClientTimeout(total=self.timeout)
+            )
+
+    async def stop(self) -> None:
+        """Close HTTP session and flush any remaining events."""
+        if self.batch:
+            await self._flush()
+        if self._session:
+            await self._session.close()
+            self._session = None
+
+    async def send_matched_event(self, event: Event) -> None:
+        """Add event to batch, flush if batch is full."""
+        async with self.lock:
+            self.batch.append(event)
+            if len(self.batch) >= self.batch_size:
+                await self._flush()
+
+    async def _flush(self) -> None:
+        """Send batch of events to HTTP endpoint."""
+        if not self.batch:
+            return
+
+        if not self._session:
+            await self.start()
+
+        try:
+            # Convert events to JSON-serializable dicts
+            events_data = [
+                {
+                    "timestamp": event.timestamp.isoformat(),
+                    "type": event.type,
+                    "name": event.name,
+                    "namespace": event.namespace,
+                    "message": event.message,
+                    "data": self._serializer(event.data),
+                    "trace_id": event.trace_id,
+                    "span_id": event.span_id,
+                    "context": event.context.dict() if event.context else None,
+                }
+                for event in self.batch
+            ]
+
+            async with self._session.post(self.endpoint, json=events_data) as response:
+                if response.status >= 400:
+                    text = await response.text()
+                    print(
+                        f"Error sending log events to {self.endpoint}. "
+                        f"Status: {response.status}, Response: {text}"
+                    )
+        except Exception as e:
+            print(f"Error sending log events to {self.endpoint}: {e}")
+        finally:
+            self.batch.clear()
+
+
+class AsyncEventBus:
+    """
+    Async event bus with local in-process listeners + optional remote transport.
+    Also injects distributed tracing (trace_id, span_id) if there's a current span.
+    """
+
+    _instance = None
+
+    def __init__(self, transport: EventTransport | None = None) -> None:
+        self.transport: EventTransport = transport or NoOpTransport()
+        self.listeners: dict[str, EventListener] = {}
+        self._queue: asyncio.Queue | None = None
+        self._task: asyncio.Task | None = None
+        self._running = False
+
+    @classmethod
+    def get(cls, transport: EventTransport | None = None) -> "AsyncEventBus":
+        """Get the singleton instance of the event bus."""
+        if cls._instance is None:
+            cls._instance = cls(transport=transport)
+        elif transport is not None:
+            # Update transport if provided
+            cls._instance.transport = transport
+        return cls._instance
+
+    @classmethod
+    def reset(cls) -> None:
+        """
+        Reset the singleton instance.
+        This is primarily useful for testing scenarios where you need to ensure
+        a clean state between tests.
+        """
+        if cls._instance:
+            # Signal shutdown
+            cls._instance._running = False
+
+            # Clear the singleton instance
+            cls._instance = None
+
+    async def start(self) -> None:
+        """Start the event bus and all lifecycle-aware listeners."""
+        if self._running:
+            return
+
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+
+        self._queue = asyncio.Queue()
+
+        # Start each lifecycle-aware listener
+        for listener in self.listeners.values():
+            if isinstance(listener, LifecycleAwareListener):
+                await listener.start()
+
+        # Start processing
+        self._running = True
+        self._task = asyncio.create_task(self._process_events())
+
+    async def stop(self) -> None:
+        """Stop the event bus and all lifecycle-aware listeners."""
+        if not self._running:
+            return
+
+        # Signal processing to stop
+        self._running = False
+
+        # Try to process remaining items with a timeout
+        if not self._queue.empty():
+            try:
+                # Give some time for remaining items to be processed
+                await asyncio.wait_for(self._queue.join(), timeout=5.0)
+            except asyncio.TimeoutError:
+                # If we timeout, drain the queue to prevent deadlock
+                while not self._queue.empty():
+                    try:
+                        self._queue.get_nowait()
+                        self._queue.task_done()
+                    except asyncio.QueueEmpty:
+                        break
+            except Exception as e:
+                print(f"Error during queue cleanup: {e}")
+        self._queue = None
+
+        # Cancel and wait for task with timeout
+        if self._task and not self._task.done():
+            self._task.cancel()
+            try:
+                # Wait for task to complete with timeout
+                await asyncio.wait_for(self._task, timeout=5.0)
+            except (asyncio.CancelledError, asyncio.TimeoutError):
+                pass  # Task was cancelled or timed out
+            except Exception as e:
+                print(f"Error cancelling process task: {e}")
+        self._task = None
+
+        # Stop each lifecycle-aware listener
+        for listener in self.listeners.values():
+            if isinstance(listener, LifecycleAwareListener):
+                try:
+                    await asyncio.wait_for(listener.stop(), timeout=3.0)
+                except asyncio.TimeoutError:
+                    print(f"Timeout stopping listener: {listener}")
+                except Exception as e:
+                    print(f"Error stopping listener: {e}")
+
+    async def emit(self, event: Event) -> None:
+        """Emit an event to all listeners and transport."""
+        if not self._running:
+            return
+
+        # Inject current tracing info if available
+        span = trace.get_current_span()
+        if span.is_recording():
+            ctx = span.get_span_context()
+            event.trace_id = f"{ctx.trace_id:032x}"
+            event.span_id = f"{ctx.span_id:016x}"
+
+        # Forward to transport first (immediate processing)
+        try:
+            await self.transport.send_event(event)
+        except Exception as e:
+            print(f"Error in transport.send_event: {e}")
+
+        # Then queue for listeners
+        await self._queue.put(event)
+
+    def add_listener(self, name: str, listener: EventListener) -> None:
+        """Add a listener to the event bus."""
+        self.listeners[name] = listener
+
+    def remove_listener(self, name: str) -> None:
+        """Remove a listener from the event bus."""
+        self.listeners.pop(name, None)
+
+    async def _process_events(self) -> None:
+        """Process events from the queue until stopped."""
+        while self._running:
+            event = None
+            try:
+                # Use wait_for with a timeout to allow checking running state
+                try:
+                    event = await asyncio.wait_for(self._queue.get(), timeout=0.1)
+                except asyncio.TimeoutError:
+                    continue
+
+                # Process the event through all listeners
+                tasks = []
+                for listener in self.listeners.values():
+                    try:
+                        tasks.append(listener.handle_event(event))
+                    except Exception as e:
+                        print(f"Error creating listener task: {e}")
+
+                if tasks:
+                    results = await asyncio.gather(*tasks, return_exceptions=True)
+                    for r in results:
+                        if isinstance(r, Exception):
+                            print(f"Error in listener: {r}")
+                            print(
+                                f"Stacktrace: {''.join(traceback.format_exception(type(r), r, r.__traceback__))}"
+                            )
+
+            except asyncio.CancelledError:
+                # TODO -- added _queue assertion; is that necessary?
+                if event is not None and self._queue is not None:
+                    self._queue.task_done()
+                raise
+            except Exception as e:
+                print(f"Error in event processing loop: {e}")
+                # Mark task done for this event
+                if event is not None and self._queue is not None:
+                    self._queue.task_done()
+
+        # Process remaining events in queue
+        if self._queue:
+            while not self._queue.empty():
+                try:
+                    event = self._queue.get_nowait()
+                    tasks = []
+                    for listener in self.listeners.values():
+                        try:
+                            tasks.append(listener.handle_event(event))
+                        except Exception:
+                            pass
+                    if tasks:
+                        await asyncio.gather(*tasks, return_exceptions=True)
+                    self._queue.task_done()
+                except asyncio.QueueEmpty:
+                    break
+
+
+def create_transport(
+    settings: LoggerSettings, event_filter: EventFilter | None = None
+) -> EventTransport:
+    """Create event transport based on settings."""
+    if settings.type == "none":
+        return NoOpTransport(event_filter=event_filter)
+    elif settings.type == "console":
+        return ConsoleTransport(event_filter=event_filter)
+    elif settings.type == "file":
+        if not settings.path:
+            raise ValueError("File path required for file transport")
+        return FileTransport(
+            filepath=settings.path,
+            event_filter=event_filter,
+        )
+    elif settings.type == "http":
+        if not settings.http_endpoint:
+            raise ValueError("HTTP endpoint required for HTTP transport")
+        return HTTPTransport(
+            endpoint=settings.http_endpoint,
+            headers=settings.http_headers,
+            batch_size=settings.batch_size,
+            timeout=settings.http_timeout,
+            event_filter=event_filter,
+        )
+    else:
+        raise ValueError(f"Unsupported transport type: {settings.type}")

fast_agent/core/prompt.py

@@ -0,0 +1,9 @@
+"""
+Compatibility shim: expose Prompt under fast_agent.core.prompt during migration.
+
+Canonical location: fast_agent.mcp.prompt.Prompt
+"""
+
+from fast_agent.mcp.prompt import Prompt
+
+__all__ = ["Prompt"]

fast_agent/core/prompt_templates.py

@@ -0,0 +1,183 @@
+"""
+Helpers for applying template variables to system prompts after initial bootstrap.
+"""
+
+from __future__ import annotations
+
+import platform
+import re
+from pathlib import Path
+from typing import TYPE_CHECKING, Mapping, MutableMapping
+
+if TYPE_CHECKING:
+    from fast_agent.skills import SkillManifest
+
+
+def apply_template_variables(
+    template: str | None, variables: Mapping[str, str | None] | None
+) -> str | None:
+    """
+    Apply a mapping of template variables to the provided template string.
+
+    This helper intentionally performs no work when either the template or variables
+    are empty so callers can safely execute it during both the initial and late
+    initialization passes without accidentally stripping placeholders too early.
+
+    Supports both simple variable substitution and file template patterns:
+    - {{variable}} - Simple variable replacement
+    - {{file:relative/path}} - Reads file contents (relative to workspaceRoot, errors if missing)
+    - {{file_silent:relative/path}} - Reads file contents (relative to workspaceRoot, empty if missing)
+    """
+    if not template or not variables:
+        return template
+
+    resolved = template
+
+    # Get workspaceRoot for file resolution
+    workspace_root = variables.get("workspaceRoot")
+
+    # Apply {{file:...}} templates (relative paths required, resolved from workspaceRoot)
+    file_pattern = re.compile(r"\{\{file:([^}]+)\}\}")
+
+    def replace_file(match):
+        file_path_str = match.group(1).strip()
+        file_path = Path(file_path_str).expanduser()
+
+        # Enforce relative paths
+        if file_path.is_absolute():
+            raise ValueError(
+                f"File template paths must be relative, got absolute path: {file_path_str}"
+            )
+
+        # Resolve against workspaceRoot if available
+        if workspace_root:
+            resolved_path = (Path(workspace_root) / file_path).resolve()
+        else:
+            resolved_path = file_path.resolve()
+
+        return resolved_path.read_text(encoding="utf-8")
+
+    resolved = file_pattern.sub(replace_file, resolved)
+
+    # Apply {{file_silent:...}} templates (missing files become empty strings)
+    file_silent_pattern = re.compile(r"\{\{file_silent:([^}]+)\}\}")
+
+    def replace_file_silent(match):
+        file_path_str = match.group(1).strip()
+        file_path = Path(file_path_str).expanduser()
+
+        # Enforce relative paths
+        if file_path.is_absolute():
+            raise ValueError(
+                f"File template paths must be relative, got absolute path: {file_path_str}"
+            )
+
+        # Resolve against workspaceRoot if available
+        if workspace_root:
+            resolved_path = (Path(workspace_root) / file_path).resolve()
+        else:
+            resolved_path = file_path.resolve()
+
+        try:
+            return resolved_path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return ""
+
+    resolved = file_silent_pattern.sub(replace_file_silent, resolved)
+
+    # Apply simple variable substitutions
+    for key, value in variables.items():
+        if value is None:
+            continue
+        placeholder = f"{{{{{key}}}}}"
+        if placeholder in resolved:
+            resolved = resolved.replace(placeholder, value)
+
+    return resolved
+
+
+def load_skills_for_context(
+    workspace_root: str | None, skills_directory_override: str | None = None
+) -> list["SkillManifest"]:
+    """
+    Load skill manifests from the workspace root or override directory.
+
+    Args:
+        workspace_root: The workspace root directory
+        skills_directory_override: Optional override for skills directory (relative to workspace_root)
+
+    Returns:
+        List of SkillManifest objects
+    """
+    from fast_agent.skills.registry import SkillRegistry
+
+    if not workspace_root:
+        return []
+
+    base_dir = Path(workspace_root)
+
+    # If override is provided, treat it as relative to workspace_root
+    override_dir = None
+    if skills_directory_override:
+        override_path = Path(skills_directory_override)
+        # If it's absolute, use as-is; otherwise make relative to workspace_root
+        if override_path.is_absolute():
+            override_dir = override_path
+        else:
+            override_dir = base_dir / override_path
+
+    registry = SkillRegistry(base_dir=base_dir, override_directory=override_dir)
+    return registry.load_manifests()
+
+
+def enrich_with_environment_context(
+    context: MutableMapping[str, str],
+    cwd: str | None,
+    client_info: Mapping[str, str] | None,
+    skills_directory_override: str | None = None,
+) -> None:
+    """
+    Populate the provided context mapping with environment details used for template replacement.
+
+    Args:
+        context: The context mapping to populate
+        cwd: The current working directory (workspace root)
+        client_info: Client information mapping
+        skills_directory_override: Optional override for skills directory
+    """
+    if cwd:
+        context["workspaceRoot"] = cwd
+
+    server_platform = platform.platform()
+    python_version = platform.python_version()
+
+    # Provide individual placeholders for automation
+    if server_platform:
+        context["hostPlatform"] = server_platform
+    context["pythonVer"] = python_version
+
+    # Load and format agent skills
+    if cwd:
+        from fast_agent.skills.registry import format_skills_for_prompt
+
+        skill_manifests = load_skills_for_context(cwd, skills_directory_override)
+        skills_text = format_skills_for_prompt(skill_manifests)
+        context["agentSkills"] = skills_text
+
+    env_lines: list[str] = []
+    if cwd:
+        env_lines.append(f"Workspace root: {cwd}")
+    if client_info:
+        display_name = client_info.get("title") or client_info.get("name")
+        version = client_info.get("version")
+        if display_name:
+            if version and version != "unknown":
+                env_lines.append(f"Client: {display_name} {version}")
+            else:
+                env_lines.append(f"Client: {display_name}")
+    if server_platform:
+        env_lines.append(f"Host platform: {server_platform}")
+
+    if env_lines:
+        formatted = "Environment:\n- " + "\n- ".join(env_lines)
+        context["env"] = formatted