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

langchain_agentx/tools/bash/sed_validation.py

@@ -0,0 +1,163 @@
+"""
+tools/bash/sed_validation.py — BashRuntimeTool 模块2：sed 命令安全与工作流判定
+
+职责：
+    将 `sed` 从普通 Bash 写命令里解耦出来，决定它应该走哪条执行路径：
+    1. 普通非原地 `sed`：继续走原有 Bash 权限链
+    2. 可稳定预览的 simple `sed -i`：进入 preview -> confirm -> apply
+    3. 含危险语义或无法稳定预览的 `sed -i`：保守 ask
+
+核心判定点：
+    - 是否为 in-place edit（`-i` / `--in-place`）
+    - substitution flags 中是否包含 `e/E/w/W` 等危险能力
+    - 是否能够通过 `sed_edit_parser.py` 生成确定性 preview
+
+与 `tool.py` 的关系：
+    `tool.py` 负责编排工作流和暂存 preview 结果；
+    本文件只回答“这个 sed 命令是否安全、是否可预览、是否必须人工审批”。
+
+与 CC 对照：
+    对应 CC `sedValidation.ts` 的基础版能力，当前只覆盖模块 2 需要的高价值分支。
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+from dataclasses import dataclass
+
+from .sed_edit_parser import BashSedEditParser, SedEditInfo
+
+
+@dataclass(frozen=True)
+class BashSedCommandCheck:
+    is_sed: bool
+    is_in_place: bool
+    requires_manual_approval: bool
+    reason: str | None = None
+    edit_info: SedEditInfo | None = None
+
+
+class BashSedCommandValidator:
+    """判断 sed 是否能走 preview/apply，或必须人工审批。"""
+
+    _DANGEROUS_SUBST_FLAGS = frozenset({"e", "E", "w", "W"})
+
+    def __init__(self, parser: BashSedEditParser | None = None) -> None:
+        self._parser = parser or BashSedEditParser()
+
+    def evaluate(self, command: str) -> BashSedCommandCheck:
+        tokens = self._split(command)
+        if not tokens or tokens[0] != "sed":
+            return BashSedCommandCheck(False, False, False)
+
+        in_place = self._has_in_place_flag(tokens[1:])
+        expressions = self._collect_inline_expressions(tokens[1:])
+        if self._contains_dangerous_expression(expressions):
+            return BashSedCommandCheck(
+                is_sed=True,
+                is_in_place=in_place,
+                requires_manual_approval=True,
+                reason=(
+                    "sed command requires explicit approval because it contains potentially "
+                    "dangerous write/execute operations."
+                ),
+            )
+
+        if not in_place:
+            return BashSedCommandCheck(
+                is_sed=True,
+                is_in_place=False,
+                requires_manual_approval=False,
+            )
+
+        edit_info = self._parser.parse(command)
+        if edit_info is None:
+            return BashSedCommandCheck(
+                is_sed=True,
+                is_in_place=True,
+                requires_manual_approval=True,
+                reason=(
+                    "sed -i command requires explicit approval because a deterministic preview "
+                    "cannot be generated safely."
+                ),
+            )
+        return BashSedCommandCheck(
+            is_sed=True,
+            is_in_place=True,
+            requires_manual_approval=False,
+            edit_info=edit_info,
+        )
+
+    @staticmethod
+    def _split(command: str) -> list[str]:
+        try:
+            return shlex.split(command)
+        except ValueError:
+            return command.split()
+
+    @staticmethod
+    def _has_in_place_flag(args: list[str]) -> bool:
+        return any(arg in {"-i", "--in-place"} or arg.startswith("-i") for arg in args)
+
+    def _collect_inline_expressions(self, args: list[str]) -> list[str]:
+        expressions: list[str] = []
+        i = 0
+        while i < len(args):
+            arg = args[i]
+            if arg in {"-e", "--expression"} and i + 1 < len(args):
+                expressions.append(args[i + 1])
+                i += 2
+                continue
+            if arg.startswith("--expression="):
+                expressions.append(arg.split("=", 1)[1])
+                i += 1
+                continue
+            if arg.startswith("-"):
+                i += 1
+                continue
+            if not expressions:
+                expressions.append(arg)
+            i += 1
+        return expressions
+
+    def _contains_dangerous_expression(self, expressions: list[str]) -> bool:
+        for expression in expressions:
+            parsed = self._parser.parse(f"sed -i {shlex.quote(expression)} dummy.txt")
+            if parsed is None:
+                dangerous_flags = self._extract_substitution_flags(expression)
+                if any(flag in self._DANGEROUS_SUBST_FLAGS for flag in dangerous_flags):
+                    return True
+                if re.search(r"(^|[;\s])[weWE](?:[\s]|$)", expression):
+                    return True
+                continue
+            if any(flag in self._DANGEROUS_SUBST_FLAGS for flag in parsed.flags):
+                return True
+        return False
+
+    @staticmethod
+    def _extract_substitution_flags(expression: str) -> str:
+        if not expression.startswith("s/"):
+            return ""
+        rest = expression[2:]
+        state = "pattern"
+        flags = ""
+        i = 0
+        while i < len(rest):
+            char = rest[i]
+            if char == "\\" and i + 1 < len(rest):
+                i += 2
+                continue
+            if char == "/":
+                if state == "pattern":
+                    state = "replacement"
+                elif state == "replacement":
+                    state = "flags"
+                else:
+                    return flags
+                i += 1
+                continue
+            if state == "flags":
+                flags += char
+            i += 1
+        return flags if state == "flags" else ""

langchain_agentx/tools/bash/semantics.py

@@ -0,0 +1,111 @@
+"""
+tools/bash/semantics.py — 命令退出码语义解析
+
+某些命令以非零退出码表达"正常信息"而非"错误"，需要特殊解释，
+否则工具框架会将其包装为 error envelope，导致模型误认为命令失败。
+
+对应 CC commandSemantics.ts 的 interpretCommandResult()。
+
+规则定义格式：
+    (命令匹配正则, {退出码: 语义描述})
+    语义描述为 None 表示该退出码视为成功（无 hint）
+    语义描述为字符串表示非错误但需要说明（作为 hint 展示）
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# ---------------------------------------------------------------------------
+# 规则表（对应 CC commandSemantics.ts）
+# ---------------------------------------------------------------------------
+
+# (command_pattern, {exit_code: hint_message | None})
+# hint_message=None  → 视为成功，无需说明
+# hint_message=str   → 视为成功，present() 中以 hint 形式告知模型
+_SEMANTIC_RULES: list[tuple[re.Pattern[str], dict[int, str | None]]] = [
+    # grep / rg / ag / ack：返回 1 = 无匹配（非错误）
+    (
+        re.compile(r"^(?:grep|rg|ag|ack|ugrep)\b"),
+        {1: "No matches found (exit code 1 is normal for grep when no lines match)"},
+    ),
+    # diff：返回 1 = 文件存在差异（非错误，是正常信息）
+    (
+        re.compile(r"^diff\b"),
+        {1: "Files differ (exit code 1 is normal for diff when files are different)"},
+    ),
+    # git diff / git log / git show：同 diff
+    (
+        re.compile(r"^git\s+(?:diff|log|show)\b"),
+        {1: "Files differ"},
+    ),
+    # test / [ ] / [[ ]]：返回 1 = 条件为假（正常行为）
+    # 注意：[ 和 [[ 不是字母字符，\b 在其后不生效，需要匹配后面的空格或行尾
+    (
+        re.compile(r"^(?:test(?:\s|$)|\[{1,2}(?:\s|$))"),
+        {1: "Condition is false (exit code 1 is normal for test/[ ] when condition is false)"},
+    ),
+    # cmp：返回 1 = 文件不同，返回 2 = 无法比较（错误）
+    (
+        re.compile(r"^cmp\b"),
+        {1: "Files are different (exit code 1 is normal for cmp when files differ)"},
+    ),
+    # ls：返回 2 = 无访问权限/不存在（真正错误，不覆盖）
+    # find：返回 1 = 无匹配或权限问题（某些 find 实现）
+    (
+        re.compile(r"^find\b"),
+        {1: None},  # 视为成功（find 无结果时返回 0 或 1 取决于实现）
+    ),
+    # git：某些子命令如 git fetch --dry-run 可能返回 1 表示有变更
+    (
+        re.compile(r"^git\s+fetch\b"),
+        {1: None},
+    ),
+]
+
+
+@dataclass
+class CommandResult:
+    """
+    命令退出码语义解析结果。
+
+    is_error=True  → 框架应将其视为错误（包装为 error envelope / 抛异常）
+    is_error=False → 视为成功，message 作为 hint 展示给模型
+    message        → 语义说明（非空时注入 present() 的 hints）
+    """
+
+    is_error: bool
+    message: str | None = None
+
+
+def interpret_command_result(
+    command: str,
+    exit_code: int,
+    stdout: str,  # noqa: ARG001  保留参数供将来内容感知判断使用
+) -> CommandResult:
+    """
+    解析命令退出码，判断是否为真正错误。
+
+    返回：
+        CommandResult.is_error=False → 非错误，可能包含 hint 说明
+        CommandResult.is_error=True  → 真正的执行错误
+
+    对应 CC commandSemantics.ts::interpretCommandResult()。
+    """
+    if exit_code == 0:
+        return CommandResult(is_error=False)
+
+    # 提取命令基础部分（去掉参数）用于正则匹配
+    cmd_stripped = command.strip()
+
+    for pattern, code_map in _SEMANTIC_RULES:
+        if pattern.match(cmd_stripped):
+            if exit_code in code_map:
+                hint = code_map[exit_code]
+                return CommandResult(is_error=False, message=hint)
+            # 命令匹配但退出码不在规则表 → 视为错误
+            return CommandResult(is_error=True)
+
+    # 未命中任何规则 → 非零退出码视为错误
+    return CommandResult(is_error=True)

langchain_agentx/tools/bash/session_manager.py

@@ -0,0 +1,205 @@
+"""
+tools/bash/session_manager.py — BashRuntimeTool v3：会话管理器
+
+职责：
+    管理多个 `BashSessionRuntime` 的创建、复用与销毁，保证：
+    1. 同一 session_key 复用同一长期 shell
+    2. 多会话之间状态隔离
+    3. 空闲会话按 TTL 清理
+
+与 CC 对照：
+    对应 CC 长期 shell 任务管理模型的 Python 化基础设施。
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+from dataclasses import dataclass
+
+from .session_runtime import BashSessionRuntime
+
+
+@dataclass
+class _SessionEntry:
+    runtime: BashSessionRuntime
+    last_used_ts: float
+    created_ts: float
+    command_count: int = 0
+    recycled_count: int = 0
+
+
+@dataclass(frozen=True)
+class BashSessionAuditRecord:
+    session_key: str
+    event: str
+    ts: float
+    details: dict[str, str]
+
+
+class BashSessionManager:
+    """Bash 长期会话管理器。"""
+
+    def __init__(
+        self,
+        *,
+        idle_ttl_sec: int = 900,
+        max_sessions: int = 16,
+        max_commands_per_session: int = 200,
+    ) -> None:
+        self._idle_ttl_sec = max(60, idle_ttl_sec)
+        self._max_sessions = max(1, max_sessions)
+        # 允许小阈值以便测试与细粒度回收（最小为 1）
+        self._max_commands_per_session = max(1, max_commands_per_session)
+        self._sessions: dict[str, _SessionEntry] = {}
+        self._audit_log: list[BashSessionAuditRecord] = []
+        self._lock = threading.Lock()
+
+    def get_or_create(
+        self,
+        *,
+        session_key: str,
+        cwd: str | None,
+        env: dict[str, str],
+    ) -> BashSessionRuntime:
+        now = time.time()
+        with self._lock:
+            self._cleanup_expired_locked(now)
+            self._enforce_max_sessions_locked(now)
+            entry = self._sessions.get(session_key)
+            if entry is None:
+                runtime = BashSessionRuntime(
+                    initial_cwd=cwd,
+                    base_env=env,
+                )
+                entry = _SessionEntry(runtime=runtime, last_used_ts=now, created_ts=now)
+                self._sessions[session_key] = entry
+                self._append_audit_locked(
+                    session_key=session_key,
+                    event="created",
+                    details={"cwd": cwd or "", "env_size": str(len(env))},
+                )
+            else:
+                entry.last_used_ts = now
+                if entry.command_count >= self._max_commands_per_session:
+                    entry.runtime.close()
+                    entry.runtime = BashSessionRuntime(initial_cwd=cwd, base_env=env)
+                    entry.command_count = 0
+                    entry.recycled_count += 1
+                    self._append_audit_locked(
+                        session_key=session_key,
+                        event="recycled_command_limit",
+                        details={"recycled_count": str(entry.recycled_count)},
+                    )
+            entry.command_count += 1
+            return entry.runtime
+
+    def reset_session(self, session_key: str, *, cwd: str | None = None, env: dict[str, str] | None = None) -> None:
+        with self._lock:
+            old = self._sessions.pop(session_key, None)
+            if old is not None:
+                old.runtime.close()
+            runtime = BashSessionRuntime(initial_cwd=cwd, base_env=(env or os.environ.copy()))
+            now = time.time()
+            self._sessions[session_key] = _SessionEntry(
+                runtime=runtime,
+                last_used_ts=now,
+                created_ts=now,
+                command_count=0,
+                recycled_count=0,
+            )
+            self._append_audit_locked(
+                session_key=session_key,
+                event="reset",
+                details={"cwd": cwd or "", "env_size": str(len(env or {}))},
+            )
+
+    def close_session(self, session_key: str) -> None:
+        with self._lock:
+            entry = self._sessions.pop(session_key, None)
+        if entry is not None:
+            entry.runtime.close()
+            with self._lock:
+                self._append_audit_locked(
+                    session_key=session_key,
+                    event="closed",
+                    details={},
+                )
+
+    def close_all(self) -> None:
+        with self._lock:
+            entries = list(self._sessions.values())
+            self._sessions.clear()
+        for entry in entries:
+            entry.runtime.close()
+
+    def _cleanup_expired_locked(self, now_ts: float) -> None:
+        expired_keys = [
+            key
+            for key, entry in self._sessions.items()
+            if (now_ts - entry.last_used_ts) > self._idle_ttl_sec
+        ]
+        for key in expired_keys:
+            entry = self._sessions.pop(key, None)
+            if entry is not None:
+                entry.runtime.close()
+                self._append_audit_locked(
+                    session_key=key,
+                    event="expired",
+                    details={"idle_ttl_sec": str(self._idle_ttl_sec)},
+                )
+
+    def _enforce_max_sessions_locked(self, now_ts: float) -> None:
+        if len(self._sessions) < self._max_sessions:
+            return
+        oldest_key = min(
+            self._sessions.keys(),
+            key=lambda k: self._sessions[k].last_used_ts,
+        )
+        oldest = self._sessions.pop(oldest_key, None)
+        if oldest is not None:
+            oldest.runtime.close()
+            self._append_audit_locked(
+                session_key=oldest_key,
+                event="evicted_max_sessions",
+                details={"max_sessions": str(self._max_sessions), "ts": str(now_ts)},
+            )
+
+    def get_audit_log(self, *, tail: int = 200) -> list[BashSessionAuditRecord]:
+        with self._lock:
+            if tail <= 0:
+                return []
+            return list(self._audit_log[-tail:])
+
+    def _append_audit_locked(self, *, session_key: str, event: str, details: dict[str, str]) -> None:
+        self._audit_log.append(
+            BashSessionAuditRecord(
+                session_key=session_key,
+                event=event,
+                ts=time.time(),
+                details=details,
+            )
+        )
+        if len(self._audit_log) > 2000:
+            self._audit_log = self._audit_log[-1000:]
+
+
+_GLOBAL_SESSION_MANAGER: BashSessionManager | None = None
+_GLOBAL_SESSION_MANAGER_LOCK = threading.Lock()
+
+
+def get_global_bash_session_manager() -> BashSessionManager:
+    """获取全局会话管理器（延迟初始化）。"""
+    global _GLOBAL_SESSION_MANAGER
+    with _GLOBAL_SESSION_MANAGER_LOCK:
+        if _GLOBAL_SESSION_MANAGER is None:
+            ttl = int(os.getenv("AGENTX_BASH_SESSION_IDLE_TTL_SEC", "900"))
+            max_sessions = int(os.getenv("AGENTX_BASH_MAX_SESSIONS", "16"))
+            max_commands = int(os.getenv("AGENTX_BASH_MAX_COMMANDS_PER_SESSION", "200"))
+            _GLOBAL_SESSION_MANAGER = BashSessionManager(
+                idle_ttl_sec=ttl,
+                max_sessions=max_sessions,
+                max_commands_per_session=max_commands,
+            )
+        return _GLOBAL_SESSION_MANAGER