solace-agent-mesh 1.0.1__py3-none-any.whl → 1.0.3__py3-none-any.whl

solace_agent_mesh/__init__.py

@@ -0,0 +1,5 @@
+"""
+Solace Agent Mesh Initialization
+"""
+from .common.utils.initializer import initialize
+initialize()

solace_agent_mesh/agent/adk/callbacks.py

@@ -785,6 +785,26 @@ It can span multiple lines.
 
 The system will automatically save the content and give you a confirmation in the next turn."""
 
+def _generate_artifact_creation_instruction() -> str:
+    return """
+    **Creating Text-Based Artifacts:**
+
+    **When to Create Text-based Artifacts:**
+    Create an artifact when the content provides value as a standalone file:
+    - Content with special formatting (HTML, Markdown, CSS, structured markup) that requires proper rendering
+    - Content explicitly intended for use outside this conversation (reports, emails, presentations, reference documents)
+    - Structured reference content users will save or follow (schedules, guides, templates)
+    - Content that will be edited, expanded, or reused
+    - Substantial text documents
+    - Technical documentation meant as reference material
+
+    **When NOT to Create Text-based Artifacts:**
+    - Simple answers, explanations, or conversational responses
+    - Brief advice, opinions, or quick information
+    - Short lists, summaries, or single paragraphs  
+    - Temporary content only relevant to the immediate conversation
+    - Basic explanations that don't require reference material
+    """
 
 def _generate_embed_instruction(
     include_artifact_content: bool,
@@ -918,7 +938,7 @@ When faced with a complex goal or request that involves multiple steps, data ret
 Simple, direct requests like 'create an image of a dog' or 'write an email to thank my boss' do not require a plan.
 
 If a plan is created:
-1. It should be a terse, hierarchical list describing the steps needed.
+1. It should be a terse, hierarchical list describing the steps needed, with each checkbox item on its own line.
 2. Use '☐' (empty checkbox emoji) for pending items and '☑' (checked checkbox emoji) for completed items.
 3. If the plan changes significantly during execution, restate the updated plan.
 4. As items are completed, update the plan to check them off.
@@ -926,6 +946,8 @@ If a plan is created:
 """
     injected_instructions.append(planning_instruction)
     log.debug("%s Added hardcoded planning instructions.", log_identifier)
+    artifact_creation_instruction = _generate_artifact_creation_instruction()
+    injected_instructions.append(artifact_creation_instruction)
     fenced_artifact_instruction = _generate_fenced_artifact_instruction()
     injected_instructions.append(fenced_artifact_instruction)
 

solace_agent_mesh/agent/adk/filesystem_artifact_service.py

@@ -23,49 +23,40 @@ class FilesystemArtifactService(BaseArtifactService):
     """
     An artifact service implementation using the local filesystem.
 
-    Stores artifacts in a structured directory based on a configured scope
-    (namespace, app name, or custom), user ID, session ID (or 'user' namespace),
+    Stores artifacts in a structured directory based on the effective app name
+    (which represents the scope), user ID, session ID (or 'user' namespace),
     filename, and version. Metadata (like mime_type) is stored in a companion file.
     """
 
-    def __init__(self, base_path: str, scope_identifier: str):
+    def __init__(self, base_path: str):
         """
         Initializes the FilesystemArtifactService.
 
         Args:
             base_path: The root directory where all artifacts will be stored.
-            scope_identifier: The sanitized identifier representing the storage scope
-                              (e.g., sanitized namespace, app name, or custom value).
 
         Raises:
-            ValueError: If base_path or scope_identifier is not provided or the
-                        scoped base path cannot be created.
+            ValueError: If base_path is not provided or cannot be created.
         """
         if not base_path:
             raise ValueError("base_path cannot be empty for FilesystemArtifactService")
-        if not scope_identifier:
-            raise ValueError(
-                "scope_identifier cannot be empty for FilesystemArtifactService"
-            )
 
         self.base_path = os.path.abspath(base_path)
-        self.scope_identifier = scope_identifier
-        self.scope_base_path = os.path.join(self.base_path, self.scope_identifier)
 
         try:
-            os.makedirs(self.scope_base_path, exist_ok=True)
+            os.makedirs(self.base_path, exist_ok=True)
             logger.info(
-                "FilesystemArtifactService initialized. Scoped base path: %s",
-                self.scope_base_path,
+                "FilesystemArtifactService initialized. Base path: %s",
+                self.base_path,
             )
         except OSError as e:
             logger.error(
-                "Failed to create scoped base directory '%s': %s",
-                self.scope_base_path,
+                "Failed to create base directory '%s': %s",
+                self.base_path,
                 e,
             )
             raise ValueError(
-                f"Could not create or access scoped base_path '{self.scope_base_path}': {e}"
+                f"Could not create or access base_path '{self.base_path}': {e}"
             ) from e
 
     def _file_has_user_namespace(self, filename: str) -> bool:
@@ -76,10 +67,10 @@ class FilesystemArtifactService(BaseArtifactService):
         self, app_name: str, user_id: str, session_id: str, filename: str
     ) -> str:
         """
-        Constructs the directory path for a specific artifact (all versions)
-        within the configured scope.
-        The app_name parameter is ignored for path construction but kept for signature compatibility.
+        Constructs the directory path for a specific artifact (all versions).
+        The `app_name` is now the effective scope identifier, resolved by the caller.
         """
+        app_name_sanitized = os.path.basename(app_name)
         user_id_sanitized = os.path.basename(user_id)
         session_id_sanitized = os.path.basename(session_id)
         filename_sanitized = os.path.basename(filename)
@@ -87,11 +78,16 @@ class FilesystemArtifactService(BaseArtifactService):
         if self._file_has_user_namespace(filename):
             filename_dir = os.path.basename(filename.split(":", 1)[1])
             return os.path.join(
-                self.scope_base_path, user_id_sanitized, "user", filename_dir
+                self.base_path,
+                app_name_sanitized,
+                user_id_sanitized,
+                "user",
+                filename_dir,
             )
         else:
             return os.path.join(
-                self.scope_base_path,
+                self.base_path,
+                app_name_sanitized,
                 user_id_sanitized,
                 session_id_sanitized,
                 filename_sanitized,
@@ -115,7 +111,7 @@ class FilesystemArtifactService(BaseArtifactService):
         filename: str,
         artifact: adk_types.Part,
     ) -> int:
-        log_prefix = f"[FSArtifact:Save:{filename}] "
+        log_prefix = "[FSArtifact:Save] "
 
         filename = self._normalize_filename_unicode(filename)
         artifact_dir = self._get_artifact_dir(app_name, user_id, session_id, filename)
@@ -192,7 +188,7 @@ class FilesystemArtifactService(BaseArtifactService):
         filename: str,
         version: Optional[int] = None,
     ) -> Optional[adk_types.Part]:
-        log_prefix = f"[FSArtifact:Load:{filename}] "
+        log_prefix = "[FSArtifact:Load] "
         filename = self._normalize_filename_unicode(filename)
         artifact_dir = self._get_artifact_dir(app_name, user_id, session_id, filename)
 
@@ -271,13 +267,14 @@ class FilesystemArtifactService(BaseArtifactService):
     async def list_artifact_keys(
         self, *, app_name: str, user_id: str, session_id: str
     ) -> List[str]:
-        log_prefix = f"[FSArtifact:ListKeys] "
+        log_prefix = "[FSArtifact:ListKeys] "
         filenames = set()
+        app_name_sanitized = os.path.basename(app_name)
         user_id_sanitized = os.path.basename(user_id)
         session_id_sanitized = os.path.basename(session_id)
 
         session_base_dir = os.path.join(
-            self.scope_base_path, user_id_sanitized, session_id_sanitized
+            self.base_path, app_name_sanitized, user_id_sanitized, session_id_sanitized
         )
         if await asyncio.to_thread(os.path.isdir, session_base_dir):
             try:
@@ -293,7 +290,9 @@ class FilesystemArtifactService(BaseArtifactService):
                     e,
                 )
 
-        user_base_dir = os.path.join(self.scope_base_path, user_id_sanitized, "user")
+        user_base_dir = os.path.join(
+            self.base_path, app_name_sanitized, user_id_sanitized, "user"
+        )
         if await asyncio.to_thread(os.path.isdir, user_base_dir):
             try:
                 for item in await asyncio.to_thread(os.listdir, user_base_dir):
@@ -316,7 +315,7 @@ class FilesystemArtifactService(BaseArtifactService):
     async def delete_artifact(
         self, *, app_name: str, user_id: str, session_id: str, filename: str
     ) -> None:
-        log_prefix = f"[FSArtifact:Delete:{filename}] "
+        log_prefix = "[FSArtifact:Delete] "
         artifact_dir = self._get_artifact_dir(app_name, user_id, session_id, filename)
 
         if not await asyncio.to_thread(os.path.isdir, artifact_dir):
@@ -332,9 +331,8 @@ class FilesystemArtifactService(BaseArtifactService):
             )
         except OSError as e:
             logger.error(
-                "%sError deleting artifact directory '%s': %s",
+                "%sError deleting artifact directory '%s'",
                 log_prefix,
-                artifact_dir,
                 e,
             )
 
@@ -342,7 +340,7 @@ class FilesystemArtifactService(BaseArtifactService):
     async def list_versions(
         self, *, app_name: str, user_id: str, session_id: str, filename: str
     ) -> List[int]:
-        log_prefix = f"[FSArtifact:ListVersions:{filename}] "
+        log_prefix = "[FSArtifact:ListVersions] "
         artifact_dir = self._get_artifact_dir(app_name, user_id, session_id, filename)
         versions = []
 
@@ -360,22 +358,17 @@ class FilesystemArtifactService(BaseArtifactService):
                 ):
                     versions.append(int(item))
         except OSError as e:
-            logger.error(
-                "%sError listing versions in directory '%s': %s",
-                log_prefix,
-                artifact_dir,
-                e,
-            )
+            logger.error("%sError listing versions in directory '%s'", log_prefix, e)
             return []
 
         sorted_versions = sorted(versions)
         logger.debug("%sFound versions: %s", log_prefix, sorted_versions)
         return sorted_versions
-    
+
     def _normalize_filename_unicode(self, filename: str) -> str:
         """
         Normalizes Unicode characters in a filename to their standard form.
         Specifically targets compatibility characters like non-breaking spaces (\u202f)
         and converts them to their regular ASCII equivalents (a standard space).
         """
-        return unicodedata.normalize('NFKC', filename)
+        return unicodedata.normalize("NFKC", filename)

solace_agent_mesh/agent/adk/runner.py

@@ -132,7 +132,7 @@ async def run_adk_async_task_thread_wrapper(
             logical_task_id,
             tce,
         )
-        sub_tasks_to_cancel = task_context.peer_sub_tasks if task_context else []
+        sub_tasks_to_cancel = task_context.active_peer_sub_tasks if task_context else {}
 
         if sub_tasks_to_cancel:
             log.info(
@@ -141,18 +141,22 @@ async def run_adk_async_task_thread_wrapper(
                 len(sub_tasks_to_cancel),
                 logical_task_id,
             )
-            for sub_task_info in sub_tasks_to_cancel:
+            for sub_task_id, sub_task_info in sub_tasks_to_cancel.items():
                 try:
-                    sub_task_id = sub_task_info.get("sub_task_id")
                     target_peer_agent_name = sub_task_info.get("peer_agent_name")
                     if not sub_task_id or not target_peer_agent_name:
                         log.warning(
-                            "%s Incomplete sub-task info found, cannot cancel: %s",
+                            "%s Incomplete sub-task info found for sub-task %s, cannot cancel: %s",
                             component.log_identifier,
+                            sub_task_id,
                             sub_task_info,
                         )
                         continue
-                    peer_cancel_params = TaskIdParams(id=sub_task_id)
+
+                    task_id_for_peer = sub_task_id.replace(
+                        component.CORRELATION_DATA_PREFIX, "", 1
+                    )
+                    peer_cancel_params = TaskIdParams(id=task_id_for_peer)
                     peer_cancel_request = CancelTaskRequest(params=peer_cancel_params)
                     peer_cancel_user_props = {"clientId": component.agent_name}
                     peer_request_topic = component._get_agent_request_topic(
@@ -167,7 +171,7 @@ async def run_adk_async_task_thread_wrapper(
                     log.error(
                         "%s Failed to send CancelTaskRequest for sub-task %s: %s",
                         component.log_identifier,
-                        sub_task_info.get("sub_task_id"),
+                        sub_task_id,
                         e_peer_cancel,
                         exc_info=True,
                     )

solace_agent_mesh/agent/adk/services.py

@@ -4,8 +4,10 @@ Initializes ADK Services based on configuration.
 
 import os
 import re
-from typing import Dict
+from typing import Dict, Optional, List, Any
+from typing_extensions import override
 
+from google.genai import types as adk_types
 from solace_ai_connector.common.log import log
 
 from google.adk.sessions import (
@@ -28,13 +30,126 @@ from google.adk.memory import (
 from .filesystem_artifact_service import FilesystemArtifactService
 
 try:
-    from tests.integration.infrastructure.artifact_service.service import (
+    from sam_test_infrastructure.artifact_service.service import (
         TestInMemoryArtifactService,
     )
 except ImportError:
     TestInMemoryArtifactService = None
 
 
+class ScopedArtifactServiceWrapper(BaseArtifactService):
+    """
+    A wrapper for an artifact service that transparently applies a configured scope.
+    This ensures all artifact operations respect either 'namespace' or 'app' scoping
+    without requiring changes at the call site. It dynamically checks the component's
+    configuration on each call to support test-specific overrides.
+    """
+
+    def __init__(
+        self,
+        wrapped_service: BaseArtifactService,
+        component: Any,
+    ):
+        """
+        Initializes the ScopedArtifactServiceWrapper.
+
+        Args:
+            wrapped_service: The concrete artifact service instance (e.g., InMemory, GCS).
+            component: The component instance (agent or gateway) that owns this service.
+        """
+        self.wrapped_service = wrapped_service
+        self.component = component
+
+    def _get_scoped_app_name(self, app_name: str) -> str:
+        """
+        Determines the effective app_name for an artifact operation by dynamically
+        checking the component's configuration.
+        """
+        # The component's get_config will handle test-injected overrides.
+        # The default scope is 'namespace' as defined in the app schema.
+        scope_type = self.component.get_config("artifact_scope", "namespace")
+
+        if scope_type == "namespace":
+            # For namespace scope, the value is always the component's namespace.
+            return self.component.namespace
+
+        # For 'app' scope, use the app_name that was passed into the method, which is
+        # typically the agent_name or gateway_id.
+        return app_name
+
+    @override
+    async def save_artifact(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        session_id: str,
+        filename: str,
+        artifact: adk_types.Part,
+    ) -> int:
+        scoped_app_name = self._get_scoped_app_name(app_name)
+        return await self.wrapped_service.save_artifact(
+            app_name=scoped_app_name,
+            user_id=user_id,
+            session_id=session_id,
+            filename=filename,
+            artifact=artifact,
+        )
+
+    @override
+    async def load_artifact(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        session_id: str,
+        filename: str,
+        version: Optional[int] = None,
+    ) -> Optional[adk_types.Part]:
+        scoped_app_name = self._get_scoped_app_name(app_name)
+        return await self.wrapped_service.load_artifact(
+            app_name=scoped_app_name,
+            user_id=user_id,
+            session_id=session_id,
+            filename=filename,
+            version=version,
+        )
+
+    @override
+    async def list_artifact_keys(
+        self, *, app_name: str, user_id: str, session_id: str
+    ) -> List[str]:
+        scoped_app_name = self._get_scoped_app_name(app_name)
+        return await self.wrapped_service.list_artifact_keys(
+            app_name=scoped_app_name, user_id=user_id, session_id=session_id
+        )
+
+    @override
+    async def delete_artifact(
+        self, *, app_name: str, user_id: str, session_id: str, filename: str
+    ) -> None:
+        scoped_app_name = self._get_scoped_app_name(app_name)
+        await self.wrapped_service.delete_artifact(
+            app_name=scoped_app_name,
+            user_id=user_id,
+            session_id=session_id,
+            filename=filename,
+        )
+        return
+
+    @override
+    async def list_versions(
+        self, *, app_name: str, user_id: str, session_id: str, filename: str
+    ) -> List[int]:
+        scoped_app_name = self._get_scoped_app_name(app_name)
+        return await self.wrapped_service.list_versions(
+            app_name=scoped_app_name,
+            user_id=user_id,
+            session_id=session_id,
+            filename=filename,
+        )
+
+
 def _sanitize_for_path(identifier: str) -> str:
     """Sanitizes a string to be safe for use as a directory name."""
     if not identifier:
@@ -88,7 +203,11 @@ def initialize_session_service(component) -> BaseSessionService:
 
 
 def initialize_artifact_service(component) -> BaseArtifactService:
-    """Initializes the ADK Artifact Service based on configuration."""
+    """
+    Initializes the ADK Artifact Service based on configuration.
+    This factory creates the concrete service instance and then wraps it with
+    the ScopedArtifactServiceWrapper to enforce artifact scoping rules dynamically.
+    """
     config: Dict = component.get_config("artifact_service", {"type": "memory"})
     service_type = config.get("type", "memory").lower()
     log.info(
@@ -97,8 +216,9 @@ def initialize_artifact_service(component) -> BaseArtifactService:
         service_type,
     )
 
+    concrete_service: BaseArtifactService
     if service_type == "memory":
-        return InMemoryArtifactService()
+        concrete_service = InMemoryArtifactService()
     elif service_type == "gcs":
         bucket_name = config.get("bucket_name")
         if not bucket_name:
@@ -107,9 +227,11 @@ def initialize_artifact_service(component) -> BaseArtifactService:
             )
         try:
             gcs_args = {
-                k: v for k, v in config.items() if k not in ["type", "bucket_name"]
+                k: v
+                for k, v in config.items()
+                if k not in ["type", "bucket_name", "artifact_scope"]
             }
-            return GcsArtifactService(bucket_name=bucket_name, **gcs_args)
+            concrete_service = GcsArtifactService(bucket_name=bucket_name, **gcs_args)
         except ImportError:
             log.error(
                 "%s google-cloud-storage not installed. Please install 'google-adk[gcs]' or 'google-cloud-storage'.",
@@ -123,60 +245,8 @@ def initialize_artifact_service(component) -> BaseArtifactService:
                 f"{component.log_identifier} 'base_path' is required for filesystem artifact service."
             )
 
-        artifact_scope = config.get("artifact_scope", "namespace").lower()
-        scope_identifier_raw = None
-
-        if artifact_scope == "app":
-            app_instance = component.get_app()
-            if not app_instance or not app_instance.name:
-                raise ValueError(
-                    f"{component.log_identifier} Cannot determine app name for 'app' scope."
-                )
-            scope_identifier_raw = app_instance.name
-            log.info(
-                "%s Using 'app' scope for filesystem artifacts: %s",
-                component.log_identifier,
-                scope_identifier_raw,
-            )
-        elif artifact_scope == "namespace":
-            scope_identifier_raw = component.get_config("namespace")
-            log.info(
-                "%s Using 'namespace' scope for filesystem artifacts: %s",
-                component.log_identifier,
-                scope_identifier_raw,
-            )
-        elif artifact_scope == "custom":
-            scope_identifier_raw = config.get("artifact_scope_value")
-            if not scope_identifier_raw:
-                raise ValueError(
-                    f"{component.log_identifier} 'artifact_scope_value' is required when artifact_scope is 'custom'."
-                )
-            log.info(
-                "%s Using 'custom' scope for filesystem artifacts: %s",
-                component.log_identifier,
-                scope_identifier_raw,
-            )
-        else:
-            raise ValueError(
-                f"{component.log_identifier} Invalid 'artifact_scope' value: {artifact_scope}"
-            )
-
-        if not scope_identifier_raw:
-            raise ValueError(
-                f"{component.log_identifier} Failed to determine scope identifier for filesystem artifacts."
-            )
-
-        scope_identifier_sanitized = _sanitize_for_path(scope_identifier_raw)
-        log.info(
-            "%s Sanitized scope identifier: %s",
-            component.log_identifier,
-            scope_identifier_sanitized,
-        )
-
         try:
-            return FilesystemArtifactService(
-                base_path=base_path, scope_identifier=scope_identifier_sanitized
-            )
+            concrete_service = FilesystemArtifactService(base_path=base_path)
         except Exception as e:
             log.error(
                 "%s Failed to initialize FilesystemArtifactService: %s",
@@ -196,12 +266,23 @@ def initialize_artifact_service(component) -> BaseArtifactService:
             "%s Using TestInMemoryArtifactService for testing.",
             component.log_identifier,
         )
-        return TestInMemoryArtifactService()
+        concrete_service = TestInMemoryArtifactService()
     else:
         raise ValueError(
             f"{component.log_identifier} Unsupported artifact service type: {service_type}"
         )
 
+    # Wrap the concrete service to enforce scoping dynamically.
+    # The wrapper will query the component's config at runtime.
+    log.info(
+        "%s Wrapping artifact service with dynamic ScopedArtifactServiceWrapper.",
+        component.log_identifier,
+    )
+    return ScopedArtifactServiceWrapper(
+        wrapped_service=concrete_service,
+        component=component,
+    )
+
 
 def initialize_memory_service(component) -> BaseMemoryService:
     """Initializes the ADK Memory Service based on configuration."""