feature: 新增 Cube/E2B 沙箱代码执行器与工作空间运行时

- 在 trpc_agent_sdk.code_executors.cube 提供 CubeCodeExecutor 与 CubeWorkspaceRuntime, 复用 e2b-code-interpreter 远程沙箱; 通过 PEP 562 lazy __getattr__ 实现按需加载, 不安装 [cube] extra 也可正常 import 包
- 公共原语 CubeSandboxClient 集中封装沙箱生命周期 (open_new/open_existing/close/destroy)、结构化命令执行 (commands_run 吞掉 CommandExitException) 与文件传输 (upload_path/download_path 自动 dispatch 文件/目录, 目录走 tar 协议保留符号链接和权限)
- 配置按 ISP 拆分: CubeCodeExecutorConfig 只承载 sandbox/执行相关字段, CubeWorkspaceRuntimeConfig 只承载 workspace 相关字段; create_cube_workspace_runtime 通过可选 workspace_cfg 注入
- 提供 examples/code_executors/cube_demo.py 端到端示例并在 pyproject.toml 增加 [cube] 可选依赖组

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: leeyyi

examples/code_executors/cube_demo.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""End-to-end demo for `CubeCodeExecutor` and `CubeWorkspaceRuntime`.
+
+Requires the optional ``[cube]`` extra and the following environment
+variables (same names hermes uses):
+
+- ``CUBE_TEMPLATE_ID``: Cube template id (e.g. ``std-XXXXXXXX``)
+- ``E2B_API_URL``:       Cube/E2B-compatible gateway URL
+- ``E2B_API_KEY``:       API key for the gateway
+
+Usage::
+
+    pip install 'trpc-agent-py[cube]'
+    export CUBE_TEMPLATE_ID=...
+    export E2B_API_URL=...
+    export E2B_API_KEY=...
+    python examples/code_executors/cube_demo.py
+
+The demo walks through:
+  1. ``CubeCodeExecutor.create`` (no sandbox_id -> fresh sandbox)
+  2. ``execute_code`` for Python and Bash code blocks
+  3. Workspace runtime: ``create_workspace`` -> ``put_files`` -> ``run_program`` -> ``collect_outputs``
+  4. ``destroy`` (kills the remote sandbox)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+
+from trpc_agent_sdk.code_executors import CubeCodeExecutor
+from trpc_agent_sdk.code_executors import CubeCodeExecutorConfig
+from trpc_agent_sdk.code_executors import create_cube_workspace_runtime
+from trpc_agent_sdk.code_executors._types import CodeBlock
+from trpc_agent_sdk.code_executors._types import CodeExecutionInput
+from trpc_agent_sdk.code_executors._types import WorkspaceOutputSpec
+from trpc_agent_sdk.code_executors._types import WorkspacePutFileInfo
+from trpc_agent_sdk.code_executors._types import WorkspaceRunProgramSpec
+
+
+def _require_env() -> None:
+    missing = [name for name in ("CUBE_TEMPLATE_ID", "E2B_API_URL", "E2B_API_KEY") if not os.getenv(name)]
+    if missing:
+        sys.stderr.write(f"missing required env vars: {', '.join(missing)}\n")
+        sys.exit(2)
+
+
+async def _run() -> None:
+    _require_env()
+
+    cfg = CubeCodeExecutorConfig(
+        execute_timeout=30.0,
+        idle_timeout=600.0,
+    )
+
+    executor = await CubeCodeExecutor.create(cfg)
+    print(f"created sandbox: {executor.sandbox_id}")
+
+    try:
+        # 1. execute_code with two blocks (python and bash).
+        result = await executor.execute_code(
+            invocation_context=None,  # type: ignore[arg-type]
+            code_execution_input=CodeExecutionInput(code_blocks=[
+                CodeBlock(code="print('hello from cube py')", language="python"),
+                CodeBlock(code="echo hello from cube bash", language="bash"),
+            ]),
+        )
+        print("execute_code result:")
+        print(result.output)
+
+        # 2. Workspace runtime end-to-end.
+        runtime = create_cube_workspace_runtime(executor)
+        manager = runtime.manager()
+        fs = runtime.fs()
+        runner = runtime.runner()
+
+        ws = await manager.create_workspace("demo-1")
+        print(f"workspace path: {ws.path}")
+
+        await fs.put_files(ws, [
+            WorkspacePutFileInfo(path="work/script.py",
+                                 content=b"print('script ran')\n"),
+        ])
+
+        run_result = await runner.run_program(
+            ws,
+            WorkspaceRunProgramSpec(cmd="python3", args=["work/script.py"], timeout=15.0),
+        )
+        print(f"run_program exit={run_result.exit_code} stdout={run_result.stdout!r}")
+
+        outputs = await fs.collect_outputs(ws, WorkspaceOutputSpec(globs=["work/*.py"], inline=True))
+        for ref in outputs.files:
+            print(f"output: {ref.name} ({len(ref.content)} chars)")
+
+        await manager.cleanup("demo-1")
+    finally:
+        await executor.destroy()
+        print("sandbox destroyed")
+
+
+if __name__ == "__main__":
+    asyncio.run(_run())

pyproject.toml

@@ -98,6 +98,10 @@ mem0 = [
     "sentence-transformers",
 ]
 
+cube = [
+    "e2b-code-interpreter>=2.0.0",
+]
+
 langchain_tool = [
     "langchain_tavily",
     "langchain",
@@ -140,6 +144,7 @@ all = [
     "aiofiles",
     "wecom-aibot-sdk-python>=0.1.5",
     "a2a-sdk<1.0.0,>=0.3.22",
+    "e2b-code-interpreter>=2.0.0",
 ]
 
 [project.scripts]

tests/code_executors/cube/__init__.py

@@ -0,0 +1,112 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Shared fixtures for the cube/ test suite.
+
+Exposes a ``fake_e2b`` fixture that patches
+:func:`trpc_agent_sdk.code_executors.cube._e2b._import_e2b` to return a
+fake vendor module with stub classes / enums that match the surface the
+production code consults. This keeps the whole test suite independent
+of the real ``e2b-code-interpreter`` dependency.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+from unittest.mock import MagicMock
+
+import pytest
+
+
+class _FakeSandboxException(Exception):
+    """Mirrors e2b_code_interpreter.SandboxException."""
+
+
+class _FakeSandboxNotFoundException(_FakeSandboxException):
+    """Mirrors e2b_code_interpreter.SandboxNotFoundException."""
+
+
+class _FakeCommandExitException(Exception):
+    """Mirrors e2b_code_interpreter.CommandExitException.
+
+    Carries stdout/stderr/exit_code, matching how the real vendor raises
+    it. ``commands_run`` reads these via getattr so the attribute names
+    are the contract here.
+    """
+
+    def __init__(self, stdout: str = "", stderr: str = "", exit_code: int = 1):
+        super().__init__(f"cmd exit {exit_code}")
+        self.stdout = stdout
+        self.stderr = stderr
+        self.exit_code = exit_code
+
+
+def _make_fake_e2b() -> SimpleNamespace:
+    ns = SimpleNamespace()
+    ns.SandboxException = _FakeSandboxException
+    ns.SandboxNotFoundException = _FakeSandboxNotFoundException
+    ns.CommandExitException = _FakeCommandExitException
+    ns.SandboxState = SimpleNamespace(
+        RUNNING=SimpleNamespace(value="running"),
+        PAUSED=SimpleNamespace(value="paused"),
+        STOPPED=SimpleNamespace(value="stopped"),
+    )
+    ns.FileType = SimpleNamespace(DIR="dir", FILE="file")
+    ns.AsyncSandbox = MagicMock()
+    return ns
+
+
+@pytest.fixture
+def fake_e2b(monkeypatch):
+    """Patch ``_import_e2b`` everywhere the cube package imports it."""
+    ns = _make_fake_e2b()
+    # The production code does ``from ._e2b import _import_e2b`` in
+    # _sandbox.py and _code_executor.py, which rebinds the symbol in
+    # those modules' globals — so we must patch every import site, not
+    # just the original definition.
+    monkeypatch.setattr(
+        "trpc_agent_sdk.code_executors.cube._e2b._import_e2b",
+        lambda: ns,
+    )
+    monkeypatch.setattr(
+        "trpc_agent_sdk.code_executors.cube._sandbox._import_e2b",
+        lambda: ns,
+    )
+    monkeypatch.setattr(
+        "trpc_agent_sdk.code_executors.cube._code_executor._import_e2b",
+        lambda: ns,
+    )
+    return ns
+
+
+def _make_fake_async_sandbox(sandbox_id: str = "sbx-1"):
+    """Build a MagicMock shaped like ``e2b_code_interpreter.AsyncSandbox``.
+
+    All the methods the production client touches are ``AsyncMock``s so
+    tests can configure ``return_value`` / ``side_effect`` as needed.
+    """
+    sbx = MagicMock()
+    sbx.sandbox_id = sandbox_id
+    sbx.kill = AsyncMock(return_value=None)
+    sbx.set_timeout = AsyncMock(return_value=None)
+    # get_info returns a state holder by default; tests override.
+    info = SimpleNamespace(state=SimpleNamespace(value="running"))
+    sbx.get_info = AsyncMock(return_value=info)
+    sbx.commands = MagicMock()
+    sbx.commands.run = AsyncMock()
+    sbx.files = MagicMock()
+    sbx.files.read = AsyncMock(return_value=b"")
+    sbx.files.write = AsyncMock(return_value=None)
+    sbx.files.get_info = AsyncMock(return_value=SimpleNamespace(type="file"))
+    return sbx
+
+
+@pytest.fixture
+def fake_async_sandbox(fake_e2b):
+    """A fresh fake AsyncSandbox whose ``get_info`` defaults to RUNNING."""
+    sbx = _make_fake_async_sandbox()
+    sbx.get_info = AsyncMock(return_value=SimpleNamespace(state=fake_e2b.SandboxState.RUNNING))
+    return sbx