langchain-agentx-python 0.1.3__tar.gz → 0.1.4__tar.gz

{langchain-agentx-python-0.1.3 → langchain-agentx-python-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: langchain-agentx-python
-Version: 0.1.3
+Version: 0.1.4
 Summary: LangChain/LangGraph-based agent utilities for CodeBaseX.
 Author-email: GoodMood2008 <GoodMood2008@users.noreply.github.com>
 License:                                  Apache License

{langchain-agentx-python-0.1.3 → langchain-agentx-python-0.1.4}/langchain_agentx/tool_runtime/loader.py

@@ -109,12 +109,17 @@ class ToolRuntimeLoader:
         from langchain_agentx.tools.bash import BashRuntimeTool
         from langchain_agentx.tools.glob import GlobRuntimeTool
         from langchain_agentx.tools.grep import GrepRuntimeTool
+        from langchain_agentx.tools.edit import BatchEditRuntimeTool, EditRuntimeTool
         from langchain_agentx.tools.read import ReadRuntimeTool
         from langchain_agentx.tools.ripgrep_plugin_exclusions import PluginCacheGlobExclusions
+        from langchain_agentx.tools.write import WriteRuntimeTool
         from langchain_agentx.tool_runtime.state_bridge import ToolStateBridge
         from langchain_agentx.workspace.config import AgentWorkspaceConfig
 
         self.register(ReadRuntimeTool())
+        self.register(WriteRuntimeTool())
+        self.register(EditRuntimeTool())
+        self.register(BatchEditRuntimeTool())
         default_tool_state_bridge = ToolStateBridge()
         wr = Path(workspace_root).resolve()
         cfg = AgentWorkspaceConfig(workspace_root=wr, agent_home=agent_home)

{langchain-agentx-python-0.1.3 → langchain-agentx-python-0.1.4}/langchain_agentx/tool_runtime/state_bridge.py

@@ -16,7 +16,8 @@ runtime/state_bridge.py — 工具级最小共享状态管理
     通过 getAppState / setAppState 读写应用级状态。
     本框架将这些能力收敛到 ToolStateBridge，通过 LangGraph state
     作为底层存储，保持与 agent loop 的状态一致性。
-    v1：last_read_map、tool_audit；v2-D：last_glob_summary（可选写入，见 GlobRuntimeTool.after_invoke）。
+    v1：last_read_map（含 mtime_ms、可选 content，供 Edit staleness 方案 B）、tool_audit；
+    v2-D：last_glob_summary（可选写入，见 GlobRuntimeTool.after_invoke）。
     不承担业务 workflow state。
 """
 
@@ -56,7 +57,10 @@ class ToolStateBridge:
         """
         获取 last_read_map。
 
-        结构：{ file_path: { tool_call_id, ts, line_start, line_end } }
+        结构（每条 file_path）：至少含 ``tool_call_id``、``ts``；Read 写入时还含
+        ``offset``、``limit``、``mtime_ms``；可选 ``content``（文本快照或占位符，
+        供 Edit staleness）、``line_start`` / ``line_end``（Read 元数据）。
+
         不存在时返回空 dict（不修改 state）。
         """
         return ctx.state.get(self.LAST_READ_MAP_KEY) or {}
@@ -69,29 +73,68 @@ class ToolStateBridge:
         """更新 last_read_map，整体替换。"""
         ctx.state[self.LAST_READ_MAP_KEY] = value
 
-    def record_read(
+    def get_last_read(
+        self, ctx: ToolExecutionContext, file_path: str
+    ) -> dict[str, Any] | None:
+        """返回 ``file_path`` 对应的最近一次读取记录；无则 ``None``。"""
+        raw = self.get_last_read_map(ctx).get(file_path)
+        return raw if isinstance(raw, dict) else None
+
+    def set_last_read(
         self,
         ctx: ToolExecutionContext,
         file_path: str,
         *,
+        offset: int | None = None,
+        limit: int | None = None,
+        mtime_ms: int = 0,
+        content: str | None = None,
         line_start: int | None = None,
         line_end: int | None = None,
     ) -> None:
         """
-        记录一次文件读取，更新 last_read_map 中对应条目。
+        写入/覆盖某路径的最近一次读取记录（Read ``after_invoke`` 主入口）。
 
-        ReadRuntimeTool.after_invoke() 调用此方法，
-        WriteRuntimeTool / EditRuntimeTool 的 check_permissions() 检查此记录。
+        ``content``：可选；UTF-8 文本快照或 ``<image:...>`` 等占位符，供 Edit
+        staleness 内容对比；过大文本由调用方截断为占位符。
         """
         last_read_map = self.get_last_read_map(ctx)
-        last_read_map[file_path] = {
+        entry: dict[str, Any] = {
             "tool_call_id": ctx.tool_call_id,
             "ts": ctx.now_ts,
+            "offset": offset,
+            "limit": limit,
+            "mtime_ms": mtime_ms,
             "line_start": line_start,
             "line_end": line_end,
         }
+        if content is not None:
+            entry["content"] = content
+        last_read_map[file_path] = entry
         self.set_last_read_map(ctx, last_read_map)
 
+    def record_read(
+        self,
+        ctx: ToolExecutionContext,
+        file_path: str,
+        *,
+        line_start: int | None = None,
+        line_end: int | None = None,
+    ) -> None:
+        """
+        记录一次文件读取（兼容旧 API / 单测），等价于 ``offset=0``、``mtime_ms=0``
+        的 ``set_last_read``。
+        """
+        self.set_last_read(
+            ctx,
+            file_path,
+            offset=0,
+            limit=None,
+            mtime_ms=0,
+            line_start=line_start,
+            line_end=line_end,
+        )
+
     def has_been_read(self, ctx: ToolExecutionContext, file_path: str) -> bool:
         """
         检查文件是否已被读取过（用于 read-before-write 约束）。

{langchain-agentx-python-0.1.3 → langchain-agentx-python-0.1.4}/langchain_agentx/tools/__init__.py

@@ -4,7 +4,7 @@
 工具体系实现状态：
     P1（已完成）：ReadRuntimeTool — 文本/图片/PDF/Notebook 读取
     P2（已完成）：GrepRuntimeTool / GlobRuntimeTool — 只读搜索工具
-    P3（待实现）：WriteRuntimeTool / EditRuntimeTool
+    P3（进行中）：WriteRuntimeTool；EditRuntimeTool — Phase 6 单测 + ``tools/`` 回归已跑通（需 ToolStateBridge + 先 Read）
     P4（已完成）：BashRuntimeTool
 """
 
@@ -14,6 +14,8 @@ from .glob import GlobRuntimeTool
 from .grep import GrepRuntimeTool
 from .read import ReadRuntimeTool
 from .skill import SkillRuntimeTool
+from .edit import BatchEditRuntimeTool, EditRuntimeTool
+from .write import WriteRuntimeTool
 
 __all__ = [
     "ReadRuntimeTool",
@@ -22,5 +24,8 @@ __all__ = [
     "GlobRuntimeTool",
     "GrepRuntimeTool",
     "SkillRuntimeTool",
+    "WriteRuntimeTool",
+    "EditRuntimeTool",
+    "BatchEditRuntimeTool",
 ]
 

langchain-agentx-python-0.1.4/langchain_agentx/tools/edit/__init__.py

@@ -0,0 +1,12 @@
+"""
+tools/edit — EditRuntimeTool / BatchEditRuntimeTool（CC FileEditTool + v2 批量）
+
+v2：Phase 1–2 单次 edit；Phase 3 ``batch_edit``；需 ``ToolStateBridge`` + 先 Read。
+"""
+
+from __future__ import annotations
+
+from .batch_tool import BatchEditRuntimeTool
+from .tool import EditRuntimeTool
+
+__all__ = ["EditRuntimeTool", "BatchEditRuntimeTool"]

langchain-agentx-python-0.1.4/langchain_agentx/tools/edit/backend.py

@@ -0,0 +1,95 @@
+"""
+tools/edit/backend.py — EditFileBackend（文件读 / 替换 / 写）
+
+职责：
+    UTF-8 读入、字符串替换、LF 落盘；与 CC applyEditToFile 语义对齐（edit-tool-migration 附录 §7.4）。
+    v2：``build_unified_diff`` 为 ``DiffGenerator`` 的薄封装（Phase 2 提取）。
+
+链路位置：
+    EditRuntimeTool.invoke() → EditFileBackend.replace_string()；diff 经 ``DiffGenerator``。
+
+当前裁剪范围：
+    ``new_string==""`` 走 CC 末尾换行分支；diff 仅 unified 文本，无 HTML/context。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .diff_generator import DiffGenerator
+
+
+# 兼容单测 / 旧 import：委托 DiffGenerator
+def build_unified_diff(
+    original: str,
+    new_content: str,
+    *,
+    label: str = "file",
+    max_bytes: int | None = None,
+) -> str:
+    """生成 unified diff；语义与 ``DiffGenerator.generate`` 一致。"""
+    gen = DiffGenerator(max_bytes=max_bytes) if max_bytes is not None else DiffGenerator()
+    return gen.generate(original, new_content, label=label)
+
+
+def apply_edit_to_content(
+    original: str,
+    old_string: str,
+    new_string: str,
+    replace_all: bool,
+) -> tuple[str, int]:
+    """
+    纯字符串变换，返回 (new_content, replaced_count)。
+
+    与 CC ``applyEditToFile`` 对齐：``new_string==''`` 时对 ``old_string+'\\n'`` 的分支。
+    """
+    if old_string == "":
+        if original != "":
+            raise ValueError("apply_edit_to_content: empty old_string requires empty original")
+        new_content = new_string
+        return new_content, (1 if new_string else 0)
+
+    if new_string != "":
+        if replace_all:
+            count = original.count(old_string)
+            new_content = original.replace(old_string, new_string)
+        else:
+            count = 1 if (old_string in original) else 0
+            new_content = original.replace(old_string, new_string, 1)
+        return new_content, count
+
+    strip_nl = (not old_string.endswith("\n")) and ((old_string + "\n") in original)
+    needle = old_string + "\n" if strip_nl else old_string
+    if replace_all:
+        count = original.count(needle)
+        new_content = original.replace(needle, "")
+    else:
+        count = 1 if (needle in original) else 0
+        new_content = original.replace(needle, "", 1)
+    return new_content, count
+
+
+class EditFileBackend:
+    """原地编辑文件内容（精确字符串替换）。"""
+
+    def replace_string(
+        self,
+        *,
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool,
+    ) -> tuple[int, str]:
+        """
+        读取文件、应用替换、写回；返回 (replaced_count, original_content)。
+
+        写盘仅在内容变化时发生，避免无谓 mtime 抖动。
+        """
+        path = Path(file_path)
+        original = path.read_text(encoding="utf-8")
+        new_content, count = apply_edit_to_content(
+            original, old_string, new_string, replace_all
+        )
+        if new_content != original:
+            path.write_text(new_content, encoding="utf-8", newline="\n")
+        return count, original

langchain-agentx-python-0.1.4/langchain_agentx/tools/edit/batch_tool.py

@@ -0,0 +1,279 @@
+"""
+tools/edit/batch_tool.py — BatchEditRuntimeTool
+
+职责：
+    单文件多段替换：内存顺序应用、**一次写回**；失败则不落盘（edit-tool-migration-v2 §2.1）。
+    invoke 内对每步 ``current_content`` 做引号解析、存在性、``replace_all=false`` 唯一性。
+
+链路位置：
+    ``ToolRuntimeLoader.register_default_tools``；与 ``EditRuntimeTool`` 共用 staleness / must-read 语义。
+
+当前裁剪范围：
+    无 LSP；``combined_diff`` 为整文件前后 unified diff；逐条 ``EditToolOutput.diff`` 恒为 None。
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from langchain_agentx.tool_runtime.base import RuntimeTool
+from langchain_agentx.tool_runtime.errors import ToolRuntimeError
+from langchain_agentx.tool_runtime.models import (
+    AuthorizationDecision,
+    ToolExecutionContext,
+    ToolResultEnvelope,
+    ValidationResult,
+)
+from langchain_agentx.utils.path_user_input import UserPathInputNormalizer
+
+from .backend import apply_edit_to_content
+from .diff_generator import DiffGenerator
+from .limits import get_edit_limits
+from .models import BatchEditInput, BatchEditOutput, EditToolOutput
+from .prompt import BATCH_DESCRIPTION, BATCH_TOOL_NAME
+from .quote_normalizer import QuoteNormalizer
+from .staleness import StalenessChecker
+from .validator import BatchEditValidator
+
+
+def _snapshot_file_for_last_read(file_path: str) -> str | None:
+    max_b = get_edit_limits()["max_file_size"]
+    try:
+        raw = Path(file_path).read_bytes()
+    except OSError:
+        return None
+    if len(raw) > max_b:
+        return f"<large file: {len(raw) // 1024}KB>"
+    try:
+        return raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return "<non-utf8 binary>"
+
+
+class BatchEditRuntimeTool(RuntimeTool):
+    """同一文件上原子批量字符串替换。"""
+
+    name: str = BATCH_TOOL_NAME
+    description: str = BATCH_DESCRIPTION
+    input_model = BatchEditInput
+    output_model = BatchEditOutput
+
+    is_read_only: bool = False
+    is_destructive: bool = True
+    is_concurrency_safe: bool = False
+    dedupe_identical_calls: bool = False
+
+    def __init__(
+        self,
+        *,
+        policy: Any | None = None,
+        state_bridge: Any | None = None,
+        path_normalizer: UserPathInputNormalizer | None = None,
+        batch_validator: BatchEditValidator | None = None,
+        staleness_checker: StalenessChecker | None = None,
+        quote_normalizer: QuoteNormalizer | None = None,
+        diff_generator: DiffGenerator | None = None,
+    ) -> None:
+        super().__init__(policy=policy, state_bridge=state_bridge)
+        self._path_normalizer = path_normalizer or UserPathInputNormalizer()
+        self._staleness_checker = staleness_checker or (
+            StalenessChecker(state_bridge) if state_bridge is not None else None
+        )
+        self._batch_validator = batch_validator or BatchEditValidator(
+            state_bridge=state_bridge,
+            staleness_checker=self._staleness_checker,
+        )
+        self._quote_normalizer = quote_normalizer or QuoteNormalizer()
+        self._diff_generator = diff_generator or DiffGenerator()
+
+    def normalize_input(
+        self,
+        raw: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> dict[str, Any]:
+        raw = dict(raw)
+        path = raw.get("file_path", "")
+        if isinstance(path, str) and path:
+            raw["file_path"] = self._path_normalizer.normalize_and_expand(
+                path, base_dir=ctx.cwd
+            )
+        return raw
+
+    def validate_input(
+        self,
+        data: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> ValidationResult:
+        return self._batch_validator.validate(data, ctx)
+
+    def check_permissions(
+        self,
+        data: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> AuthorizationDecision:
+        decision = super().check_permissions(data, ctx)
+        if decision.behavior not in ("allow", "deny", "ask"):
+            return AuthorizationDecision(
+                behavior="deny",
+                policy_id="fallback",
+                message=f"Unknown authorization behavior: {decision.behavior}",
+            )
+        return decision
+
+    def invoke(
+        self,
+        data: dict[str, Any],
+        ctx: ToolExecutionContext,
+    ) -> BatchEditOutput:
+        inp = BatchEditInput.model_validate(data)
+        if self._staleness_checker is None:
+            raise ToolRuntimeError(
+                "BatchEditRuntimeTool requires ToolStateBridge for staleness.",
+                code="MISSING_STATE_BRIDGE",
+            )
+        sr = self._staleness_checker.check(inp.file_path, ctx)
+        if not sr.ok:
+            raise ToolRuntimeError(
+                sr.message or "File is stale or modified since read.",
+                code="STALE_FILE",
+            )
+
+        try:
+            original_content = Path(inp.file_path).read_text(encoding="utf-8")
+        except OSError as exc:
+            raise ToolRuntimeError(
+                f"Failed to read file: {exc}",
+                code="FILE_READ_ERROR",
+            ) from exc
+
+        current = original_content
+        results: list[EditToolOutput] = []
+
+        for edit_op in inp.edits:
+            actual_old = self._quote_normalizer.find_actual_old_string_in_text(
+                current, edit_op.old_string
+            )
+            if actual_old is None:
+                raise ToolRuntimeError(
+                    f"old_string not found in file (after quote normalization): "
+                    f"{edit_op.old_string[:50]!r}…",
+                    code="STRING_NOT_FOUND",
+                )
+
+            if not edit_op.replace_all:
+                n_matches = current.count(actual_old)
+                if n_matches > 1:
+                    raise ToolRuntimeError(
+                        f"Found {n_matches} matches for old_string, but replace_all is false. "
+                        "Set replace_all=true or use a longer old_string that matches once.",
+                        code="NOT_UNIQUE",
+                    )
+
+            new_content, count = apply_edit_to_content(
+                current,
+                actual_old,
+                edit_op.new_string,
+                edit_op.replace_all,
+            )
+            if count == 0:
+                raise ToolRuntimeError(
+                    f"Replace produced no matches for: {edit_op.old_string[:50]!r}…",
+                    code="STRING_NOT_FOUND",
+                )
+
+            results.append(
+                EditToolOutput(
+                    file_path=inp.file_path,
+                    old_string=actual_old,
+                    new_string=edit_op.new_string,
+                    replaced_count=count,
+                    original_file=None,
+                    diff=None,
+                )
+            )
+            current = new_content
+
+        if current != original_content:
+            Path(inp.file_path).write_text(current, encoding="utf-8", newline="\n")
+
+        total_replaced = sum(r.replaced_count for r in results)
+        combined_diff: str | None = None
+        if inp.include_diff and total_replaced > 0:
+            combined_diff = self._diff_generator.generate(
+                original_content,
+                current,
+                label=Path(inp.file_path).name,
+            )
+
+        return BatchEditOutput(
+            file_path=inp.file_path,
+            total_replaced=total_replaced,
+            results=results,
+            combined_diff=combined_diff,
+        )
+
+    def after_invoke(
+        self,
+        data: dict[str, Any],
+        result: Any,
+        ctx: ToolExecutionContext,
+    ) -> None:
+        if self._state_bridge is None:
+            return
+        if not isinstance(result, BatchEditOutput):
+            return
+        inp = BatchEditInput.model_validate(data)
+        try:
+            mtime_ms = int(os.path.getmtime(inp.file_path) * 1000)
+        except OSError:
+            mtime_ms = 0
+        snap = _snapshot_file_for_last_read(inp.file_path)
+        self._state_bridge.set_last_read(
+            ctx,
+            inp.file_path,
+            offset=0,
+            limit=None,
+            mtime_ms=mtime_ms,
+            content=snap,
+            line_start=None,
+            line_end=None,
+        )
+
+    def present(
+        self,
+        data: dict[str, Any],
+        result: Any,
+        ctx: ToolExecutionContext,
+    ) -> ToolResultEnvelope:
+        _ = data, ctx
+        if not isinstance(result, BatchEditOutput):
+            return super().present(data, result, ctx)
+        n = result.total_replaced
+        summary = (
+            f"Applied {len(result.results)} edit(s), {n} replacement(s) in {result.file_path}"
+        )
+        meta: dict[str, Any] = {
+            "file_path": result.file_path,
+            "total_replaced": n,
+            "edit_count": len(result.results),
+            "edits": [
+                {
+                    "index": i,
+                    "old_string_preview": r.old_string[:50],
+                    "new_string_preview": r.new_string[:50],
+                    "replaced_count": r.replaced_count,
+                }
+                for i, r in enumerate(result.results)
+            ],
+        }
+        if result.combined_diff is not None:
+            meta["combined_diff"] = result.combined_diff
+        return ToolResultEnvelope(
+            status="ok",
+            tool_name=self.name,
+            summary=summary,
+            payload=str(n),
+            meta=meta,
+        )

langchain-agentx-python-0.1.4/langchain_agentx/tools/edit/diff_generator.py

@@ -0,0 +1,53 @@
+"""
+tools/edit/diff_generator.py — DiffGenerator
+
+职责：
+    使用 ``difflib.unified_diff`` 生成行级 unified diff；超限时 UTF-8 截断并追加说明
+    （edit-runtime-tool-v2 §0；与 Phase 1 ``build_unified_diff`` 语义一致）。
+
+链路位置：
+    ``EditRuntimeTool.invoke``（经 ``DiffGenerator.generate`` 或 ``backend.build_unified_diff`` 薄封装）。
+
+当前裁剪范围：
+    仅 unified 文本；无 HTML/context；默认上限 1024 字节（UTF-8）。
+"""
+
+from __future__ import annotations
+
+import difflib
+
+
+class DiffGenerator:
+    """行级 unified diff 生成；超大时截断，避免与「无 diff」混淆。"""
+
+    DEFAULT_MAX_BYTES: int = 1024
+
+    def __init__(self, *, max_bytes: int | None = None) -> None:
+        self._max_bytes = int(max_bytes if max_bytes is not None else self.DEFAULT_MAX_BYTES)
+
+    def generate(
+        self,
+        original: str,
+        new_content: str,
+        *,
+        label: str = "file",
+    ) -> str:
+        """返回 diff 文本；超过 ``max_bytes``（UTF-8）时截断并追加 ``[diff truncated, …]``。"""
+        a = original.splitlines(keepends=True)
+        b = new_content.splitlines(keepends=True)
+        lines = list(
+            difflib.unified_diff(
+                a,
+                b,
+                fromfile=f"a/{label}",
+                tofile=f"b/{label}",
+            )
+        )
+        diff_text = "".join(lines)
+        raw = diff_text.encode("utf-8")
+        if len(raw) <= self._max_bytes:
+            return diff_text
+        trunc = int(self._max_bytes * 0.9)
+        prefix = raw[:trunc].decode("utf-8", errors="replace")
+        total_kb = len(raw) / 1024.0
+        return prefix + f"\n... [diff truncated, {total_kb:.1f}KB total]\n"

langchain-agentx-python-0.1.4/langchain_agentx/tools/edit/git_diff_generator.py

@@ -0,0 +1,103 @@
+"""
+tools/edit/git_diff_generator.py — GitDiffGenerator
+
+职责：
+    在 Git 工作树中对给定文件运行 ``git diff``（相对 HEAD），供 Edit v3 可选展示；
+    失败或非仓库时返回 ``None``，由上层回退 unified diff（edit-tool-migration-v3 §2.1）。
+
+链路位置：
+    Phase 2 起由 ``EditRuntimeTool.invoke`` 在 ``include_diff`` 时调用；Phase 1 仅类 + 单测。
+
+当前裁剪范围：
+    仅 ``git diff --no-color <path>``；无 ``git apply``；失败不抛异常（返回 ``None``）。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from langchain_agentx.utils.subprocess_text import TextSubprocessRunner, default_text_subprocess_runner
+
+
+class GitDiffGenerator:
+    """检测 Git 仓库并生成 ``git diff`` 文本（工作区 vs HEAD）。"""
+
+    def __init__(
+        self,
+        *,
+        git_path: str = "git",
+        subprocess_runner: TextSubprocessRunner | None = None,
+    ) -> None:
+        self._git_path = git_path
+        self._run = (subprocess_runner or default_text_subprocess_runner()).run
+
+    def is_in_git_repo(self, file_path: str) -> bool:
+        """若路径所在目录链上存在 ``.git``（目录或 worktree 的 ``gitdir`` 文件）则视为在仓库内。"""
+        try:
+            path = Path(file_path).resolve()
+        except OSError:
+            return False
+
+        if not path.exists():
+            return False
+
+        for parent in [path, *path.parents]:
+            if (parent / ".git").exists():
+                return True
+        return False
+
+    def generate_git_diff(self, file_path: str) -> str | None:
+        """
+        生成 ``git diff --no-color`` 输出（工作区相对 HEAD）。
+
+        语义注意：输出可能包含该文件在编辑前已有的未提交改动，不仅限于单次 Edit（设计 §0）。
+
+        Returns:
+            非空 diff 文本，或 ``None``（非仓库、git 失败、无输出）。
+        """
+        if not self.is_in_git_repo(file_path):
+            return None
+
+        try:
+            path = Path(file_path).resolve()
+        except OSError:
+            return None
+
+        cwd = str(path.parent)
+        try:
+            top = self._run(
+                [self._git_path, "rev-parse", "--show-toplevel"],
+                cwd=cwd,
+                capture_output=True,
+                timeout=30,
+            )
+        except Exception:
+            return None
+
+        if top.returncode != 0 or not (top.stdout or "").strip():
+            return None
+
+        git_root = top.stdout.strip()
+
+        try:
+            diff = self._run(
+                [
+                    self._git_path,
+                    "diff",
+                    "--no-color",
+                    str(path),
+                ],
+                cwd=git_root,
+                capture_output=True,
+                timeout=60,
+            )
+        except Exception:
+            return None
+
+        if diff.returncode != 0:
+            return None
+
+        out = diff.stdout or ""
+        if not out.strip():
+            return None
+        return out