langchain-agentx-python 2.2.3__tar.gz → 2.2.5__tar.gz

{langchain-agentx-python-2.2.3/langchain_agentx_python.egg-info → langchain-agentx-python-2.2.5}/PKG-INFO

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

{langchain-agentx-python-2.2.3 → langchain-agentx-python-2.2.5}/langchain_agentx/__init__.py

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

{langchain-agentx-python-2.2.3 → langchain-agentx-python-2.2.5}/langchain_agentx/tools/grep/backend.py

@@ -6,7 +6,7 @@ tools/grep/backend.py — RipgrepBackend（ripgrep 子进程封装）
 
 在整体链路中的位置：
     GrepRuntimeTool.invoke() -> RipgrepBackend.search() -> run_ripgrep_lines（可选 ctx.cancel_event）
-    -> RgSubprocessController 或 TextSubprocessRunner
+    -> RgSubprocessController（有界 stdout）或 TextSubprocessRunner（测试注入）
 
 对应 CC：src/utils/ripgrep.ts + GrepTool.ts call() 中参数拼装。
 """
@@ -16,7 +16,6 @@ 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
@@ -26,6 +25,7 @@ from langchain_agentx.utils.subprocess_text import (
 )
 
 from .models import GrepOutputMode
+from .ripgrep_stdout_cap import RipgrepStdoutCap
 
 
 def resolve_ripgrep_subprocess_cwd(search_path: str) -> str:
@@ -58,6 +58,11 @@ class GrepCancelledError(ToolRuntimeError):
         super().__init__(message, code="GREP_CANCELLED")
 
 
+def _uses_injected_subprocess_run(text_runner: TextSubprocessRunner) -> bool:
+    """测试注入自定义 ``subprocess_run`` 时走 text_runner；生产默认走有界 controller。"""
+    return getattr(text_runner, "_subprocess_run", None) is not subprocess.run
+
+
 def run_ripgrep_lines(
     rg_path: str,
     args: list[str],
@@ -70,21 +75,25 @@ def run_ripgrep_lines(
 ) -> list[str]:
     """
     执行 [rg_path, *args, search_path]，解析 stdout 为行列表。
-    对齐 CC ripgrep.ts：returncode 1 -> []；EAGAIN 时以 -j 1 重试一次。
+    对齐 CC ripgrep.ts：returncode 1 -> []；EAGAIN 时以 -j 1 重试一次；
+    stdout 硬顶 ``MAX_STDOUT_BUFFER_SIZE``（20MB）。
     供 RipgrepBackend 与 Glob 的 rg --files 列文件共用。
 
     SDK 补充：``subprocess cwd`` 对齐搜索根目录（目录本身，或文件的父目录）。
     CC 隐式依赖进程 cwd≈searchDir；编排布局 ``state_root≠repo`` 时须显式设 cwd，
     否则 Windows 上目录前缀 glob（如 ``alpha/*``）误空。
 
-    若 ``cancel_event`` 非空，使用可中断子进程路径（``RgSubprocessController``），
-    不再走 ``text_runner.run``（便于测试 mock 时仅覆盖无取消路径）。
+    生产路径使用 ``RgSubprocessController`` 边收边截；仅当测试注入自定义
+    ``text_runner.subprocess_run`` 时走 ``text_runner.run``（事后硬顶）。
     """
     search_target = os.path.realpath(search_path)
     search_cwd = resolve_ripgrep_subprocess_cwd(search_path)
     cmd = [rg_path, *args, search_target]
-    if cancel_event is not None:
-        if cancel_event.is_set():
+    stdout_truncated = False
+
+    use_text_runner = cancel_event is None and _uses_injected_subprocess_run(text_runner)
+    if not use_text_runner:
+        if cancel_event is not None and cancel_event.is_set():
             raise GrepCancelledError("ripgrep cancelled before start")
         from langchain_agentx.tools.grep.rg_subprocess_controller import RgSubprocessController
 
@@ -100,6 +109,7 @@ def run_ripgrep_lines(
             raise
         except GrepCancelledError:
             raise
+        stdout_truncated = bool(getattr(result, "stdout_truncated", False))
     else:
         try:
             result = text_runner.run(
@@ -134,10 +144,7 @@ def run_ripgrep_lines(
         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]
+    return RipgrepStdoutCap.lines_from_text(out, truncated=stdout_truncated)
 
 
 class RipgrepBackend:

{langchain-agentx-python-2.2.3 → langchain-agentx-python-2.2.5}/langchain_agentx/tools/grep/rg_subprocess_controller.py

@@ -3,10 +3,11 @@ tools/grep/rg_subprocess_controller.py — ripgrep 子进程 timeout + 协作取
 
 职责：
     在无法使用单次 ``subprocess.run(..., timeout=)`` 响应协作取消时，用 Popen + 后台
-    ``communicate`` 与主线程轮询 ``cancel_event``，对齐 CC ``ripGrep(..., abortSignal)``。
+    有界 stdout/stderr 读取与主线程轮询 ``cancel_event``，对齐 CC ``ripGrep(..., abortSignal)``
+    与 ``MAX_BUFFER_SIZE`` 边收边截。
 
 链路位置：
-    ``grep.backend.run_ripgrep_lines`` 在传入非空 ``cancel_event`` 时委托本类；
+    ``grep.backend.run_ripgrep_lines`` 在生产路径（或传入 ``cancel_event``）时委托本类；
     ``RipgrepBackend.search_stream_limited`` 在读取 stdout 时轮询同一事件。
 
 当前裁剪范围：
@@ -24,13 +25,17 @@ from langchain_agentx.tools.grep.backend import (
     GrepExecutionError,
     GrepTimeoutError,
 )
+from langchain_agentx.tools.grep.ripgrep_stdout_cap import RipgrepStdoutCap
 
 
 class RgSubprocessController:
-    """封装可中断的阻塞式子进程等待（timeout + ``threading.Event``）。"""
+    """封装可中断的阻塞式子进程等待（timeout + ``threading.Event`` + stdout 硬顶）。"""
 
     _poll_interval_s = 0.05
 
+    def __init__(self, *, stdout_cap_factory: type[RipgrepStdoutCap] = RipgrepStdoutCap) -> None:
+        self._stdout_cap_factory = stdout_cap_factory
+
     def run_argv_wait_completed(
         self,
         argv: list[str],
@@ -42,8 +47,11 @@ class RgSubprocessController:
         """
         启动 ``argv``，在 ``timeout`` 秒内等待结束；若 ``cancel_event`` 被 set 则 terminate/kill。
 
+        stdout/stderr 边收边截（``RipgrepStdoutCap``），避免无界 ``communicate`` 打爆内存。
+
         Returns:
             ``CompletedProcess``（text stdout/stderr），供上层解析 returncode。
+            额外属性 ``stdout_truncated`` / ``stderr_truncated``（bool）。
         """
         if cancel_event is not None and cancel_event.is_set():
             raise GrepCancelledError("ripgrep cancelled before start")
@@ -64,19 +72,33 @@ class RgSubprocessController:
                 "'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]
+        stdout_cap = self._stdout_cap_factory()
+        stderr_cap = self._stdout_cap_factory()
         thread_exc: list[BaseException | None] = [None]
 
-        def _communicate_worker() -> None:
+        def _readers_worker() -> None:
             try:
-                o, e = proc.communicate()
-                out_box[0] = o
-                err_box[0] = e
+                assert proc.stdout is not None
+                assert proc.stderr is not None
+                out_t = threading.Thread(
+                    target=stdout_cap.drain_text_stream,
+                    args=(proc.stdout,),
+                    daemon=True,
+                )
+                err_t = threading.Thread(
+                    target=stderr_cap.drain_text_stream,
+                    args=(proc.stderr,),
+                    daemon=True,
+                )
+                out_t.start()
+                err_t.start()
+                out_t.join()
+                err_t.join()
+                proc.wait()
             except BaseException as ex:  # noqa: BLE001 — 必须兜住线程内异常
                 thread_exc[0] = ex
 
-        worker = threading.Thread(target=_communicate_worker, daemon=True)
+        worker = threading.Thread(target=_readers_worker, daemon=True)
         worker.start()
         deadline = time.monotonic() + timeout
 
@@ -98,12 +120,16 @@ class RgSubprocessController:
             if thread_exc[0] is not None:
                 raise thread_exc[0]
 
-            return subprocess.CompletedProcess(
+            result = 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 "",
+                stdout=stdout_cap.text(),
+                stderr=stderr_cap.text(),
             )
+            # 供 run_ripgrep_lines 决定是否丢弃残缺末行
+            setattr(result, "stdout_truncated", stdout_cap.truncated)
+            setattr(result, "stderr_truncated", stderr_cap.truncated)
+            return result
         finally:
             if proc.poll() is None:
                 try:

langchain-agentx-python-2.2.5/langchain_agentx/tools/grep/ripgrep_stdout_cap.py

@@ -0,0 +1,93 @@
+"""
+tools/grep/ripgrep_stdout_cap.py — ripgrep stdout/stderr 字节硬顶
+
+职责：
+    对齐 CC ``src/utils/ripgrep.ts`` 的 ``MAX_BUFFER_SIZE = 20_000_000``：
+    边收边截，超限停止 append；解析行时若已截断则丢弃可能残缺的末行。
+
+链路位置：
+    ``run_ripgrep_lines`` / ``RgSubprocessController`` 共用；Grep 与 Glob 列文件同路径受益。
+
+当前裁剪：
+    按 Unicode 字符长度计量（对齐 CC JS string ``.length``）；不在此杀进程。
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+# 对齐 CC ripgrep.ts：large monorepos can have 200k+ files
+MAX_STDOUT_BUFFER_SIZE = 20_000_000
+
+
+class RipgrepStdoutCap:
+    """可复用的有界 stdout/stderr 收集器（feed 后 to_lines / text）。"""
+
+    def __init__(self, max_size: int = MAX_STDOUT_BUFFER_SIZE) -> None:
+        if max_size <= 0:
+            raise ValueError("max_size must be positive")
+        self._max_size = max_size
+        self._parts: list[str] = []
+        self._size = 0
+        self.truncated = False
+
+    @property
+    def max_size(self) -> int:
+        return self._max_size
+
+    @property
+    def size(self) -> int:
+        return self._size
+
+    def feed(self, chunk: str) -> None:
+        """追加 chunk；已截断时忽略内容（调用方仍应继续读以排空管道）。"""
+        if self.truncated or not chunk:
+            return
+        remaining = self._max_size - self._size
+        if len(chunk) <= remaining:
+            self._parts.append(chunk)
+            self._size += len(chunk)
+            return
+        if remaining > 0:
+            self._parts.append(chunk[:remaining])
+            self._size = self._max_size
+        self.truncated = True
+
+    def text(self) -> str:
+        return "".join(self._parts)
+
+    def to_lines(self) -> list[str]:
+        """拆成非空行；截断时丢弃末行（对齐 CC buffer overflow / timeout 处理）。"""
+        return self.lines_from_text(self.text(), truncated=self.truncated)
+
+    @staticmethod
+    def lines_from_text(out: str, *, truncated: bool = False) -> list[str]:
+        """对已物化字符串做硬顶 + 分行（text_runner / mock 路径）。"""
+        if not out:
+            return []
+        was_truncated = truncated
+        if len(out) > MAX_STDOUT_BUFFER_SIZE:
+            out = out[:MAX_STDOUT_BUFFER_SIZE]
+            was_truncated = True
+        if not out.strip():
+            return []
+        lines = [ln.rstrip("\r") for ln in out.rstrip("\n").split("\n")]
+        lines = [ln for ln in lines if ln]
+        if was_truncated and lines:
+            lines = lines[:-1]
+        if was_truncated:
+            logger.warning(
+                "ripgrep stdout truncated at %s chars (CC MAX_BUFFER_SIZE alignment)",
+                MAX_STDOUT_BUFFER_SIZE,
+            )
+        return lines
+
+    def drain_text_stream(self, stream) -> None:
+        """从文本流按块读取并 feed，超限后继续排空但不入库。"""
+        while True:
+            chunk = stream.read(64 * 1024)
+            if not chunk:
+                break
+            self.feed(chunk)

{langchain-agentx-python-2.2.3 → langchain-agentx-python-2.2.5}/langchain_agentx/workflow/base.py

@@ -65,7 +65,7 @@ from .execution import (
 )
 from .memory_drain_registry import MemoryDrainRegistry
 from .memory_session_policy import collect_agent_nodes, validate_loop_session_ids
-from .state import WorkflowState
+from .state import WorkflowState, project_workflow_node_update
 
 # Lazy import for event_adapter（避免循环依赖）
 # 实际使用时通过 _get_event_adapter() 延迟导入
@@ -453,21 +453,22 @@ class BaseWorkflow(ABC):
 
         与 run() 的区别：
             - run(): 返回完整 WorkflowState（用于顶层调用）
-            - as_node(): 返回完整 WorkflowState（作为其他 Workflow 的节点）
+            - as_node(): 返回相对父 state 的 channel delta（供 LangGraph reducer 合并）
 
         实现原理：
-            - 直接调用 run() 返回完整 state
+            - 调用 run() 得到子图终态
+            - 经 project_workflow_node_update 将 messages / item_results 投影为增量
             - 传递 parent_workflow 构建层级关系
             - 使用 outer_semaphore 控制并发（如果提供）
-            - LangGraph 的 reducer 会自动处理合并
 
         并发控制（问题 19）：
             - 如果 outer_workflow 提供 semaphore，子 workflow 的执行会被限流
             - 这解决了 DeepSearch 场景下 45 个 sub-workflow 同时启动的问题
 
-        注意（问题 18 - as_node() diff 算法硬 bug）：
-            - ✅ 新设计（正确）：直接返回完整 state，让 LangGraph reducer 处理合并
-            - ❌ 旧设计（错误）：手算 diff，硬编码字段名，假设 reducer 是 list append
+        注意（聚合通道契约 · 2026-09-04）：
+            - 节点必须返回 delta，禁止把父 state 全量回写进 messages / item_results
+            - 手写节点请用 delta_messages / delta_item_results
+            - as_node 已自动投影，避免嵌套子图 2^N 膨胀
         """
         async def node_fn(state: dict) -> dict:
             # 入口即快照父 _active_run_config，避免 run() 内 set/restore 与父并发时读漂移。
@@ -475,16 +476,18 @@ class BaseWorkflow(ABC):
             # === 并发控制（问题 19）===
             if outer_semaphore is not None:
                 async with outer_semaphore:
-                    return await self.run(
+                    result = await self.run(
                         state,
                         parent_workflow=parent_workflow,
                         run_config=inherited_run_config,
                     )
-            return await self.run(
-                state,
-                parent_workflow=parent_workflow,
-                run_config=inherited_run_config,
-            )
+            else:
+                result = await self.run(
+                    state,
+                    parent_workflow=parent_workflow,
+                    run_config=inherited_run_config,
+                )
+            return project_workflow_node_update(state, result)
 
         return node_fn
 

{langchain-agentx-python-2.2.3 → langchain-agentx-python-2.2.5}/langchain_agentx/workflow/node.py

@@ -93,16 +93,22 @@ class AgentNode:
         ctx: WorkflowNodeContext,
         invocation: LoopInvocation,
     ) -> dict[str, Any]:
-        del state, ctx
-        return {
-            "messages": graph_result.get("messages", []),
-            "item_results": [
+        from .state import delta_item_results, project_workflow_node_update
+
+        del ctx
+        update = project_workflow_node_update(
+            {"messages": state.get("messages", [])},
+            {"messages": graph_result.get("messages", [])},
+        )
+        update.update(
+            delta_item_results(
                 {
                     "node": self.name,
                     "session_id": invocation.session_id,
                 }
-            ],
-        }
+            )
+        )
+        return update
 
     def map_error(
         self,
@@ -110,16 +116,16 @@ class AgentNode:
         exc: Exception,
         ctx: WorkflowNodeContext,
     ) -> dict[str, Any]:
-        return {
-            "messages": state.get("messages", []),
-            "item_results": [
-                {
-                    "node": self.name,
-                    "session_id": ctx.loop_session_id,
-                    "error": str(exc),
-                }
-            ],
-        }
+        from .state import delta_item_results
+
+        del state
+        return delta_item_results(
+            {
+                "node": self.name,
+                "session_id": ctx.loop_session_id,
+                "error": str(exc),
+            }
+        )
 
     def _resolve_graph_factory(
         self,