langchain-agentx-python 1.6.4__tar.gz → 1.6.5__tar.gz

{langchain-agentx-python-1.6.4/langchain_agentx_python.egg-info → langchain-agentx-python-1.6.5}/PKG-INFO

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

{langchain-agentx-python-1.6.4 → langchain-agentx-python-1.6.5}/langchain_agentx/__init__.py

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

{langchain-agentx-python-1.6.4 → langchain-agentx-python-1.6.5}/langchain_agentx/observability/events/workflow_aware_event_adapter.py

@@ -55,21 +55,29 @@ class WorkflowAwareLangGraphEventAdapter:
         self, events: AsyncIterator[Dict[str, Any]]
     ) -> AsyncIterator[LangchainAgentEvent]:
         async for raw_event in events:
-            self._sync_workflow_session_id(raw_event)
+            root_session_id = self._extract_session_id(raw_event)
+            if root_session_id:
+                self._workflow_adapter.set_root_fallback_session_id(root_session_id)
 
             for workflow_event in self._workflow_adapter.consume(raw_event):
                 mapped = self._workflow_mapper.map(workflow_event)
                 if mapped is not None:
                     yield mapped
 
+            loop_session_id = self._workflow_adapter.resolve_active_loop_session_id()
+            if loop_session_id:
+                self._agent_projector.state.session_id = loop_session_id
+            elif root_session_id:
+                self._agent_projector.state.session_id = root_session_id
+
             async for agent_event in self._agent_projector.consume(raw_event):
                 yield agent_event
 
     def _sync_workflow_session_id(self, raw_event: Dict[str, Any]) -> None:
-        session_id = self._extract_session_id(raw_event)
-        if session_id:
-            self._workflow_adapter.state.session_id = session_id
-            self._agent_projector.state.session_id = session_id
+        """Deprecated: session 同步已内联至 adapt()（先 reconcile stack 再派生 loop session）。"""
+        root_session_id = self._extract_session_id(raw_event)
+        if root_session_id:
+            self._workflow_adapter.set_root_fallback_session_id(root_session_id)
 
     @staticmethod
     def _extract_session_id(raw_event: Dict[str, Any]) -> str | None:

{langchain-agentx-python-1.6.4 → langchain-agentx-python-1.6.5}/langchain_agentx/workflow/__init__.py

@@ -35,6 +35,7 @@ __all__ = [
     "CatalogBackedWorkflowDisplayResolver",
     "CompositeWorkflowDisplayResolver",
     "WorkflowDisplayEnricher",
+    "collect_effective_structure_contract",
     # 事件适配器
     "WorkflowLifecycleEventData",
     "SubworkflowEventData",
@@ -91,6 +92,7 @@ _MODULE_BY_NAME = {
     "CatalogBackedWorkflowDisplayResolver": ".display_resolver",
     "CompositeWorkflowDisplayResolver": ".display_resolver",
     "WorkflowDisplayEnricher": ".display_enricher",
+    "collect_effective_structure_contract": ".structure_collector",
     # event adapter exports
     "WorkflowLifecycleEventData": ".event_adapter",
     "SubworkflowEventData": ".event_adapter",

{langchain-agentx-python-1.6.4 → langchain-agentx-python-1.6.5}/langchain_agentx/workflow/base.py

@@ -298,11 +298,19 @@ class BaseWorkflow(ABC):
         return self.build_graph().compile()
 
     def export_local_event_adapter_structure(self) -> dict:
-        """导出本 workflow 实例的局部 structure（不沿 delegate 解析）。"""
+        """导出本 workflow 实例的局部 structure 片段（local-view only）。
+
+        不沿 delegate 解析；不含 nested ``scopes[path]`` 全集或 runtime binding registry。
+        Consumer / validator / 开流 adapter 应使用 ``collect_effective_structure_contract()``。
+        """
         return {}
 
     def export_event_adapter_structure(self) -> dict:
-        """导出 event adapter 所需的 workflow_structure（wrapper 沿 delegate 解析）。"""
+        """导出 delegate 解析后的本层 structure 片段（local-view only）。
+
+        仅供 ``WorkflowStructureCollector`` 输入或模式级单测；不是 consumer SSOT。
+        完整 effective contract 请使用 ``collect_effective_structure_contract()``。
+        """
         source = self._resolve_structure_delegate_workflow()
         if source is self:
             return self.export_local_event_adapter_structure()
@@ -312,20 +320,14 @@ class BaseWorkflow(ABC):
         self,
         workflow_structure: dict | None,
     ) -> dict:
-        """合并 derived scoped structure + caller override，并对 Structured Workflow 做 fail-fast 校验。"""
-        from .structure_collector import (
-            WorkflowStructureCollector,
-            merge_scoped_structure_with_override,
-        )
-        from .structure_validation import validate_event_adapter_structure
+        """合并 derived scoped structure + caller override，并对 Structured Workflow 做 fail-fast 校验。
 
-        derived = WorkflowStructureCollector().collect(self)
-        effective_structure = merge_scoped_structure_with_override(
-            derived,
-            workflow_structure,
-        )
-        validate_event_adapter_structure(self, effective_structure)
-        return effective_structure
+        内部委托 ``collect_effective_structure_contract()``；保留此方法供
+        ``astream_langchain_events()`` 与既有测试调用。
+        """
+        from .structure_collector import collect_effective_structure_contract
+
+        return collect_effective_structure_contract(self, workflow_structure)
 
     async def run(
         self,

{langchain-agentx-python-1.6.4 → langchain-agentx-python-1.6.5}/langchain_agentx/workflow/event_adapter/adapter.py

@@ -26,6 +26,10 @@ from langchain_agentx.workflow.event_adapter.types import (
 from langchain_agentx.workflow.event_adapter.stack import WorkflowStack
 from langchain_agentx.workflow.event_adapter.depth_resolver import DepthResolver
 from langchain_agentx.workflow.event_adapter.scope_resolver import WorkflowScopeResolver
+from langchain_agentx.workflow.event_adapter.session_router import WorkflowSessionRouter
+from langchain_agentx.workflow.event_adapter.structure_lifecycle_guard import (
+    StructureLifecycleGuard,
+)
 from langchain_agentx.workflow.display_enricher import WorkflowDisplayEnricher
 from langchain_agentx.workflow.event_adapter.handlers import (
     StageHandler,
@@ -76,9 +80,7 @@ class WorkflowEventAdapter:
         self.workflow_id = workflow_id
         self.config = config or {}
         self.state = WorkflowAdapterState()
-
-        # 注入 session_id
-        self.state.session_id = session_id
+        self._root_fallback_session_id = session_id
 
         # 初始化 total_stages（从 config 传入）
         self.state.total_stages = self.config.get("total_stages", 0)
@@ -91,6 +93,12 @@ class WorkflowEventAdapter:
         self._stack = WorkflowStack(workflow_id)
         self._depth_resolver = DepthResolver()
         self._scope_resolver = WorkflowScopeResolver(self.config, self._stack)
+        self._session_router = WorkflowSessionRouter(
+            self._scope_resolver,
+            self._stack,
+            root_workflow_id=workflow_id,
+        )
+        self._lifecycle_guard = StructureLifecycleGuard()
         self._stage_handler = StageHandler(
             self.state, self._stack, self._scope_resolver, self.config
         )
@@ -104,6 +112,17 @@ class WorkflowEventAdapter:
         # 初始化状态
         self.state.root_workflow_id = workflow_id
 
+    def set_root_fallback_session_id(self, session_id: str | None) -> None:
+        """设置 root workflow 容器事件与无 task_key 场景的 fallback session_id。"""
+        self._root_fallback_session_id = session_id
+        self.state.session_id = session_id
+
+    def resolve_active_loop_session_id(self) -> str | None:
+        """按当前 active scope 派生 agent/loop session_id。"""
+        return self._session_router.resolve_active_loop_session_id(
+            root_fallback_session_id=self._root_fallback_session_id,
+        )
+
     def consume(self, event: Dict[str, Any]) -> List[WorkflowEvent]:
         """消费单个 LangGraph 事件，返回 WorkflowEvent 列表
 
@@ -186,7 +205,15 @@ class WorkflowEventAdapter:
             if e.event_type != WorkflowEventType.SUBWORKFLOW_END:
                 e.workflow_depth = self._stack.current_depth
                 e.parent_workflow_id = self._stack.parent_workflow_id
-            e.session_id = self.state.session_id
+            e.session_id = self._session_router.resolve_session_id(
+                e,
+                root_fallback_session_id=self._root_fallback_session_id,
+            )
+            self.state.session_id = e.session_id
+
+        events = self._filter_lifecycle_events(events)
+
+        for e in events:
             self._enrich_lifecycle_display(e)
 
         # === 更新序列号 ===
@@ -222,24 +249,53 @@ class WorkflowEventAdapter:
         self._stack.reconcile_to_depth(alignment.target_depth, alignment.segment_ids)
 
         new_depth = self._stack.current_depth
-        if new_depth > previous_depth:
+        if new_depth > previous_depth and self._should_emit_subworkflow_lifecycle(
+            self._stack.build_path()
+        ):
             events.append(self._build_event(
                 WorkflowEventType.SUBWORKFLOW_START,
                 {"child_workflow_id": self._stack.current_workflow_id},
             ))
-        elif exiting_nested:
-            events.append(WorkflowEvent(
+        elif exiting_nested and child_path and self._should_emit_subworkflow_lifecycle(
+            child_path
+        ):
+            sub_end = WorkflowEvent(
                 event_type=WorkflowEventType.SUBWORKFLOW_END,
                 data={"child_workflow_id": previous_child_id},
                 workflow_id=previous_child_id,
                 workflow_path=child_path or self._stack.build_path(),
                 workflow_depth=child_depth if child_depth is not None else 0,
-                session_id=self.state.session_id,
                 parent_workflow_id=child_parent_id,
-            ))
+            )
+            sub_end.session_id = self._session_router.resolve_session_id(
+                sub_end,
+                root_fallback_session_id=self._root_fallback_session_id,
+            )
+            events.append(sub_end)
 
         return events
 
+    def _should_emit_subworkflow_lifecycle(self, scope_path: str) -> bool:
+        """仅 scope_origin=nested_workflow 时发 subworkflow-* 结构事件。"""
+        from langchain_agentx.workflow.structure_collector import (
+            SCOPE_ORIGIN_NESTED_WORKFLOW,
+        )
+
+        entry = self._scope_resolver.scope_entry_at(scope_path)
+        if not entry:
+            return False
+        return entry.get("scope_origin") == SCOPE_ORIGIN_NESTED_WORKFLOW
+
+    def _filter_lifecycle_events(
+        self, events: List[WorkflowEvent]
+    ) -> List[WorkflowEvent]:
+        """结构生命周期 open/close 幂等过滤；graph-node 等内容事件不受影响。"""
+        filtered: List[WorkflowEvent] = []
+        for event in events:
+            if self._lifecycle_guard.should_emit(event):
+                filtered.append(event)
+        return filtered
+
     def _build_event(
         self,
         event_type: WorkflowEventType,
@@ -260,7 +316,6 @@ class WorkflowEventAdapter:
             workflow_id=self._stack.current_workflow_id,
             workflow_path=self._stack.build_path(),
             workflow_depth=self._stack.current_depth,
-            session_id=self.state.session_id,
             parent_workflow_id=self._stack.parent_workflow_id,
         )
 
@@ -289,7 +344,6 @@ class WorkflowEventAdapter:
             workflow_id=self._stack.current_workflow_id,
             workflow_path=self._stack.build_path(),
             workflow_depth=self._stack.current_depth,
-            session_id=self.state.session_id,
             parent_workflow_id=self._stack.parent_workflow_id,
         )
 

{langchain-agentx-python-1.6.4 → langchain-agentx-python-1.6.5}/langchain_agentx/workflow/event_adapter/scope_resolver.py

@@ -27,7 +27,9 @@ from .stack import WorkflowStack
 
 logger = logging.getLogger(__name__)
 
-_SCOPE_METADATA_FIELDS = frozenset({"workflow_id", "scope_key", "scope_kind", "graph_key"})
+_SCOPE_METADATA_FIELDS = frozenset(
+    {"workflow_id", "scope_key", "scope_kind", "scope_origin", "graph_key"}
+)
 
 
 class WorkflowScopeResolver:
@@ -54,10 +56,21 @@ class WorkflowScopeResolver:
 
     def current_scope(self) -> dict[str, Any]:
         """返回当前事件时刻应使用的 structure scope（不含 registry 元数据字段）。"""
-        scope_key = self.current_scope_key()
+        return self._strip_scope_metadata(self.current_scope_entry())
+
+    def scope_entry_at(self, scope_key: str) -> dict[str, Any] | None:
+        """按 path 查 scopes registry entry；miss 时返回 None（不抛错）。"""
         entry = self._scopes.get(scope_key)
         if isinstance(entry, dict):
-            return self._strip_scope_metadata(entry)
+            return dict(entry)
+        return None
+
+    def current_scope_entry(self) -> dict[str, Any]:
+        """返回 scopes[path] 原始 entry（含 workflow_id / graph_key / scope_origin 等）。"""
+        scope_key = self.current_scope_key()
+        entry = self.scope_entry_at(scope_key)
+        if entry is not None:
+            return entry
 
         self._record_scope_miss(scope_key)
         detail_parts = [

langchain-agentx-python-1.6.5/langchain_agentx/workflow/event_adapter/session_router.py

@@ -0,0 +1,190 @@
+"""
+session_router.py — Workflow 结构/agent 事件 session_id 路由
+
+职责：
+    - 按 active runtime scope 与 task_key 派生 loop session_id
+    - 统一走 WorkflowSessionIdPolicy.build_session_id(workflow_id, task_key)
+    - root workflow 容器事件使用 root fallback session（LangGraph input _session_id）
+
+链路位置：
+    - Layer 3: Workflow 事件适配器
+    - 由 WorkflowEventAdapter 在事件产出后绑定 session_id
+
+当前裁剪范围：
+    - 仅派生 session_id，不维护 mutable 全局单槽
+    - aggregate 使用 aggregate_key 作为 task_key，无 special case
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .scope_resolver import WorkflowScopeResolver
+from .stack import WorkflowStack
+from .types import WorkflowEvent, WorkflowEventType
+
+_STAGE_EVENTS = frozenset(
+    {
+        WorkflowEventType.STAGE_START,
+        WorkflowEventType.STAGE_DONE,
+        WorkflowEventType.STAGE_FAILED,
+    }
+)
+_PARALLEL_ITEM_EVENTS = frozenset(
+    {
+        WorkflowEventType.PARALLEL_ITEM_START,
+        WorkflowEventType.PARALLEL_ITEM_DONE,
+        WorkflowEventType.PARALLEL_ITEM_FAILED,
+    }
+)
+_AGGREGATE_EVENTS = frozenset(
+    {
+        WorkflowEventType.PARALLEL_AGGREGATE_START,
+        WorkflowEventType.PARALLEL_AGGREGATE_DONE,
+        WorkflowEventType.PARALLEL_AGGREGATE_FAILED,
+    }
+)
+_ROUTE_EVENTS = frozenset(
+    {
+        WorkflowEventType.ROUTE_BRANCH_START,
+        WorkflowEventType.ROUTE_BRANCH_DONE,
+        WorkflowEventType.ROUTE_BRANCH_FAILED,
+    }
+)
+_ROOT_CONTAINER_EVENTS = frozenset(
+    {
+        WorkflowEventType.WORKFLOW_START,
+        WorkflowEventType.WORKFLOW_END,
+        WorkflowEventType.WORKFLOW_FAILED,
+    }
+)
+
+
+def _build_policy_session_id(workflow_id: str, task_key: str) -> str:
+    from langchain_agentx.workflow.execution import (
+        WorkflowNodeContext,
+        WorkflowSessionIdPolicy,
+    )
+
+    return WorkflowSessionIdPolicy.build_session_id(
+        WorkflowNodeContext(workflow_id=workflow_id, task_key=task_key),
+    )
+
+
+class WorkflowSessionRouter:
+    """按 active scope contract 派生 structure / loop session_id。"""
+
+    def __init__(
+        self,
+        scope_resolver: WorkflowScopeResolver,
+        stack: WorkflowStack,
+        *,
+        root_workflow_id: str,
+    ) -> None:
+        self._scope_resolver = scope_resolver
+        self._stack = stack
+        self._root_workflow_id = root_workflow_id
+
+    def resolve_session_id(
+        self,
+        event: WorkflowEvent,
+        *,
+        root_fallback_session_id: str | None = None,
+    ) -> str | None:
+        """为已产出的 WorkflowEvent 绑定 session_id。"""
+        if (
+            event.event_type in _ROOT_CONTAINER_EVENTS
+            and event.workflow_depth == 0
+        ):
+            return root_fallback_session_id
+
+        task_key = self._task_key_from_event(event)
+        if not task_key:
+            return root_fallback_session_id
+
+        owner_workflow_id = self._owner_workflow_id()
+        return _build_policy_session_id(owner_workflow_id, task_key)
+
+    def resolve_active_loop_session_id(
+        self,
+        *,
+        root_fallback_session_id: str | None = None,
+    ) -> str | None:
+        """为当前 stack 下的 agent 事件派生 loop session_id（无 WorkflowEvent 上下文）。"""
+        entry = self._scope_resolver.current_scope_entry()
+        scope_kind = entry.get("scope_kind")
+        graph_key = entry.get("graph_key")
+
+        if scope_kind == "workflow_root":
+            return root_fallback_session_id
+
+        if graph_key and scope_kind in (
+            "stage",
+            "parallel_item",
+            "route",
+            "aggregate",
+        ):
+            owner_workflow_id = str(entry.get("workflow_id") or self._owner_workflow_id())
+            return _build_policy_session_id(owner_workflow_id, str(graph_key))
+
+        task_key = self._task_key_from_scope_entry(entry)
+        if task_key:
+            owner_workflow_id = str(entry.get("workflow_id") or self._owner_workflow_id())
+            return _build_policy_session_id(owner_workflow_id, task_key)
+
+        return root_fallback_session_id
+
+    def _owner_workflow_id(self) -> str:
+        entry = self._scope_resolver.current_scope_entry()
+        workflow_id = entry.get("workflow_id")
+        if workflow_id:
+            return str(workflow_id)
+        if self._stack.current_depth == 0:
+            return self._root_workflow_id
+        return self._stack.current_workflow_id
+
+    def _task_key_from_event(self, event: WorkflowEvent) -> str | None:
+        data: dict[str, Any] = event.data if isinstance(event.data, dict) else {}
+
+        if event.event_type in _STAGE_EVENTS:
+            key = data.get("stage_key")
+            return str(key) if key else None
+
+        if event.event_type in _PARALLEL_ITEM_EVENTS:
+            key = data.get("item_key")
+            return str(key) if key else None
+
+        if event.event_type in _AGGREGATE_EVENTS:
+            key = data.get("aggregate_key")
+            return str(key) if key else None
+
+        if event.event_type in _ROUTE_EVENTS:
+            key = data.get("branch_key")
+            return str(key) if key else None
+
+        if event.event_type in (
+            WorkflowEventType.SUBWORKFLOW_START,
+            WorkflowEventType.SUBWORKFLOW_END,
+        ):
+            return self._task_key_from_scope_entry(
+                self._scope_resolver.current_scope_entry()
+            )
+
+        if event.event_type in (
+            WorkflowEventType.GRAPH_NODE_START,
+            WorkflowEventType.GRAPH_NODE_END,
+        ):
+            node = data.get("node")
+            return str(node) if node else None
+
+        return None
+
+    @staticmethod
+    def _task_key_from_scope_entry(entry: dict[str, Any]) -> str | None:
+        graph_key = entry.get("graph_key")
+        if graph_key:
+            return str(graph_key)
+        return None
+
+
+__all__ = ["WorkflowSessionRouter"]

langchain-agentx-python-1.6.5/langchain_agentx/workflow/event_adapter/structure_lifecycle_guard.py

@@ -0,0 +1,144 @@
+"""
+structure_lifecycle_guard.py — 结构生命周期事件 open/close 幂等保护
+
+职责：
+    - 维护 open-set，同一 identity 未 close 前 suppress 重复 OPEN
+    - 已 close 后 suppress 重复 CLOSE；完整 close 后允许合法 reopen
+
+链路位置：
+    - Layer 3: Workflow 事件适配器
+    - 由 WorkflowEventAdapter 在事件产出后、序列号分配前过滤
+
+当前裁剪范围：
+    - 仅结构生命周期容器事件（workflow / stage / item / aggregate / branch / subworkflow）
+    - 不覆盖 graph-node 等内容/调试事件
+    - identity = workflow_path|scope:scope_key
+"""
+
+from __future__ import annotations
+
+from .types import WorkflowEvent, WorkflowEventType
+
+_OPEN_EVENTS = frozenset(
+    {
+        WorkflowEventType.WORKFLOW_START,
+        WorkflowEventType.SUBWORKFLOW_START,
+        WorkflowEventType.STAGE_START,
+        WorkflowEventType.PARALLEL_ITEM_START,
+        WorkflowEventType.PARALLEL_AGGREGATE_START,
+        WorkflowEventType.ROUTE_BRANCH_START,
+    }
+)
+_CLOSE_EVENTS = frozenset(
+    {
+        WorkflowEventType.WORKFLOW_END,
+        WorkflowEventType.WORKFLOW_FAILED,
+        WorkflowEventType.SUBWORKFLOW_END,
+        WorkflowEventType.STAGE_DONE,
+        WorkflowEventType.STAGE_FAILED,
+        WorkflowEventType.PARALLEL_ITEM_DONE,
+        WorkflowEventType.PARALLEL_ITEM_FAILED,
+        WorkflowEventType.PARALLEL_AGGREGATE_DONE,
+        WorkflowEventType.PARALLEL_AGGREGATE_FAILED,
+        WorkflowEventType.ROUTE_BRANCH_DONE,
+        WorkflowEventType.ROUTE_BRANCH_FAILED,
+    }
+)
+
+
+def build_lifecycle_identity(event: WorkflowEvent) -> str | None:
+    """构建结构容器 identity；非生命周期事件返回 None。"""
+    if event.event_type not in _OPEN_EVENTS and event.event_type not in _CLOSE_EVENTS:
+        return None
+
+    path = event.workflow_path or ""
+    data = event.data if isinstance(event.data, dict) else {}
+    scope_key: str | None = None
+
+    if event.event_type in (
+        WorkflowEventType.WORKFLOW_START,
+        WorkflowEventType.WORKFLOW_END,
+        WorkflowEventType.WORKFLOW_FAILED,
+    ):
+        raw = data.get("workflow_id") or event.workflow_id
+        scope_key = str(raw) if raw else None
+    elif event.event_type in (
+        WorkflowEventType.SUBWORKFLOW_START,
+        WorkflowEventType.SUBWORKFLOW_END,
+    ):
+        raw = data.get("child_workflow_id")
+        scope_key = str(raw) if raw else None
+    elif event.event_type in (
+        WorkflowEventType.STAGE_START,
+        WorkflowEventType.STAGE_DONE,
+        WorkflowEventType.STAGE_FAILED,
+    ):
+        raw = data.get("stage_key")
+        scope_key = str(raw) if raw else None
+    elif event.event_type in (
+        WorkflowEventType.PARALLEL_ITEM_START,
+        WorkflowEventType.PARALLEL_ITEM_DONE,
+        WorkflowEventType.PARALLEL_ITEM_FAILED,
+    ):
+        raw = data.get("item_key")
+        scope_key = str(raw) if raw else None
+    elif event.event_type in (
+        WorkflowEventType.PARALLEL_AGGREGATE_START,
+        WorkflowEventType.PARALLEL_AGGREGATE_DONE,
+        WorkflowEventType.PARALLEL_AGGREGATE_FAILED,
+    ):
+        raw = data.get("aggregate_key")
+        scope_key = str(raw) if raw else None
+    elif event.event_type in (
+        WorkflowEventType.ROUTE_BRANCH_START,
+        WorkflowEventType.ROUTE_BRANCH_DONE,
+        WorkflowEventType.ROUTE_BRANCH_FAILED,
+    ):
+        raw = data.get("branch_key")
+        scope_key = str(raw) if raw else None
+
+    if not scope_key:
+        return None
+    return f"{path}|scope:{scope_key}"
+
+
+class StructureLifecycleGuard:
+    """结构生命周期 open-set 幂等守卫（per-adapter 实例，不跨 execution 永久 dedupe）。"""
+
+    def __init__(self) -> None:
+        self._open_identities: set[str] = set()
+
+    @property
+    def open_identities(self) -> frozenset[str]:
+        """当前仍 open 的 identity 集合（测试/诊断）。"""
+        return frozenset(self._open_identities)
+
+    def should_emit(self, event: WorkflowEvent) -> bool:
+        """返回是否应向外发射该结构生命周期事件。"""
+        identity = build_lifecycle_identity(event)
+        if identity is None:
+            return True
+
+        if event.event_type in _OPEN_EVENTS:
+            if identity in self._open_identities:
+                return False
+            self._open_identities.add(identity)
+            return True
+
+        if event.event_type in _CLOSE_EVENTS:
+            if identity not in self._open_identities:
+                return False
+            self._open_identities.discard(identity)
+            return True
+
+        return True
+
+    def reset(self) -> None:
+        """清空 open-set（新 execution / 测试隔离）。"""
+        self._open_identities.clear()
+
+
+__all__ = [
+    "StructureLifecycleGuard",
+    "build_lifecycle_identity",
+]

{langchain-agentx-python-1.6.4 → langchain-agentx-python-1.6.5}/langchain_agentx/workflow/patterns/chaining.py

@@ -184,6 +184,7 @@ class ChainingWorkflow(BaseWorkflow):
         return gate_fn
 
     def export_local_event_adapter_structure(self) -> dict:
+        """导出本 ChainingWorkflow 局部 structure（local-view only；非 consumer SSOT）。"""
         stage_keys = [stage.key for stage in self._stages]
         return {
             "stage_node_prefix": "stage_",

{langchain-agentx-python-1.6.4 → langchain-agentx-python-1.6.5}/langchain_agentx/workflow/patterns/parallelization.py

@@ -147,6 +147,11 @@ class ParallelizationWorkflow(BaseWorkflow):
                 scope_kind="parallel_item",
                 owner_workflow_id=self._workflow_id,
             )
+        yield RuntimeScopeBinding(
+            graph_key=self._aggregate.key,
+            scope_kind="aggregate",
+            owner_workflow_id=self._workflow_id,
+        )
 
     def build_graph(self) -> StateGraph:
         """构建并行拓扑。"""
@@ -183,6 +188,7 @@ class ParallelizationWorkflow(BaseWorkflow):
         return self._aggregator(item_results)
 
     def export_local_event_adapter_structure(self) -> dict:
+        """导出本 ParallelizationWorkflow 局部 structure（local-view only；非 consumer SSOT）。"""
         item_keys = [item.key for item in self._items]
         return {
             "parallel_node_prefix": "parallel_",

{langchain-agentx-python-1.6.4 → langchain-agentx-python-1.6.5}/langchain_agentx/workflow/patterns/routing.py

@@ -202,6 +202,7 @@ class RoutingWorkflow(BaseWorkflow):
         )
 
     def export_local_event_adapter_structure(self) -> dict:
+        """导出本 RoutingWorkflow 局部 structure（local-view only；非 consumer SSOT）。"""
         route_keys = list(self._routes.keys())
         return {
             "route_keys": route_keys,