zjcode 0.0.1__py3-none-any.whl

deepagents_code/integrations/sandbox_provider.py

@@ -0,0 +1,137 @@
+"""Sandbox provider interface used by Deep Agents Code."""
+
+from __future__ import annotations
+
+import asyncio
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from deepagents.backends.protocol import SandboxBackendProtocol
+
+
+@dataclass(frozen=True)
+class SandboxInstallHint:
+    """How to install the package that provides a sandbox backend.
+
+    Built-in providers ship as `deepagents-code` extras (`kind="extra"`);
+    third-party providers install as arbitrary packages (`kind="package"`).
+    The distinction lets error messages emit the correct install command
+    (`/install daytona` vs. `/install acme-dcode-sandbox --package`).
+    """
+
+    kind: Literal["extra", "package"]
+    name: str
+
+    def command(self, *, in_app: bool) -> str:
+        """Render the install command for this hint.
+
+        Args:
+            in_app: Whether to render the in-app slash command (`/install`)
+                rather than the CLI command (`dcode --install`).
+
+        Returns:
+            The install command string.
+        """
+        prefix = "/install" if in_app else "dcode --install"
+        suffix = " --package" if self.kind == "package" else ""
+        return f"{prefix} {self.name}{suffix}"
+
+
+@dataclass(frozen=True)
+class SandboxProviderMetadata:
+    """Static description of a sandbox provider used by the registry.
+
+    Lets the CLI and registry describe built-in and config providers without
+    instantiating them (which may require credentials or optional
+    dependencies). Entry-point providers expose their own instance via the
+    `SandboxProvider.metadata` property, which the registry reads only when it
+    already needs to construct the provider.
+    """
+
+    name: str
+    working_dir: str
+    install: SandboxInstallHint | None = None
+    supports_sandbox_id: bool = True
+    supports_snapshot_name: bool = False
+    backend_module: str | None = None
+    """Importable backend module checked by the pre-flight dependency probe.
+
+    `None` skips the probe (e.g. bundled providers, or third-party providers
+    whose package is only resolved when the provider is constructed).
+    """
+
+
+class SandboxError(Exception):
+    """Base error for sandbox provider operations."""
+
+    @property
+    def original_exc(self) -> BaseException | None:
+        """Original exception that caused this error, if any."""
+        return self.__cause__
+
+
+class SandboxNotFoundError(SandboxError):
+    """Raised when the requested sandbox cannot be found."""
+
+
+class SandboxProvider(ABC):
+    """Interface for creating and deleting sandbox backends."""
+
+    @property
+    def metadata(self) -> SandboxProviderMetadata | None:
+        """Static metadata describing this provider.
+
+        Third-party providers published under the
+        `deepagents_code.sandbox_providers` entry-point group override this so
+        the registry can surface their working directory and capability flags
+        (snapshot/sandbox-id support) instead of falling back to a generic
+        placeholder. Returns `None` by default; the registry then synthesizes a
+        minimal default.
+        """
+        return None
+
+    @abstractmethod
+    def get_or_create(
+        self,
+        *,
+        sandbox_id: str | None = None,
+        **kwargs: Any,
+    ) -> SandboxBackendProtocol:
+        """Get an existing sandbox, or create one if needed."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def delete(
+        self,
+        *,
+        sandbox_id: str,
+        **kwargs: Any,
+    ) -> None:
+        """Delete a sandbox by id."""
+        raise NotImplementedError
+
+    async def aget_or_create(
+        self,
+        *,
+        sandbox_id: str | None = None,
+        **kwargs: Any,
+    ) -> SandboxBackendProtocol:
+        """Async wrapper around get_or_create.
+
+        Returns:
+            The created or existing sandbox backend.
+        """
+        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 wrapper around delete."""
+        await asyncio.to_thread(self.delete, sandbox_id=sandbox_id, **kwargs)

deepagents_code/integrations/sandbox_registry.py

@@ -0,0 +1,350 @@
+"""Discovery and instantiation of sandbox providers.
+
+Merges three provider sources into one registry:
+
+1. Built-in providers curated in this repo (installed as `deepagents-code`
+   extras).
+2. Entry-point providers published by third-party packages under the
+   `deepagents_code.sandbox_providers` group.
+3. Config-declared providers from `[sandboxes.providers]` in
+   `~/.deepagents/config.toml` (escape hatch for internal/local packages).
+
+Precedence on name collision: config > entry point > built-in, so a user can
+always override discovery via their config file.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.metadata
+import logging
+from typing import TYPE_CHECKING
+
+from deepagents_code.integrations.sandbox_config import SandboxConfig
+from deepagents_code.integrations.sandbox_provider import (
+    SandboxInstallHint,
+    SandboxProvider,
+    SandboxProviderMetadata,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+ENTRY_POINT_GROUP = "deepagents_code.sandbox_providers"
+"""Entry-point group third-party packages publish providers under."""
+
+BUILTIN_METADATA: dict[str, SandboxProviderMetadata] = {
+    "agentcore": SandboxProviderMetadata(
+        name="agentcore",
+        working_dir="/tmp",  # noqa: S108  # AgentCore Code Interpreter working directory
+        install=SandboxInstallHint(kind="extra", name="agentcore"),
+        supports_sandbox_id=False,
+        backend_module="langchain_agentcore_codeinterpreter",
+    ),
+    "daytona": SandboxProviderMetadata(
+        name="daytona",
+        working_dir="/home/daytona",
+        install=SandboxInstallHint(kind="extra", name="daytona"),
+        backend_module="langchain_daytona",
+    ),
+    "langsmith": SandboxProviderMetadata(
+        name="langsmith",
+        working_dir="/root",  # `$HOME` in the LangSmith sandbox
+        # Bundled with `deepagents-code` via `langsmith[sandbox]`; no extra.
+        supports_snapshot_name=True,
+    ),
+    "modal": SandboxProviderMetadata(
+        name="modal",
+        working_dir="/workspace",
+        install=SandboxInstallHint(kind="extra", name="modal"),
+        backend_module="langchain_modal",
+    ),
+    "runloop": SandboxProviderMetadata(
+        name="runloop",
+        working_dir="/home/user",
+        install=SandboxInstallHint(kind="extra", name="runloop"),
+        supports_snapshot_name=True,
+        backend_module="langchain_runloop",
+    ),
+    "vercel": SandboxProviderMetadata(
+        name="vercel",
+        working_dir="/vercel/sandbox",
+        install=SandboxInstallHint(kind="extra", name="vercel"),
+        supports_sandbox_id=True,
+        supports_snapshot_name=False,
+        backend_module="langchain_vercel_sandbox",
+    ),
+}
+"""Metadata for curated built-in providers, keyed by provider name."""
+
+
+def _load_class(class_path: str) -> type:
+    """Import a `module.path:ClassName` provider class.
+
+    Args:
+        class_path: Fully-qualified class path.
+
+    Returns:
+        The imported class object.
+
+    Raises:
+        ValueError: If `class_path` is malformed.
+        ImportError: If the module cannot be imported or lacks the class.
+    """
+    if ":" not in class_path:
+        msg = (
+            f"Invalid class_path '{class_path}': must be in "
+            "module.path:ClassName format"
+        )
+        raise ValueError(msg)
+    module_path, class_name = class_path.rsplit(":", 1)
+    module = importlib.import_module(module_path)
+    cls = getattr(module, class_name, None)
+    if cls is None or not isinstance(cls, type):
+        msg = f"Class '{class_name}' not found in module '{module_path}'"
+        raise ImportError(msg)
+    return cls
+
+
+def _provider_metadata(provider: SandboxProvider, name: str) -> SandboxProviderMetadata:
+    """Extract metadata from a provider instance or class.
+
+    Providers may expose a `metadata` attribute/property; otherwise a minimal
+    default is synthesized.
+
+    Args:
+        provider: Provider instance.
+        name: Provider name to use when synthesizing defaults.
+
+    Returns:
+        The provider's metadata.
+    """
+    meta = getattr(provider, "metadata", None)
+    if isinstance(meta, SandboxProviderMetadata):
+        return meta
+    return SandboxProviderMetadata(name=name, working_dir="/workspace")
+
+
+class SandboxRegistry:
+    """Merged view of built-in, entry-point, and config sandbox providers."""
+
+    def __init__(
+        self,
+        *,
+        config: SandboxConfig | None = None,
+        include_entry_points: bool = True,
+    ) -> None:
+        """Build the registry.
+
+        Args:
+            config: Parsed sandbox config. Loaded from the default path when
+                omitted.
+            include_entry_points: Whether to discover entry-point providers.
+                Disabled in tests that need a deterministic provider set.
+        """
+        self._config = config if config is not None else SandboxConfig.load()
+        self._include_entry_points = include_entry_points
+        self._entry_points: dict[str, importlib.metadata.EntryPoint] = (
+            self._discover_entry_points() if include_entry_points else {}
+        )
+
+    @classmethod
+    def load(cls, config_path: Path | None = None) -> SandboxRegistry:
+        """Build a registry from the config file at `config_path`.
+
+        Args:
+            config_path: Path to config file. Defaults to the user config.
+
+        Returns:
+            A new `SandboxRegistry`.
+        """
+        return cls(config=SandboxConfig.load(config_path))
+
+    @staticmethod
+    def _discover_entry_points() -> dict[str, importlib.metadata.EntryPoint]:
+        """Return entry-point providers keyed by name (best-effort)."""
+        found: dict[str, importlib.metadata.EntryPoint] = {}
+        try:
+            entries = importlib.metadata.entry_points(group=ENTRY_POINT_GROUP)
+        except Exception:
+            logger.warning("Failed to discover sandbox entry points", exc_info=True)
+            return found
+        for entry in entries:
+            found[entry.name] = entry
+        return found
+
+    @property
+    def default(self) -> str | None:
+        """The configured default provider, if any."""
+        return self._config.default
+
+    @property
+    def config_error(self) -> str | None:
+        """Why the config file failed to load, if it existed but couldn't parse.
+
+        `None` when the config parsed cleanly or simply wasn't present.
+        """
+        return self._config.parse_error
+
+    def available_providers(self) -> list[str]:
+        """Return all known provider names, sorted."""
+        names = (
+            set(BUILTIN_METADATA)
+            | set(self._entry_points)
+            | set(self._config.providers)
+        )
+        return sorted(names)
+
+    def is_available(self, name: str) -> bool:
+        """Return whether `name` resolves to a known provider."""
+        return (
+            name in self._config.providers
+            or name in self._entry_points
+            or name in BUILTIN_METADATA
+        )
+
+    def get_metadata(self, name: str) -> SandboxProviderMetadata | None:
+        """Return metadata for `name`.
+
+        Config providers may override `working_dir`, `package`, and capability
+        flags. Entry-point providers are probed for advertised metadata and
+        take precedence over built-ins with the same name.
+
+        Args:
+            name: Provider name.
+
+        Returns:
+            The provider's metadata, or `None` if unknown.
+        """
+        config_entry = self._config.providers.get(name)
+        if config_entry is not None:
+            base = BUILTIN_METADATA.get(name)
+            package = config_entry.get("package")
+            return SandboxProviderMetadata(
+                name=name,
+                working_dir=config_entry.get(
+                    "working_dir", base.working_dir if base else "/workspace"
+                ),
+                install=(
+                    SandboxInstallHint(kind="package", name=package)
+                    if package
+                    else (base.install if base else None)
+                ),
+                supports_sandbox_id=config_entry.get(
+                    "supports_sandbox_id",
+                    base.supports_sandbox_id if base else True,
+                ),
+                supports_snapshot_name=config_entry.get(
+                    "supports_snapshot_name",
+                    base.supports_snapshot_name if base else False,
+                ),
+                # Carry the built-in's probe module so a config override of a
+                # built-in keeps its dependency pre-flight check. A pure config
+                # provider (no base) leaves this `None`; its package is resolved
+                # when the provider class is imported.
+                backend_module=base.backend_module if base else None,
+            )
+        if name in self._entry_points:
+            return self.provider_metadata(name)
+        if name in BUILTIN_METADATA:
+            return BUILTIN_METADATA[name]
+        return None
+
+    def get_params(self, name: str) -> dict[str, object]:
+        """Return config `params` forwarded to the provider's `get_or_create()`."""
+        return self._config.get_params(name)
+
+    def create_provider(self, name: str) -> SandboxProvider:
+        """Instantiate the provider named `name`.
+
+        Resolution order: config `class_path` > entry point > built-in.
+
+        Args:
+            name: Provider name.
+
+        Returns:
+            A `SandboxProvider` instance. Propagates `ImportError` from
+                `_load_class` / `EntryPoint.load` if a config or entry-point
+                class cannot be imported.
+
+        Raises:
+            ValueError: If `name` is unknown or a config provider omits
+                `class_path`.
+        """
+        config_entry = self._config.providers.get(name)
+        if config_entry is not None:
+            class_path = config_entry.get("class_path")
+            if not class_path:
+                msg = f"Sandbox provider '{name}' config is missing 'class_path'"
+                raise ValueError(msg)
+            return _load_class(class_path)()
+
+        entry = self._entry_points.get(name)
+        if entry is not None:
+            return entry.load()()
+
+        if name in BUILTIN_METADATA:
+            return _create_builtin_provider(name)
+
+        msg = (
+            f"Unknown sandbox provider: {name}. "
+            f"Available providers: {', '.join(self.available_providers())}"
+        )
+        raise ValueError(msg)
+
+    def provider_metadata(self, name: str) -> SandboxProviderMetadata:
+        """Return authoritative metadata for `name`.
+
+        Config providers are described statically. Entry-point providers are
+        instantiated so capability flags they expose via a `metadata` attribute
+        take effect; on failure this falls back to the static placeholder.
+        Built-in metadata is used only when no entry point overrides that name.
+
+        Args:
+            name: Provider name.
+
+        Returns:
+            The provider's metadata.
+
+        Raises:
+            ValueError: If `name` is unknown.
+        """
+        if name in self._config.providers or (
+            name in BUILTIN_METADATA and name not in self._entry_points
+        ):
+            meta = self.get_metadata(name)
+            if meta is not None:
+                return meta
+        if name in self._entry_points:
+            try:
+                provider = self.create_provider(name)
+            except Exception:  # noqa: BLE001  # Metadata probe must not crash discovery
+                logger.debug("Could not instantiate provider %r for metadata", name)
+                return SandboxProviderMetadata(name=name, working_dir="/workspace")
+            return _provider_metadata(provider, name)
+        meta = self.get_metadata(name)
+        if meta is None:
+            msg = f"Unknown sandbox provider: {name}"
+            raise ValueError(msg)
+        return meta
+
+
+def _create_builtin_provider(name: str) -> SandboxProvider:
+    """Instantiate a built-in provider class (lazy import avoids cycles).
+
+    Returns:
+        The built-in `SandboxProvider` instance for `name`.
+    """
+    from deepagents_code.integrations import sandbox_factory
+
+    builders = {
+        "agentcore": sandbox_factory._AgentCoreProvider,
+        "daytona": sandbox_factory._DaytonaProvider,
+        "langsmith": sandbox_factory._LangSmithProvider,
+        "modal": sandbox_factory._ModalProvider,
+        "runloop": sandbox_factory._RunloopProvider,
+        "vercel": sandbox_factory._VercelProvider,
+    }
+    return builders[name]()

deepagents_code/iterm_cursor_guide.py

@@ -0,0 +1,176 @@
+"""iTerm2 cursor guide workaround for Textual alternate-screen rendering."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+# iTerm2's cursor guide (highlight cursor line) causes visual artifacts when
+# Textual takes over the terminal in alternate screen mode. We disable it at
+# module load and restore it on exit only if the active/default iTerm2 profile
+# had cursor guide enabled before launch.
+
+# Detection: check env vars AND that stderr is a TTY (avoids false positives
+# when env vars are inherited but running in non-TTY context like CI).
+_IS_ITERM = (
+    (
+        os.environ.get("LC_TERMINAL", "") == "iTerm2"
+        or os.environ.get("TERM_PROGRAM", "") == "iTerm.app"
+    )
+    and hasattr(os, "isatty")
+    and os.isatty(2)
+)
+
+# iTerm2 cursor guide escape sequences (OSC 1337)
+# Format: OSC 1337 ; HighlightCursorLine=<yes|no> ST
+# Where OSC = ESC ] (0x1b 0x5d) and ST = ESC \ (0x1b 0x5c)
+_ITERM_CURSOR_GUIDE_OFF = "\x1b]1337;HighlightCursorLine=no\x1b\\"
+_ITERM_CURSOR_GUIDE_ON = "\x1b]1337;HighlightCursorLine=yes\x1b\\"
+_ITERM_PREFS_PATH = Path("~/Library/Preferences/com.googlecode.iterm2.plist")
+
+
+def _write_iterm_escape(sequence: str) -> None:
+    """Write an iTerm2 escape sequence to stderr.
+
+    Silently fails if the terminal is unavailable (redirected, closed, broken
+    pipe). This is a cosmetic feature, so failures should never crash the app.
+    """
+    if not _IS_ITERM:
+        return
+    try:
+        import sys
+
+        if sys.__stderr__ is not None:
+            sys.__stderr__.write(sequence)
+            sys.__stderr__.flush()
+    except OSError:
+        # Terminal may be unavailable (redirected, closed, broken pipe).
+        pass
+
+
+def _plist_bool(value: object) -> bool | None:
+    """Return a plist boolean/int value as `bool`, or `None` if not boolean-like."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, int):
+        return value != 0
+    return None
+
+
+def _profile_uses_cursor_guide(profile: dict[str, object]) -> bool:
+    """Return whether an iTerm2 profile has cursor guide enabled."""
+    enabled = _plist_bool(profile.get("Use Cursor Guide"))
+    if enabled is not None:
+        return enabled
+
+    # Newer iTerm2 profiles may carry separate light/dark values. If the shared
+    # value is absent, restoring when either variant is enabled preserves the
+    # user's visible default better than losing the guide for both appearances.
+    return any(
+        _plist_bool(profile.get(key)) is True
+        for key in ("Use Cursor Guide (Dark)", "Use Cursor Guide (Light)")
+    )
+
+
+def _coerce_profile(raw: object) -> dict[str, object] | None:
+    """Return a string-keyed profile dictionary from raw plist data."""
+    if not isinstance(raw, dict):
+        return None
+    return {key: value for key, value in raw.items() if isinstance(key, str)}
+
+
+def _find_iterm_profile(
+    profiles: list[object], *, name: str, guid: str
+) -> dict[str, object] | None:
+    """Find the current iTerm2 profile by name, then by default profile GUID.
+
+    Args:
+        profiles: Profile entries from iTerm2 preferences.
+        name: Active profile name from `ITERM_PROFILE`.
+        guid: Default profile GUID from iTerm2 preferences.
+
+    Returns:
+        The matching profile dictionary, or `None` when no match is found.
+    """
+    for raw in profiles:
+        profile = _coerce_profile(raw)
+        if profile is None:
+            continue
+        if profile.get("Name") == name:
+            return profile
+    for raw in profiles:
+        profile = _coerce_profile(raw)
+        if profile is None:
+            continue
+        if profile.get("Guid") == guid:
+            return profile
+    return None
+
+
+def _iterm_profile_cursor_guide_enabled() -> bool:
+    """Infer whether iTerm2 cursor guide was enabled before startup.
+
+    iTerm2's OSC 1337 `HighlightCursorLine` command can set the guide to yes/no
+    but does not report the current state. The best cheap signal available at
+    startup is the active profile preference, exposed in the iTerm2 plist. The
+    `ITERM_PROFILE` environment variable is set by iTerm2; when it is missing,
+    fall back to the default profile GUID in preferences.
+
+    Returns:
+        `True` if the matched iTerm2 profile has cursor guide enabled.
+    """
+    if not _IS_ITERM:
+        return False
+
+    import plistlib
+
+    try:
+        with _ITERM_PREFS_PATH.expanduser().open("rb") as f:
+            prefs = plistlib.load(f)
+    except (OSError, plistlib.InvalidFileException, ValueError):
+        return False
+
+    if not isinstance(prefs, dict):
+        return False
+
+    profiles = prefs.get("New Bookmarks")
+    if not isinstance(profiles, list):
+        return False
+
+    name = os.environ.get("ITERM_PROFILE", "").strip()
+    guid = str(prefs.get("Default Bookmark Guid", ""))
+    profile = _find_iterm_profile(profiles, name=name, guid=guid)
+    if profile is None:
+        return False
+    return _profile_uses_cursor_guide(profile)
+
+
+_RESTORE_ITERM_CURSOR_GUIDE = _iterm_profile_cursor_guide_enabled()
+_ITERM_CURSOR_GUIDE_RESTORED = False
+
+
+def restore_iterm_cursor_guide() -> None:
+    """Restore iTerm2 cursor guide when launch-time profile state required it."""
+    global _ITERM_CURSOR_GUIDE_RESTORED  # noqa: PLW0603  # atexit/exit idempotence
+
+    if not _RESTORE_ITERM_CURSOR_GUIDE or _ITERM_CURSOR_GUIDE_RESTORED:
+        return
+    _ITERM_CURSOR_GUIDE_RESTORED = True
+    _write_iterm_escape(_ITERM_CURSOR_GUIDE_ON)
+
+
+def _disable_iterm_cursor_guide() -> None:
+    """Disable iTerm2 cursor guide only when the module has a restore path."""
+    if not _RESTORE_ITERM_CURSOR_GUIDE:
+        return
+    _write_iterm_escape(_ITERM_CURSOR_GUIDE_OFF)
+
+
+# Disable cursor guide at module load (before Textual takes over), but only
+# when launch-time state detection confirmed that exit cleanup will restore it.
+_disable_iterm_cursor_guide()
+
+if _RESTORE_ITERM_CURSOR_GUIDE:
+    import atexit
+
+    atexit.register(restore_iterm_cursor_guide)