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

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

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

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

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

{langchain-agentx-python-1.6.1 → langchain-agentx-python-1.6.4}/langchain_agentx/loop/graph/factory.py

@@ -388,6 +388,7 @@ class LoopGraphBuilder:
             model=model,
             schema_cache_namespace=session_id or "",
         )
+        self._sync_tool_policy_roots_from_workspace()
         from ...loop.prompt.tool_aware_sections import (
             EDIT_TOOL_NAME,
             build_tool_aware_prompt_sections,
@@ -1071,6 +1072,25 @@ class LoopGraphBuilder:
             write_roots=list(self._config.workspace.write_roots) or None,
         )
 
+    def _sync_tool_policy_roots_from_workspace(self) -> None:
+        """挂载 A：compile 后以 AgentLoopConfig.workspace 刷新 loader policy roots。"""
+        loader = self._services.loader
+        if loader is None:
+            return
+        from langchain_agentx.loop.permissions.policy_roots_sync import (
+            sync_tool_policy_roots_from_workspace,
+        )
+
+        extra_tools: list[Any] = []
+        loop_loader = getattr(self, "_loop_loader", None)
+        if loop_loader is not None:
+            extra_tools = list(loop_loader.registry.list())
+        sync_tool_policy_roots_from_workspace(
+            workspace=self._config.workspace,
+            loader=loader,
+            additional_tools=extra_tools,
+        )
+
     def _build_system_message(
         self,
         *,

langchain-agentx-python-1.6.4/langchain_agentx/loop/permissions/__init__.py

@@ -0,0 +1,11 @@
+"""loop/permissions — loop 侧权限协作者（policy 与 workspace 对齐等）。"""
+
+from langchain_agentx.loop.permissions.policy_roots_sync import (
+    PolicyRootsSynchronizer,
+    sync_tool_policy_roots_from_workspace,
+)
+
+__all__ = [
+    "PolicyRootsSynchronizer",
+    "sync_tool_policy_roots_from_workspace",
+]

langchain-agentx-python-1.6.4/langchain_agentx/loop/permissions/policy_roots_sync.py

@@ -0,0 +1,94 @@
+"""
+policy_roots_sync.py — workspace 静态 roots → ToolPolicyConfig 同步
+
+职责：
+    以 AgentStateConfig 为 SSOT，刷新 loader 上 ToolPolicyConfig 的 read/write_roots；
+    替换而非 union，保留 deny_globs / ask_globs / project_memory_layout 等字段。
+
+链路位置：
+    挂载 A LoopGraphBuilder compile · 挂载 B SubagentOrchestrator spawn · 挂载 C derive 后
+
+当前裁剪范围：
+    不含 grant 动态 roots；不修改 WorkspaceBoundary 构造逻辑。
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import TYPE_CHECKING, Any, Iterable
+
+from langchain_agentx.loop.config.loop_config import AgentStateConfig
+from langchain_agentx.tool_runtime.policy import DefaultPolicyEngine, ToolPolicyConfig
+
+if TYPE_CHECKING:
+    from langchain_agentx.tool_runtime.loader import ToolRuntimeLoader
+    from langchain_agentx.tool_runtime.process_loader import ProcessLoader
+
+
+def _resolve_base_policy_config(process: ProcessLoader) -> ToolPolicyConfig:
+    raw = process.policy_config
+    if isinstance(raw, ToolPolicyConfig):
+        return raw
+    policy = process.policy
+    if isinstance(policy, DefaultPolicyEngine):
+        return policy._config
+    return ToolPolicyConfig()
+
+
+class PolicyRootsSynchronizer:
+    """将 workspace 静态 read/write roots 写入 loader policy（不放宽）。"""
+
+    def sync(
+        self,
+        *,
+        workspace: AgentStateConfig,
+        loader: ToolRuntimeLoader,
+        additional_tools: Iterable[Any] = (),
+    ) -> ToolPolicyConfig:
+        process = loader.process_loader
+        base = _resolve_base_policy_config(process)
+        read_roots = (
+            [str(p) for p in workspace.read_roots]
+            if workspace.read_roots
+            else list(base.read_roots)
+        )
+        write_roots = (
+            [str(p) for p in workspace.write_roots]
+            if workspace.write_roots
+            else list(base.write_roots)
+        )
+        updated = replace(base, read_roots=read_roots, write_roots=write_roots)
+        process.apply_policy_config(updated)
+        self._rebind_registered_tools(loader, additional_tools=additional_tools)
+        return updated
+
+    @staticmethod
+    def _rebind_registered_tools(
+        loader: ToolRuntimeLoader,
+        *,
+        additional_tools: Iterable[Any] = (),
+    ) -> None:
+        policy = loader.policy
+        if policy is None:
+            return
+        tools = list(loader.registry.list()) + list(additional_tools)
+        for tool in tools:
+            if getattr(tool, "_policy", None) is not None:
+                tool._policy = policy
+
+
+def sync_tool_policy_roots_from_workspace(
+    *,
+    workspace: AgentStateConfig,
+    loader: ToolRuntimeLoader,
+    additional_tools: Iterable[Any] = (),
+) -> ToolPolicyConfig:
+    """薄封装：委托 PolicyRootsSynchronizer.sync。"""
+    return PolicyRootsSynchronizer().sync(
+        workspace=workspace,
+        loader=loader,
+        additional_tools=additional_tools,
+    )
+
+
+__all__ = ["PolicyRootsSynchronizer", "sync_tool_policy_roots_from_workspace"]

{langchain-agentx-python-1.6.1 → langchain-agentx-python-1.6.4}/langchain_agentx/loop/runtime/context_factory.py

@@ -63,7 +63,11 @@ class RuntimeContextFactory:
         """
         # 模型继承：override > config.default_model > parent_ctx.model
         config_model = getattr(subagent_config, "default_model", None)
-        resolved_model = overrides.model or config_model or parent_ctx.model
+        resolved_model = (
+            overrides.model
+            or config_model
+            or getattr(parent_ctx, "model", None)
+        )
 
         # max_steps 继承：override > config.default_max_steps > None
         config_max_steps = getattr(subagent_config, "default_max_steps", None)
@@ -110,6 +114,23 @@ class RuntimeContextFactory:
             )
         )
 
+        view = getattr(parent_ctx, "boundary_view", None)
+        boundary = getattr(view, "boundary", None) if view is not None else None
+        inherited_read: tuple[str, ...] = ()
+        inherited_write: tuple[str, ...] = ()
+        if boundary is not None:
+            inherited_read = tuple(str(p) for p in boundary.initial_read_roots)
+            inherited_write = tuple(str(p) for p in boundary.initial_write_roots)
+
+        enable_dynamic_root_grant = False
+        runnable = getattr(parent_ctx, "runnable_config", None)
+        if isinstance(runnable, dict):
+            loop_config = (runnable.get("configurable") or {}).get("loop_config")
+            if loop_config is not None:
+                enable_dynamic_root_grant = bool(
+                    getattr(loop_config, "enable_dynamic_root_grant", False)
+                )
+
         # 构建嵌套子结构 (Phase 3: 新的 frozen AgentLoopConfig)
         # parent_agent_id 回退机制：对齐 CC toolUseContext.agentId ?? getSessionId()
         # 当父 ctx 没有 agent_id 时（如某些初始化路径），生成回退值而非让后续验证失败
@@ -139,6 +160,10 @@ class RuntimeContextFactory:
             workspace=AgentStateConfig(
                 workspace_root=workspace_cfg.workspace_root,
                 agent_home_segment=workspace_cfg.agent_home_segment,
+                read_roots=inherited_read,
+                write_roots=inherited_write,
+                runtime_cwd=resolved_cwd,
+                enable_dynamic_root_grant=enable_dynamic_root_grant,
             ),
             trace=TraceConfig(
                 enabled=bool(getattr(parent_ctx, "trace_enabled", True)),

{langchain-agentx-python-1.6.1 → langchain-agentx-python-1.6.4}/langchain_agentx/loop/subagent/graph.py

@@ -54,6 +54,19 @@ def create_subagent_graph(
     if model is None:
         raise ValueError("model is required for create_subagent_graph")
 
+    from langchain_agentx.loop.permissions.policy_roots_sync import (
+        sync_tool_policy_roots_from_workspace,
+    )
+    from langchain_agentx.tool_runtime.loader import ToolRuntimeLoader
+
+    if ctx.boundary_snapshot is not None and isinstance(loader, ToolRuntimeLoader):
+        sync_tool_policy_roots_from_workspace(
+            workspace=ctx.boundary_snapshot.to_agent_state_config(
+                agent_home_segment=ctx.agent_home_segment,
+            ),
+            loader=loader,
+        )
+
     import uuid as _uuid
 
     # 显式 session_id：避免子图构图时生成 ephemeral id 刷屏日志，并与 ctx.agent_id 对齐便于追溯

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

@@ -237,6 +237,19 @@ class BaseWorkflow(ABC):
             return ()
         return source.iter_child_workflows()
 
+    def iter_nested_workflow_bindings(self) -> Iterable[tuple[str, BaseWorkflow]]:
+        """返回 (graph_node_key, child_workflow) 嵌套绑定（wrapper 沿 delegate 解析）。"""
+        source = self._resolve_structure_delegate_workflow()
+        if source is self:
+            return ()
+        return source.iter_nested_workflow_bindings()
+
+    def iter_runtime_scope_bindings(self) -> Iterable[Any]:
+        source = self._resolve_structure_delegate_workflow()
+        if source is self:
+            return ()
+        return source.iter_runtime_scope_bindings()
+
     def _get_workflow_loop_executor(self) -> WorkflowAgentLoopExecutor:
         """返回 workflow loop 执行器（factory-first 与 invocation-first 共用）。"""
         if self._workflow_loop_executor is None:
@@ -284,22 +297,33 @@ class BaseWorkflow(ABC):
         self._validate_manual_ui_catalog_if_needed()
         return self.build_graph().compile()
 
+    def export_local_event_adapter_structure(self) -> dict:
+        """导出本 workflow 实例的局部 structure（不沿 delegate 解析）。"""
+        return {}
+
     def export_event_adapter_structure(self) -> dict:
         """导出 event adapter 所需的 workflow_structure（wrapper 沿 delegate 解析）。"""
         source = self._resolve_structure_delegate_workflow()
         if source is self:
-            return {}
+            return self.export_local_event_adapter_structure()
         return source.export_event_adapter_structure()
 
     def _build_effective_event_adapter_structure(
         self,
         workflow_structure: dict | None,
     ) -> dict:
-        """合并 derived + caller override，并对 Structured Workflow 做 fail-fast 校验。"""
+        """合并 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_structure = self.export_event_adapter_structure()
-        effective_structure = {**derived_structure, **(workflow_structure or {})}
+        derived = WorkflowStructureCollector().collect(self)
+        effective_structure = merge_scoped_structure_with_override(
+            derived,
+            workflow_structure,
+        )
         validate_event_adapter_structure(self, effective_structure)
         return effective_structure
 

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

@@ -29,7 +29,9 @@ from .types import (
     PUBLIC_WORKFLOW_EVENT_TYPES,
 )
 from .stack import WorkflowStack
-from .depth_resolver import DepthResolver
+from .depth_resolver import DepthResolver, StackAlignment
+from .scope_resolver import WorkflowScopeResolver
+from langchain_agentx.workflow.structure_errors import WorkflowScopeResolutionError
 from .adapter import WorkflowEventAdapter
 
 __all__ = [
@@ -48,5 +50,8 @@ __all__ = [
     "WorkflowAdapterState",
     "WorkflowStack",
     "DepthResolver",
+    "StackAlignment",
+    "WorkflowScopeResolutionError",
+    "WorkflowScopeResolver",
     "WorkflowEventAdapter",
 ]

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

@@ -5,7 +5,7 @@ adapter.py — Workflow 事件适配器主控制器
     - 协调各 Handler 处理事件
     - 维护 WorkflowAdapterState 状态机
     - 统一事件产出接口
-    - 处理嵌套子图的 push/pop 逻辑
+    - 编排嵌套栈对齐（DepthResolver 推断 → WorkflowStack.reconcile_to_depth）
 
 链路位置：
     - Layer 3: Workflow 事件适配器
@@ -25,6 +25,7 @@ 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.display_enricher import WorkflowDisplayEnricher
 from langchain_agentx.workflow.event_adapter.handlers import (
     StageHandler,
@@ -50,7 +51,7 @@ class WorkflowEventAdapter:
         - consume() 方法为同步接口，返回 List[WorkflowEvent]
         - 所有事件必须是成对的（start/end），或单次性的
         - 配置驱动节点名识别规则，不硬编码
-        - push 基于"子图启动事件"判断（node == "" and ns.endswith("|")）
+        - 嵌套栈对齐：DepthResolver.derive_stack_alignment → WorkflowStack.reconcile_to_depth
     """
 
     def __init__(
@@ -65,13 +66,11 @@ class WorkflowEventAdapter:
             workflow_id: Workflow 标识符
             session_id: 会话 ID（可选）
             config: 配置字典，可包含：
-                - stage_node_prefix: stage 节点前缀（默认 "stage_"）
-                - parallel_node_prefix: parallel 节点前缀（默认 "parallel_"）
                 - aggregate_key / aggregate_node_name: 聚合节点名
-                - route_node_prefix: route 旧前缀（默认 "route_"，仅兼容）
                 - route_keys: 路由分支 key 列表（新语义，精确匹配）
                 - stage_keys / stage_index_by_key: stage 顺序映射
                 - parallel_item_keys / item_index_by_key: parallel item 顺序映射
+                - stage_node_prefix / parallel_node_prefix / route_node_prefix: 仅 structure export 保留字段，handler 不匹配前缀
                 - total_stages / total_parallel_items: 旧字段 fallback
         """
         self.workflow_id = workflow_id
@@ -91,9 +90,16 @@ class WorkflowEventAdapter:
         # 协作者（Phase 1：不包含 Orchestrator）
         self._stack = WorkflowStack(workflow_id)
         self._depth_resolver = DepthResolver()
-        self._stage_handler = StageHandler(self.state, self._stack, self.config)
-        self._parallel_handler = ParallelHandler(self.state, self._stack, self.config)
-        self._route_handler = RouteHandler(self.state, self._stack, self.config)
+        self._scope_resolver = WorkflowScopeResolver(self.config, self._stack)
+        self._stage_handler = StageHandler(
+            self.state, self._stack, self._scope_resolver, self.config
+        )
+        self._parallel_handler = ParallelHandler(
+            self.state, self._stack, self._scope_resolver, self.config
+        )
+        self._route_handler = RouteHandler(
+            self.state, self._stack, self._scope_resolver, self.config
+        )
 
         # 初始化状态
         self.state.root_workflow_id = workflow_id
@@ -117,31 +123,8 @@ class WorkflowEventAdapter:
         metadata = event.get("metadata", {})
         node = metadata.get("langgraph_node", "")
 
-        # === 嵌套子图检测（v2.5 修订）===
-        # 使用 "node == "" 守卫 + 深度差判断 push/pop"
-        is_subgraph_start = self._depth_resolver.is_subgraph_entry_event(event)
-
-        if is_subgraph_start:
-            # 进入子图：push 一次
-            child_id = self._depth_resolver.extract_child_workflow_id_from_parent(event)
-            if child_id:
-                # v2.5 修订：pattern 延迟填充，push 时为空
-                self._stack.push(child_id, pattern="")
-                events.append(self._build_event(
-                    WorkflowEventType.SUBWORKFLOW_START,
-                    {"child_workflow_id": child_id}
-                ))
-
-        # 弹栈逻辑：子图结束（ns 不再以 | 结尾的空 node 事件）
-        elif event_type == "on_chain_end" and node == "":
-            ns = metadata.get("langgraph_checkpoint_ns", "")
-            # ns 不以 | 结尾且栈非空表示离开子图
-            if not ns.endswith("|") and self._stack.current_depth > 0:
-                events.append(self._build_event(
-                    WorkflowEventType.SUBWORKFLOW_END,
-                    {"child_workflow_id": self._stack.current_workflow_id}
-                ))
-                self._stack.pop()
+        # === 嵌套栈与 scope：按 checkpoint_ns 对齐（兼容 compiled 子图无空 node 启动事件）===
+        events.extend(self._reconcile_stack_from_event(event))
 
         # === Workflow 生命周期事件 ===
         # 根 workflow 生命周期只在根层空 node 上发出；局部 node 失败交给各 handler。
@@ -197,11 +180,13 @@ class WorkflowEventAdapter:
 
         # === 后处理：回填 workflow_path 和其他字段 ===
         for e in events:
-            if not e.workflow_path:  # Handler 产出的事件 path 为空
+            if not e.workflow_path:
                 e.workflow_path = self._stack.build_path()
-            e.workflow_depth = self._stack.current_depth
+            # SUBWORKFLOW_END 在 pop 前已绑定子 scope 的 path/depth/parent，不得覆盖
+            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.parent_workflow_id = self._stack.parent_workflow_id
             self._enrich_lifecycle_display(e)
 
         # === 更新序列号 ===
@@ -215,6 +200,46 @@ class WorkflowEventAdapter:
 
         return events
 
+    def _reconcile_stack_from_event(self, event: Dict[str, Any]) -> List[WorkflowEvent]:
+        """编排：推断栈对齐目标 → reconcile → 产出 SUBWORKFLOW_* 事件。"""
+        events: List[WorkflowEvent] = []
+        previous_depth = self._stack.current_depth
+        previous_child_id = (
+            self._stack.current_workflow_id if previous_depth > 0 else None
+        )
+        alignment = self._depth_resolver.derive_stack_alignment(event)
+        target_depth = alignment.target_depth
+
+        exiting_nested = target_depth < previous_depth and previous_child_id is not None
+        child_path: str | None = None
+        child_depth: int | None = None
+        child_parent_id: str | None = None
+        if exiting_nested:
+            child_path = self._stack.build_path()
+            child_depth = self._stack.current_depth
+            child_parent_id = self._stack.parent_workflow_id
+
+        self._stack.reconcile_to_depth(alignment.target_depth, alignment.segment_ids)
+
+        new_depth = self._stack.current_depth
+        if new_depth > previous_depth:
+            events.append(self._build_event(
+                WorkflowEventType.SUBWORKFLOW_START,
+                {"child_workflow_id": self._stack.current_workflow_id},
+            ))
+        elif exiting_nested:
+            events.append(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,
+            ))
+
+        return events
+
     def _build_event(
         self,
         event_type: WorkflowEventType,

langchain-agentx-python-1.6.4/langchain_agentx/workflow/event_adapter/depth_resolver.py

@@ -0,0 +1,77 @@
+"""
+depth_resolver.py — LangGraph 嵌套深度解析器（纯推断，不改栈）
+
+职责：
+    - 从 LangGraph 事件 metadata 推导栈对齐目标（depth + segment_ids）
+    - 禁止改 WorkflowStack；栈变更唯一入口为 WorkflowStack.reconcile_to_depth
+
+链路位置：
+    - Layer 3: Workflow 事件适配器
+    - 被 WorkflowEventAdapter._reconcile_stack_from_event 编排调用
+
+当前裁剪范围：
+    - 仅支持 LangGraph v2 事件格式（langgraph_checkpoint_ns | 分段）
+    - 不支持 configurable.workflow_path（经验证不存在于事件 metadata）
+
+契约表与 snapshot 见 test_depth_resolver.py（LangGraph 事件变样时只改本模块 + 测试表）。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class StackAlignment:
+    """由 LangGraph 事件 metadata 推导的栈对齐目标（纯数据，无副作用）。"""
+
+    target_depth: int
+    segment_ids: list[str]
+
+
+class DepthResolver:
+    """LangGraph 嵌套深度解析器（纯推断）。
+
+    生产热路径：
+        derive_stack_alignment(event) → WorkflowStack.reconcile_to_depth(...)
+    """
+
+    def derive_stack_alignment(self, event: dict[str, Any]) -> StackAlignment:
+        """从事件 metadata 推导栈对齐目标（depth + graph_node segment_ids）。"""
+        metadata = event.get("metadata", {})
+        checkpoint_ns = metadata.get("langgraph_checkpoint_ns", "")
+        return StackAlignment(
+            target_depth=self.derive_target_depth(event),
+            segment_ids=self.segment_graph_node_ids(checkpoint_ns),
+        )
+
+    def derive_target_depth(self, event: dict[str, Any]) -> int:
+        """根据 checkpoint_ns 与 langgraph_node 推导嵌套栈目标深度。
+
+        与真实 LangGraph 嵌套 compiled 子图对齐：内层 parallel item 事件
+        通常没有 node=="" 的子图启动事件，需靠 ns 分段 + node 联合推断。
+        """
+        metadata = event.get("metadata", {})
+        node = metadata.get("langgraph_node", "")
+        ns = metadata.get("langgraph_checkpoint_ns", "")
+        segments = [segment for segment in ns.split("|") if segment]
+        if not segments:
+            return 0
+        if node == "":
+            return len(segments)
+        return max(0, len(segments) - 1)
+
+    def segment_graph_node_ids(self, checkpoint_ns: str) -> list[str]:
+        """从 checkpoint_ns 提取各层 graph 节点名（不含 uuid）。"""
+        return [
+            segment.split(":")[0]
+            for segment in checkpoint_ns.split("|")
+            if segment
+        ]
+
+
+__all__ = [
+    "DepthResolver",
+    "StackAlignment",
+]