dothedev-sandbox 0.1.0__tar.gz

dothedev_sandbox-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+
+# Node
+node_modules/
+.next/
+out/
+*.tsbuildinfo
+next-env.d.ts
+
+# Env and local files
+.env
+.env.*
+!.env.example
+.DS_Store

dothedev_sandbox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shahraiz ali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dothedev_sandbox-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.5
+Name: dothedev-sandbox
+Version: 0.1.0
+Summary: Deep agents sandbox backend for DoTheDev Agent Platform sandboxes
+Author: shahraiz ali
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,deepagents,langchain,langgraph,sandbox
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: deepagents>=0.7.28
+Requires-Dist: httpx>=0.28.1
+Description-Content-Type: text/markdown
+
+# dothedev-sandbox
+
+A [deep agents](https://docs.langchain.com/oss/python/deepagents/sandboxes) sandbox backend for agents
+deployed on the DoTheDev Agent Platform. The platform runs each sandbox in a locked-down container (no
+secrets, no network unless the template allows it) and gives deployed agents `DOTHEDEV_SANDBOX_URL` and
+`DOTHEDEV_SANDBOX_TOKEN`. The token stays in the agent server; only commands and files reach the sandbox.
+
+```bash
+pip install dothedev-sandbox
+```
+
+```python
+from deepagents import create_deep_agent
+from dothedev_sandbox import ThreadSandbox
+
+# One sandbox per conversation, kept across turns
+agent = create_deep_agent(
+    model="openai:gpt-4o-mini",
+    backend=ThreadSandbox(),
+)
+```
+
+`ThreadSandbox` sends each command and file call to the sandbox of the run's `configurable.thread_id`,
+created on first use. Pass `template=` to pick one of the templates the platform offers.
+
+A sandbox shared by every thread instead:
+
+```python
+from dothedev_sandbox import SandboxClient
+
+shared = SandboxClient().get_or_create("shared:research")
+agent = create_deep_agent(model=..., backend=shared)
+```
+
+Locally, point it at a platform API and a deployment's token:
+
+```bash
+export DOTHEDEV_SANDBOX_URL=http://localhost:8100
+export DOTHEDEV_SANDBOX_TOKEN=sbx_...
+```
+
+## License
+
+MIT

dothedev_sandbox-0.1.0/README.md

@@ -0,0 +1,44 @@
+# dothedev-sandbox
+
+A [deep agents](https://docs.langchain.com/oss/python/deepagents/sandboxes) sandbox backend for agents
+deployed on the DoTheDev Agent Platform. The platform runs each sandbox in a locked-down container (no
+secrets, no network unless the template allows it) and gives deployed agents `DOTHEDEV_SANDBOX_URL` and
+`DOTHEDEV_SANDBOX_TOKEN`. The token stays in the agent server; only commands and files reach the sandbox.
+
+```bash
+pip install dothedev-sandbox
+```
+
+```python
+from deepagents import create_deep_agent
+from dothedev_sandbox import ThreadSandbox
+
+# One sandbox per conversation, kept across turns
+agent = create_deep_agent(
+    model="openai:gpt-4o-mini",
+    backend=ThreadSandbox(),
+)
+```
+
+`ThreadSandbox` sends each command and file call to the sandbox of the run's `configurable.thread_id`,
+created on first use. Pass `template=` to pick one of the templates the platform offers.
+
+A sandbox shared by every thread instead:
+
+```python
+from dothedev_sandbox import SandboxClient
+
+shared = SandboxClient().get_or_create("shared:research")
+agent = create_deep_agent(model=..., backend=shared)
+```
+
+Locally, point it at a platform API and a deployment's token:
+
+```bash
+export DOTHEDEV_SANDBOX_URL=http://localhost:8100
+export DOTHEDEV_SANDBOX_TOKEN=sbx_...
+```
+
+## License
+
+MIT

dothedev_sandbox-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "dothedev-sandbox"
+version = "0.1.0"
+description = "Deep agents sandbox backend for DoTheDev Agent Platform sandboxes"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "shahraiz ali" }]
+keywords = ["deepagents", "langgraph", "langchain", "sandbox", "agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "deepagents>=0.7.28",
+    "httpx>=0.28.1",
+]
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.40.1",
+    "black>=26.5.1",
+    "pytest>=9.1.1",
+    "ruff>=0.16.10",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dothedev_sandbox"]
+
+# Only these go into the published source archive
+[tool.hatch.build.targets.sdist]
+only-include = ["src/dothedev_sandbox", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.basedpyright]
+include = ["src", "tests"]
+pythonVersion = "3.11"
+venvPath = "."
+venv = ".venv"
+typeCheckingMode = "standard"
+
+[tool.black]
+line-length = 120
+target-version = ["py311"]

dothedev_sandbox-0.1.0/src/dothedev_sandbox/__init__.py

@@ -0,0 +1,5 @@
+"""Deep agents backend for DoTheDev Agent Platform sandboxes (docs/sandboxes.md in the platform repo)."""
+
+from dothedev_sandbox.client import DoTheDevSandbox, SandboxClient, SandboxError, ThreadSandbox, sandbox_for_thread
+
+__all__ = ["DoTheDevSandbox", "SandboxClient", "SandboxError", "ThreadSandbox", "sandbox_for_thread"]

dothedev_sandbox-0.1.0/src/dothedev_sandbox/client.py

@@ -0,0 +1,455 @@
+"""A deep agents sandbox backend that runs on the DoTheDev Agent Platform.
+
+The platform gives each deployed revision `DOTHEDEV_SANDBOX_URL` and `DOTHEDEV_SANDBOX_TOKEN`. The token
+stays in the agent server: commands and files go to the platform, which runs them in a locked-down
+container with no secrets and, by default, no network.
+
+    from deepagents import create_deep_agent
+    from dothedev_sandbox import ThreadSandbox
+
+    agent = create_deep_agent(model=..., backend=ThreadSandbox())
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import os
+import threading
+from collections import OrderedDict
+from typing import Any
+
+import httpx
+from deepagents.backends.protocol import ExecuteResponse, FileDownloadResponse, FileUploadResponse
+from deepagents.backends.sandbox import BaseSandbox
+
+# Files per upload or download request; the platform takes at most 100
+BATCH = 100
+# Added to a command's own time limit for the HTTP request carrying it
+SLACK_SECONDS = 30
+# Sandboxes `sandbox_for_thread` remembers per process
+CACHED_THREADS = 256
+
+
+class SandboxError(RuntimeError):
+    """The platform refused or failed a sandbox call.
+
+    Attributes:
+        status_code: The HTTP status the platform answered with.
+    """
+
+    def __init__(self, status_code: int, message: str) -> None:
+        super().__init__(f"Sandbox API {status_code}: {message}")
+        self.status_code = status_code
+
+
+def _detail(response: httpx.Response) -> str:
+    try:
+        detail = response.json().get("detail")
+    except ValueError:
+        detail = None
+    return str(detail or response.text or response.reason_phrase)
+
+
+def _checked(response: httpx.Response) -> dict[str, Any]:
+    if response.status_code >= 400:
+        raise SandboxError(response.status_code, _detail(response))
+    return response.json() if response.content else {}
+
+
+class SandboxClient:
+    """Talks to the platform's sandbox API as one deployment.
+
+    Args:
+        url: The platform API's base URL. Defaults to `DOTHEDEV_SANDBOX_URL`.
+        token: The deployment's sandbox token. Defaults to `DOTHEDEV_SANDBOX_TOKEN`.
+        default_timeout: Seconds a command may run when the caller gives no limit; None leaves it to the
+            platform's default.
+        transport: An httpx transport for the synchronous client (tests use a mock one).
+        async_transport: An httpx transport for the asynchronous client.
+
+    Raises:
+        ValueError: If no URL or token is given or set in the environment.
+    """
+
+    def __init__(
+        self,
+        url: str | None = None,
+        token: str | None = None,
+        *,
+        default_timeout: int | None = None,
+        transport: httpx.BaseTransport | None = None,
+        async_transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        url = url or os.environ.get("DOTHEDEV_SANDBOX_URL")
+        token = token or os.environ.get("DOTHEDEV_SANDBOX_TOKEN")
+        if not url or not token:
+            raise ValueError(
+                "Set DOTHEDEV_SANDBOX_URL and DOTHEDEV_SANDBOX_TOKEN (the platform sets both on deployed agents)"
+            )
+        self.base_url = f"{url.rstrip('/')}/sandbox/v1"
+        self.default_timeout = default_timeout
+        self._headers = {"authorization": f"Bearer {token}"}
+        self._transport = transport
+        self._async_transport = async_transport
+        self._http = httpx.Client(base_url=self.base_url, headers=self._headers, timeout=60, transport=transport)
+        self._async_http: httpx.AsyncClient | None = None
+
+    def _async(self) -> httpx.AsyncClient:
+        """The async client, made on first use; it belongs to the event loop that first used it."""
+        if self._async_http is None:
+            self._async_http = httpx.AsyncClient(
+                base_url=self.base_url, headers=self._headers, timeout=60, transport=self._async_transport
+            )
+        return self._async_http
+
+    def request(self, method: str, path: str, *, timeout: float | None = None, **kwargs: Any) -> dict[str, Any]:
+        """Send one request and return its JSON body.
+
+        Args:
+            method: The HTTP method.
+            path: The path under `/sandbox/v1`.
+            timeout: Seconds to wait for the answer; the client's default when None.
+            **kwargs: Passed on to httpx (`json`, `params`).
+
+        Returns:
+            The decoded JSON body; an empty dict for an empty one.
+
+        Raises:
+            SandboxError: If the platform answers with an error status.
+        """
+        options: dict[str, Any] = {"timeout": timeout} if timeout is not None else {}
+        return _checked(self._http.request(method, path, **options, **kwargs))
+
+    async def arequest(self, method: str, path: str, *, timeout: float | None = None, **kwargs: Any) -> dict[str, Any]:
+        """Async version of `request`.
+
+        Args:
+            method: The HTTP method.
+            path: The path under `/sandbox/v1`.
+            timeout: Seconds to wait for the answer; the client's default when None.
+            **kwargs: Passed on to httpx (`json`, `params`).
+
+        Returns:
+            The decoded JSON body; an empty dict for an empty one.
+
+        Raises:
+            SandboxError: If the platform answers with an error status.
+        """
+        options: dict[str, Any] = {"timeout": timeout} if timeout is not None else {}
+        return _checked(await self._async().request(method, path, **options, **kwargs))
+
+    def get_or_create(self, key: str, *, template: str | None = None, thread_id: str | None = None) -> DoTheDevSandbox:
+        """The deployment's sandbox with this key, created if new and running when this returns.
+
+        Args:
+            key: The agent's name for it, unique per deployment: `thread:<thread id>` for one per
+                conversation, anything else for a shared one.
+            template: A template the platform offers; its default when None.
+            thread_id: The thread it belongs to, so the console shows it on that thread.
+
+        Returns:
+            A deep agents backend for the sandbox.
+
+        Raises:
+            SandboxError: If the platform refuses (unknown template, org limit reached) or can't start it.
+        """
+        body = {"key": key, "template": template, "thread_id": thread_id}
+        info = self.request("POST", "/sandboxes", json=body)
+        return DoTheDevSandbox(self, info, template=template)
+
+    def close(self) -> None:
+        """Close the synchronous client's connections."""
+        self._http.close()
+
+    async def aclose(self) -> None:
+        """Close both clients' connections."""
+        self._http.close()
+        if self._async_http is not None:
+            await self._async_http.aclose()
+            self._async_http = None
+
+
+class DoTheDevSandbox(BaseSandbox):
+    """One platform sandbox as a deep agents backend.
+
+    Files, `ls`, `grep`, `glob` and edits come from `BaseSandbox`, built on `execute`. A sandbox the platform
+    removed (after its retention period, or by a member) is got again under the same key, empty, and the
+    call retried once.
+
+    Args:
+        client: The client to call the platform with.
+        info: The sandbox as the platform returned it.
+        template: The template it was asked for, used when it has to be got again.
+    """
+
+    def __init__(self, client: SandboxClient, info: dict[str, Any], *, template: str | None = None) -> None:
+        self._client = client
+        self._info = info
+        self._template = template
+
+    @property
+    def id(self) -> str:
+        """The platform's id for the sandbox."""
+        return str(self._info["id"])
+
+    @property
+    def key(self) -> str:
+        """The key the sandbox was got by."""
+        return str(self._info["key"])
+
+    def _renew(self) -> None:
+        body = {"key": self.key, "template": self._template, "thread_id": self._info.get("thread_id")}
+        self._info = self._client.request("POST", "/sandboxes", json=body)
+
+    async def _arenew(self) -> None:
+        body = {"key": self.key, "template": self._template, "thread_id": self._info.get("thread_id")}
+        self._info = await self._client.arequest("POST", "/sandboxes", json=body)
+
+    def _call(self, method: str, suffix: str, *, timeout: float | None = None, **kwargs: Any) -> dict[str, Any]:
+        try:
+            return self._client.request(method, f"/sandboxes/{self.id}{suffix}", timeout=timeout, **kwargs)
+        except SandboxError as error:
+            if error.status_code != 404:
+                raise
+            self._renew()
+            return self._client.request(method, f"/sandboxes/{self.id}{suffix}", timeout=timeout, **kwargs)
+
+    async def _acall(self, method: str, suffix: str, *, timeout: float | None = None, **kwargs: Any) -> dict[str, Any]:
+        try:
+            return await self._client.arequest(method, f"/sandboxes/{self.id}{suffix}", timeout=timeout, **kwargs)
+        except SandboxError as error:
+            if error.status_code != 404:
+                raise
+            await self._arenew()
+            return await self._client.arequest(method, f"/sandboxes/{self.id}{suffix}", timeout=timeout, **kwargs)
+
+    def _exec_request(self, command: str, timeout: int | None) -> tuple[dict[str, Any], float | None]:
+        limit = timeout if timeout is not None else self._client.default_timeout
+        body: dict[str, Any] = {"command": command}
+        if limit:
+            body["timeout"] = limit
+        # Without a limit the platform's default applies (at most 30 minutes): wait as long as it may
+        wait = (limit or 1800) + SLACK_SECONDS
+        return body, wait
+
+    @staticmethod
+    def _response(result: dict[str, Any]) -> ExecuteResponse:
+        output = str(result.get("output", ""))
+        # Deep agents notes truncation itself, from `truncated`; it has no field for a timeout
+        if result.get("timed_out"):
+            output += "\n[Command timed out and was stopped]"
+        return ExecuteResponse(
+            output=output, exit_code=result.get("exit_code"), truncated=bool(result.get("truncated"))
+        )
+
+    def execute(self, command: str, *, timeout: int | None = None) -> ExecuteResponse:
+        """Run a shell command in the sandbox's workspace (`/app`).
+
+        Args:
+            command: The shell command, run with `sh -c`.
+            timeout: Seconds before the command is stopped; the client's or platform's default when None.
+
+        Returns:
+            Combined stdout and stderr, the exit code, and whether output was cut.
+        """
+        body, wait = self._exec_request(command, timeout)
+        return self._response(self._call("POST", "/exec", json=body, timeout=wait))
+
+    async def aexecute(self, command: str, *, timeout: int | None = None) -> ExecuteResponse:  # noqa: ASYNC109
+        """Async version of `execute`, on the client's async connection pool.
+
+        Args:
+            command: The shell command, run with `sh -c`.
+            timeout: Seconds before the command is stopped; the client's or platform's default when None.
+
+        Returns:
+            Combined stdout and stderr, the exit code, and whether output was cut.
+        """
+        body, wait = self._exec_request(command, timeout)
+        return self._response(await self._acall("POST", "/exec", json=body, timeout=wait))
+
+    def upload_files(self, files: list[tuple[str, bytes]]) -> list[FileUploadResponse]:
+        """Write files into the sandbox, creating parent directories.
+
+        Args:
+            files: (absolute path, content) pairs.
+
+        Returns:
+            One response per file, in order; `error` is set for the ones that failed.
+        """
+        responses: list[FileUploadResponse] = []
+        for start in range(0, len(files), BATCH):
+            batch = files[start : start + BATCH]
+            body = {"files": [{"path": path, "content": base64.b64encode(content).decode()} for path, content in batch]}
+            try:
+                results = self._call("POST", "/files/upload", json=body)["results"]
+            except SandboxError as error:
+                responses += [FileUploadResponse(path=path, error=str(error)) for path, _ in batch]
+                continue
+            responses += [FileUploadResponse(path=item["path"], error=item["error"]) for item in results]
+        return responses
+
+    def download_files(self, paths: list[str]) -> list[FileDownloadResponse]:
+        """Read files from the sandbox.
+
+        Args:
+            paths: Absolute paths.
+
+        Returns:
+            One response per path, in order, with `content` or `error`.
+        """
+        responses: list[FileDownloadResponse] = []
+        for start in range(0, len(paths), BATCH):
+            batch = paths[start : start + BATCH]
+            try:
+                results = self._call("POST", "/files/download", json={"paths": batch})["results"]
+            except SandboxError as error:
+                responses += [FileDownloadResponse(path=path, content=None, error=str(error)) for path in batch]
+                continue
+            responses += [
+                FileDownloadResponse(
+                    path=item["path"],
+                    content=base64.b64decode(item["content"]) if item["content"] is not None else None,
+                    error=item["error"],
+                )
+                for item in results
+            ]
+        return responses
+
+    def destroy(self) -> None:
+        """Remove the sandbox and its files. The next call with its key gets a new, empty one."""
+        try:
+            self._client.request("DELETE", f"/sandboxes/{self.id}")
+        except SandboxError as error:
+            if error.status_code != 404:
+                raise
+
+
+_lock = threading.Lock()
+_client: SandboxClient | None = None
+_threads: OrderedDict[tuple[str, str | None], DoTheDevSandbox] = OrderedDict()
+
+
+def _shared_client() -> SandboxClient:
+    global _client
+    with _lock:
+        if _client is None:
+            _client = SandboxClient()
+        return _client
+
+
+def sandbox_for_thread(thread_id: str | None = None, *, template: str | None = None) -> DoTheDevSandbox:
+    """The current thread's sandbox: one per conversation, kept across turns.
+
+    `ThreadSandbox` calls this for each command; call it directly for a sandbox outside the agent loop.
+    The platform resumes a stopped sandbox on its next command, so a remembered one stays usable.
+
+    Args:
+        thread_id: The thread; read from the run's config (`configurable.thread_id`) when None.
+        template: A template the platform offers; its default when None.
+
+    Returns:
+        The thread's sandbox backend.
+
+    Raises:
+        ValueError: If there is no thread id (the agent must run on a thread).
+        SandboxError: If the platform refuses or can't start the sandbox.
+    """
+    if thread_id is None:
+        from langgraph.config import get_config
+
+        thread_id = get_config().get("configurable", {}).get("thread_id")
+    if not thread_id:
+        raise ValueError("No thread_id: run the agent on a thread to give it a sandbox")
+    cache_key = (str(thread_id), template)
+    with _lock:
+        cached = _threads.get(cache_key)
+        if cached is not None:
+            _threads.move_to_end(cache_key)
+            return cached
+    sandbox = _shared_client().get_or_create(f"thread:{thread_id}", template=template, thread_id=str(thread_id))
+    with _lock:
+        _threads[cache_key] = sandbox
+        while len(_threads) > CACHED_THREADS:
+            _threads.popitem(last=False)
+    return sandbox
+
+
+class ThreadSandbox(BaseSandbox):
+    """A deep agents backend that runs each call in the current thread's sandbox.
+
+    Deep agents 0.7 takes a backend instance, not a factory, so the agent is built once with this and every
+    command and file call is sent to `sandbox_for_thread()` for the run's `configurable.thread_id`: one
+    sandbox per conversation, got on its first call.
+
+        agent = create_deep_agent(model=..., backend=ThreadSandbox())
+
+    Args:
+        template: A template the platform offers; its default when None.
+    """
+
+    def __init__(self, *, template: str | None = None) -> None:
+        self._template = template
+
+    def _sandbox(self) -> DoTheDevSandbox:
+        return sandbox_for_thread(template=self._template)
+
+    @property
+    def id(self) -> str:
+        """The platform's id for the current thread's sandbox."""
+        return self._sandbox().id
+
+    def execute(self, command: str, *, timeout: int | None = None) -> ExecuteResponse:
+        """Run a shell command in the current thread's sandbox.
+
+        Args:
+            command: The shell command, run with `sh -c`.
+            timeout: Seconds before the command is stopped; the client's or platform's default when None.
+
+        Returns:
+            Combined stdout and stderr, the exit code, and whether output was cut.
+
+        Raises:
+            RuntimeError: If called outside a run, so there is no thread.
+        """
+        return self._sandbox().execute(command, timeout=timeout)
+
+    async def aexecute(self, command: str, *, timeout: int | None = None) -> ExecuteResponse:  # noqa: ASYNC109
+        """Async version of `execute`; the sandbox is got off the event loop.
+
+        Args:
+            command: The shell command, run with `sh -c`.
+            timeout: Seconds before the command is stopped; the client's or platform's default when None.
+
+        Returns:
+            Combined stdout and stderr, the exit code, and whether output was cut.
+
+        Raises:
+            RuntimeError: If called outside a run, so there is no thread.
+        """
+        # to_thread copies the run's context, so the thread id is still there
+        sandbox = await asyncio.to_thread(self._sandbox)
+        return await sandbox.aexecute(command, timeout=timeout)
+
+    def upload_files(self, files: list[tuple[str, bytes]]) -> list[FileUploadResponse]:
+        """Write files into the current thread's sandbox, creating parent directories.
+
+        Args:
+            files: (absolute path, content) pairs.
+
+        Returns:
+            One response per file, in order; `error` is set for the ones that failed.
+        """
+        return self._sandbox().upload_files(files)
+
+    def download_files(self, paths: list[str]) -> list[FileDownloadResponse]:
+        """Read files from the current thread's sandbox.
+
+        Args:
+            paths: Absolute paths.
+
+        Returns:
+            One response per path, in order, with `content` or `error`.
+        """
+        return self._sandbox().download_files(paths)

dothedev_sandbox-0.1.0/tests/test_client.py

@@ -0,0 +1,213 @@
+"""The backend against a fake sandbox API with the platform's request and response shapes."""
+
+import asyncio
+import base64
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+import pytest
+from deepagents import create_deep_agent
+from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
+from langchain_core.messages import AIMessage
+from langgraph.checkpoint.memory import InMemorySaver
+
+import dothedev_sandbox.client as module
+from dothedev_sandbox import SandboxClient, SandboxError, ThreadSandbox, sandbox_for_thread
+
+
+@dataclass
+class FakeApi:
+    token: str = "sbx_test"
+    sandboxes: dict[str, dict[str, Any]] = field(default_factory=dict)
+    files: dict[str, bytes] = field(default_factory=dict)
+    requests: list[httpx.Request] = field(default_factory=list)
+
+    def handle(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        if request.headers.get("authorization") != f"Bearer {self.token}":
+            return httpx.Response(401, json={"detail": "Send the token"})
+        path = request.url.path.removeprefix("/sandbox/v1")
+        body = json.loads(request.content) if request.content else {}
+        if path == "/sandboxes" and request.method == "POST":
+            if body["template"] == "missing":
+                return httpx.Response(422, json={"detail": "Unknown sandbox template"})
+            existing = next((item for item in self.sandboxes.values() if item["key"] == body["key"]), None)
+            if existing is None:
+                existing = {"id": f"sb-{len(self.sandboxes) + 1}", "key": body["key"], "thread_id": body["thread_id"]}
+                self.sandboxes[existing["id"]] = existing
+            return httpx.Response(200, json=existing)
+        parts = path.split("/")
+        if parts[2] not in self.sandboxes:
+            return httpx.Response(404, json={"detail": "Sandbox not found"})
+        action = "/".join(parts[3:])
+        if action == "exec":
+            command = body["command"]
+            if command == "slow":
+                return httpx.Response(200, json={"output": "", "exit_code": 124, "truncated": False, "timed_out": True})
+            if command == "loud":
+                return httpx.Response(
+                    200, json={"output": "y\ny", "exit_code": 0, "truncated": True, "timed_out": False}
+                )
+            return httpx.Response(
+                200, json={"output": f"ran {command}", "exit_code": 0, "truncated": False, "timed_out": False}
+            )
+        if action == "files/upload":
+            for item in body["files"]:
+                self.files[item["path"]] = base64.b64decode(item["content"])
+            return httpx.Response(
+                200, json={"results": [{"path": item["path"], "error": None} for item in body["files"]]}
+            )
+        if action == "files/download":
+            results = [
+                (
+                    {"path": path, "content": base64.b64encode(self.files[path]).decode(), "error": None}
+                    if path in self.files
+                    else {"path": path, "content": None, "error": "file_not_found"}
+                )
+                for path in body["paths"]
+            ]
+            return httpx.Response(200, json={"results": results})
+        if action == "" and request.method == "DELETE":
+            del self.sandboxes[parts[2]]
+            return httpx.Response(204)
+        return httpx.Response(405)
+
+
+@pytest.fixture
+def api() -> FakeApi:
+    return FakeApi()
+
+
+@pytest.fixture
+def client(api: FakeApi) -> SandboxClient:
+    return SandboxClient(
+        "http://platform.test/",
+        api.token,
+        transport=httpx.MockTransport(api.handle),
+        async_transport=httpx.MockTransport(api.handle),
+    )
+
+
+def test_needs_url_and_token(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("DOTHEDEV_SANDBOX_URL", raising=False)
+    monkeypatch.delenv("DOTHEDEV_SANDBOX_TOKEN", raising=False)
+    with pytest.raises(ValueError, match="DOTHEDEV_SANDBOX_URL"):
+        SandboxClient()
+
+
+def test_execute_and_errors(api: FakeApi, client: SandboxClient) -> None:
+    sandbox = client.get_or_create("thread:t1", thread_id="t1")
+    assert sandbox.id == "sb-1" and sandbox.key == "thread:t1"
+    result = sandbox.execute("ls", timeout=5)
+    assert (result.output, result.exit_code, result.truncated) == ("ran ls", 0, False)
+    assert json.loads(api.requests[-1].content) == {"command": "ls", "timeout": 5}
+    assert "timed out" in sandbox.execute("slow").output
+    # Deep agents adds its own truncation note from `truncated`; the output stays as the sandbox gave it
+    assert (sandbox.execute("loud").output, sandbox.execute("loud").truncated) == ("y\ny", True)
+    with pytest.raises(SandboxError) as error:
+        client.get_or_create("x", template="missing")
+    assert error.value.status_code == 422
+
+
+def test_a_removed_sandbox_is_got_again(api: FakeApi, client: SandboxClient) -> None:
+    sandbox = client.get_or_create("thread:t1", thread_id="t1")
+    api.sandboxes.clear()
+    assert sandbox.execute("ls").output == "ran ls"
+    assert sandbox.id == "sb-1" and list(api.sandboxes) == ["sb-1"]
+    assert api.sandboxes["sb-1"]["thread_id"] == "t1"
+
+
+def test_files_round_trip_in_batches(api: FakeApi, client: SandboxClient, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(module, "BATCH", 2)
+    sandbox = client.get_or_create("k")
+    files = [(f"/app/{index}.txt", f"file {index}".encode()) for index in range(5)]
+    assert [item.error for item in sandbox.upload_files(files)] == [None] * 5
+    uploads = [request for request in api.requests if request.url.path.endswith("/files/upload")]
+    assert len(uploads) == 3
+    downloaded = sandbox.download_files(["/app/0.txt", "/app/4.txt", "/nope"])
+    assert [(item.content, item.error) for item in downloaded] == [
+        (b"file 0", None),
+        (b"file 4", None),
+        (None, "file_not_found"),
+    ]
+
+
+def test_async_execute(client: SandboxClient) -> None:
+    async def main() -> str:
+        sandbox = client.get_or_create("k")
+        result = await sandbox.aexecute("pwd")
+        await client.aclose()
+        return result.output
+
+    assert asyncio.run(main()) == "ran pwd"
+
+
+def test_destroy_is_safe_to_repeat(api: FakeApi, client: SandboxClient) -> None:
+    sandbox = client.get_or_create("k")
+    sandbox.destroy()
+    sandbox.destroy()
+    assert api.sandboxes == {}
+
+
+def test_sandbox_for_thread_remembers_each_thread(
+    api: FakeApi, client: SandboxClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(module, "_client", client)
+    monkeypatch.setattr(module, "_threads", module.OrderedDict())
+    first = sandbox_for_thread("t1")
+    assert sandbox_for_thread("t1") is first
+    assert sandbox_for_thread("t2").id != first.id
+    creates = [request for request in api.requests if request.url.path == "/sandbox/v1/sandboxes"]
+    assert [json.loads(request.content)["key"] for request in creates] == ["thread:t1", "thread:t2"]
+    with pytest.raises(ValueError, match="thread"):
+        sandbox_for_thread("")
+
+
+class ScriptedModel(GenericFakeChatModel):
+    def bind_tools(self, tools: Any, **kwargs: Any) -> "ScriptedModel":
+        return self
+
+
+def _sqrt_agent() -> Any:
+    call = {"name": "execute", "id": "c1", "args": {"command": "python3 -c 'print(4 ** 0.5)'"}}
+    model = ScriptedModel(messages=iter([AIMessage(content="", tool_calls=[call]), AIMessage(content="2.0")] * 2))
+    return create_deep_agent(model=model, backend=ThreadSandbox(), checkpointer=InMemorySaver())
+
+
+def test_thread_sandbox_runs_each_threads_commands_in_its_own_sandbox(
+    api: FakeApi, client: SandboxClient, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(module, "_client", client)
+    monkeypatch.setattr(module, "_threads", module.OrderedDict())
+    # Deep agents 0.7 takes backend instances only; a factory fails when the agent is built
+    agent = _sqrt_agent()
+    for thread in ("t1", "t2"):
+        out = agent.invoke(
+            {"messages": [{"role": "user", "content": "sqrt 4"}]}, {"configurable": {"thread_id": thread}}
+        )
+        assert "ran python3" in out["messages"][2].content
+    execs = [request.url.path for request in api.requests if request.url.path.endswith("/exec")]
+    assert execs == ["/sandbox/v1/sandboxes/sb-1/exec", "/sandbox/v1/sandboxes/sb-2/exec"]
+    assert [item["key"] for item in api.sandboxes.values()] == ["thread:t1", "thread:t2"]
+
+
+def test_thread_sandbox_async(api: FakeApi, client: SandboxClient, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(module, "_client", client)
+    monkeypatch.setattr(module, "_threads", module.OrderedDict())
+
+    async def main() -> str:
+        out = await _sqrt_agent().ainvoke(
+            {"messages": [{"role": "user", "content": "sqrt 4"}]}, {"configurable": {"thread_id": "t1"}}
+        )
+        await client.aclose()
+        return str(out["messages"][2].content)
+
+    assert "ran python3" in asyncio.run(main())
+    assert [item["key"] for item in api.sandboxes.values()] == ["thread:t1"]
+
+
+def test_thread_sandbox_needs_a_thread() -> None:
+    with pytest.raises(RuntimeError):
+        ThreadSandbox().execute("ls")