agent-sandbox-backends 0.1.0__tar.gz

agent_sandbox_backends-0.1.0/.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,toml,json}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.ps1]
+end_of_line = crlf

agent_sandbox_backends-0.1.0/.env.example

@@ -0,0 +1,15 @@
+# OpenSandbox Service 根地址，不要填写 Web Console 地址，也不要添加 /v1。
+OPENSANDBOX_URL=http://127.0.0.1:8080
+
+# OpenSandbox Service 开启鉴权时填写；未开启鉴权时保持为空。
+# OPENSANDBOX_API_KEY=
+
+# true: 文件、命令和健康检查通过 OpenSandbox Service 代理。
+# 客户端无法直接访问 Docker Sandbox 私有端点时必须开启。
+OPENSANDBOX_USE_SERVER_PROXY=true
+
+# 四个测试创建 Sandbox 时使用的镜像。
+OPENSANDBOX_IMAGE=python:3.12
+
+# false: 测试结束自动删除；true: 保留文件和历史供 Web Console 查看。
+OPENSANDBOX_KEEP_CREATED=false

agent_sandbox_backends-0.1.0/.gitattributes

@@ -0,0 +1,12 @@
+* text=auto eol=lf
+
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.zip binary
+*.gz binary

agent_sandbox_backends-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,93 @@
+name: Bug Report
+description: 报告可复现的 SDK、OpenSandbox 或 History 问题
+title: "[Bug]: "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        感谢反馈。请先移除 API Key、Token、密码、私网地址和 Sandbox 中的敏感数据。
+
+  - type: input
+    id: package_version
+    attributes:
+      label: agent-sandbox-backends 版本
+      description: 可通过 `python -c "import agent_sandbox_backends; print(agent_sandbox_backends.__version__)"` 查看。
+      placeholder: 0.1.0
+    validations:
+      required: true
+
+  - type: input
+    id: python_version
+    attributes:
+      label: Python 版本
+      placeholder: Python 3.12.3
+    validations:
+      required: true
+
+  - type: input
+    id: opensandbox_version
+    attributes:
+      label: OpenSandbox 版本
+      description: 可通过 `python -c "import importlib.metadata; print(importlib.metadata.version('opensandbox'))"` 查看。
+      placeholder: 0.1.14
+    validations:
+      required: true
+
+  - type: dropdown
+    id: deployment
+    attributes:
+      label: OpenSandbox 部署方式
+      options:
+        - Docker
+        - Kubernetes
+        - 本机进程
+        - 其他
+    validations:
+      required: true
+
+  - type: dropdown
+    id: server_proxy
+    attributes:
+      label: 是否启用 use_server_proxy
+      options:
+        - "true"
+        - "false"
+        - 不确定
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: 问题描述
+      description: 说明预期行为和实际行为。
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: 最小复现步骤
+      description: 提供尽可能短的代码和操作步骤，不要包含真实凭证。
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: 错误和日志
+      description: 请先删除 API Key、Token、密码、私网地址、文件内容和 Sandbox 数据。
+      render: shell
+
+  - type: checkboxes
+    id: safety
+    attributes:
+      label: 安全确认
+      options:
+        - label: 我已经确认内容中不包含真实凭证、私网地址或敏感 Sandbox 数据。
+          required: true
+        - label: 如果这是安全漏洞，我不会创建公开 Issue，而会按照 SECURITY.md 私下报告。
+          required: true

agent_sandbox_backends-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,2 @@
+blank_issues_enabled: false
+contact_links: []

agent_sandbox_backends-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,64 @@
+name: Feature Request
+description: 提议新的 SDK、History、Web Console 数据或 OpenSandbox 能力
+title: "[Feature]: "
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        第一版只支持 OpenSandbox。请优先说明真实使用场景，而不只是建议增加配置项。
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: 要解决的问题
+      description: 目前什么场景无法完成，或者使用成本过高？
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: 建议方案
+      description: 描述期望的公共 API、默认行为和示例。
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: 涉及范围
+      multiple: true
+      options:
+        - Backend 创建与生命周期
+        - 文件上传、下载和查看
+        - 命令执行
+        - Sandbox SQLite History
+        - Deep Agents 适配
+        - 并发与取消
+        - 安全与权限
+        - GitHub、PyPI 与文档
+    validations:
+      required: true
+
+  - type: textarea
+    id: compatibility
+    attributes:
+      label: 兼容性影响
+      description: 是否会改变 History Schema、Web Console 读取方式或现有用户代码？
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: 已考虑的替代方案
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: 提交确认
+      options:
+        - label: 该需求以 OpenSandbox 第一版定位为基础。
+          required: true
+        - label: 我没有在内容中提交真实凭证或敏感数据。
+          required: true

agent_sandbox_backends-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,34 @@
+## 变更说明
+
+说明本次修改解决的问题及选择该方案的原因。
+
+## 影响范围
+
+- [ ] Backend 创建与生命周期
+- [ ] 文件上传、下载和查看
+- [ ] 命令执行
+- [ ] Sandbox SQLite History
+- [ ] Deep Agents 适配
+- [ ] 并发、取消或异常处理
+- [ ] 安全边界
+- [ ] 文档、CI 或发布
+
+## 验证结果
+
+- [ ] `uv run ruff check .`
+- [ ] `uv run pyright`
+- [ ] `uv run pytest -q`
+- [ ] `uv build`
+- [ ] 如涉及真实 OpenSandbox，已运行对应手动测试
+
+## 兼容性检查
+
+- [ ] 公共 API 变更已更新 README 和类型定义
+- [ ] History Schema 或字段变更已确认 Web Console 兼容性
+- [ ] 上传修改保留 allowed roots、敏感文件排除和路径安全检查
+- [ ] 命令与 History 内容中没有加入 API Key、Token 或密码
+- [ ] 没有提交 `.env`、私网地址、Sandbox 数据或生成文件
+
+## 补充信息
+
+如有迁移步骤、性能影响或后续工作，请在此说明。

agent_sandbox_backends-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  quality:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.11", "3.12", "3.13", "3.14"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+          enable-cache: true
+      - run: uv sync --all-extras --dev --locked
+      - run: uv run ruff check .
+      - run: uv run pyright
+      - run: uv build
+
+  supply-chain:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+      - run: uv sync --all-extras --dev --locked
+      - run: >-
+          uv export --all-extras --no-dev --no-hashes --no-emit-project
+          --format requirements-txt --output-file audit-requirements.txt
+      - run: uvx pip-audit -r audit-requirements.txt

agent_sandbox_backends-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,79 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+concurrency:
+  group: pypi-${{ github.event.release.tag_name }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Check and build distributions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout release source
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev --locked
+
+      - name: Verify release tag
+        shell: bash
+        run: |
+          PACKAGE_VERSION="$(uv run python -c 'from agent_sandbox_backends import __version__; print(__version__)')"
+          if [ "v${PACKAGE_VERSION}" != "${{ github.event.release.tag_name }}" ]; then
+            echo "Release tag must be v${PACKAGE_VERSION}, got ${{ github.event.release.tag_name }}"
+            exit 1
+          fi
+
+      - name: Run quality checks
+        run: |
+          uv run ruff check .
+          uv run pyright
+
+      - name: Build wheel and source distribution
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+
+  publish:
+    name: Publish distributions to PyPI
+    needs: [build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/agent-sandbox-backends/
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

agent_sandbox_backends-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+.idea/
+.env
+.env.*
+!.env.example
+.pytest_cache/
+.hypothesis/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.py[cod]
+.pyright/
+*.log

agent_sandbox_backends-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+本项目遵循语义化版本号。正式版本发布后，同一版本号不会重复构建或覆盖。
+
+## 0.1.0 - 2026-07-20
+
+- 首次公开版本，只支持 OpenSandbox Provider。
+- 提供 `create_opensandbox_backend()` 高层入口。
+- 默认使用 `python:3.12` 镜像和 Sandbox SQLite History。
+- 支持生命周期、文件、命令、上传、下载和 Deep Agents Backend 适配。
+- 支持 Actor、Thread、Run、Correlation 标识及 Web Console History 数据。
+- 支持用户级多 Agent 并发限制、生命周期 Gate 和文件读写锁。
+- 支持本地上传根目录限制、敏感文件排除、路径逃逸和归档安全检查。
+- 支持 OpenSandbox 原生 Sandbox TTL 和独立 SDK 延迟清理 TTL。

agent_sandbox_backends-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+## 参与原则
+
+本项目欢迎不同经验、背景和观点的参与者。所有参与者都应：
+
+- 使用尊重、清晰且针对问题本身的语言。
+- 接受建设性反馈，并说明技术判断所依据的事实。
+- 尊重隐私，不公开他人的凭证、私网信息、日志和 Sandbox 数据。
+- 避免骚扰、歧视、威胁、人身攻击和持续干扰讨论。
+- 在安全问题中优先保护用户，避免公开可直接利用的细节。
+
+## 适用范围
+
+该准则适用于仓库的 Issue、Pull Request、Discussion、Release、代码评审以及代表本项目进行的
+其他公开或私下交流。
+
+## 处理方式
+
+维护者可以编辑或删除不符合准则的内容，限制参与者继续互动，或在必要时向 GitHub 平台报告。
+处理时会尽量说明原因，并优先保护报告者和受影响用户的隐私。
+
+## 报告问题
+
+行为问题应通过仓库所有者 GitHub 主页提供的私下联系方式报告，不要在公开 Issue 中披露个人
+信息。安全漏洞应按照 `SECURITY.md` 使用 Private vulnerability reporting 或 Security
+Advisory 报告。

agent_sandbox_backends-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+感谢参与 Agent Sandbox Backends 的开发。
+
+## 开发环境
+
+```powershell
+uv sync --all-extras --dev
+```
+
+## 提交前检查
+
+```powershell
+uv run ruff check .
+uv run pyright
+uv run pytest -q
+uv build
+```
+
+涉及 OpenSandbox 行为的修改还应运行：
+
+```powershell
+python scripts\deepagents_opensandbox_smoke.py
+```
+
+该脚本需要自行部署的 OpenSandbox Service，不应把真实 `.env`、API Key、私网地址或
+Sandbox 数据提交到仓库。
+
+## 修改原则
+
+- 第一版只维护 OpenSandbox Provider。
+- 优先修复根因，避免改变无关行为。
+- 公共 API 变更必须补充类型、测试和 README。
+- History Schema 变更必须同时确认 Web Console 的读取兼容性。
+- 新增本地文件上传能力时必须保留默认拒绝和路径安全边界。