langchain-agentx-python 2.3.9__py3-none-any.whl → 2.4.1__py3-none-any.whl

langchain_agentx/__init__.py

@@ -11,7 +11,7 @@ from langchain_agentx import create_loop_agent
 ```
 """
 
-__version__ = "2.3.9"
+__version__ = "2.4.1"
 
 from .mcp.call import McpToolCaller
 from .mcp.client_manager import McpClientManager, McpConnectedClient

langchain_agentx/loop/config/loop_config.py

@@ -136,6 +136,8 @@ class SubagentLinkage:
     subagent_type: str | None = None
     agent_depth: int = 0
     parent_agent_id: str | None = None
+    fork_from_parent: bool = False
+    """True = 当前子 loop 为 ForkA worker（会话继承 fork）；供 ToolExecutionContext / L1。"""
 
 
 @dataclass(frozen=True, init=False)

langchain_agentx/loop/graph/factory.py

@@ -312,7 +312,12 @@ def _flatten_config_for_runtime(config: AgentLoopConfig) -> _FlatLoopConfig:
         conversation_session_id=config.conversation_session_id,
         agent_id=config.agent_id,
         parent_agent_id=config.subagent.parent_agent_id,
-        agent_depth=config.agent_depth,
+        agent_depth=(
+            config.subagent.agent_depth
+            if config.subagent.is_subagent
+            else config.agent_depth
+        ),
+        fork_from_parent=bool(config.subagent.fork_from_parent),
         subagent_type=config.subagent.subagent_type,
         trace_enabled=config.trace.enabled,
         trace_persist=config.trace.persist,

langchain_agentx/loop/run_context.py

@@ -13,6 +13,8 @@ run_context.py — Workflow/Agent 结构化并发上下文（parent → child ca
     P1：reset 失败时在仍可见 owner 的 derived logical context 内 force-clear；
     宿主 detached ingest 用 create_task_with_copied_context / run_context_scope。
     nested Parallelization：child_contexts + 递归 cancel_tree；W4 可用 use_cancel_authority。
+    agent loop 登记：供 skill fork 同步桥 ``run_coroutine_threadsafe`` 解析父 loop
+    （ContextVar 在 ThreadPoolExecutor 上常丢失，故用进程级 stack）。
 """
 
 from __future__ import annotations
@@ -34,6 +36,111 @@ _current_run_context: ContextVar[Optional["RunContext"]] = ContextVar(
     "run_ctx", default=None
 )
 
+# 进程级父 agent loop / RunContext 栈：ThreadPoolExecutor worker 看不见 ContextVar，
+# 须 threadsafe 回父 loop（bug4）并恢复 owner 供 cancel 登记（skill-fork cancel orphan）。
+_agent_loop_lock = threading.Lock()
+_agent_loop_stack: list[asyncio.AbstractEventLoop] = []
+_agent_run_ctx_stack: list["RunContext"] = []
+
+
+def register_agent_loop(loop: asyncio.AbstractEventLoop) -> None:
+    """登记当前存活的 agent/session event loop（可嵌套；同 loop 可重复 push）。"""
+    with _agent_loop_lock:
+        _agent_loop_stack.append(loop)
+
+
+def unregister_agent_loop(loop: asyncio.AbstractEventLoop) -> None:
+    """弹出最近一次与 ``loop`` 相同的登记（LIFO；未见则 no-op）。"""
+    with _agent_loop_lock:
+        for index in range(len(_agent_loop_stack) - 1, -1, -1):
+            if _agent_loop_stack[index] is loop:
+                del _agent_loop_stack[index]
+                return
+
+
+def resolve_agent_loop(
+    *,
+    owner: RunContext | None = None,
+) -> asyncio.AbstractEventLoop | None:
+    """解析仍在跑的父 agent loop；优先 ``owner.root_task``，否则栈顶存活项。"""
+    if owner is not None:
+        try:
+            loop = owner.root_task.get_loop()
+            if not loop.is_closed() and loop.is_running():
+                return loop
+        except Exception:
+            pass
+    with _agent_loop_lock:
+        for loop in reversed(_agent_loop_stack):
+            try:
+                if not loop.is_closed() and loop.is_running():
+                    return loop
+            except Exception:
+                continue
+    return None
+
+
+def resolve_owner_run_context(
+    owner: RunContext | None = None,
+) -> RunContext | None:
+    """解析取消挂接用的 owner：显式参数 → ContextVar → 进程级 install 栈顶。"""
+    if owner is not None:
+        return owner
+    current = get_run_context()
+    if current is not None:
+        return current
+    with _agent_loop_lock:
+        if _agent_run_ctx_stack:
+            return _agent_run_ctx_stack[-1]
+    return None
+
+
+async def run_under_owner_run_context(
+    coro: Awaitable[T],
+    *,
+    owner: RunContext | None,
+) -> T:
+    """在指定 owner 的 ContextVar 下 await（threadsafe 桥恢复父 RunContext）。"""
+    if owner is None:
+        return await coro
+    if get_run_context() is owner:
+        return await coro
+    token = _current_run_context.set(owner)
+    try:
+        return await coro
+    finally:
+        _current_run_context.reset(token)
+
+
+@dataclass
+class SubagentConcurrencyGate:
+    """会话级并发子 Agent 计数（挂在 RunContext.cancel_authority 根上）。
+
+    Doc-37 C9 / Phase 2：独立于深度；无「总 spawn」帽。
+    """
+
+    _running: int = field(default=0, repr=False)
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+
+    def try_acquire(self, *, limit: int) -> bool:
+        if limit < 1:
+            return False
+        with self._lock:
+            if self._running >= limit:
+                return False
+            self._running += 1
+            return True
+
+    def release(self) -> None:
+        with self._lock:
+            if self._running > 0:
+                self._running -= 1
+
+    @property
+    def running(self) -> int:
+        with self._lock:
+            return self._running
+
 
 @dataclass
 class RunContext:
@@ -50,6 +157,28 @@ class RunContext:
     # D-EVT-6：宿主在 cancel_tree / killAll 时写入；finish 投影读取；缺省 unknown。
     # 取值：escape | workflow_stop | kill_agents | unknown；禁止从「是否有后台」猜测。
     cancel_source: str | None = None
+    # Phase 2：并发子 Agent 槽位；acquire/release 始终走 cancel_authority 根上的 gate。
+    subagent_concurrency: SubagentConcurrencyGate = field(
+        default_factory=SubagentConcurrencyGate, repr=False
+    )
+    # install 时若成功 register_agent_loop，记下以便 reset 精确 unregister（勿误弹外层）。
+    _registered_agent_loop: asyncio.AbstractEventLoop | None = field(
+        default=None, repr=False, compare=False
+    )
+    # install 时是否 push 进进程级 RunContext 栈（供 worker 解析 owner）。
+    _registered_on_ctx_stack: bool = field(default=False, repr=False, compare=False)
+
+    def try_acquire_subagent_slot(self, *, limit: int) -> bool:
+        """在 outermost RunContext 上占用一个并发槽；满则 False。"""
+        return self.cancel_authority().subagent_concurrency.try_acquire(limit=limit)
+
+    def release_subagent_slot(self) -> None:
+        """释放 outermost 上的一个并发槽（幂等下限 0）。"""
+        self.cancel_authority().subagent_concurrency.release()
+
+    @property
+    def running_subagent_count(self) -> int:
+        return self.cancel_authority().subagent_concurrency.running
 
     def register_child(self, task: asyncio.Task) -> None:
         self.child_tasks.add(task)
@@ -167,6 +296,18 @@ def install_run_context(
         parent.register_child(ctx.root_task)
         parent.register_child_context(ctx)
     token = _current_run_context.set(ctx)
+    try:
+        loop = ctx.root_task.get_loop()
+        register_agent_loop(loop)
+        ctx._registered_agent_loop = loop
+    except Exception:
+        logger.debug(
+            "register_agent_loop skipped at install_run_context",
+            exc_info=True,
+        )
+    with _agent_loop_lock:
+        _agent_run_ctx_stack.append(ctx)
+        ctx._registered_on_ctx_stack = True
     return ctx, token
 
 
@@ -177,33 +318,53 @@ def reset_run_context(token: Token, *, owner: RunContext | None = None) -> None:
     P1：若当前 logical context 仍可见 ``owner``（derived context 继承值但 token 无效），
     显式 ``set(None)`` 清理本层，避免 workflow finally 后 run_ctx 悬挂。
     """
+    source = owner if owner is not None else get_run_context()
+    loop_to_unreg: asyncio.AbstractEventLoop | None = None
+    ctx_to_unreg: RunContext | None = None
+    if source is not None and source._registered_agent_loop is not None:
+        loop_to_unreg = source._registered_agent_loop
+        source._registered_agent_loop = None
+    if source is not None and source._registered_on_ctx_stack:
+        ctx_to_unreg = source
+        source._registered_on_ctx_stack = False
+
     try:
-        _current_run_context.reset(token)
-        return
-    except ValueError:
-        pass
+        try:
+            _current_run_context.reset(token)
+            return
+        except ValueError:
+            pass
+
+        current = get_run_context()
+        if owner is not None and current is owner:
+            _current_run_context.set(None)
+            logger.warning(
+                "run_ctx force-cleared: token reset failed in derived logical context "
+                "(task=%r)",
+                owner.root_task.get_name(),
+            )
+            return
 
-    current = get_run_context()
-    if owner is not None and current is owner:
-        _current_run_context.set(None)
-        logger.warning(
-            "run_ctx force-cleared: token reset failed in derived logical context "
-            "(task=%r)",
-            owner.root_task.get_name(),
-        )
-        return
+        if owner is not None and owner.root_task.done():
+            logger.debug(
+                "run_ctx reset skipped: owner task %r already done; context discarded",
+                owner.root_task.get_name(),
+            )
+            return
 
-    if owner is not None and owner.root_task.done():
-        logger.debug(
-            "run_ctx reset skipped: owner task %r already done; context discarded",
-            owner.root_task.get_name(),
+        logger.warning(
+            "run_ctx reset skipped: token created in a different context",
+            exc_info=True,
         )
-        return
-
-    logger.warning(
-        "run_ctx reset skipped: token created in a different context",
-        exc_info=True,
-    )
+    finally:
+        if loop_to_unreg is not None:
+            unregister_agent_loop(loop_to_unreg)
+        if ctx_to_unreg is not None:
+            with _agent_loop_lock:
+                for index in range(len(_agent_run_ctx_stack) - 1, -1, -1):
+                    if _agent_run_ctx_stack[index] is ctx_to_unreg:
+                        del _agent_run_ctx_stack[index]
+                        break
 
 
 @asynccontextmanager
@@ -297,6 +458,7 @@ def register_spawned_thread(
 
 __all__ = [
     "RunContext",
+    "SubagentConcurrencyGate",
     "create_task_with_copied_context",
     "drive_async_iterator_in_current_task",
     "get_run_context",
@@ -305,5 +467,6 @@ __all__ = [
     "register_spawned_thread",
     "reset_run_context",
     "resolve_cancel_authority",
+    "resolve_owner_run_context",
     "run_context_scope",
 ]

langchain_agentx/loop/runtime/context_factory.py

@@ -146,12 +146,15 @@ class RuntimeContextFactory:
         subagent_query_source = (
             f"agent:{subagent_type}" if subagent_type else "agent:default"
         )
+        # 子 depth 与顶层 agent_depth 必须一致：factory flatten 在 is_subagent 时
+        # 优先读 subagent.agent_depth（嵌套 L1→L2 若只写顶层会误成 0）。
+        child_depth = int(getattr(parent_ctx, "agent_depth", 0) or 0) + 1
 
         return AgentLoopConfig(
             model=resolved_model,
             session_id=getattr(parent_ctx, "session_id", "") or "",
             agent_id=agent_id,
-            agent_depth=(parent_ctx.agent_depth or 0) + 1,
+            agent_depth=child_depth,
             max_steps=resolved_max_steps,
             permission_mode=resolved_permission,
             model_retry=ModelRetrySettings(query_source=subagent_query_source),
@@ -171,6 +174,9 @@ class RuntimeContextFactory:
             ),
             subagent=SubagentLinkage(
                 is_subagent=True,
+                subagent_type=str(subagent_type) if subagent_type else None,
                 parent_agent_id=parent_agent_id,
+                agent_depth=child_depth,
+                # fork_from_parent 由 orchestrator mode 决定，derive 不知 mode → False
             ),
         )

langchain_agentx/loop/stream/loop_driver.py

@@ -11,6 +11,7 @@ loop_driver.py — Loop-aware shared stream driver.
     root closeout 捕获、synthetic error/finish、orphan tool_result repair（stream surface）。
     正常结束但缺 root on_chain_end(LangGraph) 时打 anomaly WARNING（不伪造 synthetic finish）。
     R1 反应恢复：单次 drain 内 budgeted continue 重入（S2，对齐 CC queryLoop continue）。
+    进入/退出时登记 agent loop，供 Ask 路径无 Workflow RunContext 时 fork 同步桥解析。
 """
 
 from __future__ import annotations
@@ -22,6 +23,7 @@ from typing import Any, AsyncIterator, Literal
 from langgraph.errors import GraphRecursionError
 
 from langchain_agentx.loop.loop_abort import LoopAbortSignal, is_cancel_requested
+from langchain_agentx.loop.run_context import register_agent_loop, unregister_agent_loop
 from ..exit.reason_codes import (
     TERMINAL_REASON_ABORTED_STREAMING,
     TERMINAL_REASON_ABORTED_TOOLS,
@@ -84,6 +86,8 @@ class LoopStreamDriver:
         self.result.reactive_continue_drains = 0
         current_input = dict(graph_input)
         reactive_continues = 0
+        agent_loop = asyncio.get_running_loop()
+        register_agent_loop(agent_loop)
         try:
             while True:
                 async for event in self._stream_single_drain(
@@ -113,6 +117,7 @@ class LoopStreamDriver:
                     (self.result.graph_output or {}).get("transition", {}).get("reason"),
                 )
         finally:
+            unregister_agent_loop(agent_loop)
             self._log_stream_closeout_summary()
 
     async def _stream_single_drain(

langchain_agentx/loop/subagent/async_runner.py

@@ -175,8 +175,12 @@ async def _execute_background_lifecycle(
     task_id: str,
     task_runtime: Any | None,
     allowed_tool_names: set[str] | None = None,
+    slot_owner: RunContext | None = None,
 ) -> None:
-    """共享后台生命周期：run_subagent → 写 output → task_runtime 终态。"""
+    """共享后台生命周期：run_subagent → 写 output → task_runtime 终态。
+
+    ``slot_owner``：Phase 2 并发槽从 orchestrator 移交至此；终态时 release。
+    """
     execution_ctx = ctx
     execution_ctx.is_async = False
     agent_id = getattr(ctx, "agent_id", None)
@@ -252,6 +256,9 @@ async def _execute_background_lifecycle(
             agent_id=agent_id,
             terminal_reason=TERMINAL_REASON_GRAPH_RUNTIME_ERROR,
         )
+    finally:
+        if slot_owner is not None:
+            slot_owner.release_subagent_slot()
 
 
 def register_background_agent(
@@ -264,6 +271,7 @@ def register_background_agent(
     parent_ctx: Any | None = None,
     owner_run_ctx: RunContext | None = None,
     allowed_tool_names: set[str] | None = None,
+    slot_owner: RunContext | None = None,
 ) -> BackgroundAgentHandle:
     """注册并启动后台子 Agent（仅同 loop C3；无/异 loop 拒绝，D-BG-1）。"""
     task_runtime = _resolve_task_runtime(parent_ctx)
@@ -307,6 +315,7 @@ def register_background_agent(
         task_runtime=task_runtime,
         owner_run_ctx=owner_run_ctx,
         allowed_tool_names=allowed_tool_names,
+        slot_owner=slot_owner,
     )
 
 
@@ -321,6 +330,7 @@ def _register_background_agent_task(
     task_runtime: Any | None,
     owner_run_ctx: RunContext | None,
     allowed_tool_names: set[str] | None = None,
+    slot_owner: RunContext | None = None,
 ) -> BackgroundAgentHandle:
     async def _task_body() -> None:
         await _execute_background_lifecycle(
@@ -331,6 +341,7 @@ def _register_background_agent_task(
             task_id=task_id,
             task_runtime=task_runtime,
             allowed_tool_names=allowed_tool_names,
+            slot_owner=slot_owner,
         )
 
     task = loop.create_task(_task_body(), name=f"agentx-subagent-{task_id}")

langchain_agentx/loop/subagent/graph.py

@@ -119,11 +119,13 @@ def create_subagent_graph(
             parent_tool_call_id=ctx.parent_tool_call_id,
             parent_conversation_session_id=ctx.parent_conversation_session_id,
         ),
+        agent_depth=ctx.agent_depth,
         subagent=SubagentLinkage(
             is_subagent=True,
             subagent_type=ctx.subagent_type,
             parent_agent_id=ctx.parent_agent_id,
             agent_depth=ctx.agent_depth,
+            fork_from_parent=bool(ctx.fork_from_parent),
         ),
         max_steps=ctx.max_steps,
         headless=bool(ctx.headless),