sycommon-python-lib 0.2.1a28__tar.gz → 0.2.1a30__tar.gz

{sycommon_python_lib-0.2.1a28 → sycommon_python_lib-0.2.1a30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sycommon-python-lib
-Version: 0.2.1a28
+Version: 0.2.1a30
 Summary: Add your description here
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{sycommon_python_lib-0.2.1a28 → sycommon_python_lib-0.2.1a30}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sycommon-python-lib"
-version = "0.2.1a28"
+version = "0.2.1a30"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.11"

{sycommon_python_lib-0.2.1a28 → sycommon_python_lib-0.2.1a30}/src/sycommon/agent/sandbox/http_sandbox_backend.py

@@ -342,6 +342,110 @@ class HTTPSandboxBackend(FileOperationsMixin, SandboxBackendProtocol):
         """异步执行 shell 命令"""
         return await asyncio.to_thread(self.execute, command, timeout=timeout)
 
+    # ============== 后台进程执行 ==============
+
+    def execute_background(self, command: str, *, timeout: int = 600) -> dict:
+        """后台执行 shell 命令（不阻塞，立即返回 process_id）
+
+        适用于长时间运行的服务（如 uvicorn、FastAPI 等）
+
+        Args:
+            command: 要执行的命令
+            timeout: 命令超时时间（秒），默认 600 秒
+
+        Returns:
+            dict: {"process_id": str, "status": "started"}
+
+        Example:
+            # 启动后台服务
+            result = backend.execute_background("uvicorn main:app --host 0.0.0.0 --port 8000")
+            process_id = result["process_id"]
+
+            # 稍后检查状态
+            status = backend.check_process(process_id)
+            if status["status"] == "running":
+                print("服务正在运行...")
+
+            # 需要时终止进程
+            backend.kill_process(process_id)
+        """
+        self._ensure_synced_sync()
+        SYLogger.info(f"[Sandbox] 后台执行: {command}")
+        try:
+            result = self._post_sync(f"{SANDBOX_API_PREFIX}/execute_background", {
+                "command": command,
+                "user_id": self._user_id,
+                "timeout": timeout
+            })
+            SYLogger.info(f"[Sandbox] 后台进程已启动: process_id={result['process_id']}")
+            return result
+        except Exception as e:
+            SYLogger.error(f"[Sandbox] 后台执行失败: {e}")
+            return {"process_id": None, "status": "error", "error": str(e)}
+
+    async def aexecute_background(self, command: str, *, timeout: int = 600) -> dict:
+        """异步后台执行 shell 命令"""
+        return await asyncio.to_thread(self.execute_background, command, timeout=timeout)
+
+    def check_process(self, process_id: str) -> dict:
+        """检查后台进程状态
+
+        Args:
+            process_id: execute_background 返回的进程 ID
+
+        Returns:
+            dict: {
+                "process_id": str,
+                "status": "running" | "completed" | "timeout" | "error" | "not_found",
+                "exit_code": int | None,
+                "output": str | None,  # 仅在进程结束时返回
+                "truncated": bool,
+                "command": str | None,
+                "started_at": str | None
+            }
+        """
+        try:
+            result = self._post_sync(f"{SANDBOX_API_PREFIX}/process_status", {
+                "process_id": process_id,
+                "user_id": self._user_id
+            })
+            return result
+        except Exception as e:
+            SYLogger.error(f"[Sandbox] 检查进程失败: {e}")
+            return {"process_id": process_id, "status": "error", "error": str(e)}
+
+    async def acheck_process(self, process_id: str) -> dict:
+        """异步检查后台进程状态"""
+        return await asyncio.to_thread(self.check_process, process_id)
+
+    def kill_process(self, process_id: str) -> dict:
+        """终止后台进程
+
+        Args:
+            process_id: execute_background 返回的进程 ID
+
+        Returns:
+            dict: {
+                "process_id": str,
+                "status": "killed" | "not_found" | "already_completed",
+                "output": str | None  # 进程截止到被杀死时的输出
+            }
+        """
+        try:
+            result = self._post_sync(f"{SANDBOX_API_PREFIX}/kill_process", {
+                "process_id": process_id,
+                "user_id": self._user_id
+            })
+            SYLogger.info(f"[Sandbox] 进程终止: {process_id}, status={result['status']}")
+            return result
+        except Exception as e:
+            SYLogger.error(f"[Sandbox] 终止进程失败: {e}")
+            return {"process_id": process_id, "status": "error", "error": str(e)}
+
+    async def akill_process(self, process_id: str) -> dict:
+        """异步终止后台进程"""
+        return await asyncio.to_thread(self.kill_process, process_id)
+
     # ============== 批量操作 ==============
 
     def upload_files(self, files: List[tuple[str, bytes]]) -> List[FileUploadResponse]:

sycommon_python_lib-0.2.1a30/src/sycommon/middleware/background_execution.py

@@ -0,0 +1,449 @@
+"""
+后台执行中间件
+
+为 deepagents 添加后台进程执行工具：
+- execute_background: 后台启动进程，立即返回 process_id
+- check_process: 检查进程状态
+- kill_process: 终止进程
+
+使用方式：
+    from deepagents import create_deep_agent
+    from sycommon.middleware.background_execution import BackgroundExecutionMiddleware
+
+    agent = create_deep_agent(
+        model=model,
+        backend=sandbox_backend,
+        middleware=[BackgroundExecutionMiddleware()],
+    )
+"""
+
+from collections.abc import Awaitable, Callable
+from typing import Annotated, Any, NotRequired
+
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    AgentState,
+    ContextT,
+    ModelRequest,
+    ModelResponse,
+    ResponseT,
+)
+from langchain_core.tools import BaseTool, StructuredTool
+from langchain.tools import ToolRuntime
+
+from deepagents.backends.protocol import BackendProtocol, SandboxBackendProtocol
+
+
+class BackgroundExecutionState(AgentState):
+    """后台执行中间件的状态"""
+    pass
+
+
+# 工具描述
+EXECUTE_BACKGROUND_DESCRIPTION = """在后台启动一个长时间运行的命令（不阻塞）。
+
+适用于启动需要持续运行的服务，如 Web 服务器、数据库等。
+
+使用方式：
+- command: 要执行的 shell 命令
+- timeout: 命令最大运行时间（秒），默认 600 秒
+
+返回：
+- process_id: 进程 ID，用于后续检查状态或终止进程
+- status: "started" 表示启动成功
+
+示例：
+    # 后台启动 FastAPI 服务
+    result = execute_background(command="uvicorn main:app --host 0.0.0.0 --port 8000")
+    process_id = result["process_id"]
+
+    # 等待服务启动后测试
+    execute(command="sleep 3 && curl http://localhost:8000/health")
+
+    # 完成后终止进程
+    kill_process(process_id=process_id)
+
+注意：启动服务后务必记住 process_id，并在完成后调用 kill_process 终止进程。"""
+
+
+CHECK_PROCESS_DESCRIPTION = """检查后台进程的运行状态。
+
+参数：
+- process_id: execute_background 返回的进程 ID
+
+返回：
+- status: "running"（运行中）、"completed"（已完成）、"timeout"（超时）、"not_found"（未找到）
+- exit_code: 退出码（仅进程结束时）
+- output: 进程输出（仅进程结束时）
+
+示例：
+    status = check_process(process_id="abc123")
+    if status["status"] == "running":
+        print("服务正在运行...")
+    elif status["status"] == "completed":
+        print(f"服务已结束，退出码: {status['exit_code']}")
+        print(f"输出: {status['output']}")"""
+
+
+KILL_PROCESS_DESCRIPTION = """终止一个后台进程。
+
+参数：
+- process_id: 要终止的进程 ID
+
+返回：
+- status: "killed"（已终止）、"not_found"（未找到）、"already_completed"（已完成）
+- output: 进程截止到被终止时的输出
+
+示例：
+    result = kill_process(process_id="abc123")
+    if result["status"] == "killed":
+        print("进程已终止")
+        print(f"最终输出: {result['output']}")"""
+
+
+BACKGROUND_EXECUTION_SYSTEM_PROMPT = """## 后台执行工具
+
+你可以使用以下工具来管理长时间运行的进程：
+
+- execute_background: 在后台启动命令（不阻塞），返回 process_id
+- check_process: 检查后台进程的状态
+- kill_process: 终止后台进程
+
+### 使用场景
+
+当需要启动长时间运行的服务（如 Web 服务器、数据库）时：
+1. 使用 execute_background 启动服务，获取 process_id
+2. 使用 check_process 检查服务状态
+3. 完成后使用 kill_process 终止服务
+
+### 重要提示
+
+- 每次启动服务都会产生新的 process_id，请务必记住它
+- 服务会持续运行直到被终止或超时
+- 测试完成后必须调用 kill_process 清理资源"""
+
+
+def _supports_background_execution(backend: BackendProtocol) -> bool:
+    """检查 backend 是否支持后台执行"""
+    return (
+        isinstance(backend, SandboxBackendProtocol)
+        and hasattr(backend, 'execute_background')
+        and hasattr(backend, 'check_process')
+        and hasattr(backend, 'kill_process')
+    )
+
+
+class BackgroundExecutionMiddleware(AgentMiddleware[BackgroundExecutionState, ContextT, ResponseT]):
+    """后台执行中间件
+
+    为 deepagents 添加后台进程管理工具。如果 backend 实现了
+    execute_background、check_process、kill_process 方法，则添加这些工具。
+
+    Args:
+        backend: 后端实例或工厂函数。如果为 None，则从 runtime 获取。
+
+    Example:
+        ```python
+        from sycommon.middleware.background_execution import BackgroundExecutionMiddleware
+        from deepagents import create_deep_agent
+
+        agent = create_deep_agent(
+            model=model,
+            backend=sandbox_backend,
+            middleware=[BackgroundExecutionMiddleware()],
+        )
+        ```
+    """
+
+    state_schema = BackgroundExecutionState
+
+    def __init__(
+        self,
+        *,
+        backend: Any = None,
+    ) -> None:
+        """初始化后台执行中间件
+
+        Args:
+            backend: 后端实例或工厂函数。如果为 None，从 ToolRuntime 获取。
+        """
+        self._backend = backend
+
+        # 预创建工具（会在 wrap_model_call 中根据 backend 能力过滤）
+        self.tools = [
+            self._create_execute_background_tool(),
+            self._create_check_process_tool(),
+            self._create_kill_process_tool(),
+        ]
+
+    def _get_backend(self, runtime: ToolRuntime) -> BackendProtocol:
+        """获取 backend 实例"""
+        if self._backend is None:
+            # 从 runtime 获取 backend
+            return runtime.config.get("configurable", {}).get("backend")
+        if callable(self._backend):
+            return self._backend(runtime)
+        return self._backend
+
+    def _create_execute_background_tool(self) -> BaseTool:
+        """创建 execute_background 工具"""
+
+        def sync_execute_background(
+            command: Annotated[str, "要在后台执行的 shell 命令"],
+            runtime: ToolRuntime[None, BackgroundExecutionState],
+            timeout: Annotated[int, "命令最大运行时间（秒），默认 600 秒"] = 600,
+        ) -> str:
+            backend = self._get_backend(runtime)
+
+            if not _supports_background_execution(backend):
+                return "Error: 后台执行不可用。请确保 backend 实现了 execute_background 方法。"
+
+            try:
+                result = backend.execute_background(command, timeout=timeout)
+                process_id = result.get("process_id", "")
+                status = result.get("status", "unknown")
+
+                if result.get("error"):
+                    return f"Error: {result['error']}"
+
+                return f"进程已启动\nprocess_id: {process_id}\nstatus: {status}"
+            except Exception as e:
+                return f"Error: {type(e).__name__}: {e}"
+
+        async def async_execute_background(
+            command: Annotated[str, "要在后台执行的 shell 命令"],
+            runtime: ToolRuntime[None, BackgroundExecutionState],
+            timeout: Annotated[int, "命令最大运行时间（秒），默认 600 秒"] = 600,
+        ) -> str:
+            backend = self._get_backend(runtime)
+
+            if not _supports_background_execution(backend):
+                return "Error: 后台执行不可用。请确保 backend 实现了 execute_background 方法。"
+
+            try:
+                result = await backend.aexecute_background(command, timeout=timeout)
+                process_id = result.get("process_id", "")
+                status = result.get("status", "unknown")
+
+                if result.get("error"):
+                    return f"Error: {result['error']}"
+
+                return f"进程已启动\nprocess_id: {process_id}\nstatus: {status}"
+            except Exception as e:
+                return f"Error: {type(e).__name__}: {e}"
+
+        return StructuredTool.from_function(
+            name="execute_background",
+            description=EXECUTE_BACKGROUND_DESCRIPTION,
+            func=sync_execute_background,
+            coroutine=async_execute_background,
+        )
+
+    def _create_check_process_tool(self) -> BaseTool:
+        """创建 check_process 工具"""
+
+        def sync_check_process(
+            process_id: Annotated[str, "要检查的进程 ID"],
+            runtime: ToolRuntime[None, BackgroundExecutionState],
+        ) -> str:
+            backend = self._get_backend(runtime)
+
+            if not _supports_background_execution(backend):
+                return "Error: 后台执行不可用。"
+
+            try:
+                result = backend.check_process(process_id)
+                status = result.get("status", "unknown")
+
+                output_lines = [f"进程状态: {status}"]
+
+                if result.get("exit_code") is not None:
+                    output_lines.append(f"退出码: {result['exit_code']}")
+
+                if result.get("command"):
+                    output_lines.append(f"命令: {result['command']}")
+
+                if result.get("started_at"):
+                    output_lines.append(f"启动时间: {result['started_at']}")
+
+                if result.get("output"):
+                    output = result["output"]
+                    if len(output) > 2000:
+                        output = output[:2000] + "\n... [输出已截断]"
+                    output_lines.append(f"输出:\n{output}")
+
+                return "\n".join(output_lines)
+            except Exception as e:
+                return f"Error: {type(e).__name__}: {e}"
+
+        async def async_check_process(
+            process_id: Annotated[str, "要检查的进程 ID"],
+            runtime: ToolRuntime[None, BackgroundExecutionState],
+        ) -> str:
+            backend = self._get_backend(runtime)
+
+            if not _supports_background_execution(backend):
+                return "Error: 后台执行不可用。"
+
+            try:
+                result = await backend.acheck_process(process_id)
+                status = result.get("status", "unknown")
+
+                output_lines = [f"进程状态: {status}"]
+
+                if result.get("exit_code") is not None:
+                    output_lines.append(f"退出码: {result['exit_code']}")
+
+                if result.get("command"):
+                    output_lines.append(f"命令: {result['command']}")
+
+                if result.get("started_at"):
+                    output_lines.append(f"启动时间: {result['started_at']}")
+
+                if result.get("output"):
+                    output = result["output"]
+                    if len(output) > 2000:
+                        output = output[:2000] + "\n... [输出已截断]"
+                    output_lines.append(f"输出:\n{output}")
+
+                return "\n".join(output_lines)
+            except Exception as e:
+                return f"Error: {type(e).__name__}: {e}"
+
+        return StructuredTool.from_function(
+            name="check_process",
+            description=CHECK_PROCESS_DESCRIPTION,
+            func=sync_check_process,
+            coroutine=async_check_process,
+        )
+
+    def _create_kill_process_tool(self) -> BaseTool:
+        """创建 kill_process 工具"""
+
+        def sync_kill_process(
+            process_id: Annotated[str, "要终止的进程 ID"],
+            runtime: ToolRuntime[None, BackgroundExecutionState],
+        ) -> str:
+            backend = self._get_backend(runtime)
+
+            if not _supports_background_execution(backend):
+                return "Error: 后台执行不可用。"
+
+            try:
+                result = backend.kill_process(process_id)
+                status = result.get("status", "unknown")
+
+                output_lines = [f"进程终止结果: {status}"]
+
+                if result.get("output"):
+                    output = result["output"]
+                    if len(output) > 1000:
+                        output = output[:1000] + "\n... [输出已截断]"
+                    output_lines.append(f"最终输出:\n{output}")
+
+                return "\n".join(output_lines)
+            except Exception as e:
+                return f"Error: {type(e).__name__}: {e}"
+
+        async def async_kill_process(
+            process_id: Annotated[str, "要终止的进程 ID"],
+            runtime: ToolRuntime[None, BackgroundExecutionState],
+        ) -> str:
+            backend = self._get_backend(runtime)
+
+            if not _supports_background_execution(backend):
+                return "Error: 后台执行不可用。"
+
+            try:
+                result = await backend.akill_process(process_id)
+                status = result.get("status", "unknown")
+
+                output_lines = [f"进程终止结果: {status}"]
+
+                if result.get("output"):
+                    output = result["output"]
+                    if len(output) > 1000:
+                        output = output[:1000] + "\n... [输出已截断]"
+                    output_lines.append(f"最终输出:\n{output}")
+
+                return "\n".join(output_lines)
+            except Exception as e:
+                return f"Error: {type(e).__name__}: {e}"
+
+        return StructuredTool.from_function(
+            name="kill_process",
+            description=KILL_PROCESS_DESCRIPTION,
+            func=sync_kill_process,
+            coroutine=async_kill_process,
+        )
+
+    def wrap_model_call(
+        self,
+        request: ModelRequest[ContextT],
+        handler: Callable[[ModelRequest[ContextT]], ModelResponse[ResponseT]],
+    ) -> ModelResponse[ResponseT]:
+        """在 model call 前添加工具和系统提示"""
+        # 检查 backend 是否支持后台执行
+        backend = self._get_backend(request.runtime)  # type: ignore
+        if not _supports_background_execution(backend):
+            # 不支持则直接透传
+            return handler(request)
+
+        # 添加工具
+        existing_tool_names = {
+            tool.name if hasattr(tool, "name") else tool.get("name")
+            for tool in request.tools
+        }
+
+        new_tools = list(request.tools)
+        for tool in self.tools:
+            tool_name = tool.name if hasattr(tool, "name") else tool.get("name")
+            if tool_name not in existing_tool_names:
+                new_tools.append(tool)
+
+        request = request.override(tools=new_tools)
+
+        # 添加系统提示
+        from deepagents.middleware._utils import append_to_system_message
+        new_system_message = append_to_system_message(
+            request.system_message,
+            BACKGROUND_EXECUTION_SYSTEM_PROMPT
+        )
+        request = request.override(system_message=new_system_message)
+
+        return handler(request)
+
+    async def awrap_model_call(
+        self,
+        request: ModelRequest[ContextT],
+        handler: Callable[[ModelRequest[ContextT]], Awaitable[ModelResponse[ResponseT]]],
+    ) -> ModelResponse[ResponseT]:
+        """(async) 在 model call 前添加工具和系统提示"""
+        # 检查 backend 是否支持后台执行
+        backend = self._get_backend(request.runtime)  # type: ignore
+        if not _supports_background_execution(backend):
+            return await handler(request)
+
+        # 添加工具
+        existing_tool_names = {
+            tool.name if hasattr(tool, "name") else tool.get("name")
+            for tool in request.tools
+        }
+
+        new_tools = list(request.tools)
+        for tool in self.tools:
+            tool_name = tool.name if hasattr(tool, "name") else tool.get("name")
+            if tool_name not in existing_tool_names:
+                new_tools.append(tool)
+
+        request = request.override(tools=new_tools)
+
+        # 添加系统提示
+        from deepagents.middleware._utils import append_to_system_message
+        new_system_message = append_to_system_message(
+            request.system_message,
+            BACKGROUND_EXECUTION_SYSTEM_PROMPT
+        )
+        request = request.override(system_message=new_system_message)
+
+        return await handler(request)