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

langchain_agentx/tools/bash/session_runtime.py

@@ -0,0 +1,290 @@
+"""
+tools/bash/session_runtime.py — BashRuntimeTool v3：长期会话执行运行时
+
+职责：
+    提供单个长期存活 bash 会话的生命周期与命令执行能力，支持：
+    1. 同一会话内连续命令状态保持（cwd/env/shell context）
+    2. 命令级 begin/end/cwd 标记分帧
+    3. 超时中断与会话重建
+
+在整体链路中的位置：
+    - 由 `session_manager.py` 统一管理实例
+    - 由 `backend.py` 在非沙箱执行路径按配置选择调用
+
+与 CC 对照：
+    对应 CC `Shell.ts` / `LocalShellTask` 的长期 shell 会话语义基础能力。
+    当前是 v3 第一版：优先保证会话持久化与可靠分帧，不包含流式 UI 事件。
+
+**Windows 上 `BashBackend(use_persistent_session=True)` 前置条件**（exec-plan Phase 4）：
+    - 须有可用的 **POSIX shell**（`resolve_posix_shell` 或 **`posix_shell_executable=`** 注入）；
+    - 默认 **`use_persistent_session` 在 win32 为 false**（见 `bash_runtime_contract` / `BashBackend.__init__`），显式开启前请确认 **Git Bash/MSYS** 下 stdin 多行与换行稳定；
+    - 与 `BashBackend` 一致：子进程 **`SHELL`** 在未设置时指向解析到的 shell；**`AGENTX_BASH_CREATE_NO_WINDOW=1`** 时可传 **`CREATE_NO_WINDOW`**。
+"""
+
+from __future__ import annotations
+
+import os
+import queue
+import re
+import signal
+import subprocess
+import sys
+import threading
+import time
+import uuid
+from collections.abc import Iterator
+from dataclasses import dataclass
+
+from .shell_locator import resolve_posix_shell
+from .windows_shell_quoting import rewrite_windows_null_redirect
+
+
+_END_RE = re.compile(r"^__AGENTX_END_([A-Za-z0-9_]+)__:(-?\d+)$")
+
+
+@dataclass(frozen=True)
+class BashSessionExecResult:
+    stdout: str
+    exit_code: int
+    interrupted: bool
+    cwd_after: str | None = None
+
+
+@dataclass(frozen=True)
+class BashSessionStreamEvent:
+    kind: str
+    chunk: str | None = None
+    exit_code: int | None = None
+    interrupted: bool | None = None
+    cwd_after: str | None = None
+
+
+class BashSessionRuntime:
+    """单个长期 bash 会话运行时。"""
+
+    def __init__(
+        self,
+        *,
+        initial_cwd: str | None = None,
+        base_env: dict[str, str] | None = None,
+        posix_shell_executable: str | None = None,
+    ) -> None:
+        self._initial_cwd = initial_cwd
+        self._base_env = dict(base_env or os.environ.copy())
+        self._posix_shell_override = posix_shell_executable
+        self._proc: subprocess.Popen[str] | None = None
+        self._reader_thread: threading.Thread | None = None
+        self._line_queue: queue.Queue[str] = queue.Queue()
+        self._lock = threading.Lock()
+        self._closed = False
+        self._shell_exe: str | None = None
+        self._start()
+
+    def execute(self, command: str, timeout_sec: int) -> BashSessionExecResult:
+        events = self.execute_stream(command=command, timeout_sec=timeout_sec)
+        stdout_parts: list[str] = []
+        final_exit_code = -1
+        final_interrupted = False
+        final_cwd_after: str | None = None
+        for ev in events:
+            if ev.kind == "chunk" and ev.chunk:
+                stdout_parts.append(ev.chunk)
+            if ev.kind == "final":
+                final_exit_code = ev.exit_code if ev.exit_code is not None else -1
+                final_interrupted = bool(ev.interrupted)
+                final_cwd_after = ev.cwd_after
+        return BashSessionExecResult(
+            stdout="".join(stdout_parts),
+            exit_code=final_exit_code,
+            interrupted=final_interrupted,
+            cwd_after=final_cwd_after,
+        )
+
+    def execute_stream(self, command: str, timeout_sec: int) -> list[BashSessionStreamEvent]:
+        return list(self.execute_stream_iter(command=command, timeout_sec=timeout_sec))
+
+    def execute_stream_iter(
+        self,
+        *,
+        command: str,
+        timeout_sec: int,
+        cancel_event: threading.Event | None = None,
+    ) -> Iterator[BashSessionStreamEvent]:
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("Bash session runtime is closed")
+            self._ensure_alive()
+            assert self._proc is not None
+            token = uuid.uuid4().hex[:12]
+            begin_marker = f"__AGENTX_BEGIN_{token}__"
+            cwd_marker_prefix = f"__AGENTX_CWD_{token}__:"
+            end_marker_prefix = f"__AGENTX_END_{token}__:"
+            command = rewrite_windows_null_redirect(command)
+            wrapped = (
+                f"printf '%s\\n' '{begin_marker}'\n"
+                f"{command}\n"
+                f"__AGENTX_EC=$?\n"
+                f"printf '%s%s\\n' '{cwd_marker_prefix}' \"$PWD\"\n"
+                f"printf '%s%s\\n' '{end_marker_prefix}' \"$__AGENTX_EC\"\n"
+            )
+            assert self._proc.stdin is not None
+            self._proc.stdin.write(wrapped)
+            self._proc.stdin.flush()
+
+            collecting = False
+            cwd_after: str | None = None
+            deadline = time.monotonic() + max(1, timeout_sec)
+            while True:
+                if cancel_event is not None and cancel_event.is_set():
+                    self._interrupt_and_restart()
+                    yield BashSessionStreamEvent(
+                        kind="final",
+                        exit_code=-1,
+                        interrupted=True,
+                        cwd_after=cwd_after,
+                    )
+                    return
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    self._interrupt_and_restart()
+                    yield BashSessionStreamEvent(
+                        kind="final",
+                        exit_code=-1,
+                        interrupted=True,
+                        cwd_after=cwd_after,
+                    )
+                    return
+                try:
+                    line = self._line_queue.get(timeout=remaining)
+                except queue.Empty:
+                    self._interrupt_and_restart()
+                    yield BashSessionStreamEvent(
+                        kind="final",
+                        exit_code=-1,
+                        interrupted=True,
+                        cwd_after=cwd_after,
+                    )
+                    return
+
+                if not collecting:
+                    if line.rstrip("\n") == begin_marker:
+                        collecting = True
+                    continue
+
+                stripped = line.rstrip("\n")
+                if stripped.startswith(cwd_marker_prefix):
+                    cwd_after = stripped[len(cwd_marker_prefix):]
+                    continue
+                match = _END_RE.match(stripped)
+                if match and stripped.startswith(end_marker_prefix):
+                    exit_code = int(match.group(2))
+                    yield BashSessionStreamEvent(
+                        kind="final",
+                        exit_code=exit_code,
+                        interrupted=False,
+                        cwd_after=cwd_after,
+                    )
+                    return
+                yield BashSessionStreamEvent(kind="chunk", chunk=line)
+
+    def close(self) -> None:
+        with self._lock:
+            self._closed = True
+            self._terminate_process()
+
+    def _resolve_shell_exe(self) -> str:
+        if self._posix_shell_override is not None:
+            return os.path.normpath(
+                os.path.realpath(os.path.expanduser(self._posix_shell_override))
+            )
+        return resolve_posix_shell(environ=self._base_env)
+
+    def _spawn_env(self, shell_exe: str) -> dict[str, str]:
+        out = dict(self._base_env)
+        out.setdefault("SHELL", shell_exe)
+        return out
+
+    @staticmethod
+    def _win32_creationflags() -> int:
+        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 _start(self) -> None:
+        self._line_queue = queue.Queue()
+        if self._shell_exe is None:
+            self._shell_exe = self._resolve_shell_exe()
+        shell_exe = self._shell_exe
+        assert shell_exe is not None
+        spawn_env = self._spawn_env(shell_exe)
+        _cf = self._win32_creationflags()
+        if _cf:
+            self._proc = subprocess.Popen(
+                [shell_exe, "--noprofile", "--norc"],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                cwd=self._initial_cwd,
+                env=spawn_env,
+                start_new_session=True,
+                text=True,
+                bufsize=1,
+                creationflags=_cf,
+            )
+        else:
+            self._proc = subprocess.Popen(
+                [shell_exe, "--noprofile", "--norc"],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                cwd=self._initial_cwd,
+                env=spawn_env,
+                start_new_session=True,
+                text=True,
+                bufsize=1,
+            )
+        self._reader_thread = threading.Thread(
+            target=self._reader_loop,
+            name="bash-session-reader",
+            daemon=True,
+        )
+        self._reader_thread.start()
+
+    def _reader_loop(self) -> None:
+        proc = self._proc
+        if proc is None or proc.stdout is None:
+            return
+        while True:
+            line = proc.stdout.readline()
+            if line == "":
+                break
+            self._line_queue.put(line)
+
+    def _ensure_alive(self) -> None:
+        if self._proc is None or self._proc.poll() is not None:
+            self._start()
+
+    def _interrupt_and_restart(self) -> None:
+        self._terminate_process(send_interrupt=True)
+        self._start()
+
+    def _terminate_process(self, send_interrupt: bool = False) -> None:
+        proc = self._proc
+        self._proc = None
+        if proc is None:
+            return
+        try:
+            if proc.poll() is None:
+                if send_interrupt:
+                    os.killpg(proc.pid, signal.SIGINT)
+                    time.sleep(0.1)
+                if proc.poll() is None:
+                    os.killpg(proc.pid, signal.SIGTERM)
+                    time.sleep(0.1)
+                if proc.poll() is None:
+                    os.killpg(proc.pid, signal.SIGKILL)
+            proc.wait(timeout=1)
+        except Exception:
+            pass

langchain_agentx/tools/bash/shell_locator.py

@@ -0,0 +1,191 @@
+"""
+shell_locator.py — POSIX shell（bash/zsh）可执行文件解析
+
+职责：
+    按冻结顺序解析 **绝对路径**：环境变量覆盖 → PATH 上 `where`/`which` → 固定回退路径；
+    并对候选做 **basename 含 bash|zsh**、普通文件、可执行性校验（对齐 CC `findSuitableShell` 思路）。
+
+链路位置：
+    `BashBackend` / `BashSessionRuntime` 在 `Popen` / `create_subprocess_exec` 前取 argv[0]；
+    顺序常量与 `bash_runtime_contract.SHELL_ENV_PRECEDENCE` 一致。
+
+当前裁剪范围：
+    不重写用户命令；WSL 包装命令非默认解析链。Windows cwd 文件回传见 **`cwd_reporter.py`**。
+    Windows 使用 **`where.exe`** 遍历 PATH（与 CC `utils/which.ts` 语义对齐）；**不**将
+    `shutil.which("bash")` 作为 Windows 主路径来源——因 `shutil.which` 与 `where.exe` 在
+    PATHEXT、遍历顺序上可能不一致（若未来改为 which 主路径，须在模块注释与单测
+    中写明与 CC 的差异及原因）。
+
+CC 对照（src/ 相对 CC 检出根）：
+    `utils/Shell.ts` — `findSuitableShell`
+    `utils/which.ts` — `where.exe` 与首行语义
+    `utils/windowsPaths.ts` — cwd 下同名 exe 过滤（本实现 `_skip_if_in_cwd`）
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from collections.abc import Mapping
+
+from .bash_runtime_contract import SHELL_ENV_PRECEDENCE
+
+_RUNTIME_ERROR_LEAD = (
+    "BashRuntimeTool：未找到可用的 POSIX shell（bash / zsh）。\n\n"
+    "推荐：\n"
+    "  1. 安装 Git for Windows：https://git-scm.com/download/win\n"
+    "  2. 安装后在 CMD 中执行：where bash\n"
+    "     应出现类似：C:\\Program Files\\Git\\bin\\bash.exe\n\n"
+    "临时指定（本工程优先于 CC 变量）：\n"
+    "  set LANGCHAIN_AGENTX_SHELL=C:\\path\\to\\bash.exe\n\n"
+    "兼容 CC：\n"
+    "  set CLAUDE_CODE_SHELL=C:\\path\\to\\bash.exe\n\n"
+    "当前已尝试：\n"
+    "  LANGCHAIN_AGENTX_SHELL → CLAUDE_CODE_SHELL → SHELL → where/which → 常见路径回退\n"
+)
+
+_WIN_GIT_BASH_FALLBACKS: tuple[str, ...] = (
+    r"C:\Program Files\Git\bin\bash.exe",
+    r"C:\Program Files (x86)\Git\bin\bash.exe",
+)
+
+_POSIX_BASH_FALLBACKS: tuple[str, ...] = (
+    "/bin/bash",
+    "/usr/bin/bash",
+    "/usr/local/bin/bash",
+    "/opt/homebrew/bin/bash",
+)
+
+_POSIX_ZSH_FALLBACKS: tuple[str, ...] = (
+    "/bin/zsh",
+    "/usr/bin/zsh",
+    "/usr/local/bin/zsh",
+    "/opt/homebrew/bin/zsh",
+)
+
+
+def _norm_exe(path: str) -> str:
+    return os.path.normpath(os.path.realpath(os.path.expanduser(path.strip().strip('"'))))
+
+
+def _basename_ok(path: str) -> bool:
+    base = os.path.basename(path).lower()
+    return "bash" in base or "zsh" in base
+
+
+def _skip_if_in_cwd(path: str) -> bool:
+    """与 CC cwd 投毒防护类似：跳过「解析后位于当前工作目录」的候选。"""
+    try:
+        d = os.path.realpath(os.path.dirname(os.path.abspath(path)))
+        c = os.path.realpath(os.getcwd())
+        return d == c
+    except (OSError, ValueError):
+        return False
+
+
+def _is_executable_file(path: str) -> bool:
+    if not os.path.isfile(path):
+        return False
+    if os.access(path, os.X_OK):
+        return True
+    try:
+        r = subprocess.run(
+            [path, "--version"],
+            capture_output=True,
+            timeout=5,
+            env=os.environ,
+        )
+        return r.returncode == 0
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+
+
+def _validate_shell(path: str, *, allow_in_cwd: bool = False) -> str | None:
+    p = _norm_exe(path)
+    if not _basename_ok(p):
+        return None
+    if not allow_in_cwd and _skip_if_in_cwd(p):
+        return None
+    if not _is_executable_file(p):
+        return None
+    return p
+
+
+def _where_win(names: tuple[str, ...], env: dict[str, str]) -> list[str]:
+    out: list[str] = []
+    for name in names:
+        try:
+            cp = subprocess.run(
+                ["where.exe", name],
+                capture_output=True,
+                text=True,
+                timeout=30,
+                env=env,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            continue
+        if cp.returncode != 0 or not (cp.stdout or "").strip():
+            continue
+        for line in cp.stdout.splitlines():
+            s = line.strip().strip('"')
+            if s:
+                out.append(s)
+    return out
+
+
+def _which_posix(cmd: str, env: dict[str, str]) -> str | None:
+    path = env.get("PATH")
+    if path:
+        return shutil.which(cmd, path=path)
+    return shutil.which(cmd)
+
+
+class PosixShellLocator:
+    """从环境中解析 POSIX shell 绝对路径。"""
+
+    __slots__ = ("_environ",)
+
+    def __init__(self, environ: Mapping[str, str] | None = None) -> None:
+        self._environ = dict(os.environ if environ is None else environ)
+
+    def resolve(self) -> str:
+        merged = self._environ
+
+        for key in SHELL_ENV_PRECEDENCE:
+            raw = merged.get(key)
+            if raw is None or not str(raw).strip():
+                continue
+            candidate = _norm_exe(str(raw))
+            ok = _validate_shell(candidate, allow_in_cwd=True)
+            if ok:
+                return ok
+
+        if sys.platform == "win32":
+            for line in _where_win(("bash", "zsh"), merged):
+                ok = _validate_shell(line, allow_in_cwd=False)
+                if ok:
+                    return ok
+            for fb in _WIN_GIT_BASH_FALLBACKS:
+                ok = _validate_shell(fb, allow_in_cwd=False)
+                if ok:
+                    return ok
+        else:
+            for cmd in ("bash", "zsh"):
+                w = _which_posix(cmd, merged)
+                if w:
+                    ok = _validate_shell(w, allow_in_cwd=False)
+                    if ok:
+                        return ok
+            for fb in _POSIX_BASH_FALLBACKS + _POSIX_ZSH_FALLBACKS:
+                ok = _validate_shell(fb, allow_in_cwd=False)
+                if ok:
+                    return ok
+
+        raise RuntimeError(_RUNTIME_ERROR_LEAD)
+
+
+def resolve_posix_shell(environ: Mapping[str, str] | None = None) -> str:
+    """解析并返回 POSIX shell 绝对路径（薄封装）。"""
+    return PosixShellLocator(environ=environ).resolve()

langchain_agentx/tools/bash/task_runtime.py

@@ -0,0 +1,91 @@
+"""
+tools/bash/task_runtime.py — P1 任务编排统一状态机协议
+
+职责：
+    提供前后台统一任务生命周期状态机与快照模型：
+    created -> running -> (completed|failed|interrupted|cancelled)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+TaskMode = Literal["foreground", "background"]
+TaskStatus = Literal[
+    "created",
+    "running",
+    "completed",
+    "failed",
+    "interrupted",
+    "cancelled",
+]
+
+
+@dataclass(frozen=True)
+class BashTaskSnapshot:
+    task_id: str
+    task_mode: TaskMode
+    task_status: TaskStatus
+    exit_code: int | None
+    running: bool
+    created_ts: float | None = None
+    started_ts: float | None = None
+    ended_ts: float | None = None
+    output_path: str | None = None
+    pid: int | None = None
+    output_size: int | None = None
+
+
+@dataclass
+class BashTaskStateMachine:
+    """任务状态机：显式限制状态转移。"""
+
+    task_id: str
+    task_mode: TaskMode
+    status: TaskStatus = "created"
+    exit_code: int | None = None
+    created_ts: float | None = None
+    started_ts: float | None = None
+    ended_ts: float | None = None
+    output_path: str | None = None
+    pid: int | None = None
+    output_size: int | None = None
+    _history: list[TaskStatus] = field(default_factory=lambda: ["created"])
+
+    _TRANSITIONS: dict[TaskStatus, set[TaskStatus]] = field(
+        init=False,
+        default_factory=lambda: {
+            "created": {"running", "cancelled"},
+            "running": {"completed", "failed", "interrupted", "cancelled"},
+            "completed": set(),
+            "failed": set(),
+            "interrupted": set(),
+            "cancelled": set(),
+        },
+    )
+
+    def transition_to(self, status: TaskStatus) -> None:
+        allowed = self._TRANSITIONS.get(self.status, set())
+        if status not in allowed:
+            raise ValueError(f"Invalid task state transition: {self.status} -> {status}")
+        self.status = status
+        self._history.append(status)
+
+    def to_snapshot(self) -> BashTaskSnapshot:
+        # 仅 running 表示仍在执行；终态均为 running=False
+        running = self.status == "running"
+        return BashTaskSnapshot(
+            task_id=self.task_id,
+            task_mode=self.task_mode,
+            task_status=self.status,
+            exit_code=self.exit_code,
+            running=running,
+            created_ts=self.created_ts,
+            started_ts=self.started_ts,
+            ended_ts=self.ended_ts,
+            output_path=self.output_path,
+            pid=self.pid,
+            output_size=self.output_size,
+        )