e2m2e.api.mcp.envelope

统一信封：MCP 传输层输出形状（ADR 0014 §4）。

所有工具调用的返回都包成 {status, data, error, meta}：成功时 status="ok"、data 为 Response 模型的 JSON 序列化；失败时 status="error"、error 为结构化错误（错误码 + message + details）。 异常在 api/ 边界翻译，不向 Agent 泄漏原始 traceback。

Attributes

Envelope

Functions

ok_envelope(→ Envelope)	构造成功信封。
error_envelope(→ Envelope)	构造失败信封。
tool_not_found(→ Envelope)	未知工具（placeholder 或未暴露的方法不注册）的失败信封。
dispatch_tool(→ tuple[Any, Envelope | None])	校验参数并执行工具方法，返回 (原始结果, None) 或 (None, 错误信封)。
invoke_tool(→ Envelope)	执行一个 Facade 工具方法并包成信封。

Module Contents

e2m2e.api.mcp.envelope.Envelope

e2m2e.api.mcp.envelope.ok_envelope(data: Any, meta: dict[str, Any] | None = None) → Envelope

构造成功信封。

e2m2e.api.mcp.envelope.error_envelope(code: str, message: str, details: dict[str, Any] | None = None) → Envelope

构造失败信封。

e2m2e.api.mcp.envelope.tool_not_found(name: str) → Envelope

未知工具（placeholder 或未暴露的方法不注册）的失败信封。

进程内（handle_call_tool）与 worker 子进程（run_request）同名同义： 消息单一来源，两边不漂移。

e2m2e.api.mcp.envelope.dispatch_tool(method: Any, arguments: dict[str, Any], *, extra_kwargs: dict[str, Any] | None = None) → tuple[Any, Envelope | None]

校验参数并执行工具方法，返回 (原始结果, None) 或 (None, 错误信封)。

与 invoke_tool() 同一套校验与错误翻译，但不做结果的 JSON 化—— 需要在转储前处理原始结果的传输层（如 sidecar 的二进制帧抽取，ADR 0035） 用这个。失败时返回错误信封，不抛异常。extra_kwargs 是传输层注入的 额外协作者（如进度回调），按方法签名过滤后并入调用关键字。

e2m2e.api.mcp.envelope.invoke_tool(method: Any, arguments: dict[str, Any], *, extra_kwargs: dict[str, Any] | None = None) → Envelope

执行一个 Facade 工具方法并包成信封。

入参经 request_model 校验（ValidationError → INVALID_PARAMS）， OrbitError 原样翻译，其余异常归为 ``INTERNAL_ERROR``（只保留异常类型 名，不泄漏 traceback）。校验与错误翻译见 dispatch_tool()。