cocoonstack-sandbox-openai 0.1.0__tar.gz

cocoonstack_sandbox_openai-0.1.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: cocoonstack-sandbox-openai
+Version: 0.1.0
+Summary: OpenAI Agents SDK sandbox provider backed by cocoon microVMs
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: openai-agents>=0.17
+Requires-Dist: cocoonstack-sandbox>=0.1
+
+# cocoonstack-sandbox-openai
+
+OpenAI Agents SDK sandbox provider backed by cocoon microVMs: implements
+the SDK's `BaseSandboxClient`/`BaseSandboxSession` pair over the sync
+`cocoonstack-sandbox` SDK, bridged with `asyncio.to_thread`.
+
+```python
+from cocoonsandbox_openai import CocoonSandboxClient, CocoonSandboxClientOptions
+
+options = CocoonSandboxClientOptions(addr="10.0.0.5:7777", api_token="...")
+session = await CocoonSandboxClient().create(options=options)
+```
+
+One session is one claimed sandbox; `delete` releases it, `resume`
+reattaches from serialized state (id + token). Exec maps to streaming
+`run`, workspace persist/hydrate to tar pull/push, exposed ports to local
+port proxies. Requires Python >= 3.10 (the `openai-agents` floor).
+
+Full reference: https://cocoonstack.github.io/sandbox/openai-adapter

cocoonstack_sandbox_openai-0.1.0/README.md

@@ -0,0 +1,19 @@
+# cocoonstack-sandbox-openai
+
+OpenAI Agents SDK sandbox provider backed by cocoon microVMs: implements
+the SDK's `BaseSandboxClient`/`BaseSandboxSession` pair over the sync
+`cocoonstack-sandbox` SDK, bridged with `asyncio.to_thread`.
+
+```python
+from cocoonsandbox_openai import CocoonSandboxClient, CocoonSandboxClientOptions
+
+options = CocoonSandboxClientOptions(addr="10.0.0.5:7777", api_token="...")
+session = await CocoonSandboxClient().create(options=options)
+```
+
+One session is one claimed sandbox; `delete` releases it, `resume`
+reattaches from serialized state (id + token). Exec maps to streaming
+`run`, workspace persist/hydrate to tar pull/push, exposed ports to local
+port proxies. Requires Python >= 3.10 (the `openai-agents` floor).
+
+Full reference: https://cocoonstack.github.io/sandbox/openai-adapter

cocoonstack_sandbox_openai-0.1.0/cocoonsandbox_openai/__init__.py

@@ -0,0 +1,23 @@
+"""OpenAI Agents SDK sandbox provider for cocoon microVMs.
+
+    from agents.sandbox import SandboxRunConfig  # SDK side
+    from cocoonsandbox_openai import CocoonSandboxClient, CocoonSandboxClientOptions
+
+    client = CocoonSandboxClient()
+    session = await client.create(options=CocoonSandboxClientOptions(
+        addr="10.0.0.5:7777", api_token="...", template="ghcr.io/cocoonstack/sandbox/rt:24.04"))
+"""
+
+from .adapter import (
+    CocoonSandboxClient,
+    CocoonSandboxClientOptions,
+    CocoonSandboxSession,
+    CocoonSandboxSessionState,
+)
+
+__all__ = [
+    "CocoonSandboxClient",
+    "CocoonSandboxClientOptions",
+    "CocoonSandboxSession",
+    "CocoonSandboxSessionState",
+]

cocoonstack_sandbox_openai-0.1.0/cocoonsandbox_openai/adapter.py

@@ -0,0 +1,179 @@
+"""OpenAI Agents SDK sandbox provider backed by cocoon microVMs: implements
+the SDK's BaseSandboxClient/BaseSandboxSession pair on top of the sync
+cocoonsandbox SDK, bridged with asyncio.to_thread. One session is one
+claimed sandbox; delete releases it, resume reattaches by id + token."""
+
+from __future__ import annotations
+
+import asyncio
+import io
+import socket
+import uuid
+from pathlib import Path
+from typing import Literal
+
+from agents.sandbox.manifest import Manifest
+from agents.sandbox.session.base_sandbox_session import BaseSandboxSession
+from agents.sandbox.session.sandbox_client import BaseSandboxClient, BaseSandboxClientOptions
+from agents.sandbox.session.sandbox_session import SandboxSession
+from agents.sandbox.session.sandbox_session_state import SandboxSessionState
+from agents.sandbox.snapshot import SnapshotBase, SnapshotSpec, resolve_snapshot
+from agents.sandbox.types import ExecResult, ExposedPortEndpoint, User
+from cocoonsandbox import APIError, Client, Sandbox, SilkdError
+
+
+class CocoonSandboxClientOptions(BaseSandboxClientOptions):
+    """Connection settings for a sandboxd node (or cluster entry node)."""
+
+    type: Literal["cocoon"] = "cocoon"
+    addr: str = "127.0.0.1:7777"
+    api_token: str = ""
+    template: str = "rt:24.04"
+    net: str = ""
+    ttl_seconds: int = 0
+
+
+class CocoonSandboxSessionState(SandboxSessionState):
+    """Everything needed to reattach: the claim's id, token, and owner."""
+
+    type: Literal["cocoon"] = "cocoon"
+    addr: str = ""
+    api_token: str = ""
+    sandbox_id: str = ""
+    sandbox_token: str = ""
+    owner: str = ""
+
+
+class CocoonSandboxSession(BaseSandboxSession):
+    """One claimed microVM behind the Agents SDK session surface."""
+
+    state: CocoonSandboxSessionState
+
+    def __init__(self, *, state: CocoonSandboxSessionState) -> None:
+        self.state = state
+        self._proxies: list[socket.socket] = []
+
+    @classmethod
+    def from_state(cls, state: CocoonSandboxSessionState) -> CocoonSandboxSession:
+        return cls(state=state)
+
+    async def _prepare_backend_workspace(self) -> None:
+        sb = self._sandbox()
+        await asyncio.to_thread(sb.mkdir, str(self.state.manifest.root), True)
+
+    async def _exec_internal(self, *command: str | Path, timeout: float | None = None) -> ExecResult:
+        # Bound the blocking SDK call by the socket timeout too, so a
+        # wait_for cancellation is matched by the worker thread actually
+        # unblocking (recv wakes) instead of lingering.
+        sb = self._sandbox(timeout=timeout)
+        argv = [str(part) for part in command]
+        stdout, stderr = bytearray(), bytearray()
+
+        def run() -> int:
+            return sb.run(argv, on_stdout=stdout.extend, on_stderr=stderr.extend)
+
+        code = await asyncio.wait_for(asyncio.to_thread(run), timeout=timeout)
+        return ExecResult(stdout=bytes(stdout), stderr=bytes(stderr), exit_code=code)
+
+    async def read(self, path: Path, *, user: str | User | None = None) -> io.IOBase:
+        sb = self._sandbox()
+        try:
+            data = await asyncio.to_thread(sb.read_file, str(self._abs(path)))
+        except SilkdError as exc:
+            if exc.kind == "not_found":
+                raise FileNotFoundError(str(path)) from exc
+            raise
+        return io.BytesIO(data)
+
+    async def write(self, path: Path, data: io.IOBase, *, user: str | User | None = None) -> None:
+        sb = self._sandbox()
+        payload = data.read()
+        await asyncio.to_thread(sb.write_file, str(self._abs(path)), payload)
+
+    async def running(self) -> bool:
+        try:
+            await asyncio.to_thread(self._sandbox().stat, "/")
+        except (APIError, SilkdError, OSError):
+            return False
+        return True
+
+    async def persist_workspace(self) -> io.IOBase:
+        sb = self._sandbox()
+        tar = await asyncio.to_thread(sb.pull, str(self.state.manifest.root))
+        return io.BytesIO(tar)
+
+    async def hydrate_workspace(self, data: io.IOBase) -> None:
+        sb = self._sandbox()
+        await asyncio.to_thread(sb.push, str(self.state.manifest.root), data.read())
+
+    async def _resolve_exposed_port(self, port: int) -> ExposedPortEndpoint:
+        sb = self._sandbox()
+        listener = await asyncio.to_thread(sb.proxy_port, "127.0.0.1:0", port)
+        self._proxies.append(listener)
+        return ExposedPortEndpoint(host="127.0.0.1", port=listener.getsockname()[1], tls=False)
+
+    async def _shutdown_backend(self) -> None:
+        # The sandbox itself outlives shutdown (delete releases it); only the
+        # local port proxies belong to this process.
+        for listener in self._proxies:
+            listener.close()
+        self._proxies.clear()
+
+    def _sandbox(self, timeout: float | None = None) -> Sandbox:
+        s = self.state
+        client = Client(s.addr, api_token=s.api_token, timeout=timeout or 120.0)
+        return Sandbox(client=client, id=s.sandbox_id, token=s.sandbox_token, owner=s.owner or s.addr)
+
+    def _abs(self, path: Path | str) -> Path:
+        # The SDK hands paths as str or Path; a relative one roots at the
+        # manifest workspace.
+        path = Path(path)
+        if path.is_absolute():
+            return path
+        return Path(self.state.manifest.root) / path
+
+
+class CocoonSandboxClient(BaseSandboxClient[CocoonSandboxClientOptions]):
+    """Claims a sandbox per session; delete releases, resume reattaches."""
+
+    async def create(
+        self,
+        *,
+        snapshot: SnapshotSpec | SnapshotBase | None = None,
+        manifest: Manifest | None = None,
+        options: CocoonSandboxClientOptions,
+    ) -> SandboxSession:
+        client = Client(options.addr, api_token=options.api_token)
+        sb = await asyncio.to_thread(
+            client.new, options.template, net=options.net, ttl_seconds=options.ttl_seconds
+        )
+        if manifest is None:
+            manifest = Manifest(root="/workspace")
+        session_id = uuid.uuid4()
+        state = CocoonSandboxSessionState(
+            session_id=session_id,
+            manifest=manifest,
+            snapshot=resolve_snapshot(snapshot, str(session_id)),
+            addr=options.addr,
+            api_token=options.api_token,
+            sandbox_id=sb.id,
+            sandbox_token=sb.token,
+            owner=sb.owner,
+        )
+        return self._wrap_session(CocoonSandboxSession.from_state(state))
+
+    async def delete(self, session: SandboxSession) -> SandboxSession:
+        inner = session._inner
+        if not isinstance(inner, CocoonSandboxSession):
+            raise TypeError("CocoonSandboxClient.delete expects a CocoonSandboxSession")
+        await inner._shutdown_backend()  # close any local port proxies
+        await asyncio.to_thread(inner._sandbox().close)  # 404-safe in the SDK
+        return session
+
+    async def resume(self, state: SandboxSessionState) -> SandboxSession:
+        if not isinstance(state, CocoonSandboxSessionState):
+            raise TypeError("CocoonSandboxClient.resume expects a CocoonSandboxSessionState")
+        return self._wrap_session(CocoonSandboxSession.from_state(state))
+
+    def deserialize_session_state(self, payload: dict[str, object]) -> SandboxSessionState:
+        return CocoonSandboxSessionState.model_validate(payload)

cocoonstack_sandbox_openai-0.1.0/cocoonstack_sandbox_openai.egg-info/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: cocoonstack-sandbox-openai
+Version: 0.1.0
+Summary: OpenAI Agents SDK sandbox provider backed by cocoon microVMs
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: openai-agents>=0.17
+Requires-Dist: cocoonstack-sandbox>=0.1
+
+# cocoonstack-sandbox-openai
+
+OpenAI Agents SDK sandbox provider backed by cocoon microVMs: implements
+the SDK's `BaseSandboxClient`/`BaseSandboxSession` pair over the sync
+`cocoonstack-sandbox` SDK, bridged with `asyncio.to_thread`.
+
+```python
+from cocoonsandbox_openai import CocoonSandboxClient, CocoonSandboxClientOptions
+
+options = CocoonSandboxClientOptions(addr="10.0.0.5:7777", api_token="...")
+session = await CocoonSandboxClient().create(options=options)
+```
+
+One session is one claimed sandbox; `delete` releases it, `resume`
+reattaches from serialized state (id + token). Exec maps to streaming
+`run`, workspace persist/hydrate to tar pull/push, exposed ports to local
+port proxies. Requires Python >= 3.10 (the `openai-agents` floor).
+
+Full reference: https://cocoonstack.github.io/sandbox/openai-adapter

cocoonstack_sandbox_openai-0.1.0/cocoonstack_sandbox_openai.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+cocoonsandbox_openai/__init__.py
+cocoonsandbox_openai/adapter.py
+cocoonstack_sandbox_openai.egg-info/PKG-INFO
+cocoonstack_sandbox_openai.egg-info/SOURCES.txt
+cocoonstack_sandbox_openai.egg-info/dependency_links.txt
+cocoonstack_sandbox_openai.egg-info/requires.txt
+cocoonstack_sandbox_openai.egg-info/top_level.txt
+tests/test_adapter.py

cocoonstack_sandbox_openai-0.1.0/cocoonstack_sandbox_openai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cocoonstack_sandbox_openai-0.1.0/cocoonstack_sandbox_openai.egg-info/requires.txt

@@ -0,0 +1,2 @@
+openai-agents>=0.17
+cocoonstack-sandbox>=0.1

cocoonstack_sandbox_openai-0.1.0/cocoonstack_sandbox_openai.egg-info/top_level.txt

@@ -0,0 +1 @@
+cocoonsandbox_openai

cocoonstack_sandbox_openai-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cocoonstack-sandbox-openai"
+version = "0.1.0"
+description = "OpenAI Agents SDK sandbox provider backed by cocoon microVMs"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+readme = "README.md"
+dependencies = ["openai-agents>=0.17", "cocoonstack-sandbox>=0.1"]
+
+[tool.setuptools.packages.find]
+include = ["cocoonsandbox_openai*"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]

cocoonstack_sandbox_openai-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cocoonstack_sandbox_openai-0.1.0/tests/test_adapter.py

@@ -0,0 +1,136 @@
+"""Adapter unit tests: exercise the BaseSandboxSession hooks against an
+in-process fake sandboxd (control plane over http.server, data plane over
+the SDK's own conn). No real VM — this binds the adapter's mapping onto the
+cocoonsandbox surface, not cocoon itself."""
+
+import asyncio
+import io
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+
+import pytest
+from cocoonsandbox import SilkdError
+
+from cocoonsandbox_openai import CocoonSandboxClient, CocoonSandboxClientOptions, CocoonSandboxSessionState
+
+
+class FakeNode(BaseHTTPRequestHandler):
+    def do_POST(self):
+        length = int(self.headers.get("Content-Length") or 0)
+        _ = self.rfile.read(length)
+        if self.path == "/v1/claim":
+            self._reply(200, {"id": "sb_1", "token": "tok", "owner_addr": self.headers["Host"]})
+        elif self.path.endswith("/release"):
+            self._reply(204, None)
+        else:
+            self._reply(404, {"error": "no route"})
+
+    def _reply(self, code, payload):
+        self.send_response(code)
+        if payload is not None:
+            raw = json.dumps(payload).encode()
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(raw)))
+            self.end_headers()
+            self.wfile.write(raw)
+        else:
+            self.end_headers()
+
+    def log_message(self, *args):
+        pass
+
+
+@pytest.fixture
+def node():
+    server = HTTPServer(("127.0.0.1", 0), FakeNode)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    yield f"127.0.0.1:{server.server_port}"
+    server.shutdown()
+
+
+def test_create_claims_and_state_round_trips(node):
+    async def go():
+        client = CocoonSandboxClient()
+        session = await client.create(options=CocoonSandboxClientOptions(addr=node, template="rt:24.04"))
+        inner = session._inner
+        assert inner.state.sandbox_id == "sb_1" and inner.state.sandbox_token == "tok"
+
+        # serialize → deserialize must reattach to the same claim.
+        payload = client.serialize_session_state(inner.state)
+        restored = client.deserialize_session_state(payload)
+        assert isinstance(restored, CocoonSandboxSessionState)
+        assert restored.sandbox_id == "sb_1" and restored.owner == node
+
+        await client.delete(session)
+
+    asyncio.run(go())
+
+
+def test_exec_maps_stdio_and_exit(node, monkeypatch):
+
+    class FakeSandbox:
+        def __init__(self, **kw):
+            self.id = "sb_1"
+
+        def run(self, argv, on_stdout=None, on_stderr=None):
+            assert argv == ["echo", "hi"]
+            on_stdout(b"hi\n")
+            return 0
+
+    async def go():
+        client = CocoonSandboxClient()
+        session = await client.create(options=CocoonSandboxClientOptions(addr=node))
+        inner = session._inner
+        monkeypatch.setattr(inner, "_sandbox", lambda timeout=None: FakeSandbox())
+        result = await inner._exec_internal("echo", "hi")
+        assert result.exit_code == 0 and result.stdout == b"hi\n"
+        assert result.ok()
+
+    asyncio.run(go())
+
+
+def test_read_missing_maps_to_filenotfound(node, monkeypatch):
+    class FakeSandbox:
+        def read_file(self, path):
+            raise SilkdError("not_found", path)
+
+    async def go():
+        client = CocoonSandboxClient()
+        session = await client.create(options=CocoonSandboxClientOptions(addr=node))
+        inner = session._inner
+        monkeypatch.setattr(inner, "_sandbox", lambda timeout=None: FakeSandbox())
+        with pytest.raises(FileNotFoundError):
+            await inner.read(Path("/nope"))
+
+    asyncio.run(go())
+
+
+def test_write_and_persist_use_tree_verbs(node, monkeypatch):
+    calls = {}
+
+    class FakeSandbox:
+        def write_file(self, path, data):
+            calls["write"] = (path, data)
+
+        def pull(self, path):
+            calls["pull"] = path
+            return b"tar-bytes"
+
+        def push(self, dest, data):
+            calls["push"] = (dest, data)
+
+    async def go():
+        client = CocoonSandboxClient()
+        session = await client.create(options=CocoonSandboxClientOptions(addr=node))
+        inner = session._inner
+        monkeypatch.setattr(inner, "_sandbox", lambda timeout=None: FakeSandbox())
+        await inner.write(Path("/workspace/a.txt"), io.BytesIO(b"body"))
+        assert calls["write"] == ("/workspace/a.txt", b"body")
+        tar = await inner.persist_workspace()
+        assert tar.read() == b"tar-bytes" and calls["pull"] == "/workspace"
+        await inner.hydrate_workspace(io.BytesIO(b"tar-in"))
+        assert calls["push"] == ("/workspace", b"tar-in")
+
+    asyncio.run(go())