feat(box): add sandbox_exec tool loop for local-agent calculations

src/langbot/pkg/provider/runner.py

@@ -3,7 +3,8 @@ from __future__ import annotations
 import abc
 import typing
 
-from ..core import app
+if typing.TYPE_CHECKING:
+    from ..core import app
 
 
 preregistered_runners: list[typing.Type[RequestRunner]] = []
@@ -25,11 +26,11 @@ class RequestRunner(abc.ABC):
 
     name: str = None
 
-    ap: app.Application
+    ap: 'app.Application'
 
     pipeline_config: dict
 
-    def __init__(self, ap: app.Application, pipeline_config: dict):
+    def __init__(self, ap: 'app.Application', pipeline_config: dict):
         self.ap = ap
         self.pipeline_config = pipeline_config
 

src/langbot/pkg/provider/runners/localagent.py

@@ -24,11 +24,37 @@ Respond in the same language as the user's input.
 </user_message>
 """
 
+SANDBOX_EXEC_TOOL_NAME = 'sandbox_exec'
+SANDBOX_EXEC_SYSTEM_GUIDANCE = (
+    'When sandbox_exec is available, use it for exact calculations, statistics, structured data parsing, '
+    'and code execution instead of estimating mentally. If the user provides numbers, tables, CSV-like text, '
+    'JSON, or other data and asks for a computed answer, prefer running a short Python script in sandbox_exec '
+    'and then answer from the tool result.'
+)
+
 
 @runner.runner_class('local-agent')
 class LocalAgentRunner(runner.RequestRunner):
     """Local agent request runner"""
 
+    def _build_request_messages(
+        self,
+        query: pipeline_query.Query,
+        user_message: provider_message.Message,
+    ) -> list[provider_message.Message]:
+        req_messages = query.prompt.messages.copy() + query.messages.copy()
+
+        if any(getattr(tool, 'name', None) == SANDBOX_EXEC_TOOL_NAME for tool in query.use_funcs or []):
+            req_messages.append(
+                provider_message.Message(
+                    role='system',
+                    content=SANDBOX_EXEC_SYSTEM_GUIDANCE,
+                )
+            )
+
+        req_messages.append(user_message)
+        return req_messages
+
     async def _get_model_candidates(
         self,
         query: pipeline_query.Query,
@@ -236,7 +262,7 @@ class LocalAgentRunner(runner.RequestRunner):
                     ce.text = final_user_message_text
                     break
 
-        req_messages = query.prompt.messages.copy() + query.messages.copy() + [user_message]
+        req_messages = self._build_request_messages(query, user_message)
 
         try:
             is_stream = await query.adapter.is_stream_output_supported()

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

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import langbot_plugin.api.entities.builtin.resource.tool as resource_tool
+from langbot_plugin.api.entities.events import pipeline_query
+
+from .. import loader
+
+
+class NativeToolLoader(loader.ToolLoader):
+    SANDBOX_EXEC_TOOL_NAME = 'sandbox_exec'
+
+    async def get_tools(self, bound_plugins: list[str] | None = None) -> list[resource_tool.LLMTool]:
+        return [self._build_sandbox_exec_tool()]
+
+    async def has_tool(self, name: str) -> bool:
+        return name == self.SANDBOX_EXEC_TOOL_NAME
+
+    async def invoke_tool(self, name: str, parameters: dict, query: pipeline_query.Query):
+        if name != self.SANDBOX_EXEC_TOOL_NAME:
+            raise ValueError(f'未找到工具: {name}')
+        return await self.ap.box_service.execute_sandbox_tool(parameters, query)
+
+    async def shutdown(self):
+        if getattr(self.ap, 'box_service', None) is not None:
+            await self.ap.box_service.shutdown()
+
+    def _build_sandbox_exec_tool(self) -> resource_tool.LLMTool:
+        return resource_tool.LLMTool(
+            name=self.SANDBOX_EXEC_TOOL_NAME,
+            human_desc='Execute a command inside the LangBot Box sandbox',
+            description=(
+                'Run shell commands only inside the isolated LangBot Box sandbox. '
+                'Use this tool for local file edits, bash commands, Python execution, and exact calculations over '
+                'user-provided data that must not touch the host.'
+            ),
+            parameters={
+                'type': 'object',
+                'properties': {
+                    'cmd': {
+                        'type': 'string',
+                        'description': 'Shell command to execute inside the sandbox.',
+                    },
+                    'workdir': {
+                        'type': 'string',
+                        'description': 'Absolute working directory path inside the sandbox. Defaults to /workspace.',
+                        'default': '/workspace',
+                    },
+                    'timeout_sec': {
+                        'type': 'integer',
+                        'description': 'Execution timeout in seconds. Defaults to 30.',
+                        'default': 30,
+                        'minimum': 1,
+                    },
+                    'network': {
+                        'type': 'string',
+                        'description': 'Network policy for the sandbox session. Prefer off unless network is required.',
+                        'enum': ['off', 'on'],
+                        'default': 'off',
+                    },
+                    'session_id': {
+                        'type': 'string',
+                        'description': 'Optional sandbox session id. Defaults to the current request id for reuse.',
+                    },
+                    'env': {
+                        'type': 'object',
+                        'description': 'Optional environment variables to expose inside the sandbox.',
+                        'additionalProperties': {'type': 'string'},
+                        'default': {},
+                    },
+                },
+                'required': ['cmd'],
+                'additionalProperties': False,
+            },
+            func=lambda parameters: parameters,
+        )

src/langbot/pkg/provider/tools/toolmgr.py

@@ -5,7 +5,7 @@ import typing
 from ...core import app
 from langbot.pkg.utils import importutil
 from langbot.pkg.provider.tools import loaders
-from langbot.pkg.provider.tools.loaders import mcp as mcp_loader, plugin as plugin_loader
+from langbot.pkg.provider.tools.loaders import mcp as mcp_loader, native as native_loader, plugin as plugin_loader
 import langbot_plugin.api.entities.builtin.resource.tool as resource_tool
 from langbot_plugin.api.entities.events import pipeline_query
 
@@ -17,6 +17,7 @@ class ToolManager:
 
     ap: app.Application
 
+    native_tool_loader: native_loader.NativeToolLoader
     plugin_tool_loader: plugin_loader.PluginToolLoader
     mcp_tool_loader: mcp_loader.MCPLoader
 
@@ -24,6 +25,8 @@ class ToolManager:
         self.ap = ap
 
     async def initialize(self):
+        self.native_tool_loader = native_loader.NativeToolLoader(self.ap)
+        await self.native_tool_loader.initialize()
         self.plugin_tool_loader = plugin_loader.PluginToolLoader(self.ap)
         await self.plugin_tool_loader.initialize()
         self.mcp_tool_loader = mcp_loader.MCPLoader(self.ap)
@@ -35,6 +38,7 @@ class ToolManager:
         """获取所有函数"""
         all_functions: list[resource_tool.LLMTool] = []
 
+        all_functions.extend(await self.native_tool_loader.get_tools())
         all_functions.extend(await self.plugin_tool_loader.get_tools(bound_plugins))
         all_functions.extend(await self.mcp_tool_loader.get_tools(bound_mcp_servers))
 
@@ -95,7 +99,9 @@ class ToolManager:
     async def execute_func_call(self, name: str, parameters: dict, query: pipeline_query.Query) -> typing.Any:
         """执行函数调用"""
 
-        if await self.plugin_tool_loader.has_tool(name):
+        if await self.native_tool_loader.has_tool(name):
+            return await self.native_tool_loader.invoke_tool(name, parameters, query)
+        elif await self.plugin_tool_loader.has_tool(name):
             return await self.plugin_tool_loader.invoke_tool(name, parameters, query)
         elif await self.mcp_tool_loader.has_tool(name):
             return await self.mcp_tool_loader.invoke_tool(name, parameters, query)
@@ -104,5 +110,6 @@ class ToolManager:
 
     async def shutdown(self):
         """关闭所有工具"""
+        await self.native_tool_loader.shutdown()
         await self.plugin_tool_loader.shutdown()
         await self.mcp_tool_loader.shutdown()