feat: add generic sandbox provider framework

.gitignore

@@ -64,3 +64,4 @@ GenieData/
 .worktrees/
 
 dashboard/bun.lock
+docs/plans/

README_zh.md

@@ -47,9 +47,9 @@ AstrBot 是一个开源的一站式 Agentic 个人和群聊助手，可在 QQ、
 3. 🤖 支持接入 Dify、阿里云百炼、Coze 等智能体平台。
 4. 🌐 多平台，支持 QQ、企业微信、飞书、钉钉、微信公众号、Telegram、Slack 以及[更多](#支持的消息平台)。
 5. 📦 插件扩展，已有 1000+ 个插件可一键安装。
-6. 🛡️ [Agent Sandbox](https://docs.astrbot.app/use/astrbot-agent-sandbox.html) 隔离化环境，安全地执行任何代码、调用 Shell、会话级资源复用。
+6. 🛡️ [Agent Sandbox](https://docs.astrbot.app/use/astrbot-agent-sandbox.html) 提供隔离沙盒环境，支持安全执行代码、调用 Shell，并在会话内复用资源。
 7. 💻 WebUI 支持。
-8. 🌈 Web ChatUI 支持，ChatUI 内置代理沙盒、网页搜索等。
+8. 🌈 Web ChatUI 支持，内置 Agent Sandbox、网页搜索等能力。
 9. 🌐 国际化（i18n）支持。
 
 <br>

astrbot/core/agent/runners/tool_loop_agent_runner.py

@@ -146,6 +146,7 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
     REPEATED_TOOL_NOTICE_L1_THRESHOLD = 3
     REPEATED_TOOL_NOTICE_L2_THRESHOLD = 4
     REPEATED_TOOL_NOTICE_L3_THRESHOLD = 5
+    REPEATED_TOOL_NOTICE_EXEMPT_TOOL_NAMES = frozenset({"astrbot_execute_shell"})
     REPEATED_TOOL_NOTICE_L1_TEMPLATE = (
         "\n\n[SYSTEM NOTICE] By the way, you have executed the same tool "
         "`{tool_name}` {streak} times consecutively. Double-check whether another "
@@ -667,6 +668,9 @@ def _track_tool_call_streak(self, tool_name: str) -> int:
         return self._same_tool_streak
 
     def _build_repeated_tool_call_guidance(self, tool_name: str, streak: int) -> str:
+        if tool_name in self.REPEATED_TOOL_NOTICE_EXEMPT_TOOL_NAMES:
+            return ""
+
         if streak < self.REPEATED_TOOL_NOTICE_L1_THRESHOLD:
             return ""
 

astrbot/core/astr_agent_tool_exec.py

@@ -20,6 +20,7 @@
 from astrbot.core.astr_main_agent_resources import (
     BACKGROUND_TASK_RESULT_WOKE_SYSTEM_PROMPT,
 )
+from astrbot.core.computer.sandbox_tool_binding import tool_available_in_runtime
 from astrbot.core.cron.events import CronMessageEvent
 from astrbot.core.message.components import Image
 from astrbot.core.message.message_event_result import (
@@ -31,9 +32,6 @@
 from astrbot.core.provider.entites import ProviderRequest
 from astrbot.core.provider.register import llm_tools
 from astrbot.core.tools.computer_tools import (
-    CuaKeyboardTypeTool,
-    CuaMouseClickTool,
-    CuaScreenshotTool,
     ExecuteShellTool,
     FileDownloadTool,
     FileEditTool,
@@ -43,15 +41,27 @@
     GrepTool,
     LocalPythonTool,
     PythonTool,
+    SandboxLifecycleTool,
+    SandboxOperationTool,
+    SandboxQueryTool,
 )
 from astrbot.core.tools.message_tools import SendMessageToUserTool
+from astrbot.core.tools.registry import get_builtin_tool_config_rule
 from astrbot.core.utils.astrbot_path import get_astrbot_temp_path
 from astrbot.core.utils.history_saver import persist_agent_history
 from astrbot.core.utils.image_ref_utils import is_supported_image_ref
 from astrbot.core.utils.string_utils import normalize_and_dedupe_strings
 
 
 class FunctionToolExecutor(BaseFunctionToolExecutor[AstrAgentContext]):
+    _runtime_computer_tools_cache: dict[
+        tuple[int, str, str], dict[str, FunctionTool]
+    ] = {}
+
+    @classmethod
+    def clear_runtime_computer_tools_cache(cls, provider_id: str | None = None) -> None:
+        cls._runtime_computer_tools_cache.clear()
+
     @classmethod
     def _collect_image_urls_from_args(cls, image_urls_raw: T.Any) -> list[str]:
         if image_urls_raw is None:
@@ -192,8 +202,14 @@ def _get_runtime_computer_tools(
         booter: str | None = None,
     ) -> dict[str, FunctionTool]:
         booter = "" if booter is None else str(booter).lower()
+        cache_key = (id(tool_mgr), runtime, booter)
+        if cache_key in cls._runtime_computer_tools_cache:
+            return cls._runtime_computer_tools_cache[cache_key]
         if runtime == "sandbox":
             shell_tool = tool_mgr.get_builtin_tool(ExecuteShellTool)
+            sandbox_query_tool = tool_mgr.get_builtin_tool(SandboxQueryTool)
+            sandbox_lifecycle_tool = tool_mgr.get_builtin_tool(SandboxLifecycleTool)
+            sandbox_operation_tool = tool_mgr.get_builtin_tool(SandboxOperationTool)
             python_tool = tool_mgr.get_builtin_tool(PythonTool)
             upload_tool = tool_mgr.get_builtin_tool(FileUploadTool)
             download_tool = tool_mgr.get_builtin_tool(FileDownloadTool)
@@ -203,6 +219,9 @@ def _get_runtime_computer_tools(
             grep_tool = tool_mgr.get_builtin_tool(GrepTool)
             tools = {
                 shell_tool.name: shell_tool,
+                sandbox_query_tool.name: sandbox_query_tool,
+                sandbox_lifecycle_tool.name: sandbox_lifecycle_tool,
+                sandbox_operation_tool.name: sandbox_operation_tool,
                 python_tool.name: python_tool,
                 upload_tool.name: upload_tool,
                 download_tool.name: download_tool,
@@ -211,17 +230,7 @@ def _get_runtime_computer_tools(
                 edit_tool.name: edit_tool,
                 grep_tool.name: grep_tool,
             }
-            if booter == "cua":
-                screenshot_tool = tool_mgr.get_builtin_tool(CuaScreenshotTool)
-                mouse_click_tool = tool_mgr.get_builtin_tool(CuaMouseClickTool)
-                keyboard_type_tool = tool_mgr.get_builtin_tool(CuaKeyboardTypeTool)
-                tools.update(
-                    {
-                        screenshot_tool.name: screenshot_tool,
-                        mouse_click_tool.name: mouse_click_tool,
-                        keyboard_type_tool.name: keyboard_type_tool,
-                    }
-                )
+            cls._runtime_computer_tools_cache[cache_key] = tools
             return tools
         if runtime == "local":
             shell_tool = tool_mgr.get_builtin_tool(ExecuteShellTool)
@@ -230,16 +239,37 @@ def _get_runtime_computer_tools(
             write_tool = tool_mgr.get_builtin_tool(FileWriteTool)
             edit_tool = tool_mgr.get_builtin_tool(FileEditTool)
             grep_tool = tool_mgr.get_builtin_tool(GrepTool)
-            return {
+            tools = {
                 shell_tool.name: shell_tool,
                 python_tool.name: python_tool,
                 read_tool.name: read_tool,
                 write_tool.name: write_tool,
                 edit_tool.name: edit_tool,
                 grep_tool.name: grep_tool,
             }
+            cls._runtime_computer_tools_cache[cache_key] = tools
+            return tools
         return {}
 
+    @staticmethod
+    def _tool_available_for_runtime_config(tool: FunctionTool, runtime: str) -> bool:
+        if not tool_available_in_runtime(tool, runtime):
+            return False
+        rule = get_builtin_tool_config_rule(tool.name)
+        if rule is None:
+            return True
+        conditions = rule.evaluate(
+            {"provider_settings": {"computer_use_runtime": runtime}}
+        )
+        runtime_conditions = [
+            condition
+            for condition in conditions
+            if str(condition.get("key")) == "provider_settings.computer_use_runtime"
+        ]
+        if not runtime_conditions:
+            return True
+        return all(bool(condition.get("matched")) for condition in runtime_conditions)
+
     @classmethod
     def _build_handoff_toolset(
         cls,
@@ -259,17 +289,18 @@ def _build_handoff_toolset(
         runtime_computer_tools = cls._get_runtime_computer_tools(
             runtime,
             tool_mgr,
-            provider_settings.get("sandbox", {}).get("booter"),
         )
 
         # Keep persona semantics aligned with the main agent: tools=None means
         # "all tools", including runtime computer-use tools.
         if tools is None:
             toolset = ToolSet()
-            for registered_tool in llm_tools.func_list:
+            for registered_tool in getattr(tool_mgr, "func_list", llm_tools.func_list):
                 if isinstance(registered_tool, HandoffTool):
                     continue
-                if registered_tool.active:
+                if registered_tool.active and cls._tool_available_for_runtime_config(
+                    registered_tool, runtime
+                ):
                     toolset.add_tool(registered_tool)
             for runtime_tool in runtime_computer_tools.values():
                 toolset.add_tool(runtime_tool)
@@ -281,14 +312,20 @@ def _build_handoff_toolset(
         toolset = ToolSet()
         for tool_name_or_obj in tools:
             if isinstance(tool_name_or_obj, str):
-                registered_tool = llm_tools.get_func(tool_name_or_obj)
-                if registered_tool and registered_tool.active:
+                registered_tool = tool_mgr.get_func(tool_name_or_obj)
+                if (
+                    registered_tool
+                    and registered_tool.active
+                    and cls._tool_available_for_runtime_config(registered_tool, runtime)
+                ):
                     toolset.add_tool(registered_tool)
                     continue
                 runtime_tool = runtime_computer_tools.get(tool_name_or_obj)
                 if runtime_tool:
                     toolset.add_tool(runtime_tool)
-            elif isinstance(tool_name_or_obj, FunctionTool):
+            elif isinstance(
+                tool_name_or_obj, FunctionTool
+            ) and cls._tool_available_for_runtime_config(tool_name_or_obj, runtime):
                 toolset.add_tool(tool_name_or_obj)
         return None if toolset.empty() else toolset
 
@@ -538,11 +575,16 @@ async def _wake_main_agent_for_background_result(
             message_type=session.message_type,
         )
         cron_event.role = event.role
+        session_config = ctx.get_config(umo=event.unified_msg_origin)
+        provider_settings = session_config.get("provider_settings", {})
         config = MainAgentBuildConfig(
             tool_call_timeout=run_context.tool_call_timeout,
-            streaming_response=ctx.get_config()
-            .get("provider_settings", {})
-            .get("stream", False),
+            streaming_response=provider_settings.get("stream", False),
+            computer_use_runtime=str(
+                provider_settings.get("computer_use_runtime", "local")
+            ),
+            sandbox_cfg=provider_settings.get("sandbox", {}),
+            provider_settings=provider_settings,
         )
 
         req = ProviderRequest()