dothedev-sandbox 0.1.0__py3-none-any.whl

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+dothedev_sandbox/__init__.py,sha256=DEaOOHTSrSWMp6mk33Qyns3n-6uoOlS2jpd1DGX-h50,326
+dothedev_sandbox/client.py,sha256=VnVCqZjuZgNnMZsO2bsH19atlCWgbF7NVCpOHc1Bs9o,18525
+dothedev_sandbox/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dothedev_sandbox-0.1.0.dist-info/METADATA,sha256=5mOrc_qycyWGjC7qT2HXJnb_5c6sZKXMzj_dz4AZu8U,2008
+dothedev_sandbox-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+dothedev_sandbox-0.1.0.dist-info/licenses/LICENSE,sha256=DuMG864ACkJ7EaVFmUYJu2AccXCv9np8worEmFFQ7bg,1069
+dothedev_sandbox-0.1.0.dist-info/RECORD,,

dothedev_sandbox-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

dothedev_sandbox-0.1.0.dist-info/licenses/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.