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

solace_agent_mesh/common/a2a/__init__.py

@@ -14,6 +14,8 @@ from .artifact import (
     get_artifact_id,
     get_artifact_name,
     get_parts_from_artifact,
+    get_text_content_from_artifact,
+    is_text_only_artifact,
     update_artifact_parts,
     prepare_file_part_for_publishing,
     resolve_file_part_uri,
@@ -25,6 +27,8 @@ from .events import (
     get_artifact_from_artifact_update,
     get_data_parts_from_status_update,
     get_message_from_status_update,
+    is_task_artifact_update,
+    is_task_status_update,
 )
 from .message import (
     create_agent_data_message,
@@ -51,6 +55,11 @@ from .message import (
     get_text_from_message,
     get_text_from_text_part,
     get_uri_from_file_part,
+    is_data_part,
+    is_file_part,
+    is_file_part_bytes,
+    is_file_part_uri,
+    is_text_part,
 )
 from .protocol import (
     create_cancel_task_request,
@@ -92,8 +101,11 @@ from .protocol import (
     get_response_result,
     get_task_id_from_cancel_request,
     extract_task_id_from_topic,
+    is_client_event,
+    is_message_object,
     subscription_to_regex,
     topic_matches_subscription,
+    unpack_client_event,
 )
 from .task import (
     create_final_task,
@@ -122,6 +134,8 @@ __all__ = [
     "get_artifact_id",
     "get_artifact_name",
     "get_parts_from_artifact",
+    "get_text_content_from_artifact",
+    "is_text_only_artifact",
     "update_artifact_parts",
     "prepare_file_part_for_publishing",
     "resolve_file_part_uri",
@@ -132,6 +146,8 @@ __all__ = [
     "get_artifact_from_artifact_update",
     "get_data_parts_from_status_update",
     "get_message_from_status_update",
+    "is_task_artifact_update",
+    "is_task_status_update",
     # message.py
     "create_agent_data_message",
     "create_agent_parts_message",
@@ -157,6 +173,11 @@ __all__ = [
     "get_text_from_message",
     "get_uri_from_file_part",
     "get_text_from_text_part",
+    "is_data_part",
+    "is_file_part",
+    "is_file_part_bytes",
+    "is_file_part_uri",
+    "is_text_part",
     # protocol.py
     "create_cancel_task_request",
     "create_error_response",
@@ -197,8 +218,11 @@ __all__ = [
     "get_response_result",
     "get_task_id_from_cancel_request",
     "extract_task_id_from_topic",
+    "is_client_event",
+    "is_message_object",
     "subscription_to_regex",
     "topic_matches_subscription",
+    "unpack_client_event",
     # task.py
     "create_final_task",
     "create_initial_task",

solace_agent_mesh/common/a2a/artifact.py

@@ -327,3 +327,42 @@ def get_parts_from_artifact(artifact: Artifact) -> List[ContentPart]:
         A list of the unwrapped content parts.
     """
     return [part.root for part in artifact.parts]
+
+
+def is_text_only_artifact(artifact: Artifact) -> bool:
+    """
+    Checks if an artifact contains only TextParts.
+
+    Args:
+        artifact: The Artifact object to check.
+
+    Returns:
+        True if all parts are TextParts, False otherwise.
+    """
+    if not artifact.parts:
+        return False
+    
+    for part in artifact.parts:
+        if not isinstance(part.root, TextPart):
+            return False
+    
+    return True
+
+
+def get_text_content_from_artifact(artifact: Artifact) -> List[str]:
+    """
+    Extracts all text content from TextParts in an artifact.
+
+    Args:
+        artifact: The Artifact object to extract text from.
+
+    Returns:
+        A list of text strings from all TextParts. Returns empty list if no TextParts found.
+    """
+    text_content = []
+    
+    for part in artifact.parts:
+        if isinstance(part.root, TextPart):
+            text_content.append(part.root.text)
+    
+    return text_content

solace_agent_mesh/common/a2a/events.py

@@ -181,3 +181,32 @@ def get_artifact_from_artifact_update(
     if event:
         return event.artifact
     return None
+
+
+# --- Type Checking Helpers ---
+
+
+def is_task_status_update(obj: Any) -> bool:
+    """
+    Checks if an object is a TaskStatusUpdateEvent.
+
+    Args:
+        obj: The object to check.
+
+    Returns:
+        True if the object is a TaskStatusUpdateEvent, False otherwise.
+    """
+    return isinstance(obj, TaskStatusUpdateEvent)
+
+
+def is_task_artifact_update(obj: Any) -> bool:
+    """
+    Checks if an object is a TaskArtifactUpdateEvent.
+
+    Args:
+        obj: The object to check.
+
+    Returns:
+        True if the object is a TaskArtifactUpdateEvent, False otherwise.
+    """
+    return isinstance(obj, TaskArtifactUpdateEvent)

solace_agent_mesh/common/a2a/message.py

@@ -305,3 +305,71 @@ def get_filename_from_file_part(part: FilePart) -> Optional[str]:
 def get_mimetype_from_file_part(part: FilePart) -> Optional[str]:
     """Safely retrieves the MIME type from a FilePart."""
     return part.file.mime_type
+
+
+# --- Type Checking Helpers ---
+
+
+def is_text_part(part: Part) -> bool:
+    """
+    Checks if a Part contains a TextPart.
+
+    Args:
+        part: The Part object to check.
+
+    Returns:
+        True if the part contains a TextPart, False otherwise.
+    """
+    return isinstance(part.root, TextPart)
+
+
+def is_file_part(part: Part) -> bool:
+    """
+    Checks if a Part contains a FilePart.
+
+    Args:
+        part: The Part object to check.
+
+    Returns:
+        True if the part contains a FilePart, False otherwise.
+    """
+    return isinstance(part.root, FilePart)
+
+
+def is_data_part(part: Part) -> bool:
+    """
+    Checks if a Part contains a DataPart.
+
+    Args:
+        part: The Part object to check.
+
+    Returns:
+        True if the part contains a DataPart, False otherwise.
+    """
+    return isinstance(part.root, DataPart)
+
+
+def is_file_part_bytes(part: FilePart) -> bool:
+    """
+    Checks if a FilePart uses FileWithBytes (embedded content).
+
+    Args:
+        part: The FilePart object to check.
+
+    Returns:
+        True if the file content is embedded as bytes, False otherwise.
+    """
+    return isinstance(part.file, FileWithBytes)
+
+
+def is_file_part_uri(part: FilePart) -> bool:
+    """
+    Checks if a FilePart uses FileWithUri (reference to external content).
+
+    Args:
+        part: The FilePart object to check.
+
+    Returns:
+        True if the file content is a URI reference, False otherwise.
+    """
+    return isinstance(part.file, FileWithUri)

solace_agent_mesh/common/a2a/protocol.py

@@ -5,7 +5,7 @@ parsing of JSON-RPC requests and responses.
 import logging
 import re
 import uuid
-from typing import Any, Dict, Optional, Union
+from typing import Any, Dict, Optional, Tuple, Union
 
 from a2a.types import (
     A2ARequest,
@@ -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
@@ -532,3 +610,75 @@ def extract_task_id_from_topic(
         subscription_pattern,
     )
     return None
+
+
+# --- Client Event Helpers ---
+
+
+def is_client_event(obj: Any) -> bool:
+    """
+    Checks if an object is a ClientEvent tuple (Task, UpdateEvent).
+
+    A ClientEvent is a tuple with 2 elements where the first element is a Task
+    and the second is either a TaskStatusUpdateEvent, TaskArtifactUpdateEvent, or None.
+
+    Args:
+        obj: The object to check.
+
+    Returns:
+        True if the object is a ClientEvent tuple, False otherwise.
+    """
+    if not isinstance(obj, tuple) or len(obj) != 2:
+        return False
+    
+    task, update_event = obj
+    
+    # First element must be a Task
+    if not isinstance(task, Task):
+        return False
+    
+    # Second element must be an update event or None
+    if update_event is not None and not isinstance(
+        update_event, (TaskStatusUpdateEvent, TaskArtifactUpdateEvent)
+    ):
+        return False
+    
+    return True
+
+
+def is_message_object(obj: Any) -> bool:
+    """
+    Checks if an object is a Message.
+
+    Args:
+        obj: The object to check.
+
+    Returns:
+        True if the object is a Message, False otherwise.
+    """
+    return isinstance(obj, Message)
+
+
+def unpack_client_event(
+    event: tuple,
+) -> Tuple[Task, Optional[Union[TaskStatusUpdateEvent, TaskArtifactUpdateEvent]]]:
+    """
+    Safely unpacks a ClientEvent tuple into its components.
+
+    Args:
+        event: A ClientEvent tuple (Task, UpdateEvent).
+
+    Returns:
+        A tuple of (Task, Optional[UpdateEvent]) where UpdateEvent can be
+        TaskStatusUpdateEvent, TaskArtifactUpdateEvent, or None.
+
+    Raises:
+        ValueError: If the event is not a valid ClientEvent tuple.
+    """
+    if not is_client_event(event):
+        raise ValueError(
+            f"Expected a ClientEvent tuple, got {type(event).__name__}"
+        )
+    
+    task, update_event = event
+    return task, update_event

solace_agent_mesh/common/agent_registry.py

@@ -4,26 +4,37 @@ Consolidated from src/tools/common/agent_registry.py and src/tools/a2a_cli_clien
 """
 
 import threading
-from typing import Dict, List, Optional
+import time
+from typing import Dict, List, Optional, Tuple
+import logging
 
 from a2a.types import AgentCard
 
+log = logging.getLogger(__name__)
 
 class AgentRegistry:
-    """Stores and manages discovered AgentCards."""
+    """Stores and manages discovered AgentCards with health tracking."""
 
     def __init__(self):
         self._agents: Dict[str, AgentCard] = {}
+        self._last_seen: Dict[str, float] = {}  # Timestamp of last agent card received
         self._lock = threading.Lock()
 
     def add_or_update_agent(self, agent_card: AgentCard):
         """Adds a new agent or updates an existing one."""
+        
         if not agent_card or not agent_card.name:
-            return
+            log.warning("Attempted to register agent with invalid agent card or missing name")
+            return False
 
         with self._lock:
             is_new = agent_card.name not in self._agents
+            current_time = time.time()
+            
+            # Store the agent information
             self._agents[agent_card.name] = agent_card
+            self._last_seen[agent_card.name] = current_time
+                    
             return is_new
 
     def get_agent(self, agent_name: str) -> Optional[AgentCard]:
@@ -35,8 +46,77 @@ class AgentRegistry:
         """Returns a sorted list of discovered agent names."""
         with self._lock:
             return sorted(list(self._agents.keys()))
+            
+    def get_last_seen(self, agent_name: str) -> Optional[float]:
+        """Returns the timestamp when the agent was last seen."""
+        with self._lock:
+            return self._last_seen.get(agent_name)
+            
+    def check_ttl_expired(self, agent_name: str, ttl_seconds: int) -> Tuple[bool, int]:
+        """
+        Checks if an agent's TTL has expired.
+        
+        Args:
+            agent_name: The name of the agent to check
+            ttl_seconds: The TTL in seconds
+            
+        Returns:
+            A tuple of (is_expired, seconds_since_last_seen)
+        """
+        
+        with self._lock:
+            if agent_name not in self._last_seen:
+                log.debug("Attempted to check TTL for non-existent agent '%s'", agent_name)
+                return False, 0
+                
+            last_seen_time = self._last_seen.get(agent_name)
+            current_time = time.time()
+            time_since_last_seen = int(current_time - last_seen_time) if last_seen_time else 0
+            
+            is_expired = time_since_last_seen > ttl_seconds
+            
+            if is_expired:
+                log.warning(
+                    "AGENT HEALTH CRITICAL: Agent '%s' TTL expired. "
+                    "Last seen: %s seconds ago, TTL: %d seconds",
+                    agent_name,
+                    time_since_last_seen,
+                    ttl_seconds
+                )
+            
+            return is_expired, time_since_last_seen
+            
+    def remove_agent(self, agent_name: str) -> bool:
+        """Removes an agent from the registry."""
+        
+        with self._lock:
+            if agent_name in self._agents:
+                # Get agent details before removal for logging
+                last_seen_time = self._last_seen.get(agent_name)
+                current_time = time.time()
+                time_since_last_seen = int(current_time - last_seen_time) if last_seen_time else "unknown"
+                
+                # Log detailed information about the agent being removed
+                log.warning(
+                    "AGENT DE-REGISTRATION: Removing agent '%s' from registry. "
+                    "Last seen: %s seconds ago",
+                    agent_name,
+                    time_since_last_seen
+                )
+                
+                # Remove the agent from all tracking dictionaries
+                del self._agents[agent_name]
+                if agent_name in self._last_seen:
+                    del self._last_seen[agent_name]
+                
+                log.info("Agent '%s' successfully removed from registry", agent_name)
+                return True
+            else:
+                log.debug("Attempted to remove non-existent agent '%s' from registry", agent_name)
+                return False
 
     def clear(self):
         """Clears all registered agents."""
         with self._lock:
             self._agents.clear()
+            self._last_seen.clear()

solace_agent_mesh/common/constants.py

@@ -1,4 +1,6 @@
 
 DEFAULT_COMMUNICATION_TIMEOUT = 600  # 10 minutes
+HEALTH_CHECK_TTL_SECONDS = 60  # 60 seconds - time after which a health check is considered stale
+HEALTH_CHECK_INTERVAL_SECONDS = 10  # 10 seconds - interval between health checks
 TEXT_ARTIFACT_CONTEXT_MAX_LENGTH_CAPACITY = 200000  # maximum number of characters that can be loaded from a text artifact
-TEXT_ARTIFACT_CONTEXT_DEFAULT_LENGTH = 100000  # default number of characters to load from a text artifact 
+TEXT_ARTIFACT_CONTEXT_DEFAULT_LENGTH = 100000  # default number of characters to load from a text artifact