langchain-agentx-python 1.3.1__tar.gz → 1.3.2__tar.gz

{langchain-agentx-python-1.3.1 → langchain-agentx-python-1.3.2}/PKG-INFO

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

{langchain-agentx-python-1.3.1 → langchain-agentx-python-1.3.2}/langchain_agentx/__init__.py

@@ -11,7 +11,7 @@ from langchain_agentx import create_loop_agent
 ```
 """
 
-__version__ = "1.3.1"
+__version__ = "1.3.2"
 
 from .loop import (  # noqa: F401
     create_loop_agent,

{langchain-agentx-python-1.3.1 → langchain-agentx-python-1.3.2}/langchain_agentx/loop/graph/factory.py

@@ -502,19 +502,26 @@ class LoopGraphBuilder:
             from ...memory.session import make_session_memory_section
 
             self._dynamic_sections.append(make_session_memory_section(session_summary_path))
+        instruction_bootstrap = InstructionMemoryBootstrap(
+            workspace_root=Path(self._workspace_root),
+            agent_home_segment=self._agent_home_segment,
+            managed_rules=self._config.managed_rules,
+            claude_md_excludes=self._config.claude_md_excludes,
+            active_files_provider=(
+                CallbackActiveFilesProvider(self._services.active_files_getter)
+                if self._services.active_files_getter is not None
+                else None
+            ),
+        )
+        loaded_instruction_rules = instruction_bootstrap.load_rule_set()
         self._dynamic_sections.extend(
-            InstructionMemoryBootstrap(
-                workspace_root=Path(self._workspace_root),
-                agent_home_segment=self._agent_home_segment,
-                managed_rules=self._config.managed_rules,
-                claude_md_excludes=self._config.claude_md_excludes,
-                active_files_provider=(
-                    CallbackActiveFilesProvider(self._services.active_files_getter)
-                    if self._services.active_files_getter is not None
-                    else None
-                ),
-            ).build_sections()
+            instruction_bootstrap.build_sections(loaded_instruction_rules)
         )
+        if session_store is not None:
+            instruction_bootstrap.seed_injected_read_state(
+                session_store,
+                loaded_instruction_rules,
+            )
         self._dynamic_sections.extend(
             MemoryPromptBootstrap(
                 workspace_root=Path(self._workspace_root),

langchain-agentx-python-1.3.2/langchain_agentx/memory/instruction/read_state_seeder.py

@@ -0,0 +1,78 @@
+"""
+memory/instruction/read_state_seeder.py — 指令注入 read-state 播种
+
+职责：
+    将 Layer 1 规则文件注入 prompt 时同步写入 ``AgentSessionStore.file_read_state``；
+    注入内容与磁盘不一致时标记 ``is_partial_view``（对齐 CC attachments memoryFilesToAttachments）。
+
+链路位置：
+    LoopGraphBuilder 初始化 → InstructionMemoryBootstrap.seed_injected_read_state()。
+
+当前裁剪范围：
+    仅 Layer 1 ``LoadedRuleSet`` 文件路径；不含 memdir prefetch / session memory。
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Iterable
+
+from langchain_agentx.tool_runtime.session_store import AgentSessionStore
+from langchain_agentx.utils.file_mtime import FileModificationTimeReader
+
+from .loader import strip_html_comments
+from .types import LoadedRuleSet, RuleFile
+
+
+class InstructionReadStateSeeder:
+    """指令规则注入时播种 last_read（partial view 语义）。"""
+
+    def __init__(self, *, mtime_reader: FileModificationTimeReader | None = None) -> None:
+        self._mtime_reader = mtime_reader or FileModificationTimeReader()
+
+    def seed(self, session_store: AgentSessionStore, loaded: LoadedRuleSet) -> None:
+        for path, injected_content in self._iter_path_content_pairs(loaded):
+            self._seed_path(session_store, path, injected_content)
+
+    def _iter_path_content_pairs(self, loaded: LoadedRuleSet) -> Iterable[tuple[Path, str]]:
+        if loaded.user is not None and loaded.user.path is not None:
+            yield loaded.user.path, loaded.user.content
+        for rule_file in loaded.project_files:
+            if rule_file.path is not None:
+                yield rule_file.path, rule_file.content
+        if loaded.local is not None and loaded.local.path is not None:
+            yield loaded.local.path, loaded.local.content
+        for rule in loaded.conditional_rules:
+            yield rule.path, rule.content
+
+    def _seed_path(
+        self,
+        session_store: AgentSessionStore,
+        file_path: Path,
+        injected_content: str,
+    ) -> None:
+        path = str(file_path.resolve())
+        if session_store.has_been_read(path):
+            return
+        try:
+            raw_disk = file_path.read_text(encoding="utf-8")
+        except OSError:
+            return
+
+        injected_view = strip_html_comments(injected_content)
+        content_differs = injected_view != raw_disk
+        mtime_ms = self._mtime_reader.read_ms(path)
+        entry: dict[str, object] = {
+            "tool_call_id": None,
+            "ts": time.time(),
+            "offset": None,
+            "limit": None,
+            "mtime_ms": mtime_ms,
+            "line_start": None,
+            "line_end": None,
+            "content": raw_disk if content_differs else injected_view,
+        }
+        if content_differs:
+            entry["is_partial_view"] = True
+        session_store.upsert_last_read_from_bridge_entry(path, entry)

{langchain-agentx-python-1.3.1 → langchain-agentx-python-1.3.2}/langchain_agentx/memory/instruction/runtime.py

@@ -15,13 +15,15 @@ from __future__ import annotations
 import logging
 from collections.abc import Callable, Sequence
 from pathlib import Path
+from typing import Any
 
 from langchain_agentx.loop.prompt import SystemPromptSection
 from langchain_agentx.workspace import resolve_agent_state_config
 
 from .loader import load_rule_set
+from .read_state_seeder import InstructionReadStateSeeder
 from .sections import make_instruction_sections
-from .types import InstructionMemoryConfig
+from .types import InstructionMemoryConfig, LoadedRuleSet
 
 logger = logging.getLogger(__name__)
 
@@ -43,31 +45,53 @@ class InstructionMemoryBootstrap:
         self._include_depth_limit = include_depth_limit
         self._claude_md_excludes = tuple(claude_md_excludes)
         self._active_files_provider = active_files_provider or NullActiveFilesProvider()
+        self._read_state_seeder = InstructionReadStateSeeder()
 
-    def build_sections(self) -> list[SystemPromptSection]:
+    def _build_config(self) -> InstructionMemoryConfig:
         workspace_cfg = resolve_agent_state_config(
             workspace_root=self._workspace_root,
             agent_home_segment=self._agent_home_segment,
         )
-        loaded_rules = load_rule_set(
-            InstructionMemoryConfig(
-                workspace_cfg=workspace_cfg,
-                managed_rules=self._managed_rules,
-                load_user_layer=True,
-                include_depth_limit=self._include_depth_limit,
-                claude_md_excludes=self._claude_md_excludes,
-            )
+        return InstructionMemoryConfig(
+            workspace_cfg=workspace_cfg,
+            managed_rules=self._managed_rules,
+            load_user_layer=True,
+            include_depth_limit=self._include_depth_limit,
+            claude_md_excludes=self._claude_md_excludes,
         )
+
+    def load_rule_set(self) -> LoadedRuleSet:
+        loaded_rules = load_rule_set(self._build_config())
         if loaded_rules.external_include_warnings:
             logger.warning(
                 "instruction_memory: external @path includes detected outside workspace: %s",
                 ", ".join(loaded_rules.external_include_warnings),
             )
+        return loaded_rules
+
+    def build_sections(
+        self,
+        loaded_rules: LoadedRuleSet | None = None,
+    ) -> list[SystemPromptSection]:
+        rules = loaded_rules if loaded_rules is not None else self.load_rule_set()
         return make_instruction_sections(
-            loaded_rules,
+            rules,
             active_files_getter=self._active_files_provider.get_active_files,
         )
 
+    def seed_injected_read_state(
+        self,
+        session_store: Any,
+        loaded_rules: LoadedRuleSet | None = None,
+    ) -> None:
+        """注入 Layer 1 规则后播种 file_read_state（CC readFileState 对齐）。"""
+        from langchain_agentx.tool_runtime.session_store import AgentSessionStore
+
+        if not isinstance(session_store, AgentSessionStore):
+            return
+        rules = loaded_rules if loaded_rules is not None else self.load_rule_set()
+        self._read_state_seeder.seed(session_store, rules)
+
 
 class ActiveFilesProvider:
     """active_files 提供器接口。"""

{langchain-agentx-python-1.3.1 → langchain-agentx-python-1.3.2}/langchain_agentx/tool_runtime/loop_loader.py

@@ -76,7 +76,7 @@ class LoopLoader:
         from langchain_agentx.tools.bash import BashRuntimeTool
         from langchain_agentx.tools.edit import EditRuntimeTool
         from langchain_agentx.tools.edit.settings_validator import SettingsValidator
-        from langchain_agentx.tools.edit.staleness import StalenessChecker
+        from langchain_agentx.tools.shared.staleness import StalenessChecker
         from langchain_agentx.tools.edit.validator import EditStringValidator
         from langchain_agentx.tools.glob import GlobRuntimeTool
         from langchain_agentx.tools.grep import GrepRuntimeTool
@@ -124,7 +124,12 @@ class LoopLoader:
         )
 
         self.register(ReadRuntimeTool(state_bridge=shared_bridge))
-        self.register(WriteRuntimeTool(state_bridge=shared_bridge))
+        self.register(
+            WriteRuntimeTool(
+                state_bridge=shared_bridge,
+                staleness_checker=edit_staleness,
+            )
+        )
         self.register(
             EditRuntimeTool(
                 state_bridge=shared_bridge,

{langchain-agentx-python-1.3.1 → langchain-agentx-python-1.3.2}/langchain_agentx/tool_runtime/session_store.py

@@ -50,6 +50,7 @@ class FileReadRecord:
     limit: int | None = None
     mtime_ms: int = 0
     content: str | None = None
+    is_partial_view: bool = False
 
     def to_bridge_dict(self) -> dict[str, Any]:
         """转为 ToolStateBridge / StalenessChecker 消费的 dict 形态。"""
@@ -64,6 +65,8 @@ class FileReadRecord:
         }
         if self.content is not None:
             out["content"] = self.content
+        if self.is_partial_view:
+            out["is_partial_view"] = True
         return out
 
     @classmethod
@@ -79,6 +82,7 @@ class FileReadRecord:
         tool_call_id = raw_tid if isinstance(raw_tid, str) or raw_tid is None else None
         raw_content = d.get("content")
         content = raw_content if isinstance(raw_content, str) or raw_content is None else None
+        is_partial = bool(d.get("is_partial_view"))
         return cls(
             path=path,
             tool_call_id=tool_call_id,
@@ -89,6 +93,7 @@ class FileReadRecord:
             limit=d.get("limit"),
             mtime_ms=mtime_ms,
             content=content,
+            is_partial_view=is_partial,
         )
 
 

langchain-agentx-python-1.3.2/langchain_agentx/tools/edit/staleness.py

@@ -0,0 +1,16 @@
+"""
+tools/edit/staleness.py — StalenessChecker 兼容 re-export
+
+职责：
+    保留 Edit 包内 import 路径；canonical 实现见 ``tools/shared/staleness.py``。
+
+链路位置：
+    EditRuntimeTool 及既有单测 ``from .staleness import StalenessChecker``。
+
+当前裁剪范围：
+    仅 re-export；新代码优先 ``from langchain_agentx.tools.shared.staleness import StalenessChecker``。
+"""
+
+from langchain_agentx.tools.shared.staleness import StalenessChecker
+
+__all__ = ["StalenessChecker"]

{langchain-agentx-python-1.3.1 → langchain-agentx-python-1.3.2}/langchain_agentx/tools/edit/validator.py

@@ -9,7 +9,7 @@ tools/edit/validator.py — EditStringValidator
 
 当前裁剪范围：
     Phase 2：引号由 ``QuoteNormalizer``；非空文件禁止 ``old_string==''`` 的 edit 条。
-    v3 Phase 4：``SettingsValidator`` 在 quote / 唯一性之后、staleness 之前；仅单次 ``edit``。
+    v3 Phase 4：``SettingsValidator`` 在 quote / 唯一性之后、staleness 之前；L1 由 ``MustReadGuard`` 保证。
 """
 
 from __future__ import annotations
@@ -19,6 +19,8 @@ from pathlib import Path
 from typing import Any
 
 from langchain_agentx.tool_runtime.models import ToolExecutionContext, ValidationResult
+from langchain_agentx.tools.shared.read_state_guard import MustReadGuard
+from langchain_agentx.utils.unc_path import is_unc_path_skip_local_stat
 
 from .backend import apply_edit_to_content
 from .limits import get_edit_limits
@@ -35,11 +37,16 @@ class EditStringValidator:
         *,
         state_bridge: Any | None = None,
         staleness_checker: Any | None = None,
+        must_read_guard: MustReadGuard | None = None,
         quote_normalizer: QuoteNormalizer | None = None,
         settings_validator: SettingsValidator | None = None,
     ) -> None:
         self._state_bridge = state_bridge
         self._staleness_checker = staleness_checker
+        self._must_read_guard = must_read_guard or MustReadGuard(
+            state_bridge,
+            tool_label="EditRuntimeTool",
+        )
         self._quote_normalizer = quote_normalizer or QuoteNormalizer()
         self._settings_validator = settings_validator or SettingsValidator()
 
@@ -63,6 +70,10 @@ class EditStringValidator:
         if not fp or not str(fp).strip():
             return ValidationResult(ok=False, message="file_path cannot be empty")
 
+        # CC FileEditTool.validateInput L176–180：UNC 跳过本地 stat / must-read / staleness
+        if is_unc_path_skip_local_stat(fp):
+            return ValidationResult(ok=True)
+
         if not os.path.isabs(fp):
             return ValidationResult(ok=False, message="file_path must be an absolute path")
 
@@ -78,11 +89,9 @@ class EditStringValidator:
                 message="EditRuntimeTool requires ToolStateBridge (session state).",
             )
 
-        if not self._state_bridge.has_been_read(ctx, fp):
-            return ValidationResult(
-                ok=False,
-                message="File has not been read yet. Read it first before writing to it.",
-            )
+        mr = self._must_read_guard.require_read_for_mutation(ctx, fp)
+        if not mr.ok:
+            return mr
 
         limits = get_edit_limits()
         try:

langchain-agentx-python-1.3.2/langchain_agentx/tools/shared/__init__.py

@@ -0,0 +1,6 @@
+"""tools/shared — Read/Write/Edit 共用的 read-state 协作者。"""
+
+from .read_state_guard import MustReadGuard
+from .staleness import StalenessChecker
+
+__all__ = ["MustReadGuard", "StalenessChecker"]

langchain-agentx-python-1.3.2/langchain_agentx/tools/shared/read_state_guard.py

@@ -0,0 +1,55 @@
+"""
+tools/shared/read_state_guard.py — MustReadGuard
+
+职责：
+    Write/Edit 共用的 L1 must-read 校验（对齐 CC readFileState.get + isPartialView 拒绝）。
+
+链路位置：
+    WriteReadStateValidator、EditStringValidator（可选迁移）。
+
+当前裁剪范围：
+    P1：``is_partial_view`` 注入拒绝；Edit/Write 共用本 guard。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_agentx.tool_runtime.models import ToolExecutionContext, ValidationResult
+
+_MUST_READ_MESSAGE = (
+    "File has not been read yet. Read it first before writing to it."
+)
+
+
+class MustReadGuard:
+    """变更文件前要求 last_read_map 存在且非 partial view。"""
+
+    def __init__(
+        self,
+        state_bridge: Any | None,
+        *,
+        tool_label: str = "Tool",
+    ) -> None:
+        self._state_bridge = state_bridge
+        self._tool_label = tool_label
+
+    def require_read_for_mutation(
+        self,
+        ctx: ToolExecutionContext,
+        file_path: str,
+    ) -> ValidationResult:
+        if self._state_bridge is None:
+            return ValidationResult(
+                ok=False,
+                message=f"{self._tool_label} requires ToolStateBridge (session state).",
+            )
+
+        if not self._state_bridge.has_been_read(ctx, file_path):
+            return ValidationResult(ok=False, message=_MUST_READ_MESSAGE)
+
+        entry = self._state_bridge.get_last_read(ctx, file_path)
+        if entry is not None and entry.get("is_partial_view"):
+            return ValidationResult(ok=False, message=_MUST_READ_MESSAGE)
+
+        return ValidationResult(ok=True)

{langchain-agentx-python-1.3.1/langchain_agentx/tools/edit → langchain-agentx-python-1.3.2/langchain_agentx/tools/shared}/staleness.py

@@ -1,23 +1,24 @@
 """
-tools/edit/staleness.py — StalenessChecker
+tools/shared/staleness.py — StalenessChecker
 
 职责：
-    mtime + 内容对比、Windows 误报分支（edit-tool-migration §3.5.3）。
+    mtime + 内容对比、Windows 误报分支（edit-tool-migration §3.5.3）；
+    Write/Edit 共用 read-before-write L2/L3 校验。
 
 链路位置：
-    EditRuntimeTool.validate_input / invoke → StalenessChecker.check()。
+    WriteRuntimeTool / EditRuntimeTool validate_input 与 invoke → check()。
 
 当前裁剪范围：
-    仅基于 ``ToolStateBridge`` last_read；must-read 由 validator 步骤 5 保证。
+    仅基于 ToolStateBridge last_read；must-read 由 MustReadGuard / validator 保证。
 """
 
 from __future__ import annotations
 
-import os
 from pathlib import Path
 from typing import Any
 
 from langchain_agentx.tool_runtime.models import ToolExecutionContext, ValidationResult
+from langchain_agentx.utils.file_mtime import FileModificationTimeReader
 
 
 class StalenessChecker:
@@ -25,6 +26,7 @@ class StalenessChecker:
 
     def __init__(self, state_bridge: Any) -> None:
         self._state_bridge = state_bridge
+        self._mtime_reader = FileModificationTimeReader()
 
     def check(self, file_path: str, ctx: ToolExecutionContext) -> ValidationResult:
         last_read_map = self._state_bridge.get_last_read_map(ctx)
@@ -38,10 +40,7 @@ class StalenessChecker:
         read_content = last_read.get("content")
         read_mtime = int(last_read.get("mtime_ms", 0) or 0)
 
-        try:
-            current_mtime = int(os.path.getmtime(file_path) * 1000)
-        except OSError:
-            current_mtime = 0
+        current_mtime = self._mtime_reader.read_ms(file_path)
 
         if current_mtime > read_mtime:
             if read_content is not None:

langchain-agentx-python-1.3.2/langchain_agentx/tools/write/read_state_validator.py

@@ -0,0 +1,69 @@
+"""
+tools/write/read_state_validator.py — WriteReadStateValidator
+
+职责：
+    已有文件的 must-read（L1）与 staleness（L2/L3）；新建（ENOENT）跳过。
+
+链路位置：
+    WriteRuntimeTool.validate_input（在 WritePathValidator 之后）。
+
+当前裁剪范围：
+    UNC validate 跳过本地 stat（P2）；partial view 由 MustReadGuard 处理。
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from langchain_agentx.tool_runtime.models import ToolExecutionContext, ValidationResult
+from langchain_agentx.tools.shared.read_state_guard import MustReadGuard
+from langchain_agentx.utils.unc_path import is_unc_path_skip_local_stat
+
+
+class WriteReadStateValidator:
+    """Write 已有文件 read-before-write 校验。"""
+
+    def __init__(
+        self,
+        *,
+        state_bridge: Any | None = None,
+        staleness_checker: Any | None = None,
+        must_read_guard: MustReadGuard | None = None,
+    ) -> None:
+        self._state_bridge = state_bridge
+        self._staleness_checker = staleness_checker
+        self._must_read_guard = must_read_guard or MustReadGuard(
+            state_bridge,
+            tool_label="WriteRuntimeTool",
+        )
+
+    def validate(
+        self,
+        file_path: str,
+        ctx: ToolExecutionContext,
+    ) -> ValidationResult:
+        # CC FileWriteTool.validateInput L179–184：UNC 跳过 stat / must-read / staleness
+        if is_unc_path_skip_local_stat(file_path):
+            return ValidationResult(ok=True)
+
+        if not os.path.exists(file_path):
+            return ValidationResult(ok=True)
+
+        if self._state_bridge is None:
+            return ValidationResult(
+                ok=False,
+                message="WriteRuntimeTool requires ToolStateBridge (session state).",
+            )
+
+        mr = self._must_read_guard.require_read_for_mutation(ctx, file_path)
+        if not mr.ok:
+            return mr
+
+        if self._staleness_checker is None:
+            return ValidationResult(
+                ok=False,
+                message="WriteRuntimeTool requires StalenessChecker (state_bridge).",
+            )
+
+        return self._staleness_checker.check(file_path, ctx)