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

langchain_agentx/tools/grep/tool.py

@@ -0,0 +1,475 @@
+"""
+tools/grep/tool.py — GrepRuntimeTool
+
+职责：
+    RuntimeTool 生命周期编排：normalize / validate / permissions / invoke / present。
+
+对应 CC：GrepTool.ts（call + mapToolResultToToolResultBlockParam 语义由 present 承担）。
+    validate_input 对 UNC / ``//`` 前缀跳过本地 exists，与 CC validateInput 一致（utils.unc_path）。
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import Any
+
+from langchain_agentx.tool_runtime.base import RuntimeTool
+from langchain_agentx.utils.path_user_input import UserPathInputNormalizer
+from langchain_agentx.tool_runtime.models import (
+    AuthorizationDecision,
+    ToolExecutionContext,
+    ToolHint,
+    ToolResultEnvelope,
+    ValidationResult,
+)
+
+from langchain_agentx.tools.ripgrep_plugin_exclusions import PluginCacheGlobExclusions
+from langchain_agentx.utils.rg_executable import default_rg_executable
+from langchain_agentx.utils.unc_path import is_unc_path_skip_local_stat
+
+from .backend import RipgrepBackend
+from .models import DEFAULT_HEAD_LIMIT, GrepOutputMode, GrepToolInput, GrepToolOutput
+from .prompt import DESCRIPTION, TOOL_NAME
+
+
+def _apply_head_limit(
+    items: list[Any],
+    head_limit: int,
+    offset: int,
+) -> tuple[list[Any], bool, int | None, int | None]:
+    """对齐 CC applyHeadLimit：head_limit=0 无限制；截断时才设置 applied_limit。"""
+    if head_limit == 0:
+        sliced = items[offset:]
+        return sliced, False, None, offset if offset > 0 else None
+    sliced = items[offset : offset + head_limit]
+    truncated = len(items) - offset > head_limit
+    applied_limit = head_limit if truncated else None
+    applied_offset = offset if offset > 0 else None
+    return sliced, truncated, applied_limit, applied_offset
+
+
+def _resolve_hit_path(line: str, search_root: str) -> str:
+    line = line.strip()
+    if not line:
+        return line
+    if os.path.isabs(line):
+        return os.path.normpath(line)
+    base = search_root if os.path.isdir(search_root) else os.path.dirname(search_root)
+    return os.path.normpath(os.path.join(base, line))
+
+
+def _plural(n: int, one: str, many: str) -> str:
+    return one if n == 1 else many
+
+
+class GrepRuntimeTool(RuntimeTool):
+    name: str = TOOL_NAME
+    description: str = DESCRIPTION
+    input_model = GrepToolInput
+    output_model = GrepToolOutput
+    is_read_only: bool = True
+    is_concurrency_safe: bool = True
+    never_truncate: bool = False
+    dedupe_identical_calls: bool = True
+    max_result_size_chars: int = 20_000
+
+    def __init__(
+        self,
+        *,
+        workspace_root: str,
+        policy: Any | None = None,
+        state_bridge: Any | None = None,
+        backend: RipgrepBackend | None = None,
+        rg_path: str | None = None,
+        rg_timeout: int = RipgrepBackend.DEFAULT_TIMEOUT,
+        ignore_patterns: list[str] | None = None,
+        path_normalizer: UserPathInputNormalizer | None = None,
+        plugin_cache_glob_exclusions: PluginCacheGlobExclusions | None = None,
+    ) -> None:
+        super().__init__(policy=policy, state_bridge=state_bridge)
+        self._workspace_root = os.path.realpath(os.path.expanduser(workspace_root))
+        self._ignore_patterns = [p for p in (ignore_patterns or []) if str(p).strip()]
+        self._path_normalizer = path_normalizer or UserPathInputNormalizer()
+        self._plugin_cache_glob_exclusions = plugin_cache_glob_exclusions
+        resolved_rg = rg_path if rg_path is not None else default_rg_executable()
+        self._backend = backend or RipgrepBackend(rg_path=resolved_rg, timeout=rg_timeout)
+
+    def normalize_input(
+        self, raw: dict[str, Any], ctx: ToolExecutionContext
+    ) -> dict[str, Any]:
+        data = dict(raw)
+        path = data.get("path")
+        from langchain_agentx.utils.cwd import get_cwd
+
+        if path is None or (isinstance(path, str) and not path.strip()):
+            data["path"] = ctx.cwd or get_cwd()
+        elif isinstance(path, str):
+            data["path"] = self._path_normalizer.normalize_and_expand(
+                path, base_dir=ctx.cwd
+            )
+        pat = data.get("pattern")
+        if isinstance(pat, str):
+            data["pattern"] = pat.strip()
+        return data
+
+    def validate_input(
+        self, data: dict[str, Any], ctx: ToolExecutionContext
+    ) -> ValidationResult:
+        pattern = (data.get("pattern") or "").strip()
+        if not pattern:
+            return ValidationResult(
+                ok=False,
+                message="Pattern cannot be empty",
+                code="EMPTY_PATTERN",
+            )
+        search_path = data.get("path") or ""
+        # CC validateInput：UNC / // 前缀跳过本地 stat（防 NTLM 等凭据面）
+        if is_unc_path_skip_local_stat(search_path):
+            return ValidationResult(ok=True)
+        if not os.path.exists(search_path):
+            return ValidationResult(
+                ok=False,
+                message=(
+                    f"Path does not exist: {search_path}. "
+                    f"Current workspace: {self._workspace_root}."
+                ),
+                code="PATH_NOT_FOUND",
+            )
+        return ValidationResult(ok=True)
+
+    def check_permissions(
+        self, data: dict[str, Any], ctx: ToolExecutionContext
+    ) -> AuthorizationDecision:
+        """
+        显式授权入口：与 RuntimeTool 基类行为一致，委托 PolicyEngine。
+        保留该 hook 便于审计与后续扩展 grep 特有权限策略。
+        """
+        return super().check_permissions(data, ctx)
+
+    def invoke(self, data: dict[str, Any], ctx: ToolExecutionContext) -> GrepToolOutput:
+        t0 = time.perf_counter()
+        pattern = str(data["pattern"]).strip()
+        search_root = str(data["path"])
+        mode = GrepOutputMode(data.get("output_mode", GrepOutputMode.files_with_matches))
+        head_limit = int(data.get("head_limit", DEFAULT_HEAD_LIMIT))
+        offset = int(data.get("offset", 0))
+
+        glob = data.get("glob")
+        glob_s = str(glob).strip() if glob else None
+        if glob_s == "":
+            glob_s = None
+
+        ft = data.get("file_type")
+        ft_s = str(ft).strip() if ft else None
+        if ft_s == "":
+            ft_s = None
+
+        ctx_before = data.get("context_before")
+        ctx_after = data.get("context_after")
+        ctx_unified = data.get("context")
+        show_ln = bool(data.get("show_line_numbers", True))
+        case_i = bool(data.get("case_insensitive", False))
+        multiline = bool(data.get("multiline", False))
+
+        plugin_ex: list[str] | None = None
+        if self._plugin_cache_glob_exclusions is not None:
+            plugin_ex = self._plugin_cache_glob_exclusions.get_exclusions_for_search(
+                search_root
+            )
+            if not plugin_ex:
+                plugin_ex = None
+
+        cancel_ev = ctx.cancel_event
+
+        # CC 在 content/count 模式下会先 applyHeadLimit 再做相对化，避免无界输出。
+        # 这里实现“准流式提前截止”：当 head_limit!=0 时，仅收集 offset+head_limit 行。
+        if mode in (GrepOutputMode.content, GrepOutputMode.count) and head_limit != 0:
+            raw_lines = self._backend.search_stream_limited(
+                pattern,
+                search_root,
+                glob=glob_s,
+                ignore_patterns=self._ignore_patterns,
+                file_type=ft_s,
+                output_mode=mode,
+                context_before=ctx_before if mode == GrepOutputMode.content else None,
+                context_after=ctx_after if mode == GrepOutputMode.content else None,
+                context=ctx_unified if mode == GrepOutputMode.content else None,
+                show_line_numbers=show_ln if mode == GrepOutputMode.content else True,
+                case_insensitive=case_i,
+                multiline=multiline,
+                max_lines=offset + head_limit,
+                plugin_glob_exclusions=plugin_ex,
+                cancel_event=cancel_ev,
+            )
+        else:
+            raw_lines = self._backend.search(
+                pattern,
+                search_root,
+                glob=glob_s,
+                ignore_patterns=self._ignore_patterns,
+                file_type=ft_s,
+                output_mode=mode,
+                context_before=ctx_before if mode == GrepOutputMode.content else None,
+                context_after=ctx_after if mode == GrepOutputMode.content else None,
+                context=ctx_unified if mode == GrepOutputMode.content else None,
+                show_line_numbers=show_ln if mode == GrepOutputMode.content else True,
+                case_insensitive=case_i,
+                multiline=multiline,
+                plugin_glob_exclusions=plugin_ex,
+                cancel_event=cancel_ev,
+            )
+
+        duration_ms = (time.perf_counter() - t0) * 1000.0
+
+        if mode == GrepOutputMode.content:
+            return self._finish_content(
+                raw_lines, pattern, search_root, head_limit, offset, duration_ms
+            )
+        if mode == GrepOutputMode.count:
+            return self._finish_count(
+                raw_lines, pattern, search_root, head_limit, offset, duration_ms
+            )
+        return self._finish_files(
+            raw_lines, pattern, search_root, head_limit, offset, duration_ms
+        )
+
+    def _finish_files(
+        self,
+        raw_lines: list[str],
+        pattern: str,
+        search_root: str,
+        head_limit: int,
+        offset: int,
+        duration_ms: float,
+    ) -> GrepToolOutput:
+        paths = [_resolve_hit_path(ln, search_root) for ln in raw_lines if ln.strip()]
+
+        def _mtime_or_zero(p: str) -> float:
+            try:
+                return os.path.getmtime(p)
+            except OSError:
+                return 0.0
+
+        sorted_paths = sorted(paths, key=_mtime_or_zero, reverse=True)
+        sliced, truncated, applied_limit, applied_offset = _apply_head_limit(
+            sorted_paths, head_limit, offset
+        )
+        rels = [self._to_relative(p) for p in sliced]
+        return GrepToolOutput(
+            mode=GrepOutputMode.files_with_matches,
+            pattern=pattern,
+            search_root=search_root,
+            filenames=rels,
+            num_files=len(rels),
+            truncated=truncated,
+            applied_limit=applied_limit,
+            applied_offset=applied_offset,
+            duration_ms=duration_ms,
+        )
+
+    def _finish_content(
+        self,
+        raw_lines: list[str],
+        pattern: str,
+        search_root: str,
+        head_limit: int,
+        offset: int,
+        duration_ms: float,
+    ) -> GrepToolOutput:
+        sliced, truncated, applied_limit, applied_offset = _apply_head_limit(
+            raw_lines, head_limit, offset
+        )
+        final_lines = [self._relativize_content_line(ln, search_root) for ln in sliced]
+        body = "\n".join(final_lines)
+        return GrepToolOutput(
+            mode=GrepOutputMode.content,
+            pattern=pattern,
+            search_root=search_root,
+            content=body,
+            num_lines=len(final_lines),
+            truncated=truncated,
+            applied_limit=applied_limit,
+            applied_offset=applied_offset,
+            duration_ms=duration_ms,
+        )
+
+    def _finish_count(
+        self,
+        raw_lines: list[str],
+        pattern: str,
+        search_root: str,
+        head_limit: int,
+        offset: int,
+        duration_ms: float,
+    ) -> GrepToolOutput:
+        sliced, truncated, applied_limit, applied_offset = _apply_head_limit(
+            raw_lines, head_limit, offset
+        )
+        final_lines: list[str] = []
+        total_matches = 0
+        file_count = 0
+        for ln in sliced:
+            idx = ln.rfind(":")
+            if idx <= 0:
+                final_lines.append(ln)
+                continue
+            file_path = ln[:idx]
+            count_str = ln[idx + 1 :].strip()
+            try:
+                cnt = int(count_str)
+            except ValueError:
+                cnt = 0
+            total_matches += cnt
+            file_count += 1
+            final_lines.append(self._to_relative(_resolve_hit_path(file_path, search_root)) + ":" + count_str)
+
+        return GrepToolOutput(
+            mode=GrepOutputMode.count,
+            pattern=pattern,
+            search_root=search_root,
+            count_content="\n".join(final_lines),
+            num_files=file_count,
+            num_matches=total_matches,
+            truncated=truncated,
+            applied_limit=applied_limit,
+            applied_offset=applied_offset,
+            duration_ms=duration_ms,
+        )
+
+    def _to_relative(self, abs_path: str) -> str:
+        try:
+            return os.path.relpath(abs_path, self._workspace_root)
+        except ValueError:
+            return abs_path
+
+    def _relativize_content_line(self, line: str, search_root: str) -> str:
+        idx = line.find(":")
+        if idx <= 0:
+            return line
+        file_path = line[:idx]
+        rest = line[idx:]
+        resolved = _resolve_hit_path(file_path, search_root)
+        return self._to_relative(resolved) + rest
+
+    def _format_pagination(self, applied_limit: int | None, applied_offset: int | None) -> str:
+        parts: list[str] = []
+        if applied_limit is not None:
+            parts.append(f"limit: {applied_limit}")
+        if applied_offset:
+            parts.append(f"offset: {applied_offset}")
+        return ", ".join(parts)
+
+    def present(
+        self, data: dict[str, Any], result: Any, ctx: ToolExecutionContext
+    ) -> ToolResultEnvelope:
+        if not isinstance(result, GrepToolOutput):
+            return ToolResultEnvelope(
+                status="ok",
+                tool_name=self.name,
+                summary=str(result),
+                payload=str(result),
+            )
+
+        r = result
+        meta = {
+            "mode": r.mode.value,
+            "duration_ms": round(r.duration_ms, 2),
+            "pattern": r.pattern,
+        }
+
+        if r.mode == GrepOutputMode.files_with_matches:
+            if r.num_files == 0:
+                return ToolResultEnvelope(
+                    status="ok",
+                    tool_name=self.name,
+                    summary="No files found",
+                    payload="No files found",
+                    meta=meta,
+                )
+            lim = self._format_pagination(r.applied_limit, r.applied_offset)
+            summary = (
+                f"Found {r.num_files} {_plural(r.num_files, 'file', 'files')}"
+                + (f" {lim}" if lim else "")
+            )
+            body = "\n".join(r.filenames)
+            hints: list[ToolHint] | None = None
+            if r.truncated and r.applied_limit is not None:
+                off = r.applied_offset or 0
+                hints = [
+                    ToolHint(
+                        message=(
+                            f"Results truncated at {r.applied_limit}. "
+                            f"Use offset={off + r.applied_limit} to fetch more, "
+                            "or narrow pattern/path/glob."
+                        )
+                    )
+                ]
+            return ToolResultEnvelope(
+                status="ok",
+                tool_name=self.name,
+                summary=summary,
+                payload=body,
+                hints=hints,
+                meta=meta,
+            )
+
+        if r.mode == GrepOutputMode.content:
+            content = r.content if r.content else "No matches found"
+            lim = self._format_pagination(r.applied_limit, r.applied_offset)
+            if lim:
+                content = f"{content}\n\n[Showing results with pagination = {lim}]"
+            summary = f"Found {r.num_lines} matching {_plural(r.num_lines, 'line', 'lines')}"
+            if r.truncated and r.applied_limit is not None:
+                summary += f" (truncated at {r.applied_limit})"
+            hints = None
+            if r.truncated and r.applied_limit is not None:
+                off = r.applied_offset or 0
+                hints = [
+                    ToolHint(
+                        message=(
+                            f"Use offset={off + r.applied_limit} for more lines, "
+                            "or narrow the search."
+                        )
+                    )
+                ]
+            return ToolResultEnvelope(
+                status="ok",
+                tool_name=self.name,
+                summary=summary,
+                payload=content,
+                hints=hints,
+                meta=meta,
+            )
+
+        # count
+        raw_lines = r.count_content or "No matches found"
+        lim = self._format_pagination(r.applied_limit, r.applied_offset)
+        occ = _plural(r.num_matches, "occurrence", "occurrences")
+        fword = _plural(r.num_files, "file", "files")
+        summary = f"Found {r.num_matches} total {occ} across {r.num_files} {fword}."
+        if lim:
+            summary += f" (pagination: {lim})"
+        tail = f"Found {r.num_matches} total {occ} across {r.num_files} {fword}."
+        if lim:
+            tail += f" with pagination = {lim}"
+        body = raw_lines + "\n\n" + tail
+        hints = None
+        if r.truncated and r.applied_limit is not None:
+            off = r.applied_offset or 0
+            hints = [
+                ToolHint(
+                    message=(
+                        f"Use offset={off + r.applied_limit} for more entries, "
+                        "or narrow the search."
+                    )
+                )
+            ]
+        return ToolResultEnvelope(
+            status="ok",
+            tool_name=self.name,
+            summary=summary,
+            payload=body,
+            hints=hints,
+            meta=meta,
+        )

langchain_agentx/tools/read/__init__.py

@@ -0,0 +1,9 @@
+"""
+tools/read — ReadRuntimeTool 包
+
+ReadRuntimeTool 是工具体系 P1 首个工具，支持文本、图片、PDF、Jupyter Notebook 读取。
+"""
+
+from .tool import ReadRuntimeTool
+
+__all__ = ["ReadRuntimeTool"]