langchain-agentx-python 1.3.4__py3-none-any.whl → 1.3.6__py3-none-any.whl

langchain_agentx/__init__.py

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

langchain_agentx/loop/graph/factory.py

@@ -876,6 +876,7 @@ class LoopGraphBuilder:
         )
         from ...memory.memdir.fork_concurrency import default_fork_concurrency_limiter
         from ...memory.memdir.metrics import default_memory_fork_metrics
+        from ...memory.memdir.tunables import get_memory_extraction_turn_threshold
 
         metrics = default_memory_fork_metrics()
         return MemoryExtractionCoordinator(
@@ -889,6 +890,7 @@ class LoopGraphBuilder:
                 trace_collector=trace_collector,
                 session_id=session_id,
             ),
+            turn_threshold=get_memory_extraction_turn_threshold(self._workspace_cfg),
         )
 
     def _build_session_memory_extractor(

langchain_agentx/loop/hook/graph_wiring.py

@@ -123,34 +123,27 @@ class HookGraphWiring:
         return patch
 
     async def loop_end_node_async(self, state: dict[str, Any], runtime: Any) -> dict[str, Any]:
-        """async loop_end：在事件循环上 await drain，避免 sync stop 节点 blocking 死锁。"""
-        memory_patch = await self._drain_memory_extraction_async()
-        base_patch = self.loop_end_node(state, runtime)
-        if not memory_patch:
-            return base_patch
-        if not base_patch:
-            return memory_patch
-        merged = dict(base_patch)
-        if "_hook_ui_events" in memory_patch:
-            merged.setdefault("_hook_ui_events", []).extend(
-                memory_patch.get("_hook_ui_events") or []
-            )
-        return merged
+        """async loop_end：等价 CC ``stopHooks.ts:149`` 的 ``void executeExtractMemories(...)``
+        fork-and-forget 语义 —— 主回合不等抽取任务。
 
-    async def _drain_memory_extraction_async(self) -> dict[str, Any]:
-        if self.memory_extractor is None:
-            return {}
-        drain = getattr(self.memory_extractor, "drain_pending_extraction", None)
-        if callable(drain):
-            from langchain_agentx.memory.memdir.extractor import STOP_HOOK_DRAIN_TIMEOUT_MS
-
-            await drain(STOP_HOOK_DRAIN_TIMEOUT_MS)
-        drain_saved = getattr(self.memory_extractor, "drain_memory_saved_ui_events", None)
-        if callable(drain_saved):
-            saved_ui = drain_saved()
-            if saved_ui:
-                return {"_hook_ui_events": saved_ui}
-        return {}
+        抽取任务已由 ``stop_hooks_node`` 通过
+        ``Coordinator.trigger_from_state() → loop.create_task(...)`` 调度到事件循环；
+        task ownership 跟随顶层 owner，而非单个 turn。drain 由更高层负责：
+
+        * ``AgentSession.__aexit__`` / ``ConversationSession.__aexit__`` 60 s drain
+        * ``Workflow.run() finally`` ``_drain_pending_memory_extractions()`` 60 s drain
+        * ``BackgroundAgent`` 收尾路径独立 owner
+
+        以下场景不在本节点处理：
+
+        * **本回合内已就绪的 ``memory_saved`` UI 事件**：由 ``loop_end_node`` 内部
+          调用 ``drain_memory_saved_ui_events()`` 回收；async 路径完全对称走 sync 实现。
+        * **未就绪的抽取任务**：留给下一回合 trailing 回收 或 owner 边界 drain。
+
+        历史：曾经在此 ``await drain(5_000)``，等价 ``fork()`` 后立即 ``waitpid()``，
+        把 fork-and-forget 设计破坏；慢模型下必然超时 abort 导致记忆丢失。已删除。
+        """
+        return self.loop_end_node(state, runtime)
 
     def loop_end_node(self, state: dict[str, Any], runtime: Any) -> dict[str, Any]:
         if self.memory_prefetch_coordinator is not None:
@@ -161,6 +154,13 @@ class HookGraphWiring:
             patch.update(self._drain_hook_ui_events())
             if result.state_patch:
                 patch.update(dict(result.state_patch))
+        # 回收已就绪的 memory_saved UI 事件（抽取完成，下一 turn trailing）
+        if self.memory_extractor is not None:
+            drain_saved = getattr(self.memory_extractor, "drain_memory_saved_ui_events", None)
+            if callable(drain_saved):
+                saved_ui = drain_saved()
+                if saved_ui:
+                    patch.setdefault("_hook_ui_events", []).extend(saved_ui)
         if self.trace_lifecycle_collector is not None:
             patch.update(self.trace_lifecycle_collector.loop_end_node(state))
         return patch

langchain_agentx/memory/memdir/extractor.py

@@ -41,7 +41,6 @@ logger = logging.getLogger(__name__)
 
 _WRITE_TOOLS = {"Write", "Edit"}
 DEFAULT_EXTRACTION_WINDOW_MESSAGES = 30
-STOP_HOOK_DRAIN_TIMEOUT_MS = 5_000
 
 
 def _as_int(value: Any) -> int:
@@ -95,12 +94,14 @@ class MemoryExtractionCoordinator:
         cursor_store: MemoryExtractionCursorStore | None = None,
         metrics: MemoryForkMetrics | None = None,
         on_memory_saved: MemorySavedCallback | None = None,
+        turn_threshold: int = 3,  # ← 闸门 7: 默认每 3 轮 trigger 才执行一次 fork 抽取
     ) -> None:
         self._executor = extraction_executor
         self._forked_runner = forked_runner
         self._cursor_store = cursor_store or MemoryExtractionCursorStore()
         self._metrics = metrics or default_memory_fork_metrics()
         self._on_memory_saved = on_memory_saved
+        self._turn_threshold = max(1, int(turn_threshold))  # 钳位 ≥1
         self._memory_saved_ui_pending: list[dict[str, Any]] = []
         self._in_progress = False
         self._pending_context: MemoryExtractionContext | None = None
@@ -118,7 +119,7 @@ class MemoryExtractionCoordinator:
         container_type: str,
         force: bool = True,
     ) -> None:
-        """stop hook：L2 唯一触发入口；force=True，无 token 门槛（对齐 CC stopHooks）。"""
+        """stop hook：L2 唯一触发入口；force=True 无 token 门槛，turn 节流仍生效。"""
         if not self._can_extract_from_state(state, container_type, workspace_cfg):
             return
         context = self._build_context(
@@ -127,7 +128,7 @@ class MemoryExtractionCoordinator:
             session_id=session_id,
             container_type=container_type,
             force=force,
-            skip_throttle=True,
+            skip_throttle=False,  # 闸门 7 生效；pending 重放的 trailing 路径仍设 True
         )
         self.trigger(context)
 
@@ -166,10 +167,19 @@ class MemoryExtractionCoordinator:
         self._tasks.add(task)
         task.add_done_callback(self._tasks.discard)
 
-    def drain_on_stop(self, timeout_ms: int = STOP_HOOK_DRAIN_TIMEOUT_MS) -> None:
+    def drain_on_stop(self, timeout_ms: int = 60_000) -> None:
         """跨线程阻塞等待 in-flight 抽取（勿在 owner 事件循环线程调用，会死锁）。
 
-        主 Loop graph 路径应使用 ``loop_end_node_async`` → ``await drain_pending_extraction``。
+        语义：仅供 **进程退出 hook / sync owner 关闭** 等"无 event loop 可用"的
+        外部 caller 使用。等价 CC ``print.ts:968`` 进程退出前的一次性 drain。
+
+        Loop graph 路径**不再**调用本方法（Phase 2 已删除 turn-级 drain）：
+        async owner（AgentSession / ConversationSession.__aexit__、
+        Workflow.run() finally、BackgroundAgent 收尾）应直接
+        ``await drain_pending_extraction(60_000)``。
+
+        默认 ``timeout_ms`` 与 owner-级 60 s 对齐，对齐 CC
+        ``extractMemories.ts:579`` 的 ``drainer`` 默认值。
         """
         if not self._tasks:
             return
@@ -279,6 +289,18 @@ class MemoryExtractionCoordinator:
             self._advance_cursor(context, new_messages, cursor)
             return
 
+        # —— 闸门 7: turn 节流（对齐 CC tengu_bramble_lintel） ——
+        if not context.skip_throttle:
+            cursor.turns_since_last_extraction += 1
+            if cursor.turns_since_last_extraction < self._turn_threshold:
+                self._cursor_store.save(
+                    workspace_cfg=context.workspace_cfg,
+                    session_id=context.session_id,
+                    container_type=context.container_type,
+                    state=cursor,
+                )
+                return
+
         succeeded = True
         if self._executor is not None:
             await self._executor(context, new_messages)
@@ -603,7 +625,6 @@ def build_trace_memory_saved_callback(
 __all__ = [
     "MemoryExtractionContext",
     "MemoryExtractionCoordinator",
-    "STOP_HOOK_DRAIN_TIMEOUT_MS",
     "build_extract_prompt",
     "build_trace_memory_saved_callback",
     "create_auto_mem_can_use_tool",

langchain_agentx/memory/memdir/tunables.py

@@ -0,0 +1,69 @@
+"""
+tunables.py — L2 记忆抽取可调参数。
+
+职责：
+    提供 get_memory_extraction_turn_threshold()，封装 env / settings.json / 默认值
+    三层读取，作为闸门 7（turn 节流）的配置入口。
+
+链路位置：
+    factory.py _build_memory_extraction_coordinator
+        → get_memory_extraction_turn_threshold(workspace_cfg)
+        → MemoryExtractionCoordinator(turn_threshold=...)。
+
+当前裁剪范围：
+    仅 turn 节流阈值；其它 L2 可调参数（fork concurrency / drain timeout 等）保持现状。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any
+
+from langchain_agentx.workspace import ResolvedAgentStateConfig
+
+logger = logging.getLogger(__name__)
+
+_ENV_TURN_THRESHOLD = "LANGCHAIN_AGENTX_MEMORY_TURN_THRESHOLD"
+_SETTINGS_KEY = "memoryExtractionTurnThreshold"
+_DEFAULT_TURN_THRESHOLD = 3
+
+
+def get_memory_extraction_turn_threshold(
+    workspace_cfg: ResolvedAgentStateConfig,
+) -> int:
+    """L2 闸门 7 阈值；env > settings.json > 默认 3，钳位 ≥1。"""
+    raw = os.environ.get(_ENV_TURN_THRESHOLD)
+    if raw is not None:
+        try:
+            return max(1, int(raw))
+        except ValueError:
+            logger.warning(
+                "ignore non-integer %s=%r, falling back to settings/default",
+                _ENV_TURN_THRESHOLD,
+                raw,
+            )
+
+    settings = _read_workspace_settings(workspace_cfg)
+    value = settings.get(_SETTINGS_KEY)
+    if isinstance(value, int) and not isinstance(value, bool) and value >= 1:
+        return value
+
+    return _DEFAULT_TURN_THRESHOLD
+
+
+def _read_workspace_settings(workspace_cfg: ResolvedAgentStateConfig) -> dict[str, Any]:
+    """读取 workspace_config.json；缺失或损坏时返回空 dict。"""
+    path = workspace_cfg.workspace_config_path
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        logger.warning("ignore corrupt workspace settings %s: %s", path, exc)
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+__all__ = ["get_memory_extraction_turn_threshold"]

langchain_agentx/observability/__init__.py

@@ -6,12 +6,14 @@ from .events import (
     FINISH_OUTCOME_KEYS,
     FinishOutcome,
     FinishOutcomeParser,
+    ILangGraphEventAdapter,
     LangchainAgentEvent,
     LangchainAgentEventType,
     LangGraphToLangchainAgentEventAdapter,
     RecoveryAction,
     RecoveryActionResolver,
     RecoveryPolicyMode,
+    create_langgraph_event_adapter,
     enrich_run_result,
 )
 from .replay.service import (
@@ -54,6 +56,7 @@ __all__ = [
     "DECISION_LAYERS",
     "DebugBurstController",
     "DebugBurstSession",
+    "ILangGraphEventAdapter",
     "LogContext",
     "LoggingConfigBuilder",
     "OBS_SCHEMA_VERSION",
@@ -63,6 +66,7 @@ __all__ = [
     "LangchainAgentEvent",
     "LangchainAgentEventType",
     "LangGraphToLangchainAgentEventAdapter",
+    "create_langgraph_event_adapter",
     "RecoveryAction",
     "RecoveryActionResolver",
     "RecoveryPolicyMode",

langchain_agentx/observability/events/__init__.py

@@ -16,6 +16,10 @@ from .finish_outcome import (
     RecoveryPolicyMode,
     enrich_run_result,
 )
+from .factory import (
+    ILangGraphEventAdapter,
+    create_langgraph_event_adapter,
+)
 
 __all__ = [
     "LangchainAgentEventType",
@@ -30,4 +34,6 @@ __all__ = [
     "RecoveryActionResolver",
     "RecoveryPolicyMode",
     "enrich_run_result",
+    "ILangGraphEventAdapter",
+    "create_langgraph_event_adapter",
 ]