e2b-adk 0.1.0__py3-none-any.whl

e2b_adk/__init__.py

@@ -0,0 +1,34 @@
+"""e2b-adk — Google ADK plugin backed by E2B sandboxes."""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+
+from e2b import ConnectionConfig
+
+from .plugin import E2BPlugin
+from .tools import (
+    ListFiles,
+    ReadFile,
+    RunCode,
+    RunCommand,
+    StartBackgroundCommand,
+    WriteFile,
+)
+
+# E2B's integration hook is process-wide and must be set before the SDK builds
+# a connection config. Importing the modules above has no runtime side effects;
+# plugin construction can only happen after package initialization completes.
+__version__ = version("e2b-adk")
+ConnectionConfig.set_integration(f"e2b-adk/{__version__}")
+
+__all__ = [
+    "E2BPlugin",
+    "__version__",
+    "ListFiles",
+    "ReadFile",
+    "RunCode",
+    "RunCommand",
+    "StartBackgroundCommand",
+    "WriteFile",
+]

e2b_adk/_results.py

@@ -0,0 +1,96 @@
+"""Result-contract helpers and output truncation shared by all tools.
+
+Pure, dependency-free functions (no E2B/ADK imports). Every tool returns a
+JSON-serializable ``dict`` following a single shape:
+
+* Success results carry ``success: True`` plus tool-specific fields.
+* Failure results carry ``success: False``, a human-readable ``error``, the
+  echoed input relevant to the call (``path`` / ``command``), and any
+  ``partial_output`` captured before the failure.
+
+Oversized text output is trimmed to a byte bound with an explicit marker so a
+single tool call cannot exhaust the agent's context window.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+#: Default upper bound (in bytes) for a single truncatable text field.
+DEFAULT_MAX_OUTPUT_BYTES = 10_000
+
+
+def truncate_output(text: str, limit: int = DEFAULT_MAX_OUTPUT_BYTES) -> str:
+    """Trim ``text`` to at most ``limit`` *payload* bytes (UTF-8), plus a marker.
+
+    ``limit`` bounds the retained payload, not the final string: when truncation
+    occurs a short ``…[truncated N bytes]`` marker is appended *beyond* the
+    ``limit`` bytes, so the returned string may exceed ``limit`` by the marker's
+    length. This keeps a single tool call from exhausting the agent's context
+    while still reporting the exact omitted-byte count.
+
+    Text is first normalized to valid Unicode: well-formed surrogate pairs are
+    combined and lone surrogates are replaced with ``U+FFFD``. Text whose UTF-8
+    encoding is then within ``limit`` is returned without a marker. Otherwise
+    the first ``limit`` bytes are kept (decoded back at a valid character
+    boundary, dropping any partial trailing char).
+    """
+    if limit < 0:
+        raise ValueError(f"limit must be non-negative, got {limit}")
+    try:
+        encoded = text.encode("utf-8")
+        normalized = text
+    except UnicodeEncodeError:
+        # E2B builds streamed log text with json.loads(), which can produce
+        # Python strings containing UTF-16 surrogate code points. A UTF-16
+        # round-trip combines valid pairs and replaces only malformed lone
+        # surrogates, yielding text that is safe to encode and serialize.
+        normalized = text.encode("utf-16", errors="surrogatepass").decode(
+            "utf-16", errors="replace"
+        )
+        encoded = normalized.encode("utf-8")
+    total = len(encoded)
+    if total <= limit:
+        return normalized
+
+    # Decode the retained prefix, dropping any partial trailing char.
+    kept = encoded[:limit].decode("utf-8", errors="ignore")
+    omitted = total - len(kept.encode("utf-8"))
+    return f"{kept}…[truncated {omitted:,} bytes]"
+
+
+def success_result(**fields: Any) -> dict[str, Any]:
+    """Build a success result: ``{**fields, "success": True}``.
+
+    Callers pass the tool-specific fields (e.g. ``stdout``, ``path``,
+    ``exit_code``) as keyword arguments. The reserved ``success`` key is set
+    last so a caller-supplied ``success`` field can never override the contract.
+    """
+    return {**fields, "success": True}
+
+
+def failure_result(
+    error: str,
+    *,
+    path: str | None = None,
+    command: str | None = None,
+    partial_output: str = "",
+    **extra: Any,
+) -> dict[str, Any]:
+    """Build a failure result following the single failure contract.
+
+    Always includes ``success: False``, the ``error`` message, and
+    ``partial_output``. The echoed input (``path`` and/or ``command``) is
+    included only when supplied. Extra tool-specific fields may be passed via
+    ``**extra``. Reserved contract keys are applied *after* ``**extra`` so an
+    ``extra`` field can never override them.
+    """
+    result: dict[str, Any] = dict(extra)
+    result["success"] = False
+    result["error"] = error
+    result["partial_output"] = partial_output
+    if path is not None:
+        result["path"] = path
+    if command is not None:
+        result["command"] = command
+    return result

e2b_adk/_sandbox.py

@@ -0,0 +1,127 @@
+"""Lazy E2B sandbox lifecycle management.
+
+``SandboxManager`` owns a single ``AsyncSandbox`` that is created lazily on the
+first tool call and reused for the lifetime of the plugin instance, then torn
+down on shutdown. An ``asyncio.Lock`` guards creation and teardown so that
+concurrent tool calls (an agent turn may dispatch several at once) can never
+create two sandboxes and leak one.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any, cast
+
+from e2b_code_interpreter import AsyncSandbox
+
+logger = logging.getLogger(__name__)
+
+
+class SandboxManager:
+    """Lazily creates and caches one ``AsyncSandbox``.
+
+    Any keyword arguments (``api_key``, ``template``, ``metadata``, ``envs``,
+    ``timeout``, ...) are stored and forwarded verbatim to
+    ``AsyncSandbox.create(...)`` on first use.
+    """
+
+    def __init__(self, **opts: Any) -> None:
+        self._opts: dict[str, Any] = opts
+        self._sandbox: AsyncSandbox | None = None
+        self._lock = asyncio.Lock()
+
+    async def get(self) -> AsyncSandbox:
+        """Return the live sandbox, creating it on the first call and caching it.
+
+        Subsequent calls return the cached instance without creating a second
+        sandbox. Creation is guarded by a lock with a double-check so that two
+        concurrent first calls create exactly one sandbox, never two.
+
+        The cached handle is returned as-is without a liveness check: an
+        already-created sandbox that has since expired is not detected or
+        re-created here (see :meth:`keep_alive` for the keep-alive scope that
+        prevents expiry during active use).
+        """
+        if self._sandbox is None:
+            async with self._lock:
+                if self._sandbox is None:
+                    self._sandbox = await AsyncSandbox.create(**self._opts)
+        return self._sandbox
+
+    async def refresh_timeout(self) -> None:
+        """Push the sandbox's expiry window forward (no-op when none exists).
+
+        An E2B sandbox expires ``timeout`` seconds (SDK default 300) after
+        creation or the last ``set_timeout`` call — *not* after the last use.
+        This one-shot operation is also used by :meth:`keep_alive`, whose
+        recurring heartbeat covers an SDK operation that runs longer than the
+        timeout. Best-effort: a keep-alive failure is logged and swallowed.
+        """
+        sandbox = self._sandbox
+        if sandbox is not None:
+            await self._refresh_sandbox(sandbox)
+
+    def _timeout_seconds(self) -> int:
+        """Return the caller-configured TTL or E2B's default."""
+        timeout = self._opts.get("timeout")
+        if isinstance(timeout, int) and timeout > 0:
+            return timeout
+        return int(AsyncSandbox.default_sandbox_timeout)
+
+    def _keepalive_interval_seconds(self) -> float:
+        """Refresh halfway through the TTL, with a small positive floor."""
+        return max(self._timeout_seconds() / 2, 0.1)
+
+    async def _refresh_sandbox(self, sandbox: AsyncSandbox) -> None:
+        """Best-effort refresh for the currently cached sandbox."""
+        if self._sandbox is not sandbox:
+            return
+        try:
+            # E2B's class_method_variant decorator exposes set_timeout to mypy
+            # as Any | None even though the bound instance method is awaitable.
+            await cast(Any, sandbox).set_timeout(self._timeout_seconds())
+        except Exception as exc:  # noqa: BLE001 — keep-alive is best-effort
+            logger.debug("sandbox keep-alive failed: %s", exc)
+
+    async def _keepalive_loop(self, sandbox: AsyncSandbox) -> None:
+        """Refresh ``sandbox`` until its active SDK operation finishes."""
+        while self._sandbox is sandbox:
+            await asyncio.sleep(self._keepalive_interval_seconds())
+            await self._refresh_sandbox(sandbox)
+
+    @asynccontextmanager
+    async def keep_alive(self, sandbox: AsyncSandbox) -> AsyncIterator[None]:
+        """Keep ``sandbox`` alive for the full duration of one SDK operation.
+
+        The first refresh handles cached sandboxes, the heartbeat prevents a
+        call longer than the TTL from expiring mid-run, and the final refresh
+        starts a full idle window when the operation completes. Every refresh
+        is best-effort so lifecycle maintenance never changes a tool result.
+        """
+        await self._refresh_sandbox(sandbox)
+        heartbeat = asyncio.create_task(self._keepalive_loop(sandbox))
+        try:
+            yield
+        finally:
+            heartbeat.cancel()
+            await asyncio.gather(heartbeat, return_exceptions=True)
+            await self._refresh_sandbox(sandbox)
+
+    async def shutdown(self) -> None:
+        """Kill the sandbox if one exists and clear the cache.
+
+        A no-op when no sandbox was ever created. The cache is cleared even if
+        ``kill()`` raises (the error still propagates), so a dead sandbox is
+        never handed back — after shutdown, a later ``get()`` lazily creates a
+        fresh sandbox. Holds the same lock as ``get()`` so teardown cannot race
+        with a concurrent create.
+        """
+        async with self._lock:
+            if self._sandbox is not None:
+                try:
+                    await self._sandbox.kill()
+                finally:
+                    self._sandbox = None

e2b_adk/plugin.py

@@ -0,0 +1,204 @@
+"""E2BPlugin — a ``google.adk.plugins.BasePlugin`` backed by an E2B sandbox.
+
+The plugin owns a single :class:`~e2b_adk._sandbox.SandboxManager` built from
+its constructor options. No sandbox is created at construction time — the
+manager creates one lazily on the first tool call and reuses it until
+:meth:`close` tears it down.
+
+``get_tools()`` is a package convenience (not an ADK override) that returns the
+execution tools, all sharing the plugin's single ``SandboxManager`` so every
+tool call targets the same sandbox.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from google.adk.plugins import BasePlugin
+from google.adk.tools import BaseTool, ToolContext
+
+from ._sandbox import SandboxManager
+from .tools import (
+    ListFiles,
+    ReadFile,
+    RunCode,
+    RunCommand,
+    StartBackgroundCommand,
+    WriteFile,
+)
+
+logger = logging.getLogger(__name__)
+
+#: Tool-arg keys whose *values* are masked before logging: ``command`` and
+#: ``envs`` may carry credentials, while ``content`` / ``code`` may be large or
+#: sensitive payloads. Other args (path, cwd, port, ...) are logged as-is to
+#: keep the trace useful.
+_SENSITIVE_ARG_KEYS = frozenset({"command", "content", "code", "envs"})
+
+
+def _redact_args(tool_args: dict[str, Any]) -> dict[str, Any]:
+    """Return a shallow copy of ``tool_args`` with sensitive values masked."""
+    if not isinstance(tool_args, dict):
+        return tool_args
+    return {
+        key: ("<redacted>" if key in _SENSITIVE_ARG_KEYS else value)
+        for key, value in tool_args.items()
+    }
+
+
+class E2BPlugin(BasePlugin):
+    """ADK plugin that runs tool calls inside a shared E2B sandbox.
+
+    Constructor options (all optional) are forwarded to the owned
+    ``SandboxManager`` and, through it, to ``AsyncSandbox.create(...)`` on first
+    use. Only the options that were actually supplied (non-``None``) are
+    forwarded, so E2B's own defaults apply otherwise.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        template: str | None = None,
+        metadata: dict[str, str] | None = None,
+        envs: dict[str, str] | None = None,
+        timeout: int | None = None,
+        secure: bool | None = None,
+        allow_internet_access: bool | None = None,
+        mcp: Any | None = None,
+        network: Any | None = None,
+        lifecycle: Any | None = None,
+        volume_mounts: Any | None = None,
+        plugin_name: str = "e2b_plugin",
+        **opts: Any,
+    ) -> None:
+        """Build the plugin and its (lazy) ``SandboxManager``.
+
+        Every option except ``plugin_name`` maps to an ``AsyncSandbox.create``
+        parameter and is forwarded verbatim; only options the caller actually
+        set (non-``None``) are passed, so E2B's own defaults apply otherwise.
+
+        The named parameters cover ``create``'s sandbox options. Any further
+        keyword arguments (``**opts``) are forwarded verbatim too, covering the
+        connection-level ``ApiParams`` (``proxy``, ``request_timeout``,
+        ``headers``, ...) and any future ``create`` parameter without a plugin
+        change — the plugin stays a thin, neutral passthrough.
+
+        ``api_key`` is optional and normally omitted: when it is ``None`` the
+        E2B SDK reads ``E2B_API_KEY`` from the environment automatically, which
+        is the recommended way to supply the credential (keep it out of source).
+
+        ``lifecycle`` controls what happens when the sandbox times out. Omitting
+        it keeps E2B's default (``on_timeout: "kill"``); pass e.g.
+        ``{"on_timeout": {"action": "pause"}, "auto_resume": True}`` to preserve
+        state across idle gaps instead.
+        """
+        super().__init__(name=plugin_name)
+
+        named: dict[str, Any] = {
+            "api_key": api_key,
+            "template": template,
+            "metadata": metadata,
+            "envs": envs,
+            "timeout": timeout,
+            "secure": secure,
+            "allow_internet_access": allow_internet_access,
+            "mcp": mcp,
+            "network": network,
+            "lifecycle": lifecycle,
+            "volume_mounts": volume_mounts,
+        }
+        # Forward only the named options the caller actually set, plus any extra
+        # keyword args verbatim (e.g. connection-level ApiParams).
+        forwarded = {key: value for key, value in named.items() if value is not None}
+        forwarded.update(opts)
+        self._manager = SandboxManager(**forwarded)
+
+    def get_tools(self) -> list[BaseTool]:
+        """Return the execution tools, all sharing this plugin's sandbox.
+
+        Not an ADK override — a convenience so callers can wire the tools into
+        an ``Agent``. Each tool receives the plugin's single ``SandboxManager``
+        instance, so every tool call targets the same lazily-created sandbox.
+        """
+        return [
+            RunCode(self._manager),
+            RunCommand(self._manager),
+            WriteFile(self._manager),
+            ReadFile(self._manager),
+            ListFiles(self._manager),
+            StartBackgroundCommand(self._manager),
+        ]
+
+    async def close(self) -> None:
+        """Tear down the sandbox on plugin shutdown (ADK teardown hook)."""
+        await self._manager.shutdown()
+
+    def _owns(self, tool: BaseTool) -> bool:
+        """Whether ``tool`` is one of this plugin's own sandbox tools.
+
+        ADK dispatches plugin callbacks for *every* tool in the app, including
+        tools this plugin didn't create. Ownership is checked by identity on the
+        shared ``SandboxManager`` so foreign tools are left alone — no misleading
+        "E2B tool" log lines and no warnings about other tools' result shapes.
+        """
+        return getattr(tool, "manager", None) is self._manager
+
+    async def before_tool_callback(
+        self,
+        *,
+        tool: BaseTool,
+        tool_args: dict[str, Any],
+        tool_context: ToolContext,
+    ) -> dict[str, Any] | None:
+        """Log the owned sandbox tool about to run (non-intrusive)."""
+        if not self._owns(tool):
+            return None
+        logger.debug("E2B tool starting: %s args=%s", tool.name, _redact_args(tool_args))
+        return None
+
+    async def after_tool_callback(
+        self,
+        *,
+        tool: BaseTool,
+        tool_args: dict[str, Any],
+        tool_context: ToolContext,
+        result: dict[str, Any],
+    ) -> dict[str, Any] | None:
+        """Log the outcome of a sandbox tool call (non-intrusive).
+
+        A tool that returns ``success: False`` (a failure it *handled* per the
+        result contract) is surfaced at warning level; an exception that escapes
+        a tool is handled separately in :meth:`on_tool_error_callback`.
+        """
+        if not self._owns(tool):
+            return None
+        if isinstance(result, dict) and result.get("success") is False:
+            logger.warning(
+                "E2B tool %s returned a failure result: %s",
+                tool.name,
+                result.get("error"),
+            )
+        else:
+            logger.debug("E2B tool finished: %s", tool.name)
+        return None
+
+    async def on_tool_error_callback(
+        self,
+        *,
+        tool: BaseTool,
+        tool_args: dict[str, Any],
+        tool_context: ToolContext,
+        error: Exception,
+    ) -> dict[str, Any] | None:
+        """Log an *uncaught* tool exception.
+
+        The tools return failures via the result contract rather than raising,
+        so reaching here indicates a bug or an unexpected SDK error worth a
+        louder log line. Returns ``None`` (no result substitution).
+        """
+        if not self._owns(tool):
+            return None
+        logger.error("E2B tool %s raised an uncaught exception: %s", tool.name, error)
+        return None

e2b_adk/tools/__init__.py

@@ -0,0 +1,43 @@
+"""ADK ``BaseTool`` subclasses that execute inside the E2B sandbox.
+
+One tool per module, re-exported here so ``from e2b_adk.tools import RunCode``
+(and the plugin's own imports) keep working. The tools:
+
+* ``RunCode`` (``run_code``) — run a code snippet in the sandbox interpreter.
+* ``RunCommand`` (``run_command``) — run a shell command in the sandbox.
+* ``WriteFile`` (``write_file``) — write a file into the sandbox filesystem.
+* ``ReadFile`` (``read_file``) — read a file from the sandbox filesystem.
+* ``ListFiles`` (``list_files``) — list a directory in the sandbox filesystem.
+* ``StartBackgroundCommand`` (``start_background_command``) — start a
+  long-running command (e.g. a dev server) and return immediately.
+
+All follow the single result contract from :mod:`e2b_adk._results`:
+
+* The tool *ran* (even if the user's code raised or the command exited
+  non-zero) → ``success: True`` with the captured output / normalized error.
+* The tool *could not run* (sandbox unavailable, create failure, timeout) →
+  ``success: False`` with an ``error`` and any ``partial_output``.
+
+Failures are always **returned**, never raised out of ``run_async`` — a raised
+exception would abort the whole agent run.
+"""
+
+from __future__ import annotations
+
+from ._common import SUPPORTED_LANGUAGES
+from .list_files import ListFiles
+from .read_file import ReadFile
+from .run_code import RunCode
+from .run_command import RunCommand
+from .start_background_command import StartBackgroundCommand
+from .write_file import WriteFile
+
+__all__ = [
+    "SUPPORTED_LANGUAGES",
+    "ListFiles",
+    "ReadFile",
+    "RunCode",
+    "RunCommand",
+    "StartBackgroundCommand",
+    "WriteFile",
+]

e2b_adk/tools/_common.py

@@ -0,0 +1,77 @@
+"""Shared helpers for the E2B tool classes.
+
+Small, pure helpers used by more than one tool (or that derive a constant from
+the SDK). Each tool class lives in its own module and imports what it needs
+from here; the package ``__init__`` re-exports the public surface.
+"""
+
+from __future__ import annotations
+
+from typing import Any, get_args
+
+from e2b_code_interpreter import FileType, RunCodeLanguage
+
+
+def _supported_languages() -> list[str]:
+    """Derive the known languages from E2B's ``RunCodeLanguage`` type alias.
+
+    E2B declares it as ``Union[Literal["python", ...], str]`` — an *open* union
+    (any string is accepted; the literals are the known set). We unpack those
+    literal members so the enum we advertise stays in lockstep with the pinned
+    SDK and is never maintained in two places. Falls back to ``["python"]`` if
+    the alias shape ever changes (``run_code`` still accepts any string).
+    """
+    args = get_args(RunCodeLanguage)
+    for arg in args:
+        members = get_args(arg)
+        if members and all(isinstance(m, str) for m in members):
+            return list(members)
+    return ["python"]
+
+
+#: Languages E2B's ``run_code`` supports natively, sourced from the SDK's own
+#: ``RunCodeLanguage``. E2B runs all of them through a single ``run_code`` call,
+#: so this tool needs no per-language branching.
+SUPPORTED_LANGUAGES = _supported_languages()
+
+
+def _join(chunks: list[str] | None) -> str:
+    """Join a list of E2B log chunks into a single text blob.
+
+    E2B ``Logs.stdout`` / ``Logs.stderr`` are lists of chunks whose entries
+    already carry their own newlines, so they are concatenated with no
+    separator to avoid doubling line breaks. ``None`` collapses to ``""``.
+    """
+    if not chunks:
+        return ""
+    return "".join(chunks)
+
+
+def _normalize_type(file_type: FileType | None) -> str:
+    """Normalize an E2B ``FileType`` entry to a plain string.
+
+    ``FileType.FILE`` / ``FileType.DIR`` map to their ``.value`` (``"file"`` /
+    ``"dir"``). A ``None`` type (E2B may omit it for an entry it cannot classify)
+    collapses to ``"unknown"`` so every entry carries a JSON-friendly string
+    ``type`` and callers never have to handle ``None``.
+    """
+    if file_type is None:
+        return "unknown"
+    return str(file_type.value)
+
+
+def _require_str(args: dict[str, Any], key: str, *, allow_empty: bool = False) -> str | None:
+    """Return ``args[key]`` when it is a valid string, else ``None``.
+
+    Guards a *required* argument so a malformed tool call (a missing or
+    non-string value) is turned into a returned failure rather than a ``KeyError``
+    raised out of ``run_async`` — the tools must never raise. ``allow_empty=True``
+    permits ``""`` (e.g. writing an empty file); otherwise an empty string is
+    rejected like a missing value.
+    """
+    value = args.get(key)
+    if not isinstance(value, str):
+        return None
+    if not value and not allow_empty:
+        return None
+    return value

e2b_adk/tools/list_files.py

@@ -0,0 +1,82 @@
+"""``list_files`` — list a directory in the sandbox filesystem."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from google.adk.tools import BaseTool, ToolContext
+from google.genai import types
+
+from .._results import failure_result, success_result
+from .._sandbox import SandboxManager
+from ._common import _normalize_type
+
+logger = logging.getLogger(__name__)
+
+
+class ListFiles(BaseTool):
+    """List a directory in the E2B sandbox filesystem.
+
+    Backed by ``AsyncSandbox.files.list``. Returns one ``entries`` element per
+    child, each ``{"name": ..., "type": ...}`` where ``type`` is the normalized
+    string ``"file"`` / ``"dir"`` (or ``"unknown"`` when E2B omits it). A
+    non-existent directory or SDK error yields ``success: False`` with the
+    echoed ``path``.
+    """
+
+    def __init__(self, manager: SandboxManager) -> None:
+        super().__init__(
+            name="list_files",
+            description=(
+                "List the entries of a directory in an isolated E2B sandbox. "
+                "Returns each child's name and type (file or dir). Defaults to "
+                "the current directory. Use this to explore the sandbox "
+                "filesystem."
+            ),
+        )
+        self.manager = manager
+
+    def _get_declaration(self) -> types.FunctionDeclaration:
+        return types.FunctionDeclaration(
+            name=self.name,
+            description=self.description,
+            parameters=types.Schema(
+                type=types.Type.OBJECT,
+                properties={
+                    "path": types.Schema(
+                        type=types.Type.STRING,
+                        description=(
+                            "Directory to list in the sandbox. Optional; "
+                            "defaults to '.' (the current directory)."
+                        ),
+                    ),
+                },
+            ),
+        )
+
+    async def run_async(
+        self, *, args: dict[str, Any], tool_context: ToolContext
+    ) -> dict[str, Any]:
+        path: str = args.get("path") or "."
+
+        try:
+            sandbox = await self.manager.get()
+        except Exception as exc:  # noqa: BLE001 — never raise out of run_async
+            logger.debug("list_files: sandbox unavailable: %s", exc)
+            return failure_result(f"Sandbox unavailable: {exc}", path=path)
+
+        try:
+            async with self.manager.keep_alive(sandbox):
+                entries = await sandbox.files.list(path)
+        except Exception as exc:  # noqa: BLE001 — missing dir/SDK failure → success:false
+            logger.debug("list_files: could not list %s: %s", path, exc)
+            return failure_result(f"Failed to list directory: {exc}", path=path)
+
+        return success_result(
+            path=path,
+            entries=[
+                {"name": entry.name, "type": _normalize_type(entry.type)}
+                for entry in entries
+            ],
+        )