langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/tools/bash/backend.py

@@ -0,0 +1,1447 @@
+"""
+tools/bash/backend.py — BashRuntimeTool 命令执行后端
+
+职责：
+    封装所有 subprocess / asyncio 操作，与工具 hook 逻辑解耦。
+    提供同步（execute）和异步（aexecute）执行接口，以及后台任务提交（submit_background）。
+    模块 4 起增加可插拔 sandbox backend，使执行层与沙箱决策层解耦。
+
+v1 实现：
+    - 每次调用新建 subprocess，通过 state_bridge 的 cwd 模拟会话持久化
+    - 后台任务使用 subprocess.Popen 在后台运行，输出写入磁盘文件
+    - cwd 提取：在命令末尾追加 `echo $PWD` 特殊标记提取执行后目录
+
+v2 升级：
+    - 维护长期运行的 bash 进程（真正的会话持久化）
+    - 输出流式返回（对应 CC runShellCommand generator）
+
+对应 CC：
+    exec() via utils/Shell.ts              → execute() / aexecute()
+    LocalShellTask / spawnShellTask()      → submit_background()
+    resetCwdIfOutsideProject()             → cwd 越界检测（v2）
+    SandboxManager / shouldUseSandbox()    → sandbox backend + decision layer（基础版）
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import queue
+import sys
+import re
+import selectors
+import shlex
+import signal
+import subprocess
+import tempfile
+import threading
+import time
+import uuid
+from collections.abc import AsyncIterator, Iterator
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol
+
+from .cwd_reporter import (
+    BashCwdReporter,
+    bash_single_quoted,
+    native_path_for_bash_redirect,
+    read_cwd_file,
+)
+from .session_manager import get_global_bash_session_manager
+from .sandbox_decision import BashSandboxDecision
+from .shell_locator import resolve_posix_shell
+from .task_runtime import BashTaskSnapshot, BashTaskStateMachine
+from .windows_shell_quoting import rewrite_windows_null_redirect
+
+# cwd 提取用的特殊 sentinel（不太可能出现在正常输出中）
+_CWD_SENTINEL = "__BASH_CWD_SENTINEL_63f8a2__"
+
+
+@dataclass
+class ExecuteResult:
+    """同步/异步命令执行结果。"""
+
+    stdout: str
+    """命令输出（stderr 已合并）。"""
+
+    exit_code: int
+    """命令退出码。"""
+
+    interrupted: bool
+    """是否因超时或信号中断。"""
+
+    cwd_after: str | None = None
+    """命令执行后的工作目录（cd 命令会改变此值）。"""
+
+    sandboxed: bool = False
+    """是否通过 sandbox backend 执行。"""
+
+    sandbox_bypass_reason: str | None = None
+    """未走沙箱时的原因。"""
+
+    sandbox_temp_dir: str | None = None
+    """沙箱执行时注入的 TMPDIR。"""
+
+    sandbox_violation_message: str | None = None
+    """沙箱 backend 返回的结构化 violation 信息。"""
+
+
+@dataclass
+class BackgroundTask:
+    """后台任务描述符。"""
+
+    task_id: str
+    """唯一任务 ID（UUID4）。"""
+
+    output_path: str
+    """输出文件的绝对路径（模型可用 Read 工具读取）。"""
+
+    pid: int
+    """后台进程 PID。"""
+
+    sandboxed: bool = False
+    """后台任务是否在沙箱模式下执行。"""
+
+    sandbox_temp_dir: str | None = None
+    """后台任务的 TMPDIR（如适用）。"""
+
+
+@dataclass(frozen=True)
+class BashStreamEvent:
+    """前台执行流式事件。"""
+
+    kind: str
+    chunk: str | None = None
+    exit_code: int | None = None
+    interrupted: bool | None = None
+    cwd_after: str | None = None
+
+
+@dataclass(frozen=True)
+class BackgroundTaskStatus:
+    """后台任务状态快照。"""
+
+    task_id: str
+    output_path: str
+    pid: int
+    running: bool
+    exit_code: int | None
+    output_size: int
+
+
+@dataclass(frozen=True)
+class BackgroundTaskOutputDelta:
+    """后台任务输出增量。"""
+
+    task_id: str
+    chunk: str
+    next_offset: int
+    finished: bool
+    exit_code: int | None
+
+
+@dataclass(frozen=True)
+class SandboxExecutionRequest:
+    command: str
+    cwd: str | None
+    timeout_sec: int
+    env: dict[str, str]
+    decision: BashSandboxDecision
+    output_dir: str | None = None
+
+
+class BashSandboxBackendProtocol(Protocol):
+    """可插拔的 Bash 沙箱后端协议。"""
+
+    def execute(self, request: SandboxExecutionRequest) -> ExecuteResult:
+        ...
+
+    async def aexecute(self, request: SandboxExecutionRequest) -> ExecuteResult:
+        ...
+
+    def submit_background(self, request: SandboxExecutionRequest) -> BackgroundTask:
+        ...
+
+
+class LocalTmpdirSandboxBackend:
+    """
+    基础版沙箱后端。
+
+    当前不尝试实现完整 OS 级隔离，而是先保证：
+    - 每次执行使用独立 TMPDIR
+    - 后续可替换为真正的 sandbox backend 而不改变上层接口
+    """
+
+    def __init__(self, backend: "BashBackend") -> None:
+        self._backend = backend
+
+    def execute(self, request: SandboxExecutionRequest) -> ExecuteResult:
+        sandbox_env, temp_dir = self._build_env(request)
+        result = self._backend._execute_raw(
+            command=request.command,
+            cwd=request.cwd,
+            timeout_sec=request.timeout_sec,
+            env=sandbox_env,
+        )
+        payload = dict(result.__dict__)
+        payload["sandboxed"] = True
+        payload["sandbox_temp_dir"] = temp_dir
+        payload["sandbox_bypass_reason"] = None
+        return ExecuteResult(**payload)
+
+    async def aexecute(self, request: SandboxExecutionRequest) -> ExecuteResult:
+        sandbox_env, temp_dir = self._build_env(request)
+        result = await self._backend._aexecute_raw(
+            command=request.command,
+            cwd=request.cwd,
+            timeout_sec=request.timeout_sec,
+            env=sandbox_env,
+        )
+        payload = dict(result.__dict__)
+        payload["sandboxed"] = True
+        payload["sandbox_temp_dir"] = temp_dir
+        payload["sandbox_bypass_reason"] = None
+        return ExecuteResult(**payload)
+
+    def submit_background(self, request: SandboxExecutionRequest) -> BackgroundTask:
+        sandbox_env, temp_dir = self._build_env(request)
+        task = self._backend._submit_background_raw(
+            command=request.command,
+            cwd=request.cwd,
+            output_dir=request.output_dir or "~/.cache/langchain_agentx/tasks",
+            env=sandbox_env,
+        )
+        return BackgroundTask(
+            task_id=task.task_id,
+            output_path=task.output_path,
+            pid=task.pid,
+            sandboxed=True,
+            sandbox_temp_dir=temp_dir,
+        )
+
+    @staticmethod
+    def _sandbox_root(cwd: str | None) -> str:
+        base_dir = cwd if cwd and os.path.isdir(cwd) else tempfile.gettempdir()
+        root = os.path.join(base_dir, ".agentx-sandbox")
+        os.makedirs(root, exist_ok=True)
+        return root
+
+    def _build_env(self, request: SandboxExecutionRequest) -> tuple[dict[str, str], str]:
+        temp_dir = tempfile.mkdtemp(prefix="tmp-", dir=self._sandbox_root(request.cwd))
+        sandbox_env = dict(request.env)
+        sandbox_env["TMPDIR"] = temp_dir
+        sandbox_env["TMP"] = temp_dir
+        sandbox_env["TEMP"] = temp_dir
+        return sandbox_env, temp_dir
+
+
+@dataclass(frozen=True)
+class BashSandboxRuntimeConfig:
+    """
+    P0 约束型沙箱运行配置。
+
+    目标不是完整替代 OS 级隔离，而是先落地两条可验证防线：
+    1. 网络命令默认阻断（可配置放开）
+    2. 显式写路径必须在允许根目录内
+    """
+
+    allow_network: bool = False
+    blocked_network_commands: tuple[str, ...] = (
+        "curl", "wget", "nc", "ncat", "netcat", "telnet", "ftp", "ssh",
+    )
+    allowed_write_roots: tuple[str, ...] = ()
+
+
+class ConstrainedSandboxBackend:
+    """
+    约束型沙箱后端（P0）。
+
+    在 `LocalTmpdirSandboxBackend` 之上增加 command preflight：
+    - 阻断网络命令
+    - 阻断显式越界写路径
+
+    与 CC 对齐方向：
+    对应 `SandboxManager` 的“执行前约束 + violation 可解释”能力。
+    当前仍是基础版，不替代后续真实 OS 级隔离实现。
+    """
+
+    _SEGMENT_SPLIT_RE = re.compile(r"\s*(?:&&|\|\||;|\|)\s*")
+    _REDIRECTION_WRITE_RE = re.compile(
+        r"(?:^|\s)(?:\d*>>?|\d*>\||&>)(?:\s*|)([^\s;&|]+)"
+    )
+
+    def __init__(
+        self,
+        delegate: LocalTmpdirSandboxBackend,
+        config: BashSandboxRuntimeConfig | None = None,
+    ) -> None:
+        self._delegate = delegate
+        self._config = config or BashSandboxRuntimeConfig()
+
+    def execute(self, request: SandboxExecutionRequest) -> ExecuteResult:
+        violation = self._violation_for_request(request)
+        if violation is not None:
+            return self._violation_result(violation)
+        return self._delegate.execute(request)
+
+    async def aexecute(self, request: SandboxExecutionRequest) -> ExecuteResult:
+        violation = self._violation_for_request(request)
+        if violation is not None:
+            return self._violation_result(violation)
+        return await self._delegate.aexecute(request)
+
+    def submit_background(self, request: SandboxExecutionRequest) -> BackgroundTask:
+        # P0 先沿用模块4语义，后台任务不做预检查阻断，避免改变既有回传协议。
+        return self._delegate.submit_background(request)
+
+    def _violation_for_request(self, request: SandboxExecutionRequest) -> str | None:
+        network_violation = self._check_network_violation(request.command)
+        if network_violation is not None:
+            return network_violation
+        return self._check_write_violation(request.command, request.cwd)
+
+    def _check_network_violation(self, command: str) -> str | None:
+        if self._config.allow_network:
+            return None
+        for segment in self._SEGMENT_SPLIT_RE.split(command):
+            executable = self._extract_executable(segment)
+            if not executable:
+                continue
+            if executable in self._config.blocked_network_commands:
+                return (
+                    "Sandbox violation: network-restricted command detected "
+                    f"(`{executable}`)."
+                )
+        return None
+
+    def _check_write_violation(self, command: str, cwd: str | None) -> str | None:
+        if not self._config.allowed_write_roots:
+            return None
+        write_paths: list[str] = []
+        write_paths.extend(self._extract_redirection_paths(command))
+        write_paths.extend(self._extract_explicit_write_paths(command))
+        for raw in write_paths:
+            resolved = self._resolve_path(raw, cwd)
+            if resolved is None:
+                continue
+            if not any(self._is_within_root(resolved, root) for root in self._config.allowed_write_roots):
+                return (
+                    "Sandbox violation: write target outside sandbox roots "
+                    f"(`{resolved}`)."
+                )
+        return None
+
+    def _extract_redirection_paths(self, command: str) -> list[str]:
+        results: list[str] = []
+        for match in self._REDIRECTION_WRITE_RE.finditer(command):
+            path = match.group(1).strip("\"'")
+            if path and not path.startswith("$"):
+                results.append(path)
+        return results
+
+    @staticmethod
+    def _extract_explicit_write_paths(command: str) -> list[str]:
+        try:
+            args = shlex.split(command)
+        except ValueError:
+            return []
+        if not args:
+            return []
+        base = os.path.basename(args[0])
+        if base in {"touch", "mkdir", "rmdir", "rm", "chmod", "chown"}:
+            return [a for a in args[1:] if a and not a.startswith("-")]
+        if base in {"cp", "mv", "install", "ln"} and len(args) >= 2:
+            candidates = [a for a in args[1:] if a and not a.startswith("-")]
+            return candidates[-1:] if candidates else []
+        if base == "dd":
+            for item in args[1:]:
+                if item.startswith("of="):
+                    return [item[3:]]
+        return []
+
+    @staticmethod
+    def _extract_executable(segment: str) -> str | None:
+        try:
+            args = shlex.split(segment)
+        except ValueError:
+            return None
+        if not args:
+            return None
+        index = 0
+        while index < len(args):
+            token = args[index]
+            if re.match(r"^[A-Za-z_][A-Za-z0-9_]*=.*$", token):
+                index += 1
+                continue
+            return os.path.basename(token)
+        return None
+
+    @staticmethod
+    def _resolve_path(raw: str, cwd: str | None) -> str | None:
+        if not raw or raw.startswith("$"):
+            return None
+        path = os.path.expanduser(raw)
+        if not os.path.isabs(path):
+            base = cwd or os.getcwd()
+            path = os.path.join(base, path)
+        return os.path.realpath(path)
+
+    @staticmethod
+    def _is_within_root(path: str, root: str) -> bool:
+        root_real = os.path.realpath(os.path.expanduser(root))
+        try:
+            common = os.path.commonpath([path, root_real])
+        except ValueError:
+            return False
+        return common == root_real
+
+    @staticmethod
+    def _violation_result(message: str) -> ExecuteResult:
+        return ExecuteResult(
+            stdout="",
+            exit_code=126,
+            interrupted=False,
+            sandboxed=True,
+            sandbox_violation_message=message,
+        )
+
+
+class BashBackend:
+    """
+    命令执行 I/O 后端。
+
+    与 BashRuntimeTool 解耦，便于在测试中 mock。
+    """
+
+    def __init__(
+        self,
+        sandbox_backend: BashSandboxBackendProtocol | None = None,
+        sandbox_runtime_config: BashSandboxRuntimeConfig | None = None,
+        use_persistent_session: bool | None = None,
+        posix_shell_executable: str | None = None,
+    ) -> None:
+        # Phase 0 冻结（exec-plan bash-runtime-tool-cross-platform）：win32 上默认关闭
+        # 真持久会话，直至 Phase 4 冒烟；忽略 AGENTX_BASH_USE_PERSISTENT_SESSION，避免
+        # pass_fds/select 与 Git Bash 组合在未验证路径上被 env 误开。
+        if use_persistent_session is not None:
+            self._use_persistent_session = bool(use_persistent_session)
+        elif sys.platform == "win32":
+            self._use_persistent_session = False
+        else:
+            self._use_persistent_session = bool(
+                int(os.getenv("AGENTX_BASH_USE_PERSISTENT_SESSION", "0"))
+            )
+        if sandbox_backend is not None:
+            self._sandbox_backend = sandbox_backend
+        else:
+            base_backend = LocalTmpdirSandboxBackend(self)
+            self._sandbox_backend = ConstrainedSandboxBackend(
+                delegate=base_backend,
+                config=sandbox_runtime_config,
+            )
+        self._posix_shell_override = posix_shell_executable
+
+    def _posix_shell_executable(self, env: dict[str, str]) -> str:
+        """解析 argv[0]；测试可注入 `posix_shell_executable` 跳过 PATH 探测。"""
+        if self._posix_shell_override is not None:
+            return os.path.normpath(
+                os.path.realpath(os.path.expanduser(self._posix_shell_override))
+            )
+        merged = os.environ.copy()
+        merged.update(env)
+        return resolve_posix_shell(environ=merged)
+
+    def _preprocess_shell_command(self, command: str) -> str:
+        """进入 `-c` 包装前：win32 上纠偏 CMD 风格 `nul` 重定向（见 `windows_shell_quoting`）。"""
+        return rewrite_windows_null_redirect(command)
+
+    @staticmethod
+    def _spawn_env_with_shell(env: dict[str, str], shell_exe: str) -> dict[str, str]:
+        """子进程 env：对齐 CC 思路，在未显式设置时注入 `SHELL`。"""
+        out = dict(env)
+        out.setdefault("SHELL", shell_exe)
+        return out
+
+    @staticmethod
+    def _win32_creationflags() -> int:
+        """可选隐藏控制台：`AGENTX_BASH_CREATE_NO_WINDOW=1`（默认关闭，兼容性风险见 exec-plan）。"""
+        if sys.platform != "win32":
+            return 0
+        if os.environ.get("AGENTX_BASH_CREATE_NO_WINDOW") != "1":
+            return 0
+        return int(getattr(subprocess, "CREATE_NO_WINDOW", 0))
+
+    def execute(
+        self,
+        command: str,
+        cwd: str | None = None,
+        timeout_sec: int = 120,
+        env: dict[str, str] | None = None,
+        sandbox_decision: BashSandboxDecision | None = None,
+        session_key: str | None = None,
+    ) -> ExecuteResult:
+        """
+        同步执行 Shell 命令。
+
+        - cwd：工作目录（来自 state_bridge）
+        - stderr 合并到 stdout（与 CC merged fd 等价）
+        - 在命令末尾注入 cwd 提取指令
+        """
+        effective_env = os.environ.copy()
+        if env:
+            effective_env.update(env)
+
+        decision = sandbox_decision or BashSandboxDecision(
+            use_sandbox=False,
+            reason="sandbox_not_requested",
+        )
+        if decision.use_sandbox:
+            return self._sandbox_backend.execute(
+                SandboxExecutionRequest(
+                    command=command,
+                    cwd=cwd,
+                    timeout_sec=timeout_sec,
+                    env=effective_env,
+                    decision=decision,
+                )
+            )
+
+        if self._use_persistent_session and session_key:
+            result = self._execute_via_session(
+                command=command,
+                cwd=cwd,
+                timeout_sec=timeout_sec,
+                env=effective_env,
+                session_key=session_key,
+            )
+            result.sandbox_bypass_reason = decision.reason
+            return result
+
+        result = self._execute_raw(
+            command=command,
+            cwd=cwd,
+            timeout_sec=timeout_sec,
+            env=effective_env,
+        )
+        result.sandbox_bypass_reason = decision.reason
+        return result
+
+    def _execute_raw(
+        self,
+        *,
+        command: str,
+        cwd: str | None,
+        timeout_sec: int,
+        env: dict[str, str],
+    ) -> ExecuteResult:
+        # cwd 提取：Unix = fd3 + pass_fds（与 Phase 0 冻结一致）；win32 = 临时文件 + pwd -P
+        # （见 `cwd_reporter.py` / bash-tool-cross-platform Phase 2）。
+        import subprocess as _sp
+
+        shell_exe = self._posix_shell_executable(env)
+        command = self._preprocess_shell_command(command)
+        if sys.platform == "win32":
+            return self._execute_raw_win32(
+                command=command,
+                cwd=cwd,
+                timeout_sec=timeout_sec,
+                env=env,
+                shell_exe=shell_exe,
+            )
+
+        read_fd, write_fd = os.pipe()
+        wrapped = BashCwdReporter.wrap_with_fd3(command, write_fd)
+
+        try:
+            proc = _sp.Popen(
+                [shell_exe, "-c", wrapped],
+                stdout=_sp.PIPE,
+                stderr=_sp.STDOUT,
+                cwd=cwd,
+                env=self._spawn_env_with_shell(env, shell_exe),
+                pass_fds=(write_fd,),
+            )
+            os.close(write_fd)
+            write_fd = -1
+
+            try:
+                stdout_bytes, _ = proc.communicate(timeout=timeout_sec)
+            except _sp.TimeoutExpired:
+                proc.kill()
+                stdout_bytes, _ = proc.communicate()
+                cwd_after = _read_fd_safe(read_fd)
+                os.close(read_fd)
+                partial = stdout_bytes.decode("utf-8", errors="replace")
+                return ExecuteResult(
+                    stdout=partial,
+                    exit_code=-1,
+                    interrupted=True,
+                    cwd_after=cwd_after,
+                )
+
+            cwd_after = _read_fd_safe(read_fd)
+            os.close(read_fd)
+            read_fd = -1
+
+            stdout_str = stdout_bytes.decode("utf-8", errors="replace")
+            return ExecuteResult(
+                stdout=stdout_str,
+                exit_code=proc.returncode,
+                interrupted=False,
+                cwd_after=cwd_after,
+            )
+        except FileNotFoundError:
+            return ExecuteResult(
+                stdout="bash: command not found",
+                exit_code=127,
+                interrupted=False,
+            )
+        finally:
+            if write_fd != -1:
+                try:
+                    os.close(write_fd)
+                except OSError:
+                    pass
+            if read_fd != -1:
+                try:
+                    os.close(read_fd)
+                except OSError:
+                    pass
+
+    def _execute_raw_win32(
+        self,
+        *,
+        command: str,
+        cwd: str | None,
+        timeout_sec: int,
+        env: dict[str, str],
+        shell_exe: str,
+    ) -> ExecuteResult:
+        fd, cwd_file = tempfile.mkstemp(prefix="agentx_bash_cwd_", suffix=".txt")
+        os.close(fd)
+        posix_tgt = native_path_for_bash_redirect(cwd_file)
+        wrapped = BashCwdReporter.wrap_with_cwd_file(
+            command, bash_single_quoted(posix_tgt)
+        )
+        spawn_env = self._spawn_env_with_shell(env, shell_exe)
+        _cf = self._win32_creationflags()
+        try:
+            if _cf:
+                proc = subprocess.Popen(
+                    [shell_exe, "-c", wrapped],
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.STDOUT,
+                    cwd=cwd,
+                    env=spawn_env,
+                    creationflags=_cf,
+                )
+            else:
+                proc = subprocess.Popen(
+                    [shell_exe, "-c", wrapped],
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.STDOUT,
+                    cwd=cwd,
+                    env=spawn_env,
+                )
+            try:
+                stdout_bytes, _ = proc.communicate(timeout=timeout_sec)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                stdout_bytes, _ = proc.communicate()
+                cwd_after = read_cwd_file(cwd_file)
+                partial = stdout_bytes.decode("utf-8", errors="replace")
+                return ExecuteResult(
+                    stdout=partial,
+                    exit_code=-1,
+                    interrupted=True,
+                    cwd_after=cwd_after,
+                )
+
+            cwd_after = read_cwd_file(cwd_file)
+            stdout_str = stdout_bytes.decode("utf-8", errors="replace")
+            return ExecuteResult(
+                stdout=stdout_str,
+                exit_code=proc.returncode,
+                interrupted=False,
+                cwd_after=cwd_after,
+            )
+        except FileNotFoundError:
+            return ExecuteResult(
+                stdout="bash: command not found",
+                exit_code=127,
+                interrupted=False,
+            )
+        finally:
+            try:
+                os.unlink(cwd_file)
+            except OSError:
+                pass
+
+    async def aexecute(
+        self,
+        command: str,
+        cwd: str | None = None,
+        timeout_sec: int = 120,
+        env: dict[str, str] | None = None,
+        sandbox_decision: BashSandboxDecision | None = None,
+        session_key: str | None = None,
+    ) -> ExecuteResult:
+        """
+        异步执行 Shell 命令（asyncio.subprocess）。
+
+        行为与 execute() 等价，但不阻塞事件循环。
+        cwd 提取：Unix 为 fd3 + pass_fds；win32 为临时文件 + pwd -P（与 `_execute_raw` 一致）。
+        """
+        effective_env = os.environ.copy()
+        if env:
+            effective_env.update(env)
+
+        decision = sandbox_decision or BashSandboxDecision(
+            use_sandbox=False,
+            reason="sandbox_not_requested",
+        )
+        if decision.use_sandbox:
+            return await self._sandbox_backend.aexecute(
+                SandboxExecutionRequest(
+                    command=command,
+                    cwd=cwd,
+                    timeout_sec=timeout_sec,
+                    env=effective_env,
+                    decision=decision,
+                )
+            )
+
+        if self._use_persistent_session and session_key:
+            loop = asyncio.get_event_loop()
+            result = await loop.run_in_executor(
+                None,
+                lambda: self._execute_via_session(
+                    command=command,
+                    cwd=cwd,
+                    timeout_sec=timeout_sec,
+                    env=effective_env,
+                    session_key=session_key,
+                ),
+            )
+        else:
+            result = await self._aexecute_raw(
+                command=command,
+                cwd=cwd,
+                timeout_sec=timeout_sec,
+                env=effective_env,
+            )
+        result.sandbox_bypass_reason = decision.reason
+        return result
+
+    async def _aexecute_raw(
+        self,
+        *,
+        command: str,
+        cwd: str | None,
+        timeout_sec: int,
+        env: dict[str, str],
+    ) -> ExecuteResult:
+        shell_exe = self._posix_shell_executable(env)
+        command = self._preprocess_shell_command(command)
+        if sys.platform == "win32":
+            return await self._aexecute_raw_win32(
+                command=command,
+                cwd=cwd,
+                timeout_sec=timeout_sec,
+                env=env,
+                shell_exe=shell_exe,
+            )
+
+        read_fd, write_fd = os.pipe()
+        wrapped = BashCwdReporter.wrap_with_fd3(command, write_fd)
+
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                shell_exe,
+                "-c",
+                wrapped,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.STDOUT,
+                cwd=cwd,
+                env=self._spawn_env_with_shell(env, shell_exe),
+                pass_fds=(write_fd,),
+            )
+            os.close(write_fd)
+            write_fd = -1
+
+            try:
+                stdout_bytes, _ = await asyncio.wait_for(
+                    proc.communicate(),
+                    timeout=timeout_sec,
+                )
+            except asyncio.TimeoutError:
+                proc.kill()
+                await proc.wait()
+                cwd_after = _read_fd_safe(read_fd)
+                os.close(read_fd)
+                read_fd = -1
+                return ExecuteResult(
+                    stdout="",
+                    exit_code=-1,
+                    interrupted=True,
+                    cwd_after=cwd_after,
+                )
+
+            cwd_after = _read_fd_safe(read_fd)
+            os.close(read_fd)
+            read_fd = -1
+
+            stdout_str = stdout_bytes.decode("utf-8", errors="replace")
+            return ExecuteResult(
+                stdout=stdout_str,
+                exit_code=proc.returncode or 0,
+                interrupted=False,
+                cwd_after=cwd_after,
+            )
+        except FileNotFoundError:
+            return ExecuteResult(
+                stdout="bash: command not found",
+                exit_code=127,
+                interrupted=False,
+            )
+        finally:
+            if write_fd != -1:
+                try:
+                    os.close(write_fd)
+                except OSError:
+                    pass
+            if read_fd != -1:
+                try:
+                    os.close(read_fd)
+                except OSError:
+                    pass
+
+    async def _aexecute_raw_win32(
+        self,
+        *,
+        command: str,
+        cwd: str | None,
+        timeout_sec: int,
+        env: dict[str, str],
+        shell_exe: str,
+    ) -> ExecuteResult:
+        fd, cwd_file = tempfile.mkstemp(prefix="agentx_bash_cwd_", suffix=".txt")
+        os.close(fd)
+        posix_tgt = native_path_for_bash_redirect(cwd_file)
+        wrapped = BashCwdReporter.wrap_with_cwd_file(
+            command, bash_single_quoted(posix_tgt)
+        )
+        spawn_env = self._spawn_env_with_shell(env, shell_exe)
+        _cf = self._win32_creationflags()
+        try:
+            if _cf:
+                proc = await asyncio.create_subprocess_exec(
+                    shell_exe,
+                    "-c",
+                    wrapped,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.STDOUT,
+                    cwd=cwd,
+                    env=spawn_env,
+                    creationflags=_cf,
+                )
+            else:
+                proc = await asyncio.create_subprocess_exec(
+                    shell_exe,
+                    "-c",
+                    wrapped,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.STDOUT,
+                    cwd=cwd,
+                    env=spawn_env,
+                )
+            try:
+                stdout_bytes, _ = await asyncio.wait_for(
+                    proc.communicate(),
+                    timeout=timeout_sec,
+                )
+            except asyncio.TimeoutError:
+                proc.kill()
+                await proc.wait()
+                cwd_after = read_cwd_file(cwd_file)
+                return ExecuteResult(
+                    stdout="",
+                    exit_code=-1,
+                    interrupted=True,
+                    cwd_after=cwd_after,
+                )
+
+            cwd_after = read_cwd_file(cwd_file)
+            stdout_str = (stdout_bytes or b"").decode("utf-8", errors="replace")
+            return ExecuteResult(
+                stdout=stdout_str,
+                exit_code=proc.returncode or 0,
+                interrupted=False,
+                cwd_after=cwd_after,
+            )
+        except FileNotFoundError:
+            return ExecuteResult(
+                stdout="bash: command not found",
+                exit_code=127,
+                interrupted=False,
+            )
+        finally:
+            try:
+                os.unlink(cwd_file)
+            except OSError:
+                pass
+
+    def submit_background(
+        self,
+        command: str,
+        cwd: str | None = None,
+        output_dir: str = "~/.cache/langchain_agentx/tasks",
+        env: dict[str, str] | None = None,
+        sandbox_decision: BashSandboxDecision | None = None,
+    ) -> BackgroundTask:
+        """
+        提交后台任务，立即返回 BackgroundTask（不等待完成）。
+
+        输出写入磁盘文件，模型可通过 Read 工具读取。
+        对应 CC spawnShellTask() + LocalShellTask。
+        """
+        effective_env = os.environ.copy()
+        if env:
+            effective_env.update(env)
+
+        decision = sandbox_decision or BashSandboxDecision(
+            use_sandbox=False,
+            reason="sandbox_not_requested",
+        )
+        if decision.use_sandbox:
+            return self._sandbox_backend.submit_background(
+                SandboxExecutionRequest(
+                    command=command,
+                    cwd=cwd,
+                    timeout_sec=0,
+                    env=effective_env,
+                    decision=decision,
+                    output_dir=output_dir,
+                )
+            )
+
+        return self._submit_background_raw(
+            command=command,
+            cwd=cwd,
+            output_dir=output_dir,
+            env=effective_env,
+        )
+
+    def stream_execute(
+        self,
+        command: str,
+        cwd: str | None = None,
+        timeout_sec: int = 120,
+        env: dict[str, str] | None = None,
+        session_key: str | None = None,
+    ) -> list[BashStreamEvent]:
+        """
+        P1 基础版：前台流式执行接口。
+
+        当前返回离散事件列表（chunk/final），后续可升级为 async generator。
+        """
+        return list(
+            self.stream_execute_iter(
+                command=command,
+                cwd=cwd,
+                timeout_sec=timeout_sec,
+                env=env,
+                session_key=session_key,
+            )
+        )
+
+    def stream_execute_iter(
+        self,
+        command: str,
+        cwd: str | None = None,
+        timeout_sec: int = 120,
+        env: dict[str, str] | None = None,
+        session_key: str | None = None,
+        cancel_event: threading.Event | None = None,
+        sandbox_decision: BashSandboxDecision | None = None,
+    ) -> Iterator[BashStreamEvent]:
+        """
+        P1 完整版：前台实时流式执行迭代器。
+        """
+        effective_env = os.environ.copy()
+        if env:
+            effective_env.update(env)
+        if self._use_persistent_session and session_key:
+            manager = get_global_bash_session_manager()
+            runtime = manager.get_or_create(session_key=session_key, cwd=cwd, env=effective_env)
+            for ev in runtime.execute_stream_iter(
+                command=self._preprocess_shell_command(command),
+                timeout_sec=timeout_sec,
+                cancel_event=cancel_event,
+            ):
+                yield BashStreamEvent(
+                    kind=ev.kind,
+                    chunk=ev.chunk,
+                    exit_code=ev.exit_code,
+                    interrupted=ev.interrupted,
+                    cwd_after=ev.cwd_after,
+                )
+            return
+        decision = sandbox_decision or BashSandboxDecision(
+            use_sandbox=False,
+            reason="sandbox_not_requested",
+        )
+        if decision.use_sandbox:
+            result = self.execute(
+                command=command,
+                cwd=cwd,
+                timeout_sec=timeout_sec,
+                env=effective_env,
+                session_key=session_key,
+                sandbox_decision=decision,
+            )
+            if result.stdout:
+                yield BashStreamEvent(kind="chunk", chunk=result.stdout)
+            yield BashStreamEvent(
+                kind="final",
+                exit_code=result.exit_code,
+                interrupted=result.interrupted,
+                cwd_after=result.cwd_after,
+            )
+            return
+
+        wrapped = self._build_stream_wrapper(self._preprocess_shell_command(command))
+        yield from self._stream_execute_raw_iter(
+            wrapped_command=wrapped,
+            cwd=cwd,
+            timeout_sec=timeout_sec,
+            env=effective_env,
+            cancel_event=cancel_event,
+        )
+
+    @staticmethod
+    def _build_stream_wrapper(command: str) -> str:
+        marker = "__AGENTX_STREAM_CWD__"
+        return (
+            f"{command}\n"
+            "__EC=$?\n"
+            f'printf "\\n{marker}%s\\n" "$PWD"\n'
+            "exit $__EC"
+        )
+
+    def _stream_execute_raw_iter(
+        self,
+        *,
+        wrapped_command: str,
+        cwd: str | None,
+        timeout_sec: int,
+        env: dict[str, str],
+        cancel_event: threading.Event | None,
+    ) -> Iterator[BashStreamEvent]:
+        marker = "__AGENTX_STREAM_CWD__"
+        shell_exe = self._posix_shell_executable(env)
+        spawn_env = self._spawn_env_with_shell(env, shell_exe)
+        _cf = self._win32_creationflags()
+        if _cf:
+            proc = subprocess.Popen(
+                [shell_exe, "-c", wrapped_command],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                cwd=cwd,
+                env=spawn_env,
+                text=False,
+                bufsize=0,
+                creationflags=_cf,
+            )
+        else:
+            proc = subprocess.Popen(
+                [shell_exe, "-c", wrapped_command],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                cwd=cwd,
+                env=spawn_env,
+                text=False,
+                bufsize=0,
+            )
+        selector = selectors.DefaultSelector()
+        assert proc.stdout is not None
+        selector.register(proc.stdout, selectors.EVENT_READ)
+
+        started = time.time()
+        interrupted = False
+        chunks: list[str] = []
+        try:
+            while True:
+                if cancel_event is not None and cancel_event.is_set():
+                    interrupted = True
+                    proc.kill()
+                    break
+                if time.time() - started > timeout_sec:
+                    interrupted = True
+                    proc.kill()
+                    break
+                if proc.poll() is not None and not selector.get_map():
+                    break
+                events = selector.select(timeout=0.1)
+                if not events:
+                    if proc.poll() is not None:
+                        break
+                    continue
+                for key, _ in events:
+                    raw = key.fileobj.read1(4096) if hasattr(key.fileobj, "read1") else key.fileobj.read(4096)
+                    if not raw:
+                        selector.unregister(key.fileobj)
+                        continue
+                    text = raw.decode("utf-8", errors="replace")
+                    chunks.append(text)
+                    yield BashStreamEvent(kind="chunk", chunk=text)
+            proc.wait(timeout=1)
+        finally:
+            selector.close()
+            if proc.poll() is None:
+                proc.kill()
+
+        merged = "".join(chunks)
+        cwd_after = None
+        if marker in merged:
+            before, _, after = merged.rpartition(marker)
+            # 末尾的 cwd 标记不再作为 chunk 内容处理
+            cleaned = before
+            cwd_after = after.strip().splitlines()[0] if after.strip() else None
+            if cleaned != merged:
+                # 让上游获得去 marker 后的稳定输出
+                pass
+        exit_code = proc.returncode if proc.returncode is not None else (-1 if interrupted else 0)
+        yield BashStreamEvent(
+            kind="final",
+            exit_code=exit_code,
+            interrupted=interrupted,
+            cwd_after=cwd_after,
+        )
+
+    async def astream_execute_iter(
+        self,
+        command: str,
+        cwd: str | None = None,
+        timeout_sec: int = 120,
+        env: dict[str, str] | None = None,
+        session_key: str | None = None,
+        cancel_event: threading.Event | None = None,
+    ) -> AsyncIterator[BashStreamEvent]:
+        """
+        异步流式执行：在后台线程中驱动同步迭代器，主协程逐块消费（对齐 CC generator 体验）。
+        """
+        sync_q: queue.Queue[BashStreamEvent | None] = queue.Queue()
+
+        def producer() -> None:
+            try:
+                for ev in self.stream_execute_iter(
+                    command=command,
+                    cwd=cwd,
+                    timeout_sec=timeout_sec,
+                    env=env,
+                    session_key=session_key,
+                    cancel_event=cancel_event,
+                ):
+                    sync_q.put(ev)
+            finally:
+                sync_q.put(None)
+
+        threading.Thread(target=producer, name="bash-stream-producer", daemon=True).start()
+        while True:
+            ev = await asyncio.to_thread(sync_q.get)
+            if ev is None:
+                break
+            yield ev
+
+    def _execute_via_session(
+        self,
+        *,
+        command: str,
+        cwd: str | None,
+        timeout_sec: int,
+        env: dict[str, str],
+        session_key: str,
+    ) -> ExecuteResult:
+        command = self._preprocess_shell_command(command)
+        manager = get_global_bash_session_manager()
+        runtime = manager.get_or_create(session_key=session_key, cwd=cwd, env=env)
+        session_result = runtime.execute(command=command, timeout_sec=timeout_sec)
+        return ExecuteResult(
+            stdout=session_result.stdout,
+            exit_code=session_result.exit_code,
+            interrupted=session_result.interrupted,
+            cwd_after=session_result.cwd_after,
+        )
+
+    def _submit_background_raw(
+        self,
+        *,
+        command: str,
+        cwd: str | None,
+        output_dir: str,
+        env: dict[str, str],
+    ) -> BackgroundTask:
+        task_id = str(uuid.uuid4())
+        output_dir_expanded = os.path.expanduser(output_dir)
+        task_dir = os.path.join(output_dir_expanded, task_id)
+        os.makedirs(task_dir, exist_ok=True)
+        output_path = os.path.join(task_dir, "output.txt")
+
+        output_file = open(output_path, "wb")  # noqa: WPS515
+        exit_code_path = os.path.join(task_dir, "exit_code")
+
+        command = self._preprocess_shell_command(command)
+        quoted_exit_code_path = shlex.quote(exit_code_path)
+        wrapped = (
+            "{ "
+            f"{command}; "
+            "__AGENTX_EC=$?; "
+            f"printf '%s\\n' \"$__AGENTX_EC\" > {quoted_exit_code_path}; "
+            "exit $__AGENTX_EC; "
+            "}"
+        )
+        shell_exe = self._posix_shell_executable(env)
+        spawn_env = self._spawn_env_with_shell(env, shell_exe)
+        _cf = self._win32_creationflags()
+        if _cf:
+            proc = subprocess.Popen(
+                [shell_exe, "-c", wrapped],
+                stdout=output_file,
+                stderr=subprocess.STDOUT,
+                cwd=cwd,
+                env=spawn_env,
+                start_new_session=True,
+                creationflags=_cf,
+            )
+        else:
+            proc = subprocess.Popen(
+                [shell_exe, "-c", wrapped],
+                stdout=output_file,
+                stderr=subprocess.STDOUT,
+                cwd=cwd,
+                env=spawn_env,
+                start_new_session=True,
+            )
+
+        pid_path = os.path.join(task_dir, "pid")
+        with open(pid_path, "w") as f:
+            f.write(str(proc.pid))
+
+        output_file.close()
+
+        return BackgroundTask(
+            task_id=task_id,
+            output_path=output_path,
+            pid=proc.pid,
+        )
+
+    def get_background_status(self, task: BackgroundTask) -> BackgroundTaskStatus:
+        task_dir = os.path.dirname(task.output_path)
+        exit_code_path = os.path.join(task_dir, "exit_code")
+        output_size = os.path.getsize(task.output_path) if os.path.exists(task.output_path) else 0
+        running = _is_process_alive(task.pid)
+        exit_code: int | None = None
+        if os.path.exists(exit_code_path):
+            try:
+                with open(exit_code_path, "r", encoding="utf-8") as f:
+                    raw = f.read().strip()
+                if raw:
+                    exit_code = int(raw)
+            except (OSError, ValueError):
+                exit_code = None
+        if exit_code is not None:
+            running = False
+        return BackgroundTaskStatus(
+            task_id=task.task_id,
+            output_path=task.output_path,
+            pid=task.pid,
+            running=running,
+            exit_code=exit_code,
+            output_size=output_size,
+        )
+
+    def read_background_output_delta(
+        self,
+        task: BackgroundTask,
+        *,
+        offset: int = 0,
+    ) -> BackgroundTaskOutputDelta:
+        status = self.get_background_status(task)
+        if not os.path.exists(task.output_path):
+            return BackgroundTaskOutputDelta(
+                task_id=task.task_id,
+                chunk="",
+                next_offset=offset,
+                finished=(not status.running and status.exit_code is not None),
+                exit_code=status.exit_code,
+            )
+        with open(task.output_path, "rb") as f:
+            f.seek(max(0, offset))
+            raw = f.read()
+        chunk = raw.decode("utf-8", errors="replace")
+        next_offset = max(0, offset) + len(raw)
+        finished = (not status.running) and (status.exit_code is not None)
+        return BackgroundTaskOutputDelta(
+            task_id=task.task_id,
+            chunk=chunk,
+            next_offset=next_offset,
+            finished=finished,
+            exit_code=status.exit_code,
+        )
+
+    @staticmethod
+    def build_foreground_snapshot(result: ExecuteResult) -> BashTaskSnapshot:
+        t0 = time.time()
+        sm = BashTaskStateMachine(task_id="foreground", task_mode="foreground")
+        sm.created_ts = t0
+        sm.transition_to("running")
+        sm.started_ts = time.time()
+        if result.interrupted:
+            sm.transition_to("interrupted")
+        elif result.exit_code == 0:
+            sm.transition_to("completed")
+        else:
+            sm.transition_to("failed")
+        sm.ended_ts = time.time()
+        sm.exit_code = result.exit_code
+        return sm.to_snapshot()
+
+    def build_background_snapshot(self, task: BackgroundTask) -> BashTaskSnapshot:
+        status = self.get_background_status(task)
+        sm = BashTaskStateMachine(task_id=task.task_id, task_mode="background")
+        sm.created_ts = time.time()
+        sm.output_path = status.output_path
+        sm.pid = status.pid
+        sm.output_size = status.output_size
+        sm.transition_to("running")
+        sm.started_ts = time.time()
+        if status.running:
+            return sm.to_snapshot()
+        sm.ended_ts = time.time()
+        if status.exit_code == -2:
+            sm.transition_to("cancelled")
+        elif status.exit_code == 0:
+            sm.transition_to("completed")
+        elif status.exit_code is None:
+            sm.transition_to("interrupted")
+        else:
+            sm.transition_to("failed")
+        sm.exit_code = status.exit_code
+        return sm.to_snapshot()
+
+    def cancel_background_task(self, task: BackgroundTask) -> bool:
+        """
+        取消后台任务：发信号终止进程，并标记为 cancelled（exit_code 文件写 -2）。
+        """
+        task_dir = os.path.dirname(task.output_path)
+        exit_code_path = os.path.join(task_dir, "exit_code")
+        cancelled_path = os.path.join(task_dir, "cancelled")
+        try:
+            with open(cancelled_path, "w", encoding="utf-8") as f:
+                f.write("1")
+        except OSError:
+            pass
+        if _is_process_alive(task.pid):
+            try:
+                os.killpg(task.pid, signal.SIGTERM)
+            except OSError:
+                try:
+                    os.kill(task.pid, signal.SIGTERM)
+                except OSError:
+                    pass
+            time.sleep(0.05)
+            if _is_process_alive(task.pid):
+                try:
+                    os.killpg(task.pid, signal.SIGKILL)
+                except OSError:
+                    try:
+                        os.kill(task.pid, signal.SIGKILL)
+                    except OSError:
+                        pass
+        try:
+            with open(exit_code_path, "w", encoding="utf-8") as f:
+                f.write("-2\n")
+        except OSError:
+            return False
+        return True
+
+
+# ---------------------------------------------------------------------------
+# 辅助函数
+# ---------------------------------------------------------------------------
+
+
+def _read_fd_safe(fd: int) -> str | None:
+    """
+    从 fd 中读取 cwd 字符串（由子进程写入），安全处理 EOF/错误。
+    返回去掉首尾空白的路径字符串，或 None（读取失败/空）。
+    """
+    try:
+        data = b""
+        while True:
+            chunk = os.read(fd, 4096)
+            if not chunk:
+                break
+            data += chunk
+        result = data.decode("utf-8", errors="replace").strip()
+        return result if result else None
+    except OSError:
+        return None
+
+
+def _is_process_alive(pid: int) -> bool:
+    """判断进程是否存活。"""
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError:
+        return False
+
+
+def _extract_cwd_from_output(raw_output: str) -> tuple[str, str | None]:
+    """
+    兼容旧接口：从命令输出中提取 cwd sentinel 行（已废弃，保留供测试引用）。
+    新代码使用 fd-3 策略，此函数仅用于测试模块中的直接调用。
+    """
+    lines = raw_output.splitlines(keepends=True)
+    cwd_after: str | None = None
+    clean_lines = []
+
+    for line in lines:
+        stripped = line.rstrip("\n").rstrip("\r")
+        if stripped.startswith(_CWD_SENTINEL):
+            cwd_after = stripped[len(_CWD_SENTINEL):]
+        else:
+            clean_lines.append(line)
+
+    return "".join(clean_lines), cwd_after
+
+
+def strip_empty_lines(text: str) -> str:
+    """
+    压缩连续空行为单个空行，并去除首尾空白行。
+    对应 CC utils.ts::stripEmptyLines()。
+    """
+    if not text:
+        return text
+
+    # 去除首部连续空白行（对应 CC `replace(/^(\s*\n)+/, '')`)
+    lines = text.splitlines(keepends=True)
+    start = 0
+    while start < len(lines) and lines[start].strip() == "":
+        start += 1
+
+    # 压缩中间连续空行
+    result = []
+    prev_empty = False
+    for line in lines[start:]:
+        is_empty = line.strip() == ""
+        if is_empty and prev_empty:
+            continue  # 跳过连续空行
+        result.append(line)
+        prev_empty = is_empty
+
+    # 去除末尾空白
+    return "".join(result).rstrip()