Tools

Tools 模块定义 Beaver 可调用工具的规格、注册、选择和执行。它把内置工具与 MCP 工具统一成 provider tool schema，再把模型返回的 tool_calls 安全地执行成 tool result。

大模块流程

注册内置工具 + MCP wrapper
->
选择always + skill hints + embedding top-k
->
导出 schemaprovider function/tool schema
->
执行ToolExecutor 执行 tool_call
->
回填tool message + session event

小模块拆分

base

ToolSpec 描述 name、description、input schema、always flag；ToolContext 携带 workspace、session、user、services；ToolResult 统一 success/content/error。

工具实现暴露成 BaseTool 或 ObjectBackedTool。
ToolSpec 同时可转 MCP descriptor、provider schema、embedding candidate。
执行结果必须是 ToolResult，AgentLoop 再转成 provider tool message。

registry

ToolRegistry 是工具目录。EngineLoader 会注册内置工具，MCP manager connect_all 后也把外部 MCP 工具注册进来。

register tool spec 与 callable。
list_specs/list_always_specs/get_specs 供 ToolAssembler 使用。
export_selected_provider_schemas 输出本轮模型可见工具。

ToolAssembler

按 run 选择工具，不做 LLM prompt。选择顺序固定：always tools、配置里的默认 always names、activated skills 的 tool hints、embedding top-k。

先加入 registry.list_always_specs。
再加入默认 memory、session_search。
收集 activated skill 的 tool_hints 或 loader 中的 skill tool hints。
对剩余工具做 embedding retrieve，补充 top-k。

runtime executor

ToolExecutor 接收 provider 返回的 ToolCallRequest，查 registry，解析 arguments，传入 ToolContext，捕获异常并返回 ToolResult。

模型返回 tool_calls。
AgentLoop 序列化并记录 assistant tool call。
ToolExecutor 执行对应工具。
AgentLoop 把 result.content 追加为 role=tool message。

builtins

内置工具包括 terminal、filesystem、web、memory、session_search、skill_view、skills_admin、cron、utility、echo。它们覆盖本地开发、记忆、会话检索、skill 管理和定时任务。

工具从 ToolContext 取 workspace/services。
执行具体 IO 或服务动作。
返回文本结果，进入下一轮模型上下文。

mcp wrapper

把外部 MCP tool 适配成 Beaver ToolSpec/callable，使外部工具和内置工具对 AgentLoop 呈现同一种接口。

MCP manager connect_all。
为每个外部 tool 建 wrapper。
注册进 ToolRegistry，后续由 ToolAssembler 选择。