solace-agent-mesh 1.6.0__py3-none-any.whl → 1.6.1__py3-none-any.whl

solace_agent_mesh/client/webui/frontend/static/index.html

@@ -5,7 +5,7 @@
         <link rel="icon" type="image/svg+xml" href="/assets/favicon-BLgzUch9.ico" />
         <meta name="viewport" content="width=device-width, initial-scale=1.0" />
         <title>Solace Agent Mesh</title>
-      <script type="module" crossorigin src="/assets/main-BGTaW0uv.js"></script>
+      <script type="module" crossorigin src="/assets/main-B32noGmR.js"></script>
       <link rel="modulepreload" crossorigin href="/assets/vendor-BEmvJSYz.js">
       <link rel="modulepreload" crossorigin href="/assets/client-CaY59VuC.js">
       <link rel="stylesheet" crossorigin href="/assets/main-DHJKSW1S.css">

solace_agent_mesh/common/a2a/protocol.py

@@ -197,6 +197,84 @@ def get_sam_events_subscription_topic(namespace: str, category: str) -> str:
     return f"{namespace.rstrip('/')}/sam/events/{category}/>"
 
 
+def get_trust_card_topic(namespace: str, component_type: str, component_id: str) -> str:
+    """
+    Returns the topic for publishing a Trust Card.
+
+    IMPORTANT: The component_id parameter MUST be the exact broker client-username
+    that the component uses to authenticate with the Solace broker. This is critical
+    for trust verification - trust cards are validated against the actual broker
+    authentication identity.
+
+    Args:
+        namespace: SAM namespace
+        component_type: Type of component ("gateway", "agent", etc.)
+        component_id: MUST be the broker client-username (from broker_username config).
+                     DO NOT use arbitrary IDs like agent_name or gateway_id unless they
+                     match the broker_username exactly.
+
+    Returns:
+        Topic string: {namespace}/a2a/v1/trust/{component_type}/{component_id}
+
+    Raises:
+        ValueError: If any parameter is empty
+
+    Security Note:
+        Trust card verification relies on matching the topic component_id with the
+        authenticated broker client-username. Using a different value breaks the
+        security model and trust chain verification.
+    """
+    if not namespace:
+        raise ValueError("Namespace cannot be empty.")
+    if not component_type:
+        raise ValueError("Component type cannot be empty.")
+    if not component_id:
+        raise ValueError("Component ID cannot be empty.")
+    return f"{get_a2a_base_topic(namespace)}/trust/{component_type}/{component_id}"
+
+
+def get_trust_card_subscription_topic(namespace: str, component_type: Optional[str] = None) -> str:
+    """
+    Returns subscription pattern for Trust Cards.
+    
+    Args:
+        namespace: SAM namespace
+        component_type: Optional - subscribe to specific type, or None for all types
+    
+    Returns:
+        Subscription pattern
+    """
+    if not namespace:
+        raise ValueError("Namespace cannot be empty.")
+    
+    if component_type:
+        return f"{get_a2a_base_topic(namespace)}/trust/{component_type}/*"
+    else:
+        return f"{get_a2a_base_topic(namespace)}/trust/*/*"
+
+
+def extract_trust_card_info_from_topic(topic: str) -> tuple[str, str]:
+    """
+    Extracts component type and ID from trust card topic.
+    
+    Args:
+        topic: Trust card topic
+    
+    Returns:
+        Tuple of (component_type, component_id)
+    
+    Raises:
+        ValueError: If topic format is invalid
+    """
+    parts = topic.split('/')
+    if len(parts) < 6 or parts[1] != 'a2a' or parts[2] != 'v1' or parts[3] != 'trust':
+        raise ValueError(f"Invalid trust card topic format: {topic}")
+    
+    component_type = parts[4]
+    component_id = parts[5]
+    return component_type, component_id
+
+
 def subscription_to_regex(subscription: str) -> str:
     """Converts a Solace topic subscription string to a regex pattern."""
     # Escape regex special characters except for Solace wildcards

solace_agent_mesh/common/sac/sam_component_base.py

@@ -6,7 +6,8 @@ import logging
 import abc
 import asyncio
 import threading
-from typing import Any
+import functools
+from typing import Any, Optional
 
 from solace_ai_connector.components.component_base import ComponentBase
 
@@ -15,6 +16,7 @@ from ..utils.message_utils import validate_message_size
 
 log = logging.getLogger(__name__)
 
+
 class SamComponentBase(ComponentBase, abc.ABC):
     """
     Abstract base class for high-level SAM components (Agents, Gateways).
@@ -54,8 +56,294 @@ class SamComponentBase(ComponentBase, abc.ABC):
 
         self._async_loop: asyncio.AbstractEventLoop | None = None
         self._async_thread: threading.Thread | None = None
+
+        # Timer callback registry
+        self._timer_callbacks: dict[str, Any] = {}
+        self._timer_callbacks_lock = threading.Lock()
+
+        # Trust Manager integration (enterprise feature) - initialized as part of _late_init
+        self.trust_manager: Optional[Any] = None
+
         log.info("%s SamComponentBase initialized successfully.", self.log_identifier)
 
+    def add_timer(
+        self,
+        delay_ms: int,
+        timer_id: str,
+        interval_ms: int = 0,
+        callback: Optional[Any] = None,
+    ):
+        """
+        Add a timer with optional callback.
+
+        Args:
+            delay_ms: Initial delay in milliseconds
+            timer_id: Unique timer identifier
+            interval_ms: Repeat interval in milliseconds (0 for one-shot)
+            callback: Optional callback function to invoke when timer fires.
+                     If provided, callback will be invoked when timer event occurs.
+                     Callback receives timer_data dict as argument.
+                     Callback should be thread-safe or schedule work appropriately.
+        """
+        # Register callback if provided
+        if callback:
+            with self._timer_callbacks_lock:
+                if timer_id in self._timer_callbacks:
+                    log.warning(
+                        "%s Timer ID '%s' already has a registered callback. Overwriting.",
+                        self.log_identifier,
+                        timer_id,
+                    )
+                self._timer_callbacks[timer_id] = callback
+                log.debug(
+                    "%s Registered callback for timer: %s",
+                    self.log_identifier,
+                    timer_id,
+                )
+
+        # Call parent implementation to actually create the timer
+        super().add_timer(delay_ms=delay_ms, timer_id=timer_id, interval_ms=interval_ms)
+
+    def cancel_timer(self, timer_id: str):
+        """
+        Cancel a timer and remove its callback if registered.
+
+        Args:
+            timer_id: Timer identifier to cancel
+        """
+        # Remove callback registration
+        with self._timer_callbacks_lock:
+            if timer_id in self._timer_callbacks:
+                del self._timer_callbacks[timer_id]
+                log.debug(
+                    "%s Unregistered callback for timer: %s",
+                    self.log_identifier,
+                    timer_id,
+                )
+
+        # Call parent implementation to actually cancel the timer
+        super().cancel_timer(timer_id)
+
+    def process_event(self, event):
+        """
+        Process incoming events by routing to appropriate handlers.
+
+        This base implementation handles MESSAGE and TIMER events:
+        - MESSAGE events are routed to _handle_message() abstract method
+        - TIMER events are routed to registered callbacks
+        - Other events are passed to parent class
+
+        Args:
+            event: Event object from SAC framework
+        """
+        from solace_ai_connector.common.event import Event, EventType
+        from solace_ai_connector.common.message import Message as SolaceMessage
+
+        if event.event_type == EventType.MESSAGE:
+            message: SolaceMessage = event.data
+            topic = message.get_topic()
+
+            if not topic:
+                log.warning(
+                    "%s Received message without topic. Ignoring.",
+                    self.log_identifier,
+                )
+                try:
+                    message.call_negative_acknowledgements()
+                except Exception as nack_e:
+                    log.error(
+                        "%s Failed to NACK message without topic: %s",
+                        self.log_identifier,
+                        nack_e,
+                    )
+                return
+
+            try:
+                # Delegate to abstract method implemented by subclass
+                self._handle_message(message, topic)
+            except Exception as e:
+                log.error(
+                    "%s Error in _handle_message for topic %s: %s",
+                    self.log_identifier,
+                    topic,
+                    e,
+                    exc_info=True,
+                )
+                try:
+                    message.call_negative_acknowledgements()
+                except Exception as nack_e:
+                    log.error(
+                        "%s Failed to NACK message after error: %s",
+                        self.log_identifier,
+                        nack_e,
+                    )
+                self.handle_error(e, event)
+
+        elif event.event_type == EventType.TIMER:
+            # Handle timer events via callback registry
+            timer_data = event.data
+            timer_id = timer_data.get("timer_id")
+
+            if not timer_id:
+                log.warning(
+                    "%s Timer event missing timer_id: %s",
+                    self.log_identifier,
+                    timer_data,
+                )
+                return
+
+            # Look up registered callback
+            with self._timer_callbacks_lock:
+                callback = self._timer_callbacks.get(timer_id)
+
+            if callback:
+                try:
+                    log.debug(
+                        "%s Invoking registered callback for timer: %s",
+                        self.log_identifier,
+                        timer_id,
+                    )
+                    callback(timer_data)
+                except Exception as e:
+                    log.error(
+                        "%s Error in timer callback for %s: %s",
+                        self.log_identifier,
+                        timer_id,
+                        e,
+                        exc_info=True,
+                    )
+            else:
+                log.warning(
+                    "%s No callback registered for timer: %s. Timer event ignored.",
+                    self.log_identifier,
+                    timer_id,
+                )
+        else:
+            # Pass other event types to parent class
+            super().process_event(event)
+
+    def _handle_message(self, message, topic: str) -> None:
+        """
+        Handle an incoming message by routing to async handler.
+
+        This base implementation schedules async processing on the component's
+        event loop. Subclasses can override this for custom sync handling,
+        or implement _handle_message_async() for async handling.
+
+        Args:
+            message: The Solace message (SolaceMessage instance)
+            topic: The topic the message was received on
+        """
+        loop = self.get_async_loop()
+        if loop and loop.is_running():
+            # Schedule async processing
+            coro = self._handle_message_async(message, topic)
+            future = asyncio.run_coroutine_threadsafe(coro, loop)
+            future.add_done_callback(
+                functools.partial(self._handle_async_message_completion, topic=topic)
+            )
+        else:
+            log.error(
+                "%s Async loop not available. Cannot process message on topic: %s",
+                self.log_identifier,
+                topic,
+            )
+            raise RuntimeError("Async loop not available for message processing")
+
+    def _handle_async_message_completion(self, future: asyncio.Future, topic: str):
+        """Callback to handle completion of async message processing."""
+        try:
+            if future.cancelled():
+                log.warning(
+                    "%s Message processing for topic %s was cancelled.",
+                    self.log_identifier,
+                    topic,
+                )
+            elif future.done():
+                exception = future.exception()
+                if exception is not None:
+                    log.error(
+                        "%s Message processing for topic %s failed: %s",
+                        self.log_identifier,
+                        topic,
+                        exception,
+                        exc_info=exception,
+                    )
+                else:
+                    # Handle successful completion
+                    try:
+                        _ = future.result()
+                        log.debug(
+                            "%s Message processing for topic %s completed successfully.",
+                            self.log_identifier,
+                            topic,
+                        )
+                        # Optional: Process the result if needed
+                        # self._process_successful_result(result, topic)
+                    except Exception as result_exception:
+                        # This catches exceptions that might occur when getting the result
+                        log.error(
+                            "%s Error retrieving result for topic %s: %s",
+                            self.log_identifier,
+                            topic,
+                            result_exception,
+                            exc_info=result_exception,
+                        )
+            else:
+                # This case shouldn't normally occur in a completion callback,
+                # but it's good defensive programming
+                log.warning(
+                    "%s Future for topic %s is not done in completion handler.",
+                    self.log_identifier,
+                    topic,
+                )
+        except Exception as e:
+            log.error(
+                "%s Error in async message completion handler for topic %s: %s",
+                self.log_identifier,
+                topic,
+                e,
+                exc_info=True,
+            )
+
+    @abc.abstractmethod
+    async def _handle_message_async(self, message, topic: str) -> None:
+        """
+        Async handler for incoming messages.
+
+        Subclasses must implement this to process messages asynchronously.
+        This runs on the component's dedicated async event loop.
+
+        Args:
+            message: The Solace message (SolaceMessage instance)
+            topic: The topic the message was received on
+        """
+        pass
+
+    def _late_init(self):
+        """Late initialization hook called after the component is fully set up."""
+
+        # Setup the Trust Manager if present (enterprise feature)
+        # NOTE: The Trust Manager should use component.get_broker_username() to retrieve
+        # the actual broker client-username for trust card topic construction. This is
+        # critical because trust cards MUST be published on topics that match the actual
+        # authentication identity (client-username) used to connect to the broker.
+        try:
+            from solace_agent_mesh_enterprise.common.trust import (
+                initialize_trust_manager,
+            )
+
+            trust_config = self.get_config("trust_manager")
+            if trust_config and trust_config.get("enabled", False):
+                self.trust_manager = initialize_trust_manager(self)
+                log.info("%s Enterprise Trust Manager initialized", self.log_identifier)
+        except ImportError:
+            log.debug("%s Enterprise Trust Manager not available", self.log_identifier)
+        except Exception as e:
+            log.error(
+                "%s Failed to initialize Trust Manager: %s", self.log_identifier, e
+            )
+
     def publish_a2a_message(
         self, payload: dict, topic: str, user_properties: dict | None = None
     ):
@@ -197,6 +485,10 @@ class SamComponentBase(ComponentBase, abc.ABC):
     def run(self):
         """Starts the component's dedicated async thread."""
         log.info("%s Starting SamComponentBase run method.", self.log_identifier)
+
+        # Do all initialization that needs to be done after we are fully setup
+        self._late_init()
+
         if not self._async_thread or not self._async_thread.is_alive():
             self._async_thread = threading.Thread(
                 target=self._run_async_operations,
@@ -256,14 +548,101 @@ class SamComponentBase(ComponentBase, abc.ABC):
         """Returns the dedicated asyncio event loop for this component's async tasks."""
         return self._async_loop
 
+    def get_broker_username(self) -> Optional[str]:
+        """
+        Returns the broker username (client-username) that this component uses
+        to authenticate with the Solace broker.
+
+        This is critical for trust card publishing and verification, as the
+        trust card topic must match the actual authentication identity.
+
+        Returns:
+            The broker username if available, None otherwise.
+        """
+        try:
+            app = self.get_app()
+            if app and hasattr(app, "app_info"):
+                broker_config = app.app_info.get("broker", {})
+                broker_username = broker_config.get("broker_username")
+                if broker_username:
+                    log.debug(
+                        "%s Retrieved broker username: %s",
+                        self.log_identifier,
+                        broker_username,
+                    )
+                    return broker_username
+                else:
+                    log.warning(
+                        "%s Broker username not found in broker configuration",
+                        self.log_identifier,
+                    )
+            else:
+                log.warning(
+                    "%s Unable to access app or app_info to retrieve broker username",
+                    self.log_identifier,
+                )
+        except Exception as e:
+            log.error(
+                "%s Error retrieving broker username: %s",
+                self.log_identifier,
+                e,
+                exc_info=True,
+            )
+        return None
+
     @abc.abstractmethod
-    async def _async_setup_and_run(self) -> None:
+    def _get_component_id(self) -> str:
+        """
+        Returns unique identifier for this component instance.
+        Must be implemented by subclasses.
+
+        Returns:
+            Unique component identifier (e.g., agent_name, gateway_id)
         """
-        Abstract method for subclasses to implement their main asynchronous logic.
-        This coroutine is executed within the managed event loop.
+        pass
+
+    @abc.abstractmethod
+    def _get_component_type(self) -> str:
+        """
+        Returns component type string.
+        Must be implemented by subclasses.
+
+        Returns:
+            Component type ("gateway", "agent", etc.)
         """
         pass
 
+    async def _async_setup_and_run(self) -> None:
+        """
+        Base async setup that initializes Trust Manager if present.
+        Subclasses should override and call super() first, then add their logic.
+        """
+        # Initialize Trust Manager if present (ENTERPRISE FEATURE)
+        if self.trust_manager:
+            try:
+                log.info(
+                    "%s Initializing Trust Manager with periodic publishing...",
+                    self.log_identifier,
+                )
+                # Pass event loop and add_timer method to Trust Manager
+                await self.trust_manager.initialize(
+                    add_timer_callback=self.add_timer,
+                    event_loop=self.get_async_loop(),
+                )
+                log.info(
+                    "%s Trust Manager initialized successfully", self.log_identifier
+                )
+            except Exception as e:
+                log.error(
+                    "%s Failed to initialize Trust Manager: %s",
+                    self.log_identifier,
+                    e,
+                    exc_info=True,
+                )
+                # Trust Manager failure should not prevent component startup
+                # Set to None to disable trust manager for this session
+                self.trust_manager = None
+
     @abc.abstractmethod
     def _pre_async_cleanup(self) -> None:
         """

solace_agent_mesh/gateway/base/app.py

@@ -19,6 +19,7 @@ from ...common.a2a import (
 
 log = logging.getLogger(__name__)
 
+
 class BaseGatewayComponent(ComponentBase):
     pass
 
@@ -244,6 +245,20 @@ class BaseGatewayApp(App):
                 )
             },
         ]
+
+        # Add trust card subscription if trust manager is enabled
+        trust_config = resolved_app_config_block.get("trust_manager")
+        if trust_config and trust_config.get("enabled", False):
+            from ...common.a2a.protocol import get_trust_card_subscription_topic
+
+            trust_card_topic = get_trust_card_subscription_topic(self.namespace)
+            subscriptions.append({"topic": trust_card_topic})
+            log.info(
+                "Trust Manager enabled for gateway '%s', added trust card subscription: %s",
+                self.gateway_id,
+                trust_card_topic,
+            )
+
         log.info(
             "Generated Solace subscriptions for gateway '%s': %s",
             self.gateway_id,