deepagents 0.3.9__py3-none-any.whl → 0.3.10__py3-none-any.whl

deepagents/backends/sandbox.py

@@ -3,14 +3,21 @@
 This module provides a base class that implements all SandboxBackendProtocol
 methods using shell commands executed via execute(). Concrete implementations
 only need to implement the execute() method.
+
+It also defines the SandboxProvider abstract base class for third-party SDK
+implementations to manage sandbox lifecycle (list, create, delete).
 """
 
 from __future__ import annotations
 
+import asyncio
 import base64
 import json
 import shlex
 from abc import ABC, abstractmethod
+from typing import Any, Generic, NotRequired, TypeVar
+
+from typing_extensions import TypedDict
 
 from deepagents.backends.protocol import (
     EditResult,
@@ -23,6 +30,353 @@ from deepagents.backends.protocol import (
     WriteResult,
 )
 
+# Type variable for provider-specific metadata
+MetadataT = TypeVar("MetadataT", covariant=True)
+"""Type variable for sandbox metadata.
+
+Providers can define their own TypedDict to specify the structure of sandbox metadata,
+enabling type-safe access to metadata fields.
+
+Example:
+    ```python
+    class ProviderMetadata(TypedDict, total=False):
+        status: Literal["running", "stopped"]
+        created_at: str
+        template: str
+
+    class MyProvider(SandboxProvider[ProviderMetadata]):
+        def list(
+            self, *, cursor=None, **kwargs: Any
+        ) -> SandboxListResponse[ProviderMetadata]:
+            # Extract kwargs as needed
+            status = kwargs.get("status")
+            ...
+    ```
+"""
+
+
+class SandboxInfo(TypedDict, Generic[MetadataT]):
+    """Metadata for a single sandbox instance.
+
+    This lightweight structure is returned from list operations and provides
+    basic information about a sandbox without requiring a full connection.
+
+    Type Parameters:
+        MetadataT: Type of the metadata field. Providers should define a TypedDict
+            for type-safe metadata access.
+
+    Attributes:
+        sandbox_id: Unique identifier for the sandbox instance.
+        metadata: Optional provider-specific metadata (e.g., creation time, status,
+            resource limits, template information). Structure is provider-defined.
+
+    Example:
+        ```python
+        # Using default dict[str, Any]
+        info: SandboxInfo = {
+            "sandbox_id": "sb_abc123",
+            "metadata": {"status": "running", "created_at": "2024-01-15T10:30:00Z", "template": "python-3.11"},
+        }
+
+
+        # Using typed metadata
+        class MyMetadata(TypedDict, total=False):
+            status: Literal["running", "stopped"]
+            created_at: str
+
+
+        typed_info: SandboxInfo[MyMetadata] = {
+            "sandbox_id": "sb_abc123",
+            "metadata": {"status": "running", "created_at": "2024-01-15T10:30:00Z"},
+        }
+        ```
+    """
+
+    sandbox_id: str
+    metadata: NotRequired[MetadataT]
+
+
+class SandboxListResponse(TypedDict, Generic[MetadataT]):
+    """Paginated response from a sandbox list operation.
+
+    This structure supports cursor-based pagination for efficiently browsing
+    large collections of sandboxes.
+
+    Type Parameters:
+        MetadataT: Type of the metadata field in SandboxInfo items.
+
+    Attributes:
+        items: List of sandbox metadata objects for the current page.
+        cursor: Opaque continuation token for retrieving the next page.
+            None indicates no more pages available. Clients should treat this
+            as an opaque string and pass it to subsequent list() calls.
+
+    Example:
+        ```python
+        response: SandboxListResponse[MyMetadata] = {
+            "items": [{"sandbox_id": "sb_001", "metadata": {"status": "running"}}, {"sandbox_id": "sb_002", "metadata": {"status": "stopped"}}],
+            "cursor": "eyJvZmZzZXQiOjEwMH0=",
+        }
+
+        # Fetch next page
+        next_response = provider.list(cursor=response["cursor"])
+        ```
+    """
+
+    items: list[SandboxInfo[MetadataT]]
+    cursor: str | None
+
+
+class SandboxProvider(ABC, Generic[MetadataT]):
+    """Abstract base class for third-party sandbox provider implementations.
+
+    Defines the lifecycle management interface for sandbox providers. Implementations
+    should integrate with their respective SDKs to provide standardized sandbox
+    lifecycle operations (list, get_or_create, delete).
+
+    Implementations can add provider-specific parameters as keyword-only arguments
+    with defaults, maintaining compatibility while providing type-safe APIs.
+
+    Sync/Async Convention: Following LangChain convention, providers should offer both
+    sync and async methods in the same namespace if possible (doesn't hurt performance)
+    (e.g., both `list()` and `alist()` in one class). The default async implementations
+    delegate to sync methods via a thread pool. Providers can override async methods to
+    provide optimized async implementations if needed.
+
+    Alternatively, if necessary for performance optimization, providers may split into
+    separate implementations (e.g., `MySyncProvider` and `MyAsyncProvider`). In this
+    case, unimplemented methods should raise NotImplementedError with clear guidance
+    (e.g., "This provider only supports async operations. Use 'await provider.alist()'
+    or switch to MySyncProvider for synchronous code").
+
+    Example Implementation:
+        ```python
+        class CustomMetadata(TypedDict, total=False):
+            status: Literal["running", "stopped"]
+            template: str
+            created_at: str
+
+
+        class CustomSandboxProvider(SandboxProvider[CustomMetadata]):
+            def list(
+                self, *, cursor=None, status: Literal["running", "stopped"] | None = None, template_id: str | None = None, **kwargs: Any
+            ) -> SandboxListResponse[CustomMetadata]:
+                # Type-safe parameters with IDE autocomplete
+                # ... query provider API
+                return {"items": [...], "cursor": None}
+
+            def get_or_create(
+                self, *, sandbox_id=None, template_id: str = "default", timeout_minutes: int | None = None, **kwargs: Any
+            ) -> SandboxBackendProtocol:
+                # Type-safe parameters with IDE autocomplete
+                return CustomSandbox(sandbox_id or self._create_new(), template_id)
+
+            def delete(self, *, sandbox_id: str, force: bool = False, **kwargs: Any) -> None:
+                # Implementation
+                self._client.delete(sandbox_id, force=force)
+        ```
+    """
+
+    @abstractmethod
+    def list(
+        self,
+        *,
+        cursor: str | None = None,
+        **kwargs: Any,
+    ) -> SandboxListResponse[MetadataT]:
+        """List available sandboxes with optional filtering and pagination.
+
+        Args:
+            cursor: Optional continuation token from a previous list() call.
+                Pass None to start from the beginning. The cursor is opaque
+                and provider-specific; clients should not parse or modify it.
+            **kwargs: Provider-specific filter parameters. Implementations should
+                expose these as named keyword-only parameters with defaults for
+                type safety. Common examples include status filters, creation time
+                ranges, template filters, or owner filters.
+
+        Returns:
+            SandboxListResponse containing:
+                - items: List of sandbox metadata for the current page
+                - cursor: Token for next page, or None if this is the last page
+
+        Example:
+            ```python
+            # First page
+            response = provider.list()
+            for sandbox in response["items"]:
+                print(sandbox["sandbox_id"])
+
+            # Next page if available
+            if response["cursor"]:
+                next_response = provider.list(cursor=response["cursor"])
+
+            # With filters (if provider supports them)
+            running = provider.list(status="running")
+            ```
+        """
+
+    @abstractmethod
+    def get_or_create(
+        self,
+        *,
+        sandbox_id: str | None = None,
+        **kwargs: Any,
+    ) -> SandboxBackendProtocol:
+        """Get an existing sandbox or create a new one.
+
+        This method retrieves a connection to an existing sandbox if sandbox_id
+        is provided, or creates a new sandbox instance if sandbox_id is None.
+        The returned object implements SandboxBackendProtocol and can be used
+        for all sandbox operations (execute, read, write, etc.).
+
+        Important: If a sandbox_id is provided but does not exist, this method
+        should raise an error rather than creating a new sandbox. Only when
+        sandbox_id is explicitly None should a new sandbox be created.
+
+        Args:
+            sandbox_id: Unique identifier of an existing sandbox to retrieve.
+                If None, creates a new sandbox instance. The new sandbox's ID
+                can be accessed via the returned object's .id property.
+                If a non-None value is provided but the sandbox doesn't exist,
+                an error will be raised.
+            **kwargs: Provider-specific creation/connection parameters. Implementations
+                should expose these as named keyword-only parameters with defaults
+                for type safety. Common examples include template_id, resource limits,
+                environment variables, or timeout settings.
+
+        Returns:
+            An object implementing SandboxBackendProtocol that can execute
+            commands, read/write files, and perform other sandbox operations.
+
+        Raises:
+            Implementation-specific exceptions for errors such as:
+                - Sandbox not found (if sandbox_id provided but doesn't exist)
+                - Insufficient permissions
+                - Resource limits exceeded
+                - Invalid template or configuration
+
+        Example:
+            ```python
+            # Create a new sandbox
+            sandbox = provider.get_or_create(sandbox_id=None, template_id="python-3.11", timeout_minutes=60)
+            print(sandbox.id)  # "sb_new123"
+
+            # Reconnect to existing sandbox
+            existing = provider.get_or_create(sandbox_id="sb_new123")
+
+            # Use the sandbox
+            result = sandbox.execute("python --version")
+            print(result.output)
+            ```
+        """
+
+    @abstractmethod
+    def delete(
+        self,
+        *,
+        sandbox_id: str,
+        **kwargs: Any,
+    ) -> None:
+        """Delete a sandbox instance.
+
+        This permanently destroys the sandbox and all its associated data.
+        The operation is typically irreversible.
+
+        Idempotency: This method should be idempotent - calling delete on a
+        non-existent sandbox should succeed without raising an error. This makes
+        cleanup code simpler and safe to retry.
+
+        Args:
+            sandbox_id: Unique identifier of the sandbox to delete.
+            **kwargs: Provider-specific deletion options. Implementations should
+                expose these as named keyword-only parameters with defaults for
+                type safety. Common examples include force flags, grace periods,
+                or cleanup options.
+
+        Raises:
+            Implementation-specific exceptions for errors such as:
+                - Insufficient permissions
+                - Sandbox is locked or in use
+                - Network or API errors
+
+        Example:
+            ```python
+            # Simple deletion
+            provider.delete(sandbox_id="sb_123")
+
+            # Safe to call multiple times (idempotent)
+            provider.delete(sandbox_id="sb_123")  # No error even if already deleted
+
+            # With options (if provider supports them)
+            provider.delete(sandbox_id="sb_456", force=True)
+            ```
+        """
+
+    async def alist(
+        self,
+        *,
+        cursor: str | None = None,
+        **kwargs: Any,
+    ) -> SandboxListResponse[MetadataT]:
+        """Async version of list().
+
+        By default, runs the synchronous list() method in a thread pool.
+        Providers can override this for native async implementations.
+
+        Args:
+            cursor: Optional continuation token from a previous list() call.
+            **kwargs: Provider-specific filter parameters.
+
+        Returns:
+            SandboxListResponse containing items and cursor for pagination.
+        """
+        return await asyncio.to_thread(self.list, cursor=cursor, **kwargs)
+
+    async def aget_or_create(
+        self,
+        *,
+        sandbox_id: str | None = None,
+        **kwargs: Any,
+    ) -> SandboxBackendProtocol:
+        """Async version of get_or_create().
+
+        By default, runs the synchronous get_or_create() method in a thread pool.
+        Providers can override this for native async implementations.
+
+        Important: If a sandbox_id is provided but does not exist, this method
+        should raise an error rather than creating a new sandbox. Only when
+        sandbox_id is explicitly None should a new sandbox be created.
+
+        Args:
+            sandbox_id: Unique identifier of an existing sandbox to retrieve.
+                If None, creates a new sandbox instance. If a non-None value
+                is provided but the sandbox doesn't exist, an error will be raised.
+            **kwargs: Provider-specific creation/connection parameters.
+
+        Returns:
+            An object implementing SandboxBackendProtocol.
+        """
+        return await asyncio.to_thread(self.get_or_create, sandbox_id=sandbox_id, **kwargs)
+
+    async def adelete(
+        self,
+        *,
+        sandbox_id: str,
+        **kwargs: Any,
+    ) -> None:
+        """Async version of delete().
+
+        By default, runs the synchronous delete() method in a thread pool.
+        Providers can override this for native async implementations.
+
+        Args:
+            sandbox_id: Unique identifier of the sandbox to delete.
+            **kwargs: Provider-specific deletion options.
+        """
+        await asyncio.to_thread(self.delete, sandbox_id=sandbox_id, **kwargs)
+
+
 _GLOB_COMMAND_TEMPLATE = """python3 -c "
 import glob
 import os
@@ -70,12 +424,12 @@ try:
     file_path = data['path']
     content = base64.b64decode(data['content']).decode('utf-8')
 except Exception as e:
-    print(f'Error: Failed to decode write payload: {e}', file=sys.stderr)
+    print(f'Error: Failed to decode write payload: {{e}}', file=sys.stderr)
     sys.exit(1)
 
 # Check if file already exists (atomic with write)
 if os.path.exists(file_path):
-    print(f'Error: File \\'{file_path}\\' already exists', file=sys.stderr)
+    print(f'Error: File \\'{{file_path}}\\' already exists', file=sys.stderr)
     sys.exit(1)
 
 # Create parent directory if needed
@@ -111,7 +465,7 @@ try:
     old = data['old']
     new = data['new']
 except Exception as e:
-    print(f'Error: Failed to decode edit payload: {e}', file=sys.stderr)
+    print(f'Error: Failed to decode edit payload: {{e}}', file=sys.stderr)
     sys.exit(4)
 
 # Check if file exists

deepagents/backends/utils.py

@@ -219,17 +219,26 @@ def truncate_if_too_long(result: list[str] | str) -> list[str] | str:
     return result
 
 
-def _validate_path(path: str | None) -> str:
-    """Validate and normalize a path.
+def _normalize_path(path: str | None) -> str:
+    """Normalize a path to canonical form.
+
+    Converts path to absolute form starting with /, removes trailing slashes
+    (except for root), and validates that the path is not empty.
 
     Args:
-        path: Path to validate
+        path: Path to normalize (None defaults to "/")
 
     Returns:
-        Normalized path starting with /
+        Normalized path starting with / (without trailing slash unless it's root)
 
     Raises:
-        ValueError: If path is invalid
+        ValueError: If path is invalid (empty string after strip)
+
+    Example:
+        _normalize_path(None) -> "/"
+        _normalize_path("/dir/") -> "/dir"
+        _normalize_path("dir") -> "/dir"
+        _normalize_path("/") -> "/"
     """
     path = path or "/"
     if not path or path.strip() == "":
@@ -237,12 +246,43 @@ def _validate_path(path: str | None) -> str:
 
     normalized = path if path.startswith("/") else "/" + path
 
-    if not normalized.endswith("/"):
-        normalized += "/"
+    # Only root should have trailing slash
+    if normalized != "/" and normalized.endswith("/"):
+        normalized = normalized.rstrip("/")
 
     return normalized
 
 
+def _filter_files_by_path(files: dict[str, Any], normalized_path: str) -> dict[str, Any]:
+    """Filter files dict by normalized path, handling exact file matches and directory prefixes.
+
+    Expects a normalized path from _normalize_path (no trailing slash except root).
+
+    Args:
+        files: Dictionary mapping file paths to file data
+        normalized_path: Normalized path from _normalize_path (e.g., "/", "/dir", "/dir/file")
+
+    Returns:
+        Filtered dictionary of files matching the path
+
+    Example:
+        files = {"/dir/file": {...}, "/dir/other": {...}}
+        _filter_files_by_path(files, "/dir/file")  # Returns {"/dir/file": {...}}
+        _filter_files_by_path(files, "/dir")       # Returns both files
+    """
+    # Check if path matches an exact file
+    if normalized_path in files:
+        return {normalized_path: files[normalized_path]}
+
+    # Otherwise treat as directory prefix
+    if normalized_path == "/":
+        # Root directory - match all files starting with /
+        return {fp: fd for fp, fd in files.items() if fp.startswith("/")}
+    # Non-root directory - add trailing slash for prefix matching
+    dir_prefix = normalized_path + "/"
+    return {fp: fd for fp, fd in files.items() if fp.startswith(dir_prefix)}
+
+
 def _glob_search_files(
     files: dict[str, Any],
     pattern: str,
@@ -267,11 +307,11 @@ def _glob_search_files(
         ```
     """
     try:
-        normalized_path = _validate_path(path)
+        normalized_path = _normalize_path(path)
     except ValueError:
         return "No files found"
 
-    filtered = {fp: fd for fp, fd in files.items() if fp.startswith(normalized_path)}
+    filtered = _filter_files_by_path(files, normalized_path)
 
     # Respect standard glob semantics:
     # - Patterns without path separators (e.g., "*.py") match only in the current
@@ -281,9 +321,17 @@ def _glob_search_files(
 
     matches = []
     for file_path, file_data in filtered.items():
-        relative = file_path[len(normalized_path) :].lstrip("/")
-        if not relative:
+        # Compute relative path for glob matching
+        # If normalized_path is "/dir", we want "/dir/file.txt" -> "file.txt"
+        # If normalized_path is "/dir/file.txt" (exact file), we want "file.txt"
+        if normalized_path == "/":
+            relative = file_path[1:]  # Remove leading slash
+        elif file_path == normalized_path:
+            # Exact file match - use just the filename
             relative = file_path.split("/")[-1]
+        else:
+            # Directory prefix - strip the directory path
+            relative = file_path[len(normalized_path) + 1 :]  # +1 for the slash
 
         if wcglob.globmatch(relative, effective_pattern, flags=wcglob.BRACE | wcglob.GLOBSTAR):
             matches.append((file_path, file_data["modified_at"]))
@@ -357,11 +405,11 @@ def _grep_search_files(
         return f"Invalid regex pattern: {e}"
 
     try:
-        normalized_path = _validate_path(path)
+        normalized_path = _normalize_path(path)
     except ValueError:
         return "No matches found"
 
-    filtered = {fp: fd for fp, fd in files.items() if fp.startswith(normalized_path)}
+    filtered = _filter_files_by_path(files, normalized_path)
 
     if glob:
         filtered = {fp: fd for fp, fd in filtered.items() if wcglob.globmatch(Path(fp).name, glob, flags=wcglob.BRACE)}
@@ -390,21 +438,18 @@ def grep_matches_from_files(
 ) -> list[GrepMatch] | str:
     """Return structured grep matches from an in-memory files mapping.
 
-    Returns a list of GrepMatch on success, or a string for invalid inputs
-    (e.g., invalid regex). We deliberately do not raise here to keep backends
-    non-throwing in tool contexts and preserve user-facing error messages.
-    """
-    try:
-        regex = re.compile(pattern)
-    except re.error as e:
-        return f"Invalid regex pattern: {e}"
+    Performs literal text search (not regex).
 
+    Returns a list of GrepMatch on success, or a string for invalid inputs.
+    We deliberately do not raise here to keep backends non-throwing in tool
+    contexts and preserve user-facing error messages.
+    """
     try:
-        normalized_path = _validate_path(path)
+        normalized_path = _normalize_path(path)
     except ValueError:
         return []
 
-    filtered = {fp: fd for fp, fd in files.items() if fp.startswith(normalized_path)}
+    filtered = _filter_files_by_path(files, normalized_path)
 
     if glob:
         filtered = {fp: fd for fp, fd in filtered.items() if wcglob.globmatch(Path(fp).name, glob, flags=wcglob.BRACE)}
@@ -412,7 +457,7 @@ def grep_matches_from_files(
     matches: list[GrepMatch] = []
     for file_path, file_data in filtered.items():
         for line_num, line in enumerate(file_data["content"], 1):
-            if regex.search(line):
+            if pattern in line:  # Simple substring search for literal matching
                 matches.append({"path": file_path, "line": int(line_num), "text": line})
     return matches
 

deepagents/middleware/filesystem.py

@@ -221,11 +221,13 @@ Examples:
 GREP_TOOL_DESCRIPTION = """Search for a text pattern across files.
 
 Searches for literal text (not regex) and returns matching files or content based on output_mode.
+Special characters like parentheses, brackets, pipes, etc. are treated as literal characters, not regex operators.
 
 Examples:
 - Search all files: `grep(pattern="TODO")`
 - Search Python files only: `grep(pattern="import", glob="*.py")`
-- Show matching lines: `grep(pattern="error", output_mode="content")`"""
+- Show matching lines: `grep(pattern="error", output_mode="content")`
+- Search for code with special chars: `grep(pattern="def __init__(self):")`"""
 
 EXECUTE_TOOL_DESCRIPTION = """Executes a shell command in an isolated sandbox environment.
 
@@ -493,7 +495,10 @@ class FilesystemMiddleware(AgentMiddleware):
         ) -> str:
             """Synchronous wrapper for ls tool."""
             resolved_backend = self._get_backend(runtime)
-            validated_path = _validate_path(path)
+            try:
+                validated_path = _validate_path(path)
+            except ValueError as e:
+                return f"Error: {e}"
             infos = resolved_backend.ls_info(validated_path)
             paths = [fi.get("path", "") for fi in infos]
             result = truncate_if_too_long(paths)
@@ -505,7 +510,10 @@ class FilesystemMiddleware(AgentMiddleware):
         ) -> str:
             """Asynchronous wrapper for ls tool."""
             resolved_backend = self._get_backend(runtime)
-            validated_path = _validate_path(path)
+            try:
+                validated_path = _validate_path(path)
+            except ValueError as e:
+                return f"Error: {e}"
             infos = await resolved_backend.als_info(validated_path)
             paths = [fi.get("path", "") for fi in infos]
             result = truncate_if_too_long(paths)
@@ -531,7 +539,10 @@ class FilesystemMiddleware(AgentMiddleware):
         ) -> str:
             """Synchronous wrapper for read_file tool."""
             resolved_backend = self._get_backend(runtime)
-            validated_path = _validate_path(file_path)
+            try:
+                validated_path = _validate_path(file_path)
+            except ValueError as e:
+                return f"Error: {e}"
             result = resolved_backend.read(validated_path, offset=offset, limit=limit)
 
             lines = result.splitlines(keepends=True)
@@ -557,7 +568,10 @@ class FilesystemMiddleware(AgentMiddleware):
         ) -> str:
             """Asynchronous wrapper for read_file tool."""
             resolved_backend = self._get_backend(runtime)
-            validated_path = _validate_path(file_path)
+            try:
+                validated_path = _validate_path(file_path)
+            except ValueError as e:
+                return f"Error: {e}"
             result = await resolved_backend.aread(validated_path, offset=offset, limit=limit)
 
             lines = result.splitlines(keepends=True)
@@ -593,7 +607,10 @@ class FilesystemMiddleware(AgentMiddleware):
         ) -> Command | str:
             """Synchronous wrapper for write_file tool."""
             resolved_backend = self._get_backend(runtime)
-            validated_path = _validate_path(file_path)
+            try:
+                validated_path = _validate_path(file_path)
+            except ValueError as e:
+                return f"Error: {e}"
             res: WriteResult = resolved_backend.write(validated_path, content)
             if res.error:
                 return res.error
@@ -619,7 +636,10 @@ class FilesystemMiddleware(AgentMiddleware):
         ) -> Command | str:
             """Asynchronous wrapper for write_file tool."""
             resolved_backend = self._get_backend(runtime)
-            validated_path = _validate_path(file_path)
+            try:
+                validated_path = _validate_path(file_path)
+            except ValueError as e:
+                return f"Error: {e}"
             res: WriteResult = await resolved_backend.awrite(validated_path, content)
             if res.error:
                 return res.error
@@ -659,7 +679,10 @@ class FilesystemMiddleware(AgentMiddleware):
         ) -> Command | str:
             """Synchronous wrapper for edit_file tool."""
             resolved_backend = self._get_backend(runtime)
-            validated_path = _validate_path(file_path)
+            try:
+                validated_path = _validate_path(file_path)
+            except ValueError as e:
+                return f"Error: {e}"
             res: EditResult = resolved_backend.edit(validated_path, old_string, new_string, replace_all=replace_all)
             if res.error:
                 return res.error
@@ -687,7 +710,10 @@ class FilesystemMiddleware(AgentMiddleware):
         ) -> Command | str:
             """Asynchronous wrapper for edit_file tool."""
             resolved_backend = self._get_backend(runtime)
-            validated_path = _validate_path(file_path)
+            try:
+                validated_path = _validate_path(file_path)
+            except ValueError as e:
+                return f"Error: {e}"
             res: EditResult = await resolved_backend.aedit(validated_path, old_string, new_string, replace_all=replace_all)
             if res.error:
                 return res.error

deepagents/middleware/skills.py

@@ -155,7 +155,7 @@ class SkillsState(AgentState):
     """State for the skills middleware."""
 
     skills_metadata: NotRequired[Annotated[list[SkillMetadata], PrivateStateAttr]]
-    """List of loaded skill metadata from all configured sources."""
+    """List of loaded skill metadata from configured sources. Not propagated to parent agents."""
 
 
 class SkillsStateUpdate(TypedDict):