openai-agents-msb 0.1.0__tar.gz

openai_agents_msb-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# dependencies (bun install)
+node_modules
+
+# output
+out
+dist
+*.tgz
+
+# code coverage
+coverage
+*.lcov
+
+# logs
+logs
+_.log
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# caches
+.eslintcache
+.cache
+*.tsbuildinfo
+
+# IntelliJ based IDEs
+.idea
+
+# Finder (MacOS) folder config
+.DS_Store
+design.txt
+.pnpm-store
+examples/law-firm/.sandbox-session
+
+# python
+.venv
+__pycache__
+*.py[cod]
+*.egg-info
+.pytest_cache
+.mypy_cache
+.ruff_cache
+uv.lock

openai_agents_msb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iyifr
+
+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.

openai_agents_msb-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.5
+Name: openai-agents-msb
+Version: 0.1.0
+Summary: Drop-in run() replacement and sandbox tools that give openai-agents agents an isolated microsandbox workspace.
+Project-URL: Homepage, https://github.com/iyifr/model-sandbox-tools#readme
+Project-URL: Repository, https://github.com/iyifr/model-sandbox-tools
+Project-URL: Issues, https://github.com/iyifr/model-sandbox-tools/issues
+Author: iyifr
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,code-interpreter,llm,microsandbox,openai-agents,sandbox,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: microsandbox<0.8,>=0.7.6
+Requires-Dist: openai-agents<0.24,>=0.23
+Description-Content-Type: text/markdown
+
+# openai-agents-msb
+
+**Give [OpenAI Agents](https://github.com/openai/openai-agents-python) an isolated [microsandbox](https://github.com/superradcompany/microsandbox) VM to run code and edit files in.**
+
+- **Drop-in `run()`**: Same arguments as `Runner.run()`. Swap the call, keep your agent.
+- **Files in, files out**: Seed `/workspace`, get every new or changed file back after the run.
+- **Lazy VMs**: The sandbox boots on the first tool call. Chat-only turns cost nothing.
+- **Locked-down network**: No network by default; allow the public internet or specific hosts.
+- **Secrets that stay out**: Code in the VM sees a placeholder, never the real key.
+- **Persistent sessions**: Keep one VM per conversation across turns.
+
+## Getting Started
+
+```sh
+pip install openai-agents-msb
+```
+
+> **Requirements**: Python 3.10+ on macOS (Apple Silicon), Linux (KVM) or Windows (WHP).
+
+```python
+import asyncio
+from pathlib import Path
+
+from agents import Agent
+from openai_agents_msb import (
+    InputFile,
+    WorkspaceContext,
+    run,
+    sandbox_config,
+    sandbox_exec,
+    sandbox_read_file,
+    sandbox_write_file,
+)
+
+agent = Agent(
+    name="doc-agent",
+    instructions="Files are in /workspace. Use the sandbox tools.",
+    tools=[
+        sandbox_config(image="python:3.12-slim", interpreter="python3"),
+        sandbox_exec(),
+        sandbox_read_file(),
+        sandbox_write_file(),
+    ],
+)
+
+
+async def main() -> None:
+    await run(
+        agent,
+        "Summarize data.xlsx as a PDF",
+        WorkspaceContext(
+            input_files=[InputFile("data.xlsx", Path("data.xlsx").read_bytes())],
+            on_file_output=lambda f: Path("out", f.file_name).write_bytes(f.data or b""),
+        ),
+    )
+
+
+asyncio.run(main())
+```
+
+`run()` takes the workspace as an optional third positional argument; everything else is passed
+through to `Runner.run()` unchanged. `run_sync()` mirrors `Runner.run_sync()`.
+
+## Tools
+
+| Tool | Does |
+|---|---|
+| `sandbox_config(**options)` | Runs a script; configures the sandbox |
+| `sandbox_exec(timeout_secs=600, max_output_bytes=32768)` | Runs a shell command |
+| `sandbox_read_file()` | Reads a text file |
+| `sandbox_write_file()` | Writes a text file |
+| `sandbox_list_files()` | Lists a directory |
+
+The model sees these as `sandbox_run`, `sandbox_exec`, `sandbox_read_file`, `sandbox_write_file`
+and `sandbox_list_files`.
+
+<details>
+<summary><em>All <code>sandbox_config</code> options →</em></summary>
+
+```python
+sandbox_config(
+    image="python:3.12-slim",
+    interpreter="python3",
+    network="public",                  # see Network
+    packages=["python-docx"],          # pip install on start
+    timeout_secs=120,                  # per script, default 30
+    max_output_bytes=32768,            # stdout/stderr sent to the model
+    memory=512,                        # MiB
+    cpus=1,
+    persist=True,                      # see Sessions
+    secrets=[SandboxSecret(env="API_KEY", value=key, host="api.example.com")],
+    env={"TZ": "UTC"},
+    create_kwargs={},                  # merged into microsandbox Sandbox.create()
+)
+```
+
+Handoffs and `agent.as_tool()` agents share the run's sandbox. Tools with no `sandbox_config()`
+anywhere use `python:3.12-slim`.
+
+</details>
+
+## Files
+
+`on_file_output` fires for each new or changed file after the run. `file_name` is relative to
+`/workspace`; `path` is valid during the callback; `data` is `None` for files of 2 GiB or more.
+Both callbacks may be sync or async.
+
+```python
+WorkspaceContext(
+    input_files=[InputFile("brief.docx", data), Path("contract.pdf")],
+    on_file_output=lambda f: shutil.copy(f.path, f.file_name),
+    on_workspace_snapshot=lambda paths: print(paths),
+)
+```
+
+## Streaming
+
+```python
+result = run_streamed(agent, "Draft a brief", WorkspaceContext(on_file_output=save))
+async for event in result.stream_events():
+    ...
+# outputs delivered and the VM stopped once the stream ends
+```
+
+Teardown runs when the stream finishes, including when you break out early or the run is
+cancelled. If you don't want the events, `await result.wait_completed()` instead.
+
+## Network
+
+```python
+sandbox_config(..., network="none")      # default
+sandbox_config(..., network="public")    # internet, not LAN or cloud metadata
+sandbox_config(..., network=Allow(["api.example.com", "*.github.com", "10.0.0.0/8"]))
+```
+
+`secrets` hosts and PyPI (for `packages`) are allowed automatically. A host that echoes request
+headers back can leak a secret's real value, so only scope secrets to APIs you trust. Pass a
+`microsandbox.Network` to bypass the shorthand entirely.
+
+## Sessions
+
+Set `persist=True` on `sandbox_config()` and pass a `sandbox_name` to keep one VM per conversation.
+
+```python
+await run(agent, "Draft it", WorkspaceContext(sandbox_name="case-42", input_files=files))
+await run(agent, "Now shorten it", WorkspaceContext(sandbox_name="case-42", skip_input_seed=True))
+
+await end_session("case-42")   # delete the VM and its files
+await list_sessions()          # [SessionInfo(name, workspace_dir, sandbox, last_used)]
+```
+
+A follow-up on a deleted session raises `SessionNotFoundError`. Runs on the same session are
+queued. Session workspaces live under `~/.mst/workspaces` unless you set `workspace_root`.
+
+## License
+
+MIT

openai_agents_msb-0.1.0/README.md

@@ -0,0 +1,157 @@
+# openai-agents-msb
+
+**Give [OpenAI Agents](https://github.com/openai/openai-agents-python) an isolated [microsandbox](https://github.com/superradcompany/microsandbox) VM to run code and edit files in.**
+
+- **Drop-in `run()`**: Same arguments as `Runner.run()`. Swap the call, keep your agent.
+- **Files in, files out**: Seed `/workspace`, get every new or changed file back after the run.
+- **Lazy VMs**: The sandbox boots on the first tool call. Chat-only turns cost nothing.
+- **Locked-down network**: No network by default; allow the public internet or specific hosts.
+- **Secrets that stay out**: Code in the VM sees a placeholder, never the real key.
+- **Persistent sessions**: Keep one VM per conversation across turns.
+
+## Getting Started
+
+```sh
+pip install openai-agents-msb
+```
+
+> **Requirements**: Python 3.10+ on macOS (Apple Silicon), Linux (KVM) or Windows (WHP).
+
+```python
+import asyncio
+from pathlib import Path
+
+from agents import Agent
+from openai_agents_msb import (
+    InputFile,
+    WorkspaceContext,
+    run,
+    sandbox_config,
+    sandbox_exec,
+    sandbox_read_file,
+    sandbox_write_file,
+)
+
+agent = Agent(
+    name="doc-agent",
+    instructions="Files are in /workspace. Use the sandbox tools.",
+    tools=[
+        sandbox_config(image="python:3.12-slim", interpreter="python3"),
+        sandbox_exec(),
+        sandbox_read_file(),
+        sandbox_write_file(),
+    ],
+)
+
+
+async def main() -> None:
+    await run(
+        agent,
+        "Summarize data.xlsx as a PDF",
+        WorkspaceContext(
+            input_files=[InputFile("data.xlsx", Path("data.xlsx").read_bytes())],
+            on_file_output=lambda f: Path("out", f.file_name).write_bytes(f.data or b""),
+        ),
+    )
+
+
+asyncio.run(main())
+```
+
+`run()` takes the workspace as an optional third positional argument; everything else is passed
+through to `Runner.run()` unchanged. `run_sync()` mirrors `Runner.run_sync()`.
+
+## Tools
+
+| Tool | Does |
+|---|---|
+| `sandbox_config(**options)` | Runs a script; configures the sandbox |
+| `sandbox_exec(timeout_secs=600, max_output_bytes=32768)` | Runs a shell command |
+| `sandbox_read_file()` | Reads a text file |
+| `sandbox_write_file()` | Writes a text file |
+| `sandbox_list_files()` | Lists a directory |
+
+The model sees these as `sandbox_run`, `sandbox_exec`, `sandbox_read_file`, `sandbox_write_file`
+and `sandbox_list_files`.
+
+<details>
+<summary><em>All <code>sandbox_config</code> options →</em></summary>
+
+```python
+sandbox_config(
+    image="python:3.12-slim",
+    interpreter="python3",
+    network="public",                  # see Network
+    packages=["python-docx"],          # pip install on start
+    timeout_secs=120,                  # per script, default 30
+    max_output_bytes=32768,            # stdout/stderr sent to the model
+    memory=512,                        # MiB
+    cpus=1,
+    persist=True,                      # see Sessions
+    secrets=[SandboxSecret(env="API_KEY", value=key, host="api.example.com")],
+    env={"TZ": "UTC"},
+    create_kwargs={},                  # merged into microsandbox Sandbox.create()
+)
+```
+
+Handoffs and `agent.as_tool()` agents share the run's sandbox. Tools with no `sandbox_config()`
+anywhere use `python:3.12-slim`.
+
+</details>
+
+## Files
+
+`on_file_output` fires for each new or changed file after the run. `file_name` is relative to
+`/workspace`; `path` is valid during the callback; `data` is `None` for files of 2 GiB or more.
+Both callbacks may be sync or async.
+
+```python
+WorkspaceContext(
+    input_files=[InputFile("brief.docx", data), Path("contract.pdf")],
+    on_file_output=lambda f: shutil.copy(f.path, f.file_name),
+    on_workspace_snapshot=lambda paths: print(paths),
+)
+```
+
+## Streaming
+
+```python
+result = run_streamed(agent, "Draft a brief", WorkspaceContext(on_file_output=save))
+async for event in result.stream_events():
+    ...
+# outputs delivered and the VM stopped once the stream ends
+```
+
+Teardown runs when the stream finishes, including when you break out early or the run is
+cancelled. If you don't want the events, `await result.wait_completed()` instead.
+
+## Network
+
+```python
+sandbox_config(..., network="none")      # default
+sandbox_config(..., network="public")    # internet, not LAN or cloud metadata
+sandbox_config(..., network=Allow(["api.example.com", "*.github.com", "10.0.0.0/8"]))
+```
+
+`secrets` hosts and PyPI (for `packages`) are allowed automatically. A host that echoes request
+headers back can leak a secret's real value, so only scope secrets to APIs you trust. Pass a
+`microsandbox.Network` to bypass the shorthand entirely.
+
+## Sessions
+
+Set `persist=True` on `sandbox_config()` and pass a `sandbox_name` to keep one VM per conversation.
+
+```python
+await run(agent, "Draft it", WorkspaceContext(sandbox_name="case-42", input_files=files))
+await run(agent, "Now shorten it", WorkspaceContext(sandbox_name="case-42", skip_input_seed=True))
+
+await end_session("case-42")   # delete the VM and its files
+await list_sessions()          # [SessionInfo(name, workspace_dir, sandbox, last_used)]
+```
+
+A follow-up on a deleted session raises `SessionNotFoundError`. Runs on the same session are
+queued. Session workspaces live under `~/.mst/workspaces` unless you set `workspace_root`.
+
+## License
+
+MIT

openai_agents_msb-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openai-agents-msb"
+version = "0.1.0"
+description = "Drop-in run() replacement and sandbox tools that give openai-agents agents an isolated microsandbox workspace."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "iyifr" }]
+keywords = [
+    "openai-agents",
+    "microsandbox",
+    "sandbox",
+    "ai-agents",
+    "llm",
+    "tools",
+    "code-interpreter",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "microsandbox>=0.7.6,<0.8",
+    "openai-agents>=0.23,<0.24",
+]
+
+[project.urls]
+Homepage = "https://github.com/iyifr/model-sandbox-tools#readme"
+Repository = "https://github.com/iyifr/model-sandbox-tools"
+Issues = "https://github.com/iyifr/model-sandbox-tools/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "pytest-timeout>=2.3",
+    "mypy>=1.13",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openai_agents_msb"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+# A wedged sandbox should fail the suite, not hang it. VM tests override this.
+timeout = 60
+markers = [
+    "vm: needs a real microsandbox VM on this host",
+    "network: needs outbound network access from the VM",
+    "llm: needs a real model; set MST_LLM_BASE_URL to enable",
+]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src", "tests"]
+# microsandbox ships py.typed but its native stubs are partial in places.
+warn_unused_ignores = false
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]

openai_agents_msb-0.1.0/src/openai_agents_msb/__init__.py

@@ -0,0 +1,50 @@
+"""Give openai-agents agents an isolated microsandbox VM to run code and edit files in."""
+
+from __future__ import annotations
+
+from ._run import MstRunResultStreaming, run, run_streamed, run_sync
+from ._session import SessionInfo, end_session, list_sessions
+from .core import (
+    Allow,
+    FileOutput,
+    InputFile,
+    SandboxConfig,
+    SandboxSecret,
+    SandboxSetupError,
+    SandboxVolumeMount,
+    SessionNotFoundError,
+    WorkspaceContext,
+)
+from .tools import (
+    sandbox_config,
+    sandbox_exec,
+    sandbox_list_files,
+    sandbox_read_file,
+    sandbox_write_file,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Allow",
+    "FileOutput",
+    "InputFile",
+    "MstRunResultStreaming",
+    "SandboxConfig",
+    "SandboxSecret",
+    "SandboxSetupError",
+    "SandboxVolumeMount",
+    "SessionInfo",
+    "SessionNotFoundError",
+    "WorkspaceContext",
+    "end_session",
+    "list_sessions",
+    "run",
+    "run_streamed",
+    "run_sync",
+    "sandbox_config",
+    "sandbox_exec",
+    "sandbox_list_files",
+    "sandbox_read_file",
+    "sandbox_write_file",
+]

openai_agents_msb-0.1.0/src/openai_agents_msb/_discover.py

@@ -0,0 +1,85 @@
+"""Finding the sandbox config an agent graph asks for."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from agents import Agent
+
+from .core import SandboxConfig
+
+__all__ = [
+    "DEFAULT_SANDBOX_CONFIG",
+    "MST_SANDBOX_CONFIG_ATTR",
+    "MST_TOOL_ATTR",
+    "DiscoveredSandbox",
+    "config_key",
+    "discover_sandbox_config",
+]
+
+# Markers that `sandbox_config()` and the other tools set on their FunctionTool,
+# so run() can recognise MST tools on an arbitrary agent.
+MST_TOOL_ATTR = "__mst_tool__"
+MST_SANDBOX_CONFIG_ATTR = "__mst_sandbox_config__"
+
+DEFAULT_SANDBOX_CONFIG = SandboxConfig(image="python:3.12-slim", interpreter="python3")
+"""Used when an agent has sandbox tools but no `sandbox_config()` to configure them."""
+
+
+def config_key(c: SandboxConfig) -> tuple[Any, ...]:
+    """The parts of a config that force a separate VM."""
+    return (
+        c.image,
+        c.interpreter,
+        c.cpus or 1,
+        c.memory or 256,
+        repr(c.network),
+        tuple(sorted(c.packages)),
+    )
+
+
+@dataclass(frozen=True)
+class DiscoveredSandbox:
+    config: SandboxConfig | None
+    """Config from `sandbox_config()` tools; None if none were found."""
+    has_tools: bool
+    """Whether any MST tool is reachable."""
+
+
+def discover_sandbox_config(agent: Agent[Any]) -> DiscoveredSandbox:
+    """Collects sandbox tools from the agent and every agent reachable through handoffs.
+
+    Agents wrapped with `as_tool()` can't be inspected; their tools get the
+    sandbox lazily, from whichever config the run settles on.
+    """
+    configs: list[SandboxConfig] = []
+    has_tools = False
+    seen: set[int] = set()
+
+    def visit(a: Agent[Any]) -> None:
+        nonlocal has_tools
+        if id(a) in seen:
+            return
+        seen.add(id(a))
+        for tool in a.tools:
+            if getattr(tool, MST_TOOL_ATTR, False):
+                has_tools = True
+            config = getattr(tool, MST_SANDBOX_CONFIG_ATTR, None)
+            if config is not None:
+                configs.append(config)
+        for handoff in a.handoffs or []:
+            target = getattr(handoff, "agent", handoff)
+            if isinstance(target, Agent):
+                visit(target)
+
+    visit(agent)
+
+    if len(configs) > 1:
+        first = config_key(configs[0])
+        if any(config_key(c) != first for c in configs):
+            raise ValueError(
+                "[mst] All sandbox_config() tools reachable from an agent (including "
+                "handoffs) must use an identical SandboxConfig"
+            )
+    return DiscoveredSandbox(config=configs[0] if configs else None, has_tools=has_tools)