feat(box): shared MCP container with persistent session support

- All MCP servers share single 'mcp-shared' Docker container
- Each server gets unique process_id within shared session
- Persistent workspace survives LangBot restarts
- Cleanup only removes managed process, not shared session
- Add process_id passthrough in service, workspace, and MCP layers
- Fix workspace.py docstring placement for ruff E402
- Update tests for shared session model and default image change

Author: RockChinQ

docker/docker-compose.yaml

@@ -23,10 +23,7 @@ services:
     container_name: langbot_box
     volumes:
       - ./data/box:/workspaces
-      # Mount container runtime socket for Box sandbox backend.
-      # Uncomment the one that matches your container runtime:
-      # - /var/run/podman/podman.sock:/var/run/podman/podman.sock   # Podman
-      - /var/run/docker.sock:/var/run/docker.sock                   # Docker
+      - /var/run/docker.sock:/var/run/docker.sock
     restart: on-failure
     environment:
       - TZ=Asia/Shanghai

docs/review/box-architecture.md

@@ -39,8 +39,7 @@
 │  BoxRuntime (session 管理/进程生命周期)                         │
 │       │                                                       │
 │  Backend (启动时选择一个):                                      │
-│    PodmanBackend ─┐                                           │
-│    DockerBackend ─┤── CLISandboxBackend                       │
+│    DockerBackend ─┬── CLISandboxBackend                       │
 │    NsjailBackend ─┘                                           │
 │                                                               │
 │  aiohttp WS Relay (:5410)                                     │
@@ -50,7 +49,7 @@
                │
                ▼
 ┌──────────────────────────────────────────────────────────────┐
-│  容器/沙箱 (Podman/Docker container 或 nsjail sandbox)        │
+│  容器/沙箱 (Docker container 或 nsjail sandbox)               │
 │  - 隔离文件系统、网络、PID 命名空间                              │
 │  - 资源限制 (CPU, 内存, PID 数)                                │
 │  - exec: 用户命令在此执行                                      │
@@ -158,14 +157,14 @@ Session 生命周期:
 
 ### 3.2 Backend 系统
 
-#### CLISandboxBackend (`box/backend.py`, 389 行)
+#### CLISandboxBackend (`box/backend.py`)
 
-Podman/Docker 的公共基类：
+Docker 的基类：
 
 ```
 start_session(spec):
   1. validate_sandbox_security(spec)     安全校验
-  2. docker/podman run -d --rm --name <name>
+  2. docker run -d --rm --name <name>
      --network none (可选)
      --cpus/--memory/--pids-limit        资源限制
      --read-only + --tmpfs /tmp          只读根文件系统
@@ -174,11 +173,11 @@ start_session(spec):
   3. 返回 BoxSessionInfo
 
 exec(session, spec):
-  docker/podman exec -e KEY=VAL <container>
+  docker exec -e KEY=VAL <container>
     sh -lc 'mkdir -p <workdir> && cd <workdir> && <cmd>'
 
 start_managed_process(session, spec):
-  docker/podman exec -i <container>
+  docker exec -i <container>
     sh -lc 'mkdir -p <cwd> && cd <cwd> && exec <command> <args>'
   返回 asyncio.subprocess.Process (stdin/stdout PIPE)
 ```
@@ -197,7 +196,7 @@ start_managed_process(session, spec):
 - 资源限制: cgroup v2 优先，fallback 到 rlimit
 - **无自定义镜像**: 使用宿主 OS，`image` 字段固定为 `'host'`
 
-**后端选择优先级**: Podman → Docker → nsjail（启动时逐个探测，首个可用的胜出，不做运行时 failover）
+**后端选择优先级**: Docker → nsjail（启动时逐个探测，首个可用的胜出，不做运行时 failover）
 
 ### 3.3 Server (`box/server.py`, 268 行)
 
@@ -237,7 +236,7 @@ start_managed_process(session, spec):
 
 ### 3.6 Security (`box/security.py`, 54 行)
 
-`validate_sandbox_security()`: 黑名单校验 host_path，阻止挂载 `/etc`/`/proc`/`/sys`/`/dev`/`/root`/`/boot` 及 Docker/Podman socket。
+`validate_sandbox_security()`: 黑名单校验 host_path，阻止挂载 `/etc`/`/proc`/`/sys`/`/dev`/`/root`/`/boot` 及 Docker socket。
 
 **已知缺陷**: 根路径 `/` 未拦截，用户 home 目录未拦截，是 denylist 而非 allowlist 策略。详见 [问题清单 #5](./box-issues.md)。
 

docs/review/box-test-coverage.md

@@ -68,7 +68,7 @@
 |------|------|
 | **Session TTL 过期** | 测试配置了 `session_ttl_sec` 但从未推进时间验证过期清理 |
 | **并发 session 访问** | 无并发 exec / 并发创建 / race condition 测试 |
-| **Container backend (Podman/Docker)** | 仅通过集成测试覆盖（CI 不运行），单元测试全用 FakeBackend |
+| **Container backend (Docker)** | 仅通过集成测试覆盖（CI 不运行），单元测试全用 FakeBackend |
 | **BoxRuntime shutdown()** | 在 test cleanup 中调用但未验证行为 |
 | **BoxServerHandler 错误路径** | 畸形请求、未知 action 类型 |
 | **WS relay** | 仅在集成测试中覆盖（CI 不运行） |
@@ -83,7 +83,7 @@
 |------|------|
 | BoxSpec 校验 | 无效 session_id 格式、超长命令、env 特殊字符 |
 | BoxExecutionResult | 仅 COMPLETED 和 TIMED_OUT，无 ERROR 状态测试 |
-| 多后端 fallback | 仅单后端配置，无 Podman 不可用 → fallback Docker 测试 |
+| 多后端 fallback | 仅单后端配置，无 Docker 不可用 → fallback nsjail 测试 |
 | Profile YAML 加载 | 测试用硬编码字符串，未从真实 config.yaml 加载 |
 
 ---

docs/review/box-tob-analysis.md

@@ -10,7 +10,7 @@
 | 能力 | toB 价值 | 代码位置 |
 |------|---------|---------|
 | **沙箱隔离执行** | 企业安全运行不受信代码的基础能力 | SDK `box/backend.py` |
-| **多后端支持** | 适配不同企业容器基础设施 (Podman/Docker/nsjail) | SDK `box/runtime.py` `_select_backend()` |
+| **多后端支持** | 适配不同企业容器基础设施 (Docker/nsjail) | SDK `box/runtime.py` `_select_backend()` |
 | **Profile + locked 字段** | 运维锁定安全边界，LLM/用户无法绕过 | `pkg/box/service.py`, SDK `box/models.py` |
 | **资源限制** | CPU/内存/PID 数限制防止资源滥用 | SDK `backend.py` `--cpus/--memory/--pids-limit` |
 | **Workspace quota** | 磁盘用量控制 | `pkg/box/service.py` `_enforce_workspace_quota` |

src/langbot/pkg/box/connector.py

@@ -43,10 +43,21 @@ def resolve_box_ws_relay_url(ap: core_app.Application) -> str:
     """
     box_cfg = _get_box_config(ap)
 
-    # Explicit relay URL takes precedence.
+    # Explicit runtime URL takes precedence.  The config value should be
+    # a bare ``ws://host:port`` (no path) – the connector appends paths
+    # like ``/rpc/ws`` or ``/v1/sessions/…`` as needed.
     runtime_url = str(box_cfg.get('runtime_url', '')).strip()
     if runtime_url:
-        return runtime_url
+        parsed = urlparse(runtime_url)
+        scheme = parsed.scheme or 'ws'
+        # Normalise WebSocket schemes to HTTP for the relay base URL.
+        if scheme == 'ws':
+            scheme = 'http'
+        elif scheme == 'wss':
+            scheme = 'https'
+        host = parsed.hostname or '127.0.0.1'
+        port = parsed.port or _DEFAULT_PORT
+        return f'{scheme}://{host}:{port}'
 
     # In Docker, relay lives on the box runtime container.
     if platform.get_platform() == 'docker':
@@ -192,9 +203,18 @@ def _resolve_rpc_ws_url(self) -> str:
         """Determine the action-RPC WebSocket URL.
 
         All endpoints share a single port; action RPC is at ``/rpc/ws``.
+        The configured ``runtime_url`` is a bare ``ws://host:port`` base;
+        the ``/rpc/ws`` path is always appended by this method.
         """
         if self.configured_runtime_url:
-            return self.configured_runtime_url
+            base = self.configured_runtime_url.rstrip('/')
+            parsed = urlparse(base)
+            scheme = parsed.scheme or 'ws'
+            if scheme in ('http', 'https'):
+                scheme = 'wss' if scheme == 'https' else 'ws'
+            host = parsed.hostname or '127.0.0.1'
+            port = parsed.port or _DEFAULT_PORT
+            return f'{scheme}://{host}:{port}/rpc/ws'
 
         if platform.get_platform() == 'docker':
             return f'ws://{_DOCKER_BOX_HOST}:{_DEFAULT_PORT}/rpc/ws'

src/langbot/pkg/box/service.py

@@ -134,7 +134,7 @@ async def execute_spec_payload(
         skip_host_mount_validation: bool = False,
     ) -> dict:
         if not self._available:
-            raise BoxError('Box runtime is not available. Install and start Podman or Docker to use sandbox features.')
+            raise BoxError('Box runtime is not available. Install and start Docker to use sandbox features.')
         try:
             spec = self.build_spec(spec_payload, skip_host_mount_validation=skip_host_mount_validation)
         except BoxError as exc:
@@ -280,10 +280,10 @@ async def start_managed_process(self, session_id: str, process_payload: dict) ->
         process_spec = BoxManagedProcessSpec.model_validate(process_payload)
         return await self.client.start_managed_process(session_id, process_spec)
 
-    async def get_managed_process(self, session_id: str) -> BoxManagedProcessInfo:
-        return await self.client.get_managed_process(session_id)
+    async def get_managed_process(self, session_id: str, process_id: str = 'default') -> BoxManagedProcessInfo:
+        return await self.client.get_managed_process(session_id, process_id)
 
-    def get_managed_process_websocket_url(self, session_id: str) -> str:
+    def get_managed_process_websocket_url(self, session_id: str, process_id: str = 'default') -> str:
         getter = getattr(self.client, 'get_managed_process_websocket_url', None)
         if getter is None:
             raise BoxValidationError('box runtime client does not support managed process websocket attach')
@@ -292,7 +292,7 @@ def get_managed_process_websocket_url(self, session_id: str) -> str:
             if self._runtime_connector is not None
             else 'http://127.0.0.1:5410'
         )
-        return getter(session_id, ws_relay_base_url)
+        return getter(session_id, ws_relay_base_url, process_id)
 
     def _serialize_result(self, result: BoxExecutionResult) -> dict:
         stdout, stdout_truncated = self._truncate(result.stdout)

src/langbot/pkg/box/workspace.py

@@ -1,4 +1,3 @@
-from __future__ import annotations
 """Reusable workspace/session helpers built on top of Box.
 
 This module is the middle layer between the raw Box runtime primitives and
@@ -14,6 +13,8 @@
 - MCP stdio chooses how to prepare dependencies and attaches to a managed process
 """
 
+from __future__ import annotations
+
 import os
 import textwrap
 from typing import Any
@@ -99,9 +100,7 @@ def list_python_manifest_files(host_path: str | None) -> list[str]:
     normalized_root = normalize_host_path(host_path)
     if not normalized_root:
         return []
-    return [
-        filename for filename in PYTHON_MANIFEST_FILES if os.path.isfile(os.path.join(normalized_root, filename))
-    ]
+    return [filename for filename in PYTHON_MANIFEST_FILES if os.path.isfile(os.path.join(normalized_root, filename))]
 
 
 def classify_python_workspace(host_path: str | None) -> str | None:
@@ -269,6 +268,7 @@ def __init__(
         cpus: float | None = None,
         memory_mb: int | None = None,
         pids_limit: int | None = None,
+        persistent: bool = False,
     ):
         self.box_service = box_service
         self.session_id = session_id
@@ -283,6 +283,7 @@ def __init__(
         self.cpus = cpus
         self.memory_mb = memory_mb
         self.pids_limit = pids_limit
+        self.persistent = persistent
 
     def rewrite_path(self, path: str) -> str:
         return rewrite_mounted_path(path, self.host_path, mount_path=self.mount_path)
@@ -298,6 +299,8 @@ def build_session_payload(self) -> dict[str, Any]:
             'workdir': self.workdir,
             'env': self.env,
         }
+        if self.persistent:
+            payload['persistent'] = True
         if self.network is not None:
             payload['network'] = self.network
         if self.read_only_rootfs is not None:
@@ -388,17 +391,19 @@ async def start_managed_process(
         command: str,
         args: list[str] | None = None,
         *,
+        process_id: str = 'default',
         env: dict[str, str] | None = None,
         cwd: str = '/workspace',
     ):
         payload = self.build_process_payload(command, args, env=env, cwd=cwd)
+        payload['process_id'] = process_id
         return await self.box_service.start_managed_process(self.session_id, payload)
 
-    async def get_managed_process(self):
-        return await self.box_service.get_managed_process(self.session_id)
+    async def get_managed_process(self, process_id: str = 'default'):
+        return await self.box_service.get_managed_process(self.session_id, process_id)
 
-    def get_managed_process_websocket_url(self) -> str:
-        return self.box_service.get_managed_process_websocket_url(self.session_id)
+    def get_managed_process_websocket_url(self, process_id: str = 'default') -> str:
+        return self.box_service.get_managed_process_websocket_url(self.session_id, process_id)
 
     async def cleanup(self) -> None:
         await self.box_service.client.delete_session(self.session_id)

src/langbot/pkg/provider/tools/loaders/mcp.py

@@ -20,7 +20,7 @@
 import langbot_plugin.api.entities.builtin.resource.tool as resource_tool
 import langbot_plugin.api.entities.builtin.provider.message as provider_message
 from ....entity.persistence import mcp as persistence_mcp
-from .mcp_stdio import BoxStdioSessionRuntime, MCPServerBoxConfig, MCPSessionErrorPhase
+from .mcp_stdio import BoxStdioSessionRuntime, MCPSessionErrorPhase
 
 
 class MCPSessionStatus(enum.Enum):
@@ -320,6 +320,7 @@ def get_runtime_info_dict(self) -> dict:
         }
         if self._uses_box_stdio():
             info['box_session_id'] = self._build_box_session_id()
+            info['box_process_id'] = self._box_stdio_runtime.process_id
             info['box_enabled'] = True
         return info
 
@@ -349,7 +350,7 @@ def _uses_box_stdio(self) -> bool:
         return self._box_stdio_runtime.uses_box_stdio()
 
     def _build_box_session_id(self) -> str:
-        return f'mcp-{self.server_uuid}'
+        return 'mcp-shared'
 
     def _rewrite_path(self, path: str, host_path: str | None) -> str:
         return self._box_stdio_runtime.rewrite_path(path, host_path)

src/langbot/pkg/provider/tools/loaders/mcp_stdio.py

@@ -81,8 +81,14 @@ def _build_workspace(self) -> BoxWorkspaceSession:
             cpus=self.config.cpus,
             memory_mb=self.config.memory_mb,
             pids_limit=self.config.pids_limit,
+            persistent=True,
         )
 
+    @property
+    def process_id(self) -> str:
+        """Each MCP server gets a unique process_id within the shared session."""
+        return self.owner.server_uuid
+
     def uses_box_stdio(self) -> bool:
         if self.server_config.get('mode') != 'stdio':
             return False
@@ -104,7 +110,9 @@ async def initialize(self) -> None:
         if host_path:
             install_cmd = self.owner._detect_install_command(host_path)
             if install_cmd:
-                self.ap.logger.info(f'MCP server {self.server_name}: installing dependencies in Box with: {install_cmd}')
+                self.ap.logger.info(
+                    f'MCP server {self.server_name}: installing dependencies in Box with: {install_cmd}'
+                )
                 try:
                     result = await workspace.execute_raw(
                         install_cmd,
@@ -122,17 +130,20 @@ async def initialize(self) -> None:
             await workspace.start_managed_process(
                 self.server_config['command'],
                 self.server_config.get('args', []),
+                process_id=self.process_id,
                 env=self.server_config.get('env', {}),
             )
         except Exception:
             self.owner.error_phase = MCPSessionErrorPhase.PROCESS_START
             raise
 
         try:
-            websocket_url = workspace.get_managed_process_websocket_url()
+            websocket_url = workspace.get_managed_process_websocket_url(self.process_id)
             transport = await self.owner.exit_stack.enter_async_context(websocket_client(websocket_url))
             read_stream, write_stream = transport
-            self.owner.session = await self.owner.exit_stack.enter_async_context(ClientSession(read_stream, write_stream))
+            self.owner.session = await self.owner.exit_stack.enter_async_context(
+                ClientSession(read_stream, write_stream)
+            )
         except Exception:
             self.owner.error_phase = MCPSessionErrorPhase.RELAY_CONNECT
             raise
@@ -150,7 +161,7 @@ async def monitor_process_health(self) -> None:
         consecutive_errors = 0
         while not self.owner._shutdown_event.is_set():
             try:
-                info = await workspace.get_managed_process()
+                info = await workspace.get_managed_process(self.process_id)
                 if isinstance(info, dict):
                     status = info.get('status', '')
                 else:
@@ -173,10 +184,14 @@ async def cleanup_session(self) -> None:
         if not self.uses_box_stdio():
             return
 
-        try:
-            await self._build_workspace().cleanup()
-        except Exception as exc:
-            self.ap.logger.warning(f'Failed to cleanup Box session for MCP server {self.server_name}: {exc}')
+        # In the shared-session model, we do NOT delete the session itself.
+        # The managed process is cleaned up when it exits or when the Box
+        # runtime shuts down.  Deleting the session would kill all other
+        # MCP servers sharing the same container.
+        self.ap.logger.info(
+            f'MCP server {self.server_name}: process_id={self.process_id} cleanup complete '
+            f'(shared session {self.owner._build_box_session_id()} kept alive)'
+        )
 
     def rewrite_path(self, path: str, host_path: str | None) -> str:
         return rewrite_mounted_path(path, host_path)

src/langbot/templates/config.yaml

@@ -90,7 +90,7 @@ monitoring:
 box:
     profile: 'default'
     image: ''  # Custom sandbox container image. Leave empty to use the profile default (python:3.11-slim).
-    runtime_url: ''  # Action-RPC WebSocket URL of an external Box Runtime. Leave empty for auto-detection (stdio locally, Docker service in containers).
+    runtime_url: ''  # Base URL of an external Box Runtime (e.g. ws://localhost:5410). Leave empty for auto-detection (stdio locally, Docker service in containers).
     shared_host_root: './data/box'  # For Docker deployment, use '/workspaces'
     default_host_workspace: ''  # Defaults to '<shared_host_root>/default'
     allowed_host_mount_roots:  # Defaults to ['<shared_host_root>'] when left empty