aip-agents-binary 0.6.4__py3-none-macosx_13_0_arm64.whl → 0.6.6__py3-none-macosx_13_0_arm64.whl

aip_agents/ptc/tool_def_helpers.py

@@ -0,0 +1,101 @@
+"""Helper functions for constructing PTC tool definitions.
+
+Author: Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+
+These helpers provide a cleaner API for defining custom tools in PTCCustomToolConfig.
+They return properly-typed dictionaries that can be used in PTCCustomToolConfig.tools.
+
+Example:
+    >>> from aip_agents.ptc import package_tool, file_tool, PTCCustomToolConfig
+    >>> config = PTCCustomToolConfig(
+    ...     enabled=True,
+    ...     tools=[
+    ...         package_tool("time_tool", import_path="aip_agents.tools.time_tool", class_name="TimeTool"),
+    ...         file_tool("multiply", file_path="/path/to/multiply.py", class_name="MultiplyTool"),
+    ...     ]
+    ... )
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from aip_agents.ptc.custom_tools import PTCFileToolDef, PTCPackageToolDef
+
+
+def package_tool(
+    name: str,
+    *,
+    import_path: str,
+    class_name: str,
+    package_path: str | None = None,
+    description: str | None = None,
+    input_schema: dict[str, Any] | None = None,
+) -> PTCPackageToolDef:
+    """Create a package-based tool definition.
+
+    Args:
+        name: Tool name (will be sanitized for Python compatibility).
+        import_path: Python import path (e.g., "aip_agents.tools.time_tool").
+        class_name: Tool class name to instantiate.
+        package_path: Optional local package path for bundling.
+        description: Optional tool description (auto-derived from tool if not provided).
+        input_schema: Optional JSON schema (auto-derived from tool if not provided).
+
+    Returns:
+        PTCPackageToolDef dict ready for use in PTCCustomToolConfig.tools.
+
+    Example:
+        >>> package_tool("time_tool", import_path="aip_agents.tools.time_tool", class_name="TimeTool")
+        {'name': 'time_tool', 'kind': 'package', 'import_path': 'aip_agents.tools.time_tool', 'class_name': 'TimeTool'}
+    """
+    result: PTCPackageToolDef = {
+        "name": name,
+        "kind": "package",
+        "import_path": import_path,
+        "class_name": class_name,
+    }
+    if package_path is not None:
+        result["package_path"] = package_path
+    if description is not None:
+        result["description"] = description
+    if input_schema is not None:
+        result["input_schema"] = input_schema
+    return result
+
+
+def file_tool(
+    name: str,
+    *,
+    file_path: str,
+    class_name: str,
+    description: str | None = None,
+    input_schema: dict[str, Any] | None = None,
+) -> PTCFileToolDef:
+    """Create a file-based tool definition.
+
+    Args:
+        name: Tool name (will be sanitized for Python compatibility).
+        file_path: Absolute path to the Python file containing the tool.
+        class_name: Tool class name to instantiate.
+        description: Optional tool description (auto-derived from tool if not provided).
+        input_schema: Optional JSON schema (auto-derived from tool if not provided).
+
+    Returns:
+        PTCFileToolDef dict ready for use in PTCCustomToolConfig.tools.
+
+    Example:
+        >>> file_tool("multiply", file_path="/path/to/multiply_tool.py", class_name="MultiplyTool")
+        {'name': 'multiply', 'kind': 'file', 'file_path': '/path/to/multiply_tool.py', 'class_name': 'MultiplyTool'}
+    """
+    result: PTCFileToolDef = {
+        "name": name,
+        "kind": "file",
+        "file_path": file_path,
+        "class_name": class_name,
+    }
+    if description is not None:
+        result["description"] = description
+    if input_schema is not None:
+        result["input_schema"] = input_schema
+    return result

aip_agents/ptc/tool_def_helpers.pyi

@@ -0,0 +1,38 @@
+from aip_agents.ptc.custom_tools import PTCFileToolDef as PTCFileToolDef, PTCPackageToolDef as PTCPackageToolDef
+from typing import Any
+
+def package_tool(name: str, *, import_path: str, class_name: str, package_path: str | None = None, description: str | None = None, input_schema: dict[str, Any] | None = None) -> PTCPackageToolDef:
+    '''Create a package-based tool definition.
+
+    Args:
+        name: Tool name (will be sanitized for Python compatibility).
+        import_path: Python import path (e.g., "aip_agents.tools.time_tool").
+        class_name: Tool class name to instantiate.
+        package_path: Optional local package path for bundling.
+        description: Optional tool description (auto-derived from tool if not provided).
+        input_schema: Optional JSON schema (auto-derived from tool if not provided).
+
+    Returns:
+        PTCPackageToolDef dict ready for use in PTCCustomToolConfig.tools.
+
+    Example:
+        >>> package_tool("time_tool", import_path="aip_agents.tools.time_tool", class_name="TimeTool")
+        {\'name\': \'time_tool\', \'kind\': \'package\', \'import_path\': \'aip_agents.tools.time_tool\', \'class_name\': \'TimeTool\'}
+    '''
+def file_tool(name: str, *, file_path: str, class_name: str, description: str | None = None, input_schema: dict[str, Any] | None = None) -> PTCFileToolDef:
+    '''Create a file-based tool definition.
+
+    Args:
+        name: Tool name (will be sanitized for Python compatibility).
+        file_path: Absolute path to the Python file containing the tool.
+        class_name: Tool class name to instantiate.
+        description: Optional tool description (auto-derived from tool if not provided).
+        input_schema: Optional JSON schema (auto-derived from tool if not provided).
+
+    Returns:
+        PTCFileToolDef dict ready for use in PTCCustomToolConfig.tools.
+
+    Example:
+        >>> file_tool("multiply", file_path="/path/to/multiply_tool.py", class_name="MultiplyTool")
+        {\'name\': \'multiply\', \'kind\': \'file\', \'file_path\': \'/path/to/multiply_tool.py\', \'class_name\': \'MultiplyTool\'}
+    '''

aip_agents/ptc/tool_enrichment.py

@@ -0,0 +1,163 @@
+"""Tool metadata enrichment utilities.
+
+This module provides functions to enrich custom tool definitions with metadata
+from actual tool objects (name, description, input_schema).
+
+Author: Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from aip_agents.ptc.custom_tools import (
+    PTCToolDef,
+    enrich_tool_def_with_metadata,
+)
+from aip_agents.ptc.naming import sanitize_function_name
+
+if TYPE_CHECKING:
+    from aip_agents.ptc import PTCCustomToolConfig
+
+logger = logging.getLogger(__name__)
+
+
+def build_tool_lookup(tools: list[object]) -> dict[str, object]:
+    """Build a lookup map from tool objects for name-based matching.
+
+    Creates entries for both original and sanitized names to support
+    fuzzy matching (e.g., "web-search" matches "web_search").
+
+    Args:
+        tools: List of tool objects with `name` attribute.
+
+    Returns:
+        Dict mapping tool names (and sanitized names) to tool objects.
+
+    Example:
+        >>> tools = [TimeTool(), WebSearchTool()]  # names: "time_tool", "web-search"
+        >>> lookup = build_tool_lookup(tools)
+        >>> lookup.keys()
+        dict_keys(['time_tool', 'web-search', 'web_search'])
+    """
+    tool_lookup: dict[str, object] = {}
+
+    for tool in tools:
+        if not hasattr(tool, "name"):
+            continue
+
+        tool_name = tool.name
+        if not tool_name:  # Skip None or empty string names
+            continue
+        tool_name = str(tool_name)
+        tool_lookup[tool_name] = tool
+
+        # Also add sanitized name for fuzzy matching
+        sanitized = sanitize_function_name(tool_name)
+        if sanitized != tool_name:
+            tool_lookup[sanitized] = tool
+
+    return tool_lookup
+
+
+def match_tool_by_name(
+    tool_def: PTCToolDef,
+    tool_lookup: dict[str, object],
+) -> tuple[object | None, str | None]:
+    """Find a matching tool object for a tool definition.
+
+    Tries exact name match first, then falls back to sanitized name.
+
+    Args:
+        tool_def: Tool definition dict with "name" key.
+        tool_lookup: Lookup map from build_tool_lookup().
+
+    Returns:
+        Tuple of (matching_tool, canonical_name) or (None, None) if no match.
+        canonical_name is the tool object's actual name (may differ from tool_def name).
+    """
+    def_name = tool_def.get("name", "")
+    sanitized_def_name = sanitize_function_name(def_name)
+
+    # Try exact match first, then sanitized
+    matching_tool = tool_lookup.get(def_name) or tool_lookup.get(sanitized_def_name)
+
+    if matching_tool is None:
+        return None, None
+
+    # Get canonical name from tool object
+    canonical_name = str(getattr(matching_tool, "name", ""))
+
+    # Treat empty canonical name as no match
+    if not canonical_name:
+        return None, None
+
+    return matching_tool, canonical_name
+
+
+def enrich_custom_tools_from_agent(
+    custom_tools_config: PTCCustomToolConfig,
+    agent_tools: list[object],
+    agent_name: str = "",
+) -> int:
+    """Enrich custom tool definitions with metadata from agent's tool objects.
+
+    Matches custom tool definitions with actual tool objects by name (including
+    sanitized name matching) and enriches them with description and input_schema.
+
+    Note: This function modifies custom_tools_config.tools in-place.
+
+    Args:
+        custom_tools_config: The PTCCustomToolConfig to enrich.
+        agent_tools: List of tool objects from the agent.
+        agent_name: Agent name for logging context.
+
+    Returns:
+        Number of tools that were enriched.
+
+    Example:
+        >>> config = PTCCustomToolConfig(enabled=True, tools=[{"name": "multiply", ...}])
+        >>> count = enrich_custom_tools_from_agent(config, [MultiplyTool()], "my_agent")
+        >>> count
+        1
+    """
+    if not custom_tools_config.enabled:
+        return 0
+
+    if not custom_tools_config.tools:
+        return 0
+
+    # Build lookup map
+    tool_lookup = build_tool_lookup(agent_tools)
+
+    # Enrich each tool definition
+    enriched_count = 0
+    log_prefix = f"Agent '{agent_name}': " if agent_name else ""
+
+    for i, tool_def in enumerate(custom_tools_config.tools):
+        def_name = tool_def.get("name", "")
+        matching_tool, canonical_name = match_tool_by_name(tool_def, tool_lookup)
+
+        if matching_tool is None:
+            logger.debug(
+                f"{log_prefix}No matching tool object found for custom tool '{def_name}', using existing definition"
+            )
+            continue
+
+        # Handle name correction if matched by sanitized name
+        if canonical_name and canonical_name != def_name:
+            tool_def_copy = dict(tool_def)
+            tool_def_copy["name"] = canonical_name
+            enriched = enrich_tool_def_with_metadata(tool_def_copy, matching_tool)
+        else:
+            enriched = enrich_tool_def_with_metadata(tool_def, matching_tool)
+
+        custom_tools_config.tools[i] = enriched
+        enriched_count += 1
+        logger.debug(f"{log_prefix}Enriched custom tool '{def_name}' with metadata")
+
+    if enriched_count > 0:
+        logger.info(f"{log_prefix}Enriched {enriched_count} custom tool(s) with metadata")
+
+    return enriched_count

aip_agents/ptc/tool_enrichment.pyi

@@ -0,0 +1,60 @@
+from _typeshed import Incomplete
+from aip_agents.ptc import PTCCustomToolConfig as PTCCustomToolConfig
+from aip_agents.ptc.custom_tools import PTCToolDef as PTCToolDef, enrich_tool_def_with_metadata as enrich_tool_def_with_metadata
+from aip_agents.ptc.naming import sanitize_function_name as sanitize_function_name
+
+logger: Incomplete
+
+def build_tool_lookup(tools: list[object]) -> dict[str, object]:
+    '''Build a lookup map from tool objects for name-based matching.
+
+    Creates entries for both original and sanitized names to support
+    fuzzy matching (e.g., "web-search" matches "web_search").
+
+    Args:
+        tools: List of tool objects with `name` attribute.
+
+    Returns:
+        Dict mapping tool names (and sanitized names) to tool objects.
+
+    Example:
+        >>> tools = [TimeTool(), WebSearchTool()]  # names: "time_tool", "web-search"
+        >>> lookup = build_tool_lookup(tools)
+        >>> lookup.keys()
+        dict_keys([\'time_tool\', \'web-search\', \'web_search\'])
+    '''
+def match_tool_by_name(tool_def: PTCToolDef, tool_lookup: dict[str, object]) -> tuple[object | None, str | None]:
+    '''Find a matching tool object for a tool definition.
+
+    Tries exact name match first, then falls back to sanitized name.
+
+    Args:
+        tool_def: Tool definition dict with "name" key.
+        tool_lookup: Lookup map from build_tool_lookup().
+
+    Returns:
+        Tuple of (matching_tool, canonical_name) or (None, None) if no match.
+        canonical_name is the tool object\'s actual name (may differ from tool_def name).
+    '''
+def enrich_custom_tools_from_agent(custom_tools_config: PTCCustomToolConfig, agent_tools: list[object], agent_name: str = '') -> int:
+    '''Enrich custom tool definitions with metadata from agent\'s tool objects.
+
+    Matches custom tool definitions with actual tool objects by name (including
+    sanitized name matching) and enriches them with description and input_schema.
+
+    Note: This function modifies custom_tools_config.tools in-place.
+
+    Args:
+        custom_tools_config: The PTCCustomToolConfig to enrich.
+        agent_tools: List of tool objects from the agent.
+        agent_name: Agent name for logging context.
+
+    Returns:
+        Number of tools that were enriched.
+
+    Example:
+        >>> config = PTCCustomToolConfig(enabled=True, tools=[{"name": "multiply", ...}])
+        >>> count = enrich_custom_tools_from_agent(config, [MultiplyTool()], "my_agent")
+        >>> count
+        1
+    '''

aip_agents/sandbox/defaults.py

@@ -1,9 +1,205 @@
 """Defaults for PTC sandbox templates and packages."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from aip_agents.mcp.client.base_mcp_client import BaseMCPClient
+    from aip_agents.ptc.custom_tools import PTCCustomToolConfig
+
 DEFAULT_PTC_TEMPLATE = "aip-agents-ptc-v1"
+AIP_AGENTS_BINARY_LOCAL = "aip-agents-binary[local]"
 DEFAULT_PTC_PACKAGES: tuple[str, ...] = (
-    "aip-agents-binary[local]",
+    AIP_AGENTS_BINARY_LOCAL,
     "mcp",
     "httpx",
     "gllm-plugin-binary==0.0.7",
 )
+
+
+def _has_mcp_tools(mcp_client: BaseMCPClient | None) -> bool:
+    """Check if MCP tools are present.
+
+    Args:
+        mcp_client: The MCP client to check.
+
+    Returns:
+        True if MCP client has servers configured.
+    """
+    return mcp_client is not None and bool(getattr(mcp_client, "servers", None))
+
+
+def _has_custom_tools(custom_tools_config: PTCCustomToolConfig | None) -> bool:
+    """Check if custom tools are present and enabled.
+
+    Args:
+        custom_tools_config: The custom tools configuration to check.
+
+    Returns:
+        True if custom tools are enabled and tools list is non-empty.
+    """
+    return custom_tools_config is not None and custom_tools_config.enabled and bool(custom_tools_config.tools)
+
+
+def _has_native_aip_tools(custom_tools_config: PTCCustomToolConfig | None) -> bool:
+    """Check if native AIP tools are present.
+
+    Native AIP tools are package-based custom tools with import_path starting with "aip_agents.tools.".
+
+    Args:
+        custom_tools_config: The custom tools configuration to check.
+
+    Returns:
+        True if at least one native AIP tool is found.
+    """
+    if not _has_custom_tools(custom_tools_config):
+        return False
+
+    assert custom_tools_config is not None
+    for tool in custom_tools_config.tools:
+        if tool.get("kind") == "package":
+            import_path = tool.get("import_path", "")
+            if import_path.startswith("aip_agents.tools."):
+                return True
+
+    return False
+
+
+def _merge_requirements(packages: list[str], requirements: list[str]) -> None:
+    """Merge requirements into packages list, avoiding duplicates.
+
+    Args:
+        packages: Target list to merge into (modified in place).
+        requirements: Requirements to merge.
+    """
+    for req in requirements:
+        if req not in packages:
+            packages.append(req)
+
+
+def _merge_custom_requirements(
+    packages: list[str],
+    custom_tools_config: PTCCustomToolConfig | None,
+) -> None:
+    """Merge custom tool requirements into packages list.
+
+    Args:
+        packages: Target list to merge into (modified in place).
+        custom_tools_config: Custom tools configuration.
+    """
+    if not _has_custom_tools(custom_tools_config):
+        return
+
+    assert custom_tools_config is not None
+    if custom_tools_config.requirements:
+        _merge_requirements(packages, custom_tools_config.requirements)
+
+
+def _packages_for_default_template(
+    custom_tools_config: PTCCustomToolConfig | None,
+    user_ptc_packages: list[str] | None,
+) -> list[str] | None:
+    """Build package list when using the default template.
+
+    Args:
+        custom_tools_config: Custom tools configuration.
+        user_ptc_packages: Explicitly provided packages by user (None if not set).
+
+    Returns:
+        List of packages to install, or None to skip installation.
+    """
+    packages = list(user_ptc_packages) if user_ptc_packages is not None else []
+    _merge_custom_requirements(packages, custom_tools_config)
+    return packages if packages else None
+
+
+def _packages_for_other_templates(
+    *,
+    mcp_client: BaseMCPClient | None,
+    custom_tools_config: PTCCustomToolConfig | None,
+    user_ptc_packages: list[str] | None,
+) -> list[str] | None:
+    """Build package list when using a non-default template.
+
+    Args:
+        mcp_client: The MCP client (check if has servers for MCP tools).
+        custom_tools_config: Custom tools configuration.
+        user_ptc_packages: Explicitly provided packages by user (None if not set).
+
+    Returns:
+        List of packages to install, or None to skip installation.
+    """
+    packages = list(user_ptc_packages) if user_ptc_packages is not None else []
+    base_packages = _build_base_packages(mcp_client=mcp_client, custom_tools_config=custom_tools_config)
+    _merge_requirements(packages, base_packages)
+    _merge_custom_requirements(packages, custom_tools_config)
+    return packages if packages else None
+
+
+def _build_base_packages(
+    *,
+    mcp_client: BaseMCPClient | None,
+    custom_tools_config: PTCCustomToolConfig | None,
+) -> list[str]:
+    """Build base package list based on tool types.
+
+    Args:
+        mcp_client: The MCP client (check if has servers for MCP tools).
+        custom_tools_config: Custom tools configuration.
+
+    Returns:
+        List of base packages needed for the tool types present.
+    """
+    packages: list[str] = []
+
+    if _has_mcp_tools(mcp_client):
+        packages.extend(["mcp", "httpx"])
+
+    if _has_custom_tools(custom_tools_config):
+        packages.extend(["langchain", "gllm-plugin-binary==0.0.7"])
+
+    if _has_native_aip_tools(custom_tools_config):
+        if AIP_AGENTS_BINARY_LOCAL not in packages:
+            packages.append(AIP_AGENTS_BINARY_LOCAL)
+
+    return packages
+
+
+def select_sandbox_packages(
+    *,
+    mcp_client: BaseMCPClient | None,
+    custom_tools_config: PTCCustomToolConfig | None,
+    template: str | None,
+    user_ptc_packages: list[str] | None,
+) -> list[str] | None:
+    """Select minimal packages to install in sandbox based on tool types.
+
+    This function implements the smart package selection logic:
+    - DEFAULT_PTC_TEMPLATE + no user packages: Skip install (template has all deps)
+    - DEFAULT_PTC_TEMPLATE + user packages: User packages + PTCCustomToolConfig.requirements
+    - Other template + no user packages: Build packages from tool types
+    - Other template + user packages: User packages + tool-type packages + PTCCustomToolConfig.requirements
+
+    Key principle: Tools won't work without their required packages. Always ensure:
+    - MCP tools → mcp + httpx installed
+    - Custom LangChain tools → langchain + gllm-plugin-binary installed
+    - Native AIP tools → aip-agents-binary[local] installed
+
+    Args:
+        mcp_client: The MCP client (check if has servers for MCP tools).
+        custom_tools_config: Custom tools configuration (includes tools list and .requirements field).
+        template: Sandbox template being used.
+        user_ptc_packages: Explicitly provided packages by user (None if not set).
+
+    Returns:
+        List of packages to install, or None to skip installation.
+    """
+    if template == DEFAULT_PTC_TEMPLATE:
+        return _packages_for_default_template(custom_tools_config, user_ptc_packages)
+
+    return _packages_for_other_templates(
+        mcp_client=mcp_client,
+        custom_tools_config=custom_tools_config,
+        user_ptc_packages=user_ptc_packages,
+    )

aip_agents/sandbox/defaults.pyi

@@ -1,2 +1,30 @@
+from aip_agents.mcp.client.base_mcp_client import BaseMCPClient as BaseMCPClient
+from aip_agents.ptc.custom_tools import PTCCustomToolConfig as PTCCustomToolConfig
+
 DEFAULT_PTC_TEMPLATE: str
+AIP_AGENTS_BINARY_LOCAL: str
 DEFAULT_PTC_PACKAGES: tuple[str, ...]
+
+def select_sandbox_packages(*, mcp_client: BaseMCPClient | None, custom_tools_config: PTCCustomToolConfig | None, template: str | None, user_ptc_packages: list[str] | None) -> list[str] | None:
+    """Select minimal packages to install in sandbox based on tool types.
+
+    This function implements the smart package selection logic:
+    - DEFAULT_PTC_TEMPLATE + no user packages: Skip install (template has all deps)
+    - DEFAULT_PTC_TEMPLATE + user packages: User packages + PTCCustomToolConfig.requirements
+    - Other template + no user packages: Build packages from tool types
+    - Other template + user packages: User packages + tool-type packages + PTCCustomToolConfig.requirements
+
+    Key principle: Tools won't work without their required packages. Always ensure:
+    - MCP tools → mcp + httpx installed
+    - Custom LangChain tools → langchain + gllm-plugin-binary installed
+    - Native AIP tools → aip-agents-binary[local] installed
+
+    Args:
+        mcp_client: The MCP client (check if has servers for MCP tools).
+        custom_tools_config: Custom tools configuration (includes tools list and .requirements field).
+        template: Sandbox template being used.
+        user_ptc_packages: Explicitly provided packages by user (None if not set).
+
+    Returns:
+        List of packages to install, or None to skip installation.
+    """

aip_agents/sandbox/e2b_runtime.py

@@ -6,6 +6,8 @@ Authors:
     Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
 """
 
+from collections.abc import Callable
+
 from e2b_code_interpreter import AsyncSandbox, OutputMessage
 
 from aip_agents.sandbox.defaults import DEFAULT_PTC_PACKAGES, DEFAULT_PTC_TEMPLATE
@@ -13,6 +15,10 @@ from aip_agents.sandbox.types import SandboxExecutionResult
 from aip_agents.sandbox.validation import validate_package_names
 from aip_agents.utils.logger import get_logger
 
+# Type alias for package selector callback.
+# Called after sandbox creation with actual template status (None if template failed).
+PackageSelector = Callable[[str | None], list[str] | None]
+
 logger = get_logger(__name__)
 
 SANDBOX_NOT_INITIALIZED_ERROR = "Sandbox not initialized"
@@ -40,15 +46,21 @@ class E2BSandboxRuntime:
         self,
         template: str | None = None,
         ptc_packages: list[str] | None = None,
+        package_selector: PackageSelector | None = None,
     ) -> None:
         """Initialize E2B sandbox runtime.
 
         Args:
             template: Optional E2B template ID for custom sandbox environments.
             ptc_packages: Packages to install in sandbox. If None or empty, skip install.
+                Overwritten by package_selector if provided.
+            package_selector: Optional callback to select packages after sandbox creation.
+                Called with actual template (None if template failed) to enable smart
+                package selection based on whether template was successfully created.
         """
         self._template = template
         self._ptc_packages = ptc_packages
+        self._package_selector = package_selector
         self._sandbox: AsyncSandbox | None = None
         self._sandbox_created_with_template = False
 
@@ -153,6 +165,22 @@ class E2BSandboxRuntime:
             self._sandbox_created_with_template = False
             await create_default_sandbox()
 
+        # Determine packages to install
+        # If package_selector is provided, use it with actual template status
+        # This enables smart package selection based on whether template succeeded
+        if self._package_selector is not None:
+            actual_template = template if self._sandbox_created_with_template else None
+            try:
+                self._ptc_packages = self._package_selector(actual_template)
+                logger.info(
+                    f"Package selector called with actual_template={actual_template}, "
+                    f"selected packages: {self._ptc_packages}"
+                )
+            except Exception as e:
+                logger.error(f"Package selector failed: {e}")
+                await self.cleanup()
+                raise
+
         # Install ptc_packages if non-empty
         if self._ptc_packages:
             if self._should_skip_default_ptc_install(template):