refactor: 按 code review 重构 code_executors，强化 cube 子包的依赖契约

主要变更（按评审意见整理）：

- code_executors 父包不再 lazy 重导出 Cube 符号；业务方需显式
  `from trpc_agent_sdk.code_executors.cube import ...`，让 [cube]
  依赖在调用点显性暴露，避免错把可选依赖伪装成核心依赖。
- 移除 cube 子包"未装 [cube] 也能 import"的隐含契约：
  `cube/_e2b.py` 删除，`_sandbox.py` / `_code_executor.py` 改为顶层
  `import e2b_code_interpreter as e2b`；缺失 extra 时直接以
  ImportError 在 import 处失败，而非延迟到 sandbox 打开时。
- 工作空间收集流水线：删除 utils/_collect.py，将
  `build_code_files` / `build_manifest_output` 上提为
  `BaseWorkspaceFS._build_code_files` / `._build_manifest_output`
  保护静态方法；local/container/cube 三个后端通过 self.* 调用，
  子类可直接复用或重写。`max_read_size` 由
  `Optional[int]=None` 改为 `int = MAX_READ_SIZE_BYTES`，签名更直接。
- `CubeCodeExecutor.code_block_delimiters` 改用 `default_factory`
  复用基类默认值并追加 bash fence，避免重复声明 tool_code/python；
  父类未来扩展默认列表时自动跟随。
- `cube/_runtime.py::_copy_remote`：rm -rf 调用加 Safety 注释，
  记录 normalize_remote_relative + join_remote + shell_quote +
  GNU rm `--preserve-root` 的多层校验不变量，作为后续维护合同。

测试同步：
- 新增 tests/code_executors/test_base_workspace_fs_collect.py，针对
  BaseWorkspaceFS 上的保护方法测试，并新增子类覆写用例。
- tests/code_executors/cube/conftest.py 重写 `fake_e2b` fixture，
  patch `_sandbox.e2b` / `_code_executor.e2b` 模块级符号。
- 删除 test_e2b.py、test_package_lazy_import.py，新增
  test_package_imports.py（保留父包 non-reexport + 父包 import
  不触发 e2b 的两条契约）。
- 其余测试更新 monkeypatch 目标到新的实现位置。

Assisted-by: Cursor:claude-opus-4.7
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: leeyyi

examples/code_executors/cube_demo.py

@@ -34,9 +34,9 @@
 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.cube import CubeCodeExecutor
+from trpc_agent_sdk.code_executors.cube import CubeCodeExecutorConfig
+from trpc_agent_sdk.code_executors.cube 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

tests/code_executors/cube/conftest.py

@@ -5,11 +5,18 @@
 # 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.
+Production code does ``import e2b_code_interpreter as e2b`` at module
+top-level in :mod:`trpc_agent_sdk.code_executors.cube._sandbox` and
+:mod:`trpc_agent_sdk.code_executors.cube._code_executor`. Tests still
+need to swap that vendor surface out for a fake — both to avoid talking
+to a real Cube server and to inject precise exception types — so the
+``fake_e2b`` fixture monkeypatches the ``e2b`` symbol in *both* importer
+modules' globals (NOT ``sys.modules['e2b_code_interpreter']``, which
+would only affect callers that re-import the package after the patch).
+
+The fake mirrors just the surface the production code actually
+consults: a handful of vendor exceptions, the ``SandboxState`` /
+``FileType`` enums, and a placeholder ``AsyncSandbox``.
 """
 
 from __future__ import annotations
@@ -44,11 +51,25 @@ def __init__(self, stdout: str = "", stderr: str = "", exit_code: int = 1):
         self.exit_code = exit_code
 
 
+class _FakeTimeoutException(Exception):
+    """Mirrors e2b_code_interpreter.TimeoutException.
+
+    The real vendor message is long and prescriptive ("passing 'timeout'
+    when making the request", "Use '0' to disable"). Production code
+    catches this type in :meth:`CubeSandboxClient.commands_run` and
+    rewrites it into a structured ``CubeCommandResult(timed_out=True)``,
+    so what actually gets surfaced to callers never contains this
+    message. The fake keeps the *type* precise while leaving the message
+    empty so tests can assert on the translated shape.
+    """
+
+
 def _make_fake_e2b() -> SimpleNamespace:
     ns = SimpleNamespace()
     ns.SandboxException = _FakeSandboxException
     ns.SandboxNotFoundException = _FakeSandboxNotFoundException
     ns.CommandExitException = _FakeCommandExitException
+    ns.TimeoutException = _FakeTimeoutException
     ns.SandboxState = SimpleNamespace(
         RUNNING=SimpleNamespace(value="running"),
         PAUSED=SimpleNamespace(value="paused"),
@@ -61,23 +82,22 @@ def _make_fake_e2b() -> SimpleNamespace:
 
 @pytest.fixture
 def fake_e2b(monkeypatch):
-    """Patch ``_import_e2b`` everywhere the cube package imports it."""
+    """Swap ``e2b_code_interpreter`` for a fake in every cube import site.
+
+    Production code does ``import e2b_code_interpreter as e2b`` at the
+    top of ``_sandbox.py`` and ``_code_executor.py``, which binds an
+    ``e2b`` name in those modules' globals. We patch each of those
+    bindings independently (rather than ``sys.modules``) so already-
+    executed ``from … import e2b`` statements see the fake.
+    """
     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,
+        "trpc_agent_sdk.code_executors.cube._sandbox.e2b",
+        ns,
     )
     monkeypatch.setattr(
-        "trpc_agent_sdk.code_executors.cube._code_executor._import_e2b",
-        lambda: ns,
+        "trpc_agent_sdk.code_executors.cube._code_executor.e2b",
+        ns,
     )
     return ns
 
@@ -92,7 +112,6 @@ def _make_fake_async_sandbox(sandbox_id: str = "sbx-1"):
     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()

tests/code_executors/cube/test_bug_hunt.py

@@ -556,3 +556,77 @@ async def test_bug11_copy_remote_issues_rm_before_cp(mock_client):
     cp_idx = next(i for i, c in enumerate(cmds) if c.startswith("cp -a"))
     assert rm_idx < cp_idx, "rm must precede cp"
 
+
+
+
+
+@pytest.mark.asyncio
+async def test_bug12_commands_run_translates_timeout_to_structured_result(
+    fake_e2b, fake_async_sandbox,
+):
+    """TimeoutException at the e2b boundary must become a CubeCommandResult."""
+    fake_async_sandbox.commands.run = AsyncMock(
+        side_effect=fake_e2b.TimeoutException()
+    )
+    client = CubeSandboxClient(
+        fake_async_sandbox, idle_timeout=60, execute_timeout=30.0,
+    )
+    result = await client.commands_run("sleep 9999", timeout=1.5)
+    assert isinstance(result, CubeCommandResult)
+    assert result.timed_out is True, "timed_out flag must be set"
+    assert result.exit_code == -1, (
+        f"exit_code on timeout must be -1 (matches local/container "
+        f"executors); got {result.exit_code}"
+    )
+    assert result.stdout == "", f"stdout must be empty on timeout: {result.stdout!r}"
+    # The rewritten stderr is short and hand-written. Importantly, it does
+    # NOT contain the e2b vendor boilerplate.
+    assert "timed out" in result.stderr.lower(), (
+        f"stderr must describe the timeout: {result.stderr!r}"
+    )
+    assert "1.5" in result.stderr, (
+        f"stderr must mention the configured timeout value: {result.stderr!r}"
+    )
+    for leaked in ("passing 'timeout'", "context deadline exceeded", "Use '0'"):
+        assert leaked not in result.stderr, (
+            f"vendor message leaked into stderr: {leaked!r} in {result.stderr!r}"
+        )
+
+
+@pytest.mark.asyncio
+async def test_bug12_execute_code_surfaces_deadline_exceeded_outcome(
+    fake_e2b, fake_async_sandbox,
+):
+    """Timeout must appear as OUTCOME_DEADLINE_EXCEEDED, not a raised exception."""
+    from trpc_agent_sdk.code_executors._types import (
+        CodeBlock,
+        CodeExecutionInput,
+        Outcome,
+    )
+    from trpc_agent_sdk.code_executors.cube._code_executor import CubeCodeExecutor
+
+    fake_async_sandbox.commands.run = AsyncMock(
+        side_effect=fake_e2b.TimeoutException()
+    )
+    client = CubeSandboxClient(
+        fake_async_sandbox, idle_timeout=60, execute_timeout=2.0,
+    )
+    cfg = CubeCodeExecutorConfig(
+        template="t", api_url="u", api_key="k",
+        idle_timeout=60, execute_timeout=2.0,
+    )
+    executor = CubeCodeExecutor(client, cfg)
+
+    # execute_code MUST return a result, not raise.
+    result = await executor.execute_code(
+        invocation_context=None,  # type: ignore[arg-type]
+        code_execution_input=CodeExecutionInput(
+            code_blocks=[CodeBlock(code="import time; time.sleep(9999)", language="python")],
+        ),
+    )
+    assert result.outcome == Outcome.OUTCOME_DEADLINE_EXCEEDED, (
+        f"expected OUTCOME_DEADLINE_EXCEEDED, got {result.outcome}"
+    )
+    assert "timed out" in result.output.lower(), (
+        f"output must mention the timeout: {result.output!r}"
+    )

tests/code_executors/cube/test_e2b.py

@@ -0,0 +1,103 @@
+# 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.
+"""Unit tests for the cube subpackage import surface.
+
+The Cube/E2B backend is shipped as the optional ``[cube]`` extra and
+requires ``e2b-code-interpreter`` at import time. Two contracts are
+pinned here:
+
+1. The parent ``trpc_agent_sdk.code_executors`` package intentionally
+   does NOT re-export Cube symbols. Re-exporting optional-dependency
+   symbols would silently force every importer of the parent package
+   to install ``[cube]``; instead, business code that genuinely needs
+   the Cube backend imports the subpackage directly:
+
+       from trpc_agent_sdk.code_executors.cube import CubeCodeExecutor
+
+2. As a corollary, importing the parent package alone does NOT pull in
+   ``e2b_code_interpreter`` — the parent's ``__init__.py`` deliberately
+   does not reference ``trpc_agent_sdk.code_executors.cube``. (Importing
+   the cube subpackage itself, by contrast, does eagerly import the
+   vendor SDK; that is the explicit cost of opting into the [cube]
+   backend.)
+
+Tests that need a **cold** ``sys.modules`` state are run in a subprocess
+so they never corrupt the in-process module cache (which is shared
+across the whole test session).
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import textwrap
+
+import pytest
+
+
+def _run_isolated(script: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [sys.executable, "-c", textwrap.dedent(script)],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def test_parent_package_does_not_reexport_cube_symbols():
+    """Cube symbols must NOT be reachable from the parent package.
+
+    Re-exporting optional-dependency symbols from the eager package
+    would silently make ``[cube]`` mandatory for everyone who imports
+    ``code_executors``. Force callers to make the dependency explicit
+    by importing from the subpackage.
+    """
+    from trpc_agent_sdk import code_executors as ce
+    cube_symbols = (
+        "CubeCodeExecutor",
+        "CubeCodeExecutorConfig",
+        "CubeCommandResult",
+        "CubeProgramRunner",
+        "CubeSandboxClient",
+        "CubeWorkspaceFS",
+        "CubeWorkspaceManager",
+        "CubeWorkspaceRuntime",
+        "CubeWorkspaceRuntimeConfig",
+        "OnExisting",
+        "create_cube_workspace_runtime",
+    )
+    for name in cube_symbols:
+        assert name not in ce.__all__, f"{name!r} leaked into parent __all__"
+        with pytest.raises(AttributeError):
+            getattr(ce, name)
+
+
+def test_parent_package_import_does_not_touch_e2b():
+    """Plain ``import code_executors`` does NOT import e2b_code_interpreter.
+
+    The parent package never references the cube subpackage, so
+    importing it must stay cheap and dependency-free even when the
+    [cube] extra is installed in the same environment.
+
+    Run in a subprocess so the main test session's module cache cannot
+    mask the behaviour.
+    """
+    result = _run_isolated("""
+        import sys
+        import trpc_agent_sdk.code_executors  # noqa: F401
+        assert "e2b_code_interpreter" not in sys.modules, \
+            "bare import of code_executors pulled in e2b_code_interpreter"
+        print("OK")
+    """)
+    assert result.returncode == 0, result.stderr
+    assert "OK" in result.stdout
+
+
+def test_cube_subpackage_reexports_public_api():
+    """Every entry on the cube subpackage's ``__all__`` must resolve."""
+    from trpc_agent_sdk.code_executors import cube
+    for name in cube.__all__:
+        assert hasattr(cube, name), f"{name} missing from cube/__init__.py"