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

langchain_agentx/tools/grep/backend.py

@@ -0,0 +1,375 @@
+"""
+tools/grep/backend.py — RipgrepBackend（ripgrep 子进程封装）
+
+职责：
+    构建 rg 参数、执行子进程、解析退出码与 stdout 行列表。
+
+在整体链路中的位置：
+    GrepRuntimeTool.invoke() -> RipgrepBackend.search() -> run_ripgrep_lines（可选 ctx.cancel_event）
+    -> RgSubprocessController 或 TextSubprocessRunner
+
+对应 CC：src/utils/ripgrep.ts + GrepTool.ts call() 中参数拼装。
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import threading
+from typing import Any
+
+from langchain_agentx.tool_runtime.errors import ToolRuntimeError
+from langchain_agentx.utils.rg_executable import default_rg_executable
+from langchain_agentx.utils.subprocess_text import (
+    TextSubprocessRunner,
+    default_text_subprocess_runner,
+)
+
+from .models import GrepOutputMode
+
+
+class GrepTimeoutError(ToolRuntimeError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, code="GREP_TIMEOUT")
+
+
+class GrepExecutionError(ToolRuntimeError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, code="GREP_EXECUTION_ERROR")
+
+
+class GrepCancelledError(ToolRuntimeError):
+    """协作取消（对齐 CC AbortSignal）；由 ``threading.Event`` 触发。"""
+
+    def __init__(self, message: str = "ripgrep cancelled") -> None:
+        super().__init__(message, code="GREP_CANCELLED")
+
+
+def run_ripgrep_lines(
+    rg_path: str,
+    args: list[str],
+    search_path: str,
+    *,
+    timeout: int,
+    text_runner: TextSubprocessRunner,
+    is_retry: bool = False,
+    cancel_event: threading.Event | None = None,
+) -> list[str]:
+    """
+    执行 [rg_path, *args, search_path]，解析 stdout 为行列表。
+    对齐 CC ripgrep.ts：returncode 1 -> []；EAGAIN 时以 -j 1 重试一次。
+    供 RipgrepBackend 与 Glob 的 rg --files 列文件共用。
+
+    若 ``cancel_event`` 非空，使用可中断子进程路径（``RgSubprocessController``），
+    不再走 ``text_runner.run``（便于测试 mock 时仅覆盖无取消路径）。
+    """
+    cmd = [rg_path, *args, search_path]
+    if cancel_event is not None:
+        if cancel_event.is_set():
+            raise GrepCancelledError("ripgrep cancelled before start")
+        from langchain_agentx.tools.grep.rg_subprocess_controller import RgSubprocessController
+
+        ctrl = RgSubprocessController()
+        try:
+            result = ctrl.run_argv_wait_completed(
+                cmd, timeout=float(timeout), cancel_event=cancel_event
+            )
+        except GrepTimeoutError:
+            raise
+        except GrepCancelledError:
+            raise
+    else:
+        try:
+            result = text_runner.run(
+                cmd,
+                capture_output=True,
+                timeout=timeout,
+            )
+        except subprocess.TimeoutExpired:
+            raise GrepTimeoutError(f"ripgrep search timed out after {timeout}s")
+        except FileNotFoundError as e:
+            raise GrepExecutionError(
+                "ripgrep executable not found. On Windows install ripgrep and ensure "
+                "'rg.exe' is on PATH; on Unix ensure 'rg' is on PATH."
+            ) from e
+
+    if result.returncode == 1:
+        return []
+
+    if result.returncode >= 2:
+        stderr = (result.stderr or "").strip()
+        if (not is_retry) and RipgrepBackend._is_eagain_error(stderr):
+            return run_ripgrep_lines(
+                rg_path,
+                ["-j", "1", *args],
+                search_path,
+                timeout=timeout,
+                text_runner=text_runner,
+                is_retry=True,
+                cancel_event=cancel_event,
+            )
+        raise GrepExecutionError(f"ripgrep failed: {stderr or f'exit code {result.returncode}'}")
+
+    out = result.stdout or ""
+    if not out.strip():
+        return []
+    lines = [ln.rstrip("\r") for ln in out.rstrip("\n").split("\n")]
+    return [ln for ln in lines if ln]
+
+
+class RipgrepBackend:
+    DEFAULT_TIMEOUT = 20
+    MAX_COLUMNS = 500
+    VCS_EXCLUDE_DIRS = (".git", ".svn", ".hg", ".bzr", ".jj", ".sl")
+
+    def __init__(
+        self,
+        *,
+        rg_path: str | None = None,
+        timeout: int = DEFAULT_TIMEOUT,
+        text_runner: TextSubprocessRunner | None = None,
+    ) -> None:
+        self._rg_path = rg_path if rg_path is not None else default_rg_executable()
+        self.timeout = timeout
+        self._text_runner = text_runner or default_text_subprocess_runner()
+
+    @staticmethod
+    def _parse_glob_patterns(glob_str: str) -> list[str]:
+        """与 CC GrepTool.ts 一致：空格分段，逗号拆分，保留 {...} 段。"""
+        patterns: list[str] = []
+        for raw in glob_str.split():
+            if "{" in raw and "}" in raw:
+                patterns.append(raw)
+            else:
+                patterns.extend(p for p in raw.split(",") if p)
+        return patterns
+
+    def _build_args(
+        self,
+        pattern: str,
+        *,
+        glob: str | None,
+        ignore_patterns: list[str] | None,
+        file_type: str | None,
+        output_mode: GrepOutputMode,
+        context_before: int | None,
+        context_after: int | None,
+        context: int | None,
+        show_line_numbers: bool,
+        case_insensitive: bool,
+        multiline: bool,
+        plugin_glob_exclusions: list[str] | None = None,
+    ) -> list[str]:
+        args: list[str] = ["--hidden"]
+        for d in self.VCS_EXCLUDE_DIRS:
+            args.extend(["--glob", f"!{d}"])
+        args.extend(["--max-columns", str(self.MAX_COLUMNS)])
+        if multiline:
+            args.extend(["-U", "--multiline-dotall"])
+        if case_insensitive:
+            args.append("-i")
+        if output_mode == GrepOutputMode.files_with_matches:
+            args.append("-l")
+        elif output_mode == GrepOutputMode.count:
+            args.append("-c")
+        if output_mode == GrepOutputMode.content and show_line_numbers:
+            args.append("-n")
+        if output_mode == GrepOutputMode.content:
+            if context is not None:
+                args.extend(["-C", str(context)])
+            else:
+                if context_before is not None:
+                    args.extend(["-B", str(context_before)])
+                if context_after is not None:
+                    args.extend(["-A", str(context_after)])
+        if pattern.startswith("-"):
+            args.extend(["-e", pattern])
+        else:
+            args.append(pattern)
+        if file_type:
+            args.extend(["--type", file_type])
+        if glob:
+            for g in self._parse_glob_patterns(glob):
+                args.extend(["--glob", g])
+        # Add ignore patterns (CC: getFileReadIgnorePatterns + normalizePatternsToPath).
+        # We implement the same ripgrep glob semantics:
+        # - patterns starting with '/' are treated as repo-root anchored (pass through)
+        # - otherwise prefix with '**/' so ripgrep applies them from the search root
+        # - negate with '!' to exclude them
+        if ignore_patterns:
+            for p in ignore_patterns:
+                p = str(p).strip()
+                if not p:
+                    continue
+                rg_pat = f"!{p}" if p.startswith("/") else f"!**/{p}"
+                args.extend(["--glob", rg_pat])
+        if plugin_glob_exclusions:
+            for ex in plugin_glob_exclusions:
+                if ex:
+                    args.extend(["--glob", ex])
+        return args
+
+    def search(
+        self,
+        pattern: str,
+        search_path: str,
+        *,
+        glob: str | None = None,
+        ignore_patterns: list[str] | None = None,
+        file_type: str | None = None,
+        output_mode: GrepOutputMode = GrepOutputMode.files_with_matches,
+        context_before: int | None = None,
+        context_after: int | None = None,
+        context: int | None = None,
+        show_line_numbers: bool = True,
+        case_insensitive: bool = False,
+        multiline: bool = False,
+        plugin_glob_exclusions: list[str] | None = None,
+        cancel_event: threading.Event | None = None,
+    ) -> list[str]:
+        args = self._build_args(
+            pattern,
+            glob=glob,
+            ignore_patterns=ignore_patterns,
+            file_type=file_type,
+            output_mode=output_mode,
+            context_before=context_before,
+            context_after=context_after,
+            context=context,
+            show_line_numbers=show_line_numbers,
+            case_insensitive=case_insensitive,
+            multiline=multiline,
+            plugin_glob_exclusions=plugin_glob_exclusions,
+        )
+        return self._execute(args, search_path, cancel_event=cancel_event)
+
+    def _execute(
+        self, args: list[str], search_path: str, *, cancel_event: threading.Event | None
+    ) -> list[str]:
+        return self._execute_with_retry(args, search_path, cancel_event=cancel_event)
+
+    @staticmethod
+    def _is_eagain_error(stderr: str) -> bool:
+        s = (stderr or "").lower()
+        return ("eagain" in s) or ("resource temporarily unavailable" in s)
+
+    def _execute_with_retry(
+        self,
+        args: list[str],
+        search_path: str,
+        *,
+        cancel_event: threading.Event | None,
+    ) -> list[str]:
+        """
+        对齐 CC ripgrep.ts 的关键鲁棒性：
+        - exit code 1: no matches -> []
+        - 遇到疑似 EAGAIN 启动错误时，额外重试一次单线程（-j 1）
+        """
+        return run_ripgrep_lines(
+            self._rg_path,
+            args,
+            search_path,
+            timeout=self.timeout,
+            text_runner=self._text_runner,
+            is_retry=False,
+            cancel_event=cancel_event,
+        )
+
+    def search_stream_limited(
+        self,
+        pattern: str,
+        search_path: str,
+        *,
+        glob: str | None = None,
+        ignore_patterns: list[str] | None = None,
+        file_type: str | None = None,
+        output_mode: GrepOutputMode,
+        context_before: int | None = None,
+        context_after: int | None = None,
+        context: int | None = None,
+        show_line_numbers: bool = True,
+        case_insensitive: bool = False,
+        multiline: bool = False,
+        max_lines: int,
+        plugin_glob_exclusions: list[str] | None = None,
+        cancel_event: threading.Event | None = None,
+    ) -> list[str]:
+        """
+        准流式读取 stdout，达到 max_lines 后提前终止进程。
+        仅用于 content / count 两种模式（files_with_matches 需要全量结果排序）。
+        """
+        args = self._build_args(
+            pattern,
+            glob=glob,
+            ignore_patterns=ignore_patterns,
+            file_type=file_type,
+            output_mode=output_mode,
+            context_before=context_before,
+            context_after=context_after,
+            context=context,
+            show_line_numbers=show_line_numbers,
+            case_insensitive=case_insensitive,
+            multiline=multiline,
+            plugin_glob_exclusions=plugin_glob_exclusions,
+        )
+        cmd = [self._rg_path, *args, search_path]
+        if cancel_event is not None and cancel_event.is_set():
+            raise GrepCancelledError("ripgrep cancelled before start")
+        try:
+            proc = subprocess.Popen(
+                cmd,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+            )
+        except FileNotFoundError as e:
+            raise GrepExecutionError(
+                "ripgrep executable not found. On Windows install ripgrep and ensure "
+                "'rg.exe' is on PATH; on Unix ensure 'rg' is on PATH."
+            ) from e
+
+        collected: list[str] = []
+        try:
+            assert proc.stdout is not None
+            for line in proc.stdout:
+                if cancel_event is not None and cancel_event.is_set():
+                    proc.terminate()
+                    raise GrepCancelledError("ripgrep cancelled")
+                if len(collected) >= max_lines:
+                    break
+                ln = line.rstrip("\n").rstrip("\r")
+                if ln:
+                    collected.append(ln)
+
+            if len(collected) >= max_lines:
+                # We intentionally stop early to cap output.
+                proc.terminate()
+
+            try:
+                stdout_tail, stderr_tail = proc.communicate(timeout=self.timeout)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                raise GrepTimeoutError(f"ripgrep search timed out after {self.timeout}s")
+
+            # Merge any remaining stdout (rare) if we didn't early stop
+            if stdout_tail and len(collected) < max_lines:
+                for ln in stdout_tail.rstrip("\n").split("\n"):
+                    if not ln or len(collected) >= max_lines:
+                        break
+                    collected.append(ln.rstrip("\r"))
+
+            rc = proc.returncode or 0
+            if rc == 1:
+                return []
+            if rc >= 2:
+                stderr = (stderr_tail or "").strip()
+                raise GrepExecutionError(f"ripgrep failed: {stderr or f'exit code {rc}'}")
+            return collected
+        finally:
+            # Ensure no zombie
+            try:
+                if proc.poll() is None:
+                    proc.kill()
+                    proc.wait(timeout=1)
+            except Exception:
+                pass

langchain_agentx/tools/grep/models.py

@@ -0,0 +1,127 @@
+"""
+tools/grep/models.py — GrepToolInput / GrepToolOutput
+
+职责：
+    面向模型与工具内部的 Pydantic 模型；阈值常量（默认 head_limit）。
+
+对应 CC：GrepTool.ts 中 inputSchema / outputSchema 的 Python 侧表达。
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import AliasChoices, BaseModel, Field
+
+DEFAULT_HEAD_LIMIT = 250
+
+
+class GrepOutputMode(str, Enum):
+    content = "content"
+    files_with_matches = "files_with_matches"
+    count = "count"
+
+
+class GrepToolInput(BaseModel):
+    pattern: str = Field(
+        ...,
+        description=(
+            "The regular expression pattern to search for in file contents. "
+            'Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+").'
+        ),
+    )
+    path: str | None = Field(
+        default=None,
+        description=(
+            "File or directory to search in. Defaults to workspace root. "
+            "Omit this field to search the default directory."
+        ),
+    )
+    glob: str | None = Field(
+        default=None,
+        description=(
+            'Glob pattern to filter files (e.g. "*.js", "*.{ts,tsx}"). Maps to ripgrep --glob.'
+        ),
+    )
+    output_mode: GrepOutputMode = Field(
+        default=GrepOutputMode.files_with_matches,
+        description=(
+            'Output mode. "content" shows matching lines (context, line numbers, head_limit). '
+            '"files_with_matches" shows file paths sorted by modification time. '
+            '"count" shows match counts per file.'
+        ),
+    )
+    context_before: int | None = Field(
+        default=None,
+        ge=0,
+        description='Lines before each match (rg -B). Requires output_mode "content".',
+        validation_alias=AliasChoices("context_before", "-B"),
+    )
+    context_after: int | None = Field(
+        default=None,
+        ge=0,
+        description='Lines after each match (rg -A). Requires output_mode "content".',
+        validation_alias=AliasChoices("context_after", "-A"),
+    )
+    context: int | None = Field(
+        default=None,
+        ge=0,
+        description="Lines before and after each match (rg -C). Overrides context_before/after.",
+        validation_alias=AliasChoices("context", "-C"),
+    )
+    show_line_numbers: bool = Field(
+        default=True,
+        description='Show line numbers. Requires output_mode "content".',
+        validation_alias=AliasChoices("show_line_numbers", "-n"),
+    )
+    case_insensitive: bool = Field(
+        default=False,
+        description="Case insensitive search (rg -i).",
+        validation_alias=AliasChoices("case_insensitive", "-i"),
+    )
+    file_type: str | None = Field(
+        default=None,
+        description='File type for rg --type (e.g. "js", "py", "rust").',
+        validation_alias=AliasChoices("file_type", "type"),
+    )
+    head_limit: int = Field(
+        default=DEFAULT_HEAD_LIMIT,
+        ge=0,
+        description=(
+            "Limit to first N lines/entries. Default 250. Use 0 for unlimited (large results cost context)."
+        ),
+    )
+    offset: int = Field(
+        default=0,
+        ge=0,
+        description="Skip first N entries before applying head_limit.",
+    )
+    multiline: bool = Field(
+        default=False,
+        description="Multiline mode: . matches newlines (rg -U --multiline-dotall).",
+    )
+
+
+class GrepToolOutput(BaseModel):
+    """工具 invoke() 返回值，供 present() 消费。"""
+
+    model_config = {"extra": "forbid"}
+
+    mode: GrepOutputMode
+    pattern: str
+    search_root: str
+
+    filenames: list[str] = Field(default_factory=list)
+    num_files: int = 0
+
+    content: str = ""
+    num_lines: int = 0
+
+    num_matches: int = 0
+    count_content: str = ""
+
+    truncated: bool = False
+    applied_limit: int | None = None
+    applied_offset: int | None = None
+
+    duration_ms: float = 0.0

langchain_agentx/tools/grep/prompt.py

@@ -0,0 +1,30 @@
+"""
+tools/grep/prompt.py — 工具名与模型可见描述
+
+对应 CC：src/tools/GrepTool/prompt.ts（getDescription）。
+"""
+
+from __future__ import annotations
+
+TOOL_NAME = "grep"
+
+
+def get_prompt() -> str:
+    """面向 StructuredTool.description 的完整说明。"""
+    return (
+        "A powerful search tool built on ripgrep\n\n"
+        "Usage:\n"
+        f"- ALWAYS use {TOOL_NAME} for search tasks. NEVER invoke `grep` or `rg` as a bash command. "
+        f"The {TOOL_NAME} tool respects read permissions and workspace policy.\n"
+        '- Supports full regex syntax (e.g., "log.*Error", "function\\s+\\w+")\n'
+        '- Filter files with glob (e.g., "*.js", "**/*.tsx") or file_type (e.g., "js", "py", "rust")\n'
+        '- Output modes: "content" = matching lines; "files_with_matches" = paths only (default); '
+        '"count" = per-file counts\n'
+        "- For open-ended searches needing multiple rounds, use an Agent / subagent workflow if available.\n"
+        "- Pattern syntax: ripgrep (not grep) — literal braces need escaping "
+        "(use `interface\\{\\}` to find `interface{}` in Go)\n"
+        "- Multiline: default patterns are single-line; for cross-line patterns use multiline: true\n"
+    )
+
+
+DESCRIPTION = get_prompt()

langchain_agentx/tools/grep/rg_subprocess_controller.py

@@ -0,0 +1,114 @@
+"""
+tools/grep/rg_subprocess_controller.py — ripgrep 子进程 timeout + 协作取消
+
+职责：
+    在无法使用单次 ``subprocess.run(..., timeout=)`` 响应协作取消时，用 Popen + 后台
+    ``communicate`` 与主线程轮询 ``cancel_event``，对齐 CC ``ripGrep(..., abortSignal)``。
+
+链路位置：
+    ``grep.backend.run_ripgrep_lines`` 在传入非空 ``cancel_event`` 时委托本类；
+    ``RipgrepBackend.search_stream_limited`` 在读取 stdout 时轮询同一事件。
+
+当前裁剪范围：
+    仅 argv 列表进程；不处理 shell=True；编码固定 utf-8/errors=replace（与 TextSubprocessRunner 一致）。
+"""
+
+from __future__ import annotations
+
+import subprocess
+import threading
+import time
+
+from langchain_agentx.tools.grep.backend import (
+    GrepCancelledError,
+    GrepExecutionError,
+    GrepTimeoutError,
+)
+
+
+class RgSubprocessController:
+    """封装可中断的阻塞式子进程等待（timeout + ``threading.Event``）。"""
+
+    _poll_interval_s = 0.05
+
+    def run_argv_wait_completed(
+        self,
+        argv: list[str],
+        *,
+        timeout: float,
+        cancel_event: threading.Event | None,
+    ) -> subprocess.CompletedProcess[str]:
+        """
+        启动 ``argv``，在 ``timeout`` 秒内等待结束；若 ``cancel_event`` 被 set 则 terminate/kill。
+
+        Returns:
+            ``CompletedProcess``（text stdout/stderr），供上层解析 returncode。
+        """
+        if cancel_event is not None and cancel_event.is_set():
+            raise GrepCancelledError("ripgrep cancelled before start")
+
+        try:
+            proc = subprocess.Popen(
+                argv,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+            )
+        except FileNotFoundError as e:
+            raise GrepExecutionError(
+                "ripgrep executable not found. On Windows install ripgrep and ensure "
+                "'rg.exe' is on PATH; on Unix ensure 'rg' is on PATH."
+            ) from e
+
+        out_box: list[str | None] = [None]
+        err_box: list[str | None] = [None]
+        thread_exc: list[BaseException | None] = [None]
+
+        def _communicate_worker() -> None:
+            try:
+                o, e = proc.communicate()
+                out_box[0] = o
+                err_box[0] = e
+            except BaseException as ex:  # noqa: BLE001 — 必须兜住线程内异常
+                thread_exc[0] = ex
+
+        worker = threading.Thread(target=_communicate_worker, daemon=True)
+        worker.start()
+        deadline = time.monotonic() + timeout
+
+        try:
+            while worker.is_alive():
+                if cancel_event is not None and cancel_event.is_set():
+                    proc.terminate()
+                    worker.join(timeout=2.0)
+                    if worker.is_alive():
+                        proc.kill()
+                        worker.join(timeout=2.0)
+                    raise GrepCancelledError("ripgrep cancelled")
+                if time.monotonic() >= deadline:
+                    proc.kill()
+                    worker.join(timeout=2.0)
+                    raise GrepTimeoutError(f"ripgrep search timed out after {timeout:g}s")
+                worker.join(timeout=self._poll_interval_s)
+
+            if thread_exc[0] is not None:
+                raise thread_exc[0]
+
+            return subprocess.CompletedProcess(
+                args=argv,
+                returncode=proc.returncode if proc.returncode is not None else -1,
+                stdout=out_box[0] or "",
+                stderr=err_box[0] or "",
+            )
+        finally:
+            if proc.poll() is None:
+                try:
+                    proc.kill()
+                except OSError:
+                    pass
+                try:
+                    proc.wait(timeout=1.0)
+                except (OSError, subprocess.TimeoutExpired):
+                    pass