Appearance
外部能力适配：MCP 与 Workspace / Sandbox
前置：Trace、Eval 和 OpenTelemetry 怎样共用同一条 Run Identity
核心问题：MCP 远端 Tool 和本地 Workspace Tool 实现完全不同，怎样通过 Adapter 让 Runtime 只看到统一 Contract？
MCP Server 和本地 Sandbox 看起来完全不同：一个是远程协议，一个是本地/容器执行环境。但对 Runtime 来说，它们都应该停在 adapter 边界，不能把 SDK session、transport connection 或具体 sandbox provider 对象泄漏进 domain layer。
MCP Adapter
Module 15 定义 MCP 协议语义。这里的 adapter 只做 protocol↔domain mapping：把 discovery 结果映射到内部 Tool/Resource metadata，把 call/error/trace context 映射回 ToolExecutionResult。
Runtime 不依赖 MCP SDK/session object；协议版本变化只更新 adapter/conformance tests。
一个最小内部边界可以长这样：
python
class CapabilityExecutor(Protocol):
async def execute(self, call: ToolCall, ctx: ExecutionContext) -> ToolExecutionResult: ...MCPToolExecutor、WorkspaceToolExecutor、本地 function tool 都实现这个 contract；连接、session、sandbox handle 只存在各自 adapter 内部。Runtime 因此只处理统一的 operation identity、结果和错误，而不需要知道能力来自远端协议还是本地工作区。
🔍 源码对照：MCP 只做 Internal Tool ↔ Protocol 的转换
完整源码与通用分析见 06-04 Tool Search / Execution Pipeline。这里不重复代码；这里关注 Adapter integration：MCP、Workspace 与 Local Tool 共用内部 Executor Contract，各 Adapter 只负责边界转换与自身资源生命周期。
源码说明
MCP bridge 与 box/local-exec 的并列最能体现 Adapter 思维：前者把“远端/插件能力”翻译成 Tool protocol，后者把“文件/进程能力”翻译成 execution environment。Core Runtime 只应该理解 ToolCall、Observation、Capability、Workspace reference，不应该知道 MCP JSON-RPC 或 Docker/daemon 细节。
工程边界
同一个产品把这些适配器放在哪个进程不是核心；Shadow Harness 第一版可以全部 in-process，只要 dependency direction 正确。
Shadow Harness 对照
MCPAdapter与WorkspaceAdapter都实现 domain-defined Protocol，而不是让 Runtime import vendor SDK。- Adapter error 统一映射 domain error，同时保留 provider-specific diagnostic metadata。
验证
用 FakeMCPAdapter 和 LocalWorkspaceAdapter 替换真实实现，Run loop 的测试代码不变；再注入协议错误和 filesystem error，验证 domain error 分类保持稳定。
Workspace / Sandbox Adapter
Workspace Adapter 提供 read/search/patch/shell/artifact 等标准接口，Sandbox Adapter 管执行环境生命周期、capability 和 snapshot。二者避免 Runtime 直接绑具体 provider。
两种 Adapter 最终都收敛成同一种 Tool 语义
远程 MCP Tool 和本地 Workspace Tool 的执行环境完全不同：
text
MCP: JSON-RPC / auth / remote server / network failure
Workspace: filesystem / shell / sandbox / process failure但 Runtime 最好只看到统一结果：
python
ToolResult(
call_id="tc-9",
status="SUCCEEDED",
output_ref="artifact://...",
retryable=False,
metadata={...},
)MCP Adapter 负责 protocol/remote error normalization，Workspace Adapter 负责 sandbox/process/artifact normalization。权限决策也在进入真实执行环境前完成。这样 Scheduler 不需要写 if mcp ... elif shell ...，新增 Browser Adapter 时也不用修改 Run State Machine。
Failure Modes
Adapter 泄漏具体 SDK / Session 对象
症状： Runtime 直接保存 MCP session、provider-specific sandbox handle 或 transport connection。
为什么危险： 协议/执行环境切换会扩散到 domain；resume 还可能尝试恢复不可序列化的瞬态对象。
处理： Runtime 只依赖内部 Tool/Workspace/Sandbox port；连接和 SDK 对象只存在 adapter 生命周期内。
如何验证
| Case | 断言 |
|---|---|
| 替换 MCP / Sandbox provider | Runtime、Scheduler、StateStore 测试无需修改；resume 只重建 adapter 瞬态资源。 |
关联源码
自测
- MCP Tool 与本地 Workspace Tool 都是外部能力，为什么 Runtime 应看到统一 contract，而不是两套协议对象？
- Workspace 有文件权限、MCP 有协议能力；Adapter 统一接口后，安全 policy 为什么仍不能被“统一掉”？