langchain-agentx-python 1.9.5__tar.gz → 1.9.7__tar.gz

{langchain-agentx-python-1.9.5/langchain_agentx_python.egg-info → langchain-agentx-python-1.9.7}/PKG-INFO

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

{langchain-agentx-python-1.9.5 → langchain-agentx-python-1.9.7}/langchain_agentx/__init__.py

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

{langchain-agentx-python-1.9.5 → langchain-agentx-python-1.9.7}/langchain_agentx/observability/events/workflow_aware_event_adapter.py

@@ -12,14 +12,15 @@ workflow_aware_event_adapter.py — Workflow 场景下的统一公共事件适
 
 当前裁剪范围：
     - 只桥接 workflow + agent 事件到统一公共流
+    - adapt()：单轨兼容，raw 流级异常仍 re-raise
+    - adapt_isolated()：Phase 2 真双轨 L1，逐事件投影异常 swallow
     - outward finalize：正常耗尽 + 内层流异常（显示层补丁）；aclose/GeneratorExit/早退不 yield
-    - finalize() 仍为同步 bookkeeping；是否 outward 由 emit_finalize 门控
-    - 不引入工厂入口；工厂在后续 Phase 处理
 """
 
 from __future__ import annotations
 
 import asyncio
+import logging
 from typing import Any, AsyncIterator, Dict, Optional
 
 from langchain_agentx.observability.events.agent_event_projector import (
@@ -31,6 +32,10 @@ from langchain_agentx.observability.events.workflow_event_mapper import (
     WorkflowEventMapper,
 )
 from langchain_agentx.workflow.event_adapter.adapter import WorkflowEventAdapter
+from langchain_agentx.workflow.projection_isolation import ProjectionIsolationState
+from langchain_agentx.workflow.structure_errors import WorkflowScopeResolutionError
+
+logger = logging.getLogger(__name__)
 
 
 class WorkflowAwareLangGraphEventAdapter:
@@ -57,35 +62,93 @@ class WorkflowAwareLangGraphEventAdapter:
     async def adapt(
         self, events: AsyncIterator[Dict[str, Any]]
     ) -> AsyncIterator[LangchainAgentEvent]:
+        """单轨兼容：raw 流级异常仍 re-raise（显示层 finalize 补丁）。"""
+        async for event in self._adapt_legacy_raise(events):
+            yield event
+
+    async def adapt_isolated(
+        self,
+        events: AsyncIterator[Dict[str, Any]],
+        *,
+        projection_state: ProjectionIsolationState | None = None,
+    ) -> AsyncIterator[LangchainAgentEvent]:
+        """L1 观测：投影异常 swallow（白名单），不 re-raise 掐 raw 消费循环。"""
+        state = projection_state or ProjectionIsolationState()
+        emit_finalize = False
+        try:
+            async for raw_event in events:
+                try:
+                    async for mapped in self._project_raw_event(raw_event):
+                        yield mapped
+                except (GeneratorExit, asyncio.CancelledError):
+                    raise
+                except (WorkflowScopeResolutionError, ValueError) as exc:
+                    state.record(exc)
+                    logger.warning(
+                        "workflow projection degraded (isolated): %s",
+                        exc,
+                        exc_info=True,
+                    )
+                    continue
+                except BaseException as exc:
+                    if isinstance(exc, (KeyboardInterrupt, SystemExit)):
+                        raise
+                    state.record(exc)
+                    logger.warning(
+                        "workflow projection degraded (isolated): %s",
+                        exc,
+                        exc_info=True,
+                    )
+                    continue
+            emit_finalize = True
+        finally:
+            finalized = self._workflow_adapter.finalize()
+            if emit_finalize:
+                for workflow_event in finalized:
+                    mapped = self._workflow_mapper.map(workflow_event)
+                    if mapped is not None:
+                        yield mapped
+
+    async def _project_raw_event(
+        self, raw_event: Dict[str, Any]
+    ) -> AsyncIterator[LangchainAgentEvent]:
+        root_session_id = self._extract_session_id(raw_event)
+        if root_session_id and self._should_update_root_fallback(
+            root_session_id,
+            self.graph_name,
+        ):
+            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_loop_session_id_for_event(
+            raw_event
+        )
+        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
+
+    async def _adapt_legacy_raise(
+        self, events: AsyncIterator[Dict[str, Any]]
+    ) -> AsyncIterator[LangchainAgentEvent]:
+        """Legacy adapt 路径：内层流异常仍 re-raise（单轨兼容）。"""
         emit_finalize = False
         try:
             try:
                 async for raw_event in events:
-                    root_session_id = self._extract_session_id(raw_event)
-                    if root_session_id and self._should_update_root_fallback(
-                        root_session_id,
-                        self.graph_name,
-                    ):
-                        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_loop_session_id_for_event(raw_event)
-                    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
+                    async for mapped in self._project_raw_event(raw_event):
+                        yield mapped
                 emit_finalize = True
             except (GeneratorExit, asyncio.CancelledError):
                 raise
             except BaseException:
-                # 显示层补丁：内层流异常仍 outward 补 workflow-end（非终态权威）
                 emit_finalize = True
                 raise
         finally:
@@ -97,7 +160,7 @@ class WorkflowAwareLangGraphEventAdapter:
                         yield mapped
 
     def _sync_workflow_session_id(self, raw_event: Dict[str, Any]) -> None:
-        """Deprecated: session 同步已内联至 adapt()（先 reconcile stack 再派生 loop session）。"""
+        """Deprecated: session 同步已内联至 _project_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)

{langchain-agentx-python-1.9.5 → langchain-agentx-python-1.9.7}/langchain_agentx/workflow/base.py

@@ -32,9 +32,8 @@ import logging
 import warnings
 from abc import ABC, abstractmethod
 from pathlib import Path
-from collections.abc import Iterable
-from collections.abc import Iterable
-from typing import Any, AsyncIterator
+from collections.abc import AsyncIterator, Iterable
+from typing import Any
 
 from .display_resolver import (
     CatalogBackedWorkflowDisplayResolver,
@@ -331,8 +330,7 @@ class BaseWorkflow(ABC):
     ) -> dict:
         """合并 derived scoped structure + caller override，并对 Structured Workflow 做 fail-fast 校验。
 
-        内部委托 ``collect_effective_structure_contract()``；保留此方法供
-        ``astream_langchain_events()`` 与既有测试调用。
+        内部委托 ``collect_effective_structure_contract()``；供 ``run_observe()`` 等入口调用。
         """
         from .structure_collector import collect_effective_structure_contract
 
@@ -585,7 +583,8 @@ class BaseWorkflow(ABC):
                 parent_workflow=parent_workflow,
             )
             self._active_run_config = effective_config
-            driver = GraphStreamDriver()
+            capture_driver = kwargs.pop("_capture_driver", None)
+            driver = capture_driver if capture_driver is not None else GraphStreamDriver()
 
             async for event in driver.run(
                 graph,
@@ -608,44 +607,22 @@ class BaseWorkflow(ABC):
                     finally:
                         self._active_run_config = previous_active
 
-    async def astream_langchain_events(
+    def _build_langgraph_adapter_config(
         self,
-        initial_state: dict,
         *,
-        parent_workflow: "BaseWorkflow | None" = None,
         adapter_config: dict | None = None,
         workflow_structure: dict | None = None,
         ui_catalog: WorkflowUiCatalog | None = None,
         display_resolver: WorkflowDisplayResolver | None = None,
-        run_config: RunnableConfig | None = None,
-        **kwargs,
-    ) -> AsyncIterator[Any]:
-        """流式执行 Workflow，返回统一的 LangchainAgentEvent 公共事件流。
-
-        这是 Workflow 对外唯一的结构化事件流入口。
-
-        Args:
-            initial_state: 初始状态
-            parent_workflow: 父 Workflow
-            adapter_config: workflow-aware adapter 配置（workflow_adapter 命名空间）
-            workflow_structure: 结构信息（如 total_stages）
-            ui_catalog: 本次调用覆盖的 Workflow UI 目录（缺省时使用实例级 catalog）
-            display_resolver: 本次调用覆盖的 display 解析器（缺省时使用实例级 resolver）
-            run_config: LangGraph 运行配置，透传至 astream_events
-            **kwargs: 传递给 astream_events 的其他参数
-
-        Yields:
-            LangchainAgentEvent: workflow 与 agent 统一的公共事件协议
-        """
-        from langchain_agentx.observability.events.factory import (
-            create_langgraph_event_adapter,
-        )
-
+    ) -> dict[str, Any]:
+        """构建 workflow-aware LangGraph adapter 配置（run_observe 共用）。"""
         config = dict(adapter_config or {})
         workflow_adapter_config = config.get("workflow_adapter")
         if not isinstance(workflow_adapter_config, dict):
             workflow_adapter_config = {}
-        effective_structure = self._build_effective_event_adapter_structure(workflow_structure)
+        effective_structure = self._build_effective_event_adapter_structure(
+            workflow_structure
+        )
         if effective_structure:
             workflow_adapter_config = {
                 **workflow_adapter_config,
@@ -662,23 +639,86 @@ class BaseWorkflow(ABC):
         if effective_display_resolver is not None:
             workflow_adapter_config["display_resolver"] = effective_display_resolver
         config["workflow_adapter"] = workflow_adapter_config
+        return config
+
+    def run_observe(
+        self,
+        initial_state: dict,
+        *,
+        parent_workflow: "BaseWorkflow | None" = None,
+        adapter_config: dict | None = None,
+        workflow_structure: dict | None = None,
+        ui_catalog: WorkflowUiCatalog | None = None,
+        display_resolver: WorkflowDisplayResolver | None = None,
+        run_config: RunnableConfig | None = None,
+        **kwargs: Any,
+    ):
+        """Phase 2 真双轨入口：返回 L0 outcome Task + L1 观测流（F4 producer-consumer）。
+
+        消费契约：
+            - L1：``async for event in handle.events``（SSE / 缓冲投影）
+            - L0：``await handle.outcome``（execution authority）
+            - 须**并发或顺序消费 events** 以排空 raw queue；仅 ``await outcome`` 且不读
+              events 会在有界队列上阻塞 L0 drain。
+            - 仅需程序化 L0 结果时用 ``run_with_outcome()``（内部会 drain events）。
+
+        structure fail-fast 在启动 L0 drain 之前执行（``_build_langgraph_adapter_config``）。
+        """
+        from langchain_agentx.workflow.run_session import WorkflowRunSession
 
-        adapter = create_langgraph_event_adapter(
-            mode="workflow",
-            graph_name=self._workflow_id,
-            config=config,
+        self._build_langgraph_adapter_config(
+            adapter_config=adapter_config,
+            workflow_structure=workflow_structure,
+            ui_catalog=ui_catalog,
+            display_resolver=display_resolver,
         )
 
-        async for event in adapter.adapt(
-            self.astream_events(
-                initial_state,
-                parent_workflow=parent_workflow,
-                run_config=run_config,
-                **kwargs,
-            )
-        ):
-            yield event
+        astream_kwargs = {
+            key: value
+            for key, value in kwargs.items()
+            if key not in {"adapter_config", "workflow_structure", "ui_catalog", "display_resolver", "run_config"}
+        }
+        session = WorkflowRunSession(
+            self,
+            initial_state,
+            parent_workflow=parent_workflow,
+            adapter_config=adapter_config,
+            workflow_structure=workflow_structure,
+            ui_catalog=ui_catalog,
+            display_resolver=display_resolver,
+            run_config=run_config,
+            astream_kwargs=astream_kwargs,
+        )
+        return session.start()
+
+    async def run_with_outcome(
+        self,
+        initial_state: dict,
+        *,
+        parent_workflow: "BaseWorkflow | None" = None,
+        adapter_config: dict | None = None,
+        workflow_structure: dict | None = None,
+        ui_catalog: WorkflowUiCatalog | None = None,
+        display_resolver: WorkflowDisplayResolver | None = None,
+        run_config: RunnableConfig | None = None,
+        **kwargs: Any,
+    ):
+        """程序化 L0 authority： drain 完毕并消费观测轨以释放 raw queue。"""
+        from langchain_agentx.workflow.run_outcome import WorkflowRunOutcome
 
+        handle = self.run_observe(
+            initial_state,
+            parent_workflow=parent_workflow,
+            adapter_config=adapter_config,
+            workflow_structure=workflow_structure,
+            ui_catalog=ui_catalog,
+            display_resolver=display_resolver,
+            run_config=run_config,
+            **kwargs,
+        )
+        async for _ in handle.events:
+            pass
+        return await handle.outcome
 
     async def _emit_workflow_end_best_effort(self, ctx: dict) -> None:
         """WORKFLOW_END 降级为 best-effort：失败不阻断 drain / config 恢复。"""

{langchain-agentx-python-1.9.5 → langchain-agentx-python-1.9.7}/langchain_agentx/workflow/catalog_registry.py

@@ -8,7 +8,7 @@ catalog_registry.py — Workflow UI catalog 注册表
 
 链路位置：
     - Layer 3: workflow 领域 UI 语义层
-    - BaseWorkflow.compile / astream_langchain_events 前收集 → display resolver 按 ctx.workflow_id 路由
+    - BaseWorkflow.compile / run_observe 前收集 → display resolver 按 ctx.workflow_id 路由
 
 当前裁剪范围：
     - 仅静态 catalog 收集与只读 lookup，不负责运行期 display 计算

{langchain-agentx-python-1.9.5 → langchain-agentx-python-1.9.7}/langchain_agentx/workflow/event_adapter/depth_resolver.py

@@ -4,7 +4,7 @@ depth_resolver.py — LangGraph 嵌套深度解析器（纯推断，不改栈）
 职责：
     - 从 LangGraph 事件 metadata 推导栈对齐目标（depth + segment_ids）
     - 禁止改 WorkflowStack；栈变更唯一入口为 WorkflowStack.reconcile_to_depth
-    - 过滤 Agent loop 内部 technical 节点（tools / model），不抬升为 public scope path
+    - 过滤 Agent loop 内部 technical / hook 节点，不抬升为 public scope path
 
 链路位置：
     - Layer 3: Workflow 事件适配器
@@ -13,7 +13,7 @@ depth_resolver.py — LangGraph 嵌套深度解析器（纯推断，不改栈）
 当前裁剪范围：
     - 仅支持 LangGraph v2 事件格式（langgraph_checkpoint_ns | 分段）
     - 不支持 configurable.workflow_path（经验证不存在于事件 metadata）
-    - internal loop 节点过滤对齐 Doc31 §08.4.1（不校验 LangGraph synthetic/technical 节点）
+    - internal 集合对齐 F2（hook_node_names ∪ loop_end_nodes 默认 ∪ tools/model）
 
 契约表与 snapshot 见 test_depth_resolver.py（LangGraph 事件变样时只改本模块 + 测试表）。
 """
@@ -23,8 +23,27 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import Any
 
-# Agent loop graph 内部 technical 节点；不得进入 public runtime scope path（Doc31 §08.4.1）
-LANGGRAPH_INTERNAL_LOOP_NODE_NAMES = frozenset({"tools", "model"})
+# F2 冻结：与 agent_event_projector 默认 hook_node_names ∪ loop_end_nodes ∪ {tools, model}
+_LANGGRAPH_INTERNAL_HOOK_NODE_NAMES = frozenset(
+    {
+        "hook_loop_start",
+        "hook_before_model",
+        "hook_after_model",
+        "hook_stop",
+        "hook_loop_end",
+    }
+)
+_LANGGRAPH_INTERNAL_LOOP_END_NODE_NAMES = frozenset(
+    {
+        "loop_controller",
+        "prune_and_compress",
+    }
+)
+LANGGRAPH_INTERNAL_LOOP_NODE_NAMES = (
+    frozenset({"tools", "model"})
+    | _LANGGRAPH_INTERNAL_HOOK_NODE_NAMES
+    | _LANGGRAPH_INTERNAL_LOOP_END_NODE_NAMES
+)
 
 
 @dataclass(frozen=True)
@@ -56,7 +75,7 @@ class DepthResolver:
 
         与真实 LangGraph 嵌套 compiled 子图对齐：内层 parallel item 事件
         通常没有 node=="" 的子图启动事件，需靠 ns 分段 + node 联合推断。
-        Agent loop 内 tools/model 节点对齐到最近 public scope，不额外 push 栈帧。
+        Agent loop 内 internal 节点对齐到最近 public scope，不额外 push 栈帧。
         """
         metadata = event.get("metadata", {})
         node = metadata.get("langgraph_node", "")

{langchain-agentx-python-1.9.5 → langchain-agentx-python-1.9.7}/langchain_agentx/workflow/event_adapter/scope_resolver.py

@@ -3,7 +3,8 @@ scope_resolver.py — Workflow event adapter active scope 解析
 
 职责：
     - 根据 WorkflowStack.build_path() 从 flat scopes[path] registry 解析当前 active scope
-    - depth>0 且 lookup miss 时硬失败（禁止静默回退 root）
+    - public orphan path miss 时 hard-fail
+    - internal 尾段 path miss 时 warn + registered ancestor 回退（A00 P-LOSSY / P-EXEC）
 
 链路位置：
     - Layer 3: Workflow 事件适配器
@@ -13,6 +14,7 @@ scope_resolver.py — Workflow event adapter active scope 解析
     - 仅 dict lookup，不扫描 workflow 实例或 graph
     - scope key 与 WorkflowStack.build_path() / RuntimeScopePath.key() 一致
     - legacy config 无 scopes 时由 root 字段合成仅含 root 的 registry
+    - 禁止 blanket root 兜底；无 registered 祖先时仍 raise
 """
 
 from __future__ import annotations
@@ -23,6 +25,7 @@ from typing import Any
 from langchain_agentx.workflow.runtime_scope_registry import resolve_effective_scopes
 from langchain_agentx.workflow.structure_errors import WorkflowScopeResolutionError
 
+from .depth_resolver import LANGGRAPH_INTERNAL_LOOP_NODE_NAMES
 from .stack import WorkflowStack
 
 logger = logging.getLogger(__name__)
@@ -32,6 +35,10 @@ _SCOPE_METADATA_FIELDS = frozenset(
 )
 
 
+def _path_tail_segment(scope_key: str) -> str:
+    return scope_key.rsplit(">", 1)[-1]
+
+
 class WorkflowScopeResolver:
     """按当前 workflow 栈路径从 flat scopes registry 解析 active structure scope。"""
 
@@ -73,16 +80,20 @@ class WorkflowScopeResolver:
             return entry
 
         self._record_scope_miss(scope_key)
-        detail_parts = [
-            f"path={scope_key!r}",
-            f"depth={self._stack.current_depth}",
-        ]
-        detail_parts.append(f"available_keys={sorted(self._scopes)!r}")
-        raise WorkflowScopeResolutionError(
-            "workflow scope miss: "
-            + " ".join(detail_parts)
-            + "; scopes registry has no entry for this runtime path"
-        )
+
+        if not self._is_internal_path_miss(scope_key):
+            raise self._build_scope_resolution_error(scope_key)
+
+        ancestor = self._nearest_registered_ancestor_entry()
+        if ancestor is not None:
+            logger.warning(
+                "workflow scope miss degraded to ancestor: path=%r ancestor=%r",
+                scope_key,
+                ancestor.get("scope_key"),
+            )
+            return ancestor
+
+        raise self._build_scope_resolution_error(scope_key)
 
     @staticmethod
     def _strip_scope_metadata(scope: dict[str, Any]) -> dict[str, Any]:
@@ -92,6 +103,35 @@ class WorkflowScopeResolver:
             if key not in _SCOPE_METADATA_FIELDS
         }
 
+    def _is_internal_path_miss(self, scope_key: str) -> bool:
+        """miss path 末段为 internal loop 节点 → 视为 internal 误抬，可降级。"""
+        if ">" not in scope_key:
+            return False
+        return _path_tail_segment(scope_key) in LANGGRAPH_INTERNAL_LOOP_NODE_NAMES
+
+    def _nearest_registered_ancestor_entry(self) -> dict[str, Any] | None:
+        """沿 build_path() 的 '>' 分段前缀向上 walk，返回首个 scope_entry_at 命中。"""
+        scope_key = self.current_scope_key()
+        parts = scope_key.split(">")
+        for depth in range(len(parts) - 1, 0, -1):
+            prefix = ">".join(parts[:depth])
+            entry = self.scope_entry_at(prefix)
+            if entry is not None:
+                return entry
+        return None
+
+    def _build_scope_resolution_error(self, scope_key: str) -> WorkflowScopeResolutionError:
+        detail_parts = [
+            f"path={scope_key!r}",
+            f"depth={self._stack.current_depth}",
+            f"available_keys={sorted(self._scopes)!r}",
+        ]
+        return WorkflowScopeResolutionError(
+            "workflow scope miss: "
+            + " ".join(detail_parts)
+            + "; scopes registry has no entry for this runtime path"
+        )
+
     def _record_scope_miss(self, scope_key: str) -> None:
         if scope_key in self._scope_misses:
             return

langchain-agentx-python-1.9.7/langchain_agentx/workflow/projection_isolation.py

@@ -0,0 +1,26 @@
+"""
+projection_isolation.py — L1 投影隔离状态（Phase 2 adapt_isolated）
+
+职责：
+    记录投影层降级与诊断；不参与 L0 authority 判定。
+
+链路位置：
+    WorkflowAwareLangGraphEventAdapter.adapt_isolated → WorkflowRunOutcome.projection_*
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ProjectionIsolationState:
+    degraded: bool = False
+    errors: list[str] = field(default_factory=list)
+
+    def record(self, exc: BaseException) -> None:
+        self.degraded = True
+        self.errors.append(str(exc))
+
+
+__all__ = ["ProjectionIsolationState"]

langchain-agentx-python-1.9.7/langchain_agentx/workflow/run_handle.py

@@ -0,0 +1,49 @@
+"""
+run_handle.py — Workflow 真双轨对外句柄（Phase 2）
+
+职责：
+    暴露 L0 outcome Task 与 L1 观测流；类型 SSOT 在 SDK，宿主薄封装转发。
+
+链路位置：
+    BaseWorkflow.run_observe() → stream_ui wrap_workflow_run / new_agent registry（Step 2+）
+
+当前裁剪范围：
+    F6：观测方 early break 不 cancel L0 drain；outcome Task 独立完成。
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import asyncio
+
+if TYPE_CHECKING:
+    from langchain_agentx.observability.events.agent_event_projector import (
+        LangchainAgentEvent,
+    )
+
+    from .run_outcome import WorkflowRunOutcome
+
+
+@dataclass
+class WorkflowRunHandle:
+    """真双轨句柄：authority 读 outcome；SSE/缓冲读 events。
+
+    消费契约（F4 producer-consumer）：
+        - ``events`` 与 ``outcome`` 由 ``WorkflowRunSession`` 的 L0/L1 双 task 驱动。
+        - 宿主须消费 ``events``（全量 drain 或投影边读边写），否则 L0 可能在有界
+          raw queue 上阻塞，``outcome`` 无法完成。
+        - F6：观测方 early break / aclose 不 cancel L0；仍应 ``await outcome`` 取 authority。
+        - 仅要 L0 结果时用 ``BaseWorkflow.run_with_outcome()``。
+    """
+
+    outcome: asyncio.Task[WorkflowRunOutcome]
+    events: AsyncIterator[LangchainAgentEvent]
+
+    async def await_outcome(self) -> WorkflowRunOutcome:
+        return await self.outcome
+
+
+__all__ = ["WorkflowRunHandle"]

langchain-agentx-python-1.9.7/langchain_agentx/workflow/run_outcome.py

@@ -0,0 +1,59 @@
+"""
+run_outcome.py — Workflow L0 execution authority outcome (Phase 2 SSOT)
+
+职责：
+    承载 GraphStreamDriver drain 后的 authority 字段；供 run_observe / run_with_outcome 返回。
+
+链路位置：
+    WorkflowRunSession L0 task finalize → 宿主 authority（stream_ui / new_agent Step 2+）
+
+当前裁剪范围：
+    F5 映射：execution_error = driver.result.final_error；graph_completed 不受 L1 degraded 改写。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from langchain_agentx.loop.stream.graph_driver import GraphStreamDriver
+from langchain_agentx.loop.stream.result import StreamDriverResult
+
+
+@dataclass
+class WorkflowRunOutcome:
+    """L0 authority SSOT — graph drain 结果，非 L1 投影流推断。"""
+
+    graph_completed: bool = False
+    graph_output: dict[str, Any] | None = None
+    execution_error: BaseException | None = None
+    projection_degraded: bool = False
+    projection_errors: list[str] = field(default_factory=list)
+    driver_result: StreamDriverResult | None = None
+
+
+def build_workflow_run_outcome(
+    driver: GraphStreamDriver,
+    *,
+    projection_degraded: bool = False,
+    projection_errors: list[str] | None = None,
+    l0_exc: BaseException | None = None,
+) -> WorkflowRunOutcome:
+    """F5：从 GraphStreamDriver.result 构建 authority outcome。"""
+    result = driver.result
+    execution_error = result.final_error
+    if execution_error is None and l0_exc is not None:
+        execution_error = l0_exc
+    return WorkflowRunOutcome(
+        graph_completed=result.graph_completed,
+        graph_output=(
+            dict(result.graph_output) if isinstance(result.graph_output, dict) else None
+        ),
+        execution_error=execution_error,
+        projection_degraded=projection_degraded,
+        projection_errors=list(projection_errors or []),
+        driver_result=result,
+    )
+
+
+__all__ = ["WorkflowRunOutcome", "build_workflow_run_outcome"]