langchain-agentx-python 1.9.0__tar.gz → 1.9.2__tar.gz

{langchain-agentx-python-1.9.0/langchain_agentx_python.egg-info → langchain-agentx-python-1.9.2}/PKG-INFO

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

{langchain-agentx-python-1.9.0 → langchain-agentx-python-1.9.2}/langchain_agentx/__init__.py

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

langchain-agentx-python-1.9.2/langchain_agentx/loop/run_context.py

@@ -0,0 +1,173 @@
+"""
+run_context.py — Workflow/Agent 结构化并发上下文（parent → child cancel 传播）。
+
+职责：
+    持有 root asyncio task、child asyncio tasks 与 detached background threads；
+    通过 contextvars 隐式传递。
+
+链路位置：
+    BaseWorkflow.run() / astream_events() 入口 install；Agent spawn 时 register_child / register_child_thread。
+
+当前裁剪范围：
+    asyncio 为主；thread 仅 bounded join（无法强制中断 LLM）；anyio/trio 不保证 context 传播。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import threading
+import time
+from contextvars import ContextVar, Token
+from dataclasses import dataclass, field
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+_current_run_context: ContextVar[Optional["RunContext"]] = ContextVar(
+    "run_ctx", default=None
+)
+
+
+@dataclass
+class RunContext:
+    """运行上下文（Graph/Workflow/Agent 共享）。"""
+
+    root_task: asyncio.Task
+    child_tasks: set[asyncio.Task] = field(default_factory=set)
+    child_threads: set[threading.Thread] = field(default_factory=set)
+    cancel_requested: bool = False
+
+    def register_child(self, task: asyncio.Task) -> None:
+        self.child_tasks.add(task)
+
+    def register_child_thread(self, thread: threading.Thread) -> None:
+        self.child_threads.add(thread)
+
+    async def cancel_tree(self, timeout: float = 10.0) -> None:
+        self.cancel_requested = True
+        deadline = time.monotonic() + timeout
+
+        for child in list(self.child_tasks):
+            child.cancel()
+        if self.child_tasks:
+            remaining = max(0.0, deadline - time.monotonic())
+            try:
+                await asyncio.wait_for(
+                    asyncio.gather(*self.child_tasks, return_exceptions=True),
+                    timeout=remaining,
+                )
+            except TimeoutError:
+                logger.warning(
+                    "RunContext.cancel_tree asyncio children timed out after %ss",
+                    timeout,
+                )
+            finally:
+                self.child_tasks.clear()
+
+        if self.child_threads:
+            remaining = max(0.0, deadline - time.monotonic())
+            _join_child_threads_bounded(self.child_threads, timeout=remaining)
+            self.child_threads.clear()
+
+
+def _join_child_threads_bounded(
+    threads: set[threading.Thread],
+    *,
+    timeout: float,
+) -> None:
+    """Phase 4.1：detached thread 无法 cancel，仅 bounded join + 告警。"""
+    if timeout <= 0:
+        for thread in threads:
+            if thread.is_alive():
+                logger.warning(
+                    "Background thread still alive after cancel_tree (no join budget): %s",
+                    thread.name,
+                )
+        return
+    deadline = time.monotonic() + timeout
+    for thread in list(threads):
+        remaining = max(0.0, deadline - time.monotonic())
+        thread.join(timeout=remaining)
+        if thread.is_alive():
+            logger.warning(
+                "Background thread join timed out after cancel_tree: %s",
+                thread.name,
+            )
+
+
+def get_run_context() -> RunContext | None:
+    return _current_run_context.get()
+
+
+def install_run_context(
+    ctx: RunContext | None = None,
+    *,
+    parent: RunContext | None = None,
+) -> tuple[RunContext, Token]:
+    """安装 RunContext；若已有 parent 则把当前 root task 注册为 child。"""
+    if ctx is None:
+        try:
+            current = asyncio.current_task()
+        except RuntimeError as exc:
+            raise RuntimeError(
+                "install_run_context requires a running asyncio task"
+            ) from exc
+        if current is None:
+            raise RuntimeError(
+                "install_run_context requires a running asyncio task"
+            )
+        ctx = RunContext(root_task=current)
+    if parent is not None:
+        parent.register_child(ctx.root_task)
+    token = _current_run_context.set(ctx)
+    return ctx, token
+
+
+def reset_run_context(token: Token) -> None:
+    _current_run_context.reset(token)
+
+
+def register_spawned_task(
+    task: asyncio.Task,
+    *,
+    owner: RunContext | None = None,
+) -> None:
+    """将 spawn 出的 asyncio task 注册到 RunContext（无 context 时 no-op）。"""
+    ctx = owner if owner is not None else get_run_context()
+    if ctx is None:
+        return
+    try:
+        owner_loop = ctx.root_task.get_loop()
+        task_loop = task.get_loop()
+    except RuntimeError:
+        logger.warning("register_spawned_task: cannot resolve event loop; skipping registration")
+        return
+    if owner_loop is not task_loop:
+        logger.warning(
+            "register_spawned_task: skipping foreign-loop task %r",
+            task.get_name(),
+        )
+        return
+    ctx.register_child(task)
+
+
+def register_spawned_thread(
+    thread: threading.Thread,
+    *,
+    owner: RunContext | None = None,
+) -> None:
+    """Phase 4.1：detached thread spawn 注册到 owner RunContext（bounded join）。"""
+    ctx = owner if owner is not None else get_run_context()
+    if ctx is not None:
+        ctx.register_child_thread(thread)
+
+
+__all__ = [
+    "RunContext",
+    "get_run_context",
+    "install_run_context",
+    "register_spawned_task",
+    "register_spawned_thread",
+    "reset_run_context",
+]

langchain-agentx-python-1.9.2/langchain_agentx/loop/subagent/async_runner.py

@@ -0,0 +1,290 @@
+"""
+loop/subagent/async_runner.py — 子 Agent 异步生命周期管理
+
+职责：
+  - register_background_agent()：后台启动子 Agent（asyncio task 优先，无 loop 时 thread 回退）
+  - run_async_agent_lifecycle()：coordinate 模式纯 async 生命周期（供 AgentRuntimeTool 调用）
+
+链路位置：
+  AgentRuntimeTool.invoke(is_async=True) → run_async_agent_lifecycle()
+  orchestrator async/sync launch → register_background_agent()
+
+Phase 4.1：
+  - 有 running loop → asyncio.create_task + register_spawned_task(owner=...)
+  - 无 loop / 须 detach → threading.Thread + register_spawned_thread(owner=...)
+  - owner_run_ctx 显式传入以跨 _run_coroutine_sync 子线程边界注册到 workflow RunContext
+
+当前裁剪范围：
+  v1 基础版；thread 路径无法中断 LLM，cancel_tree 仅 bounded join
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import threading
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+from langchain_agentx.loop.exit.reason_codes import TERMINAL_REASON_GRAPH_RUNTIME_ERROR
+from langchain_agentx.loop.run_context import (
+    RunContext,
+    register_spawned_task,
+    register_spawned_thread,
+)
+from langchain_agentx.task_runtime.core.types import TaskScope, TaskSpec, TaskStatus, TaskType
+
+from .context import SubagentContext
+from .runner import run_subagent
+
+
+@dataclass
+class BackgroundAgentHandle:
+    task_id: str
+    agent_id: str
+    output_file: str
+    thread: threading.Thread | None = None
+    asyncio_task: asyncio.Task[None] | None = None
+
+
+_BACKGROUND_HANDLES: dict[str, BackgroundAgentHandle] = {}
+
+
+def _ensure_parent(path: str) -> None:
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+
+
+def _resolve_task_runtime(ctx: Any) -> Any | None:
+    runtime = getattr(ctx, "task_runtime", None)
+    if runtime is not None:
+        return runtime
+    state = getattr(ctx, "state", {})
+    if isinstance(state, dict):
+        return state.get("task_runtime")
+    return None
+
+
+def _spawn_task_record(task_runtime: Any, ctx: SubagentContext, description: str) -> str:
+    if task_runtime is None:
+        return str(uuid.uuid4())
+    spec = TaskSpec(
+        task_type=TaskType.LOCAL_AGENT,
+        description=description,
+        input={"prompt": description, "agent_label": ctx.subagent_type},
+        scope=TaskScope(agent_id=ctx.parent_agent_id),
+    )
+    return task_runtime.spawn(spec)
+
+
+async def _execute_background_lifecycle(
+    *,
+    ctx: SubagentContext,
+    loader: Any,
+    model: Any | None,
+    output_file: str,
+    task_id: str,
+    task_runtime: Any | None,
+) -> None:
+    """共享后台生命周期：run_subagent → 写 output → task_runtime 终态。"""
+    execution_ctx = ctx
+    execution_ctx.is_async = False
+    try:
+        result = await run_subagent(
+            ctx=execution_ctx,
+            loader=loader,
+            model=model,
+        )
+        with open(output_file, "w", encoding="utf-8") as fp:
+            fp.write(result.content)
+        if task_runtime is not None:
+            status = TaskStatus.COMPLETED if result.status == "completed" else TaskStatus.FAILED
+            task_runtime.mark_terminal(
+                task_id,
+                status,
+                result.content[:500] if result.content else (result.error_message or "subagent completed"),
+                output_file=output_file,
+                terminal_reason=result.terminal_reason or None,
+            )
+    except asyncio.CancelledError:
+        with open(output_file, "w", encoding="utf-8") as fp:
+            fp.write("cancelled")
+        if task_runtime is not None:
+            try:
+                task_runtime.mark_terminal(
+                    task_id,
+                    TaskStatus.FAILED,
+                    "subagent cancelled",
+                    output_file=output_file,
+                    terminal_reason="cancelled",
+                )
+            except Exception:
+                pass
+        raise
+    except Exception as exc:
+        with open(output_file, "w", encoding="utf-8") as fp:
+            fp.write(str(exc))
+        if task_runtime is not None:
+            task_runtime.mark_terminal(
+                task_id,
+                TaskStatus.FAILED,
+                f"Subagent background lifecycle failed: {exc}",
+                output_file=output_file,
+                terminal_reason=TERMINAL_REASON_GRAPH_RUNTIME_ERROR,
+            )
+
+
+def register_background_agent(
+    *,
+    ctx: SubagentContext,
+    loader: Any,
+    model: Any | None,
+    output_dir: str,
+    description: str,
+    parent_ctx: Any | None = None,
+    owner_run_ctx: RunContext | None = None,
+) -> BackgroundAgentHandle:
+    """注册并启动后台子 Agent（asyncio task 优先，否则 detached thread）。"""
+    task_runtime = _resolve_task_runtime(parent_ctx)
+    task_id = _spawn_task_record(task_runtime, ctx, description)
+    output_file = os.path.join(output_dir, task_id, "output.txt")
+    _ensure_parent(output_file)
+
+    owner_loop: asyncio.AbstractEventLoop | None = None
+    if owner_run_ctx is not None:
+        try:
+            owner_loop = owner_run_ctx.root_task.get_loop()
+        except RuntimeError:
+            owner_loop = None
+
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        loop = None
+
+    if loop is not None and (owner_loop is None or owner_loop is loop):
+        return _register_background_agent_task(
+            loop=loop,
+            ctx=ctx,
+            loader=loader,
+            model=model,
+            task_id=task_id,
+            output_file=output_file,
+            task_runtime=task_runtime,
+            owner_run_ctx=owner_run_ctx,
+        )
+
+    return _register_background_agent_thread(
+        ctx=ctx,
+        loader=loader,
+        model=model,
+        task_id=task_id,
+        output_file=output_file,
+        task_runtime=task_runtime,
+        owner_run_ctx=owner_run_ctx,
+    )
+
+
+def _register_background_agent_task(
+    *,
+    loop: asyncio.AbstractEventLoop,
+    ctx: SubagentContext,
+    loader: Any,
+    model: Any | None,
+    task_id: str,
+    output_file: str,
+    task_runtime: Any | None,
+    owner_run_ctx: RunContext | None,
+) -> BackgroundAgentHandle:
+    async def _task_body() -> None:
+        await _execute_background_lifecycle(
+            ctx=ctx,
+            loader=loader,
+            model=model,
+            output_file=output_file,
+            task_id=task_id,
+            task_runtime=task_runtime,
+        )
+
+    task = loop.create_task(_task_body(), name=f"agentx-subagent-{task_id}")
+    register_spawned_task(task, owner=owner_run_ctx)
+    handle = BackgroundAgentHandle(
+        task_id=task_id,
+        agent_id=ctx.agent_id,
+        output_file=output_file,
+        asyncio_task=task,
+    )
+    _BACKGROUND_HANDLES[task_id] = handle
+    return handle
+
+
+def _register_background_agent_thread(
+    *,
+    ctx: SubagentContext,
+    loader: Any,
+    model: Any | None,
+    task_id: str,
+    output_file: str,
+    task_runtime: Any | None,
+    owner_run_ctx: RunContext | None,
+) -> BackgroundAgentHandle:
+    def _run() -> None:
+        asyncio.run(
+            _execute_background_lifecycle(
+                ctx=ctx,
+                loader=loader,
+                model=model,
+                output_file=output_file,
+                task_id=task_id,
+                task_runtime=task_runtime,
+            )
+        )
+
+    thread = threading.Thread(
+        target=_run,
+        daemon=True,
+        name=f"agentx-subagent-{task_id}",
+    )
+    thread.start()
+    register_spawned_thread(thread, owner=owner_run_ctx)
+    handle = BackgroundAgentHandle(
+        task_id=task_id,
+        agent_id=ctx.agent_id,
+        output_file=output_file,
+        thread=thread,
+    )
+    _BACKGROUND_HANDLES[task_id] = handle
+    return handle
+
+
+def get_background_agent_handle(task_id: str) -> BackgroundAgentHandle | None:
+    return _BACKGROUND_HANDLES.get(task_id)
+
+
+async def run_async_agent_lifecycle(
+    task_id: str,
+    ctx: SubagentContext,
+    loader: Any,
+    task_runtime: Any,
+    output_dir: str,
+    *,
+    model: Any | None = None,
+) -> None:
+    """coordinate 模式异步生命周期：后台执行子 Agent，完成后通过 task_runtime 写通知。"""
+    output_file = os.path.join(output_dir, task_id, "output.txt")
+    _ensure_parent(output_file)
+
+    if task_runtime is not None:
+        try:
+            task_runtime.update(task_id, {"status": TaskStatus.RUNNING.value})
+        except Exception:
+            pass
+
+    await _execute_background_lifecycle(
+        ctx=ctx,
+        loader=loader,
+        model=model,
+        output_file=output_file,
+        task_id=task_id,
+        task_runtime=task_runtime,
+    )

{langchain-agentx-python-1.9.0 → langchain-agentx-python-1.9.2}/langchain_agentx/loop/subagent/orchestrator.py

@@ -38,6 +38,7 @@ from langchain_agentx.loop.subagent.runner import (
     run_subagent,
     run_subagent_with_background_signal,
 )
+from langchain_agentx.loop.run_context import get_run_context
 from langchain_agentx.loop.subagent.async_runner import register_background_agent
 from langchain_agentx.observability.logging import ObservabilityLoggerAdapter, build_log_context
 from langchain_agentx.workspace import resolve_agent_state_config
@@ -538,6 +539,7 @@ class SubagentOrchestrator:
         description: str | None,
         parent_ctx: "ToolExecutionContext",
         output_dir: str,
+        owner_run_ctx: Any | None = None,
     ) -> Any:
         return register_background_agent(
             ctx=subagent_ctx,
@@ -546,6 +548,7 @@ class SubagentOrchestrator:
             output_dir=output_dir,
             description=description,
             parent_ctx=parent_ctx,
+            owner_run_ctx=owner_run_ctx if owner_run_ctx is not None else get_run_context(),
         )
 
     def _launch_async_subagent(
@@ -559,6 +562,7 @@ class SubagentOrchestrator:
         parent_ctx: "ToolExecutionContext",
         output_dir: str,
     ) -> Any:
+        owner_run_ctx = get_run_context()
         handle = self._register_background_agent(
             subagent_ctx=subagent_ctx,
             loader=loader,
@@ -566,6 +570,7 @@ class SubagentOrchestrator:
             description=description,
             parent_ctx=parent_ctx,
             output_dir=output_dir,
+            owner_run_ctx=owner_run_ctx,
         )
         return agent_output_cls(
             status="async_launched",
@@ -592,6 +597,7 @@ class SubagentOrchestrator:
 
         子 graph 事件通过 config 自动冒泡到父 graph。
         """
+        owner_run_ctx = get_run_context()
         handle = self._register_background_agent(
             subagent_ctx=subagent_ctx,
             loader=loader,
@@ -599,6 +605,7 @@ class SubagentOrchestrator:
             output_dir=output_dir,
             description=description,
             parent_ctx=parent_ctx,
+            owner_run_ctx=owner_run_ctx,
         )
         return agent_output_cls(
             status="async_launched",
@@ -622,6 +629,8 @@ class SubagentOrchestrator:
         allowed_tool_names: set[str],
         output_dir: str,
     ) -> Any:
+        owner_run_ctx = get_run_context()
+
         def _register_from_signal(child_ctx: Any) -> str:
             handle = self._register_background_agent(
                 subagent_ctx=child_ctx,
@@ -630,6 +639,7 @@ class SubagentOrchestrator:
                 description=description,
                 parent_ctx=parent_ctx,
                 output_dir=output_dir,
+                owner_run_ctx=owner_run_ctx,
             )
             return handle.task_id
 
@@ -641,7 +651,9 @@ class SubagentOrchestrator:
                 background_signal=background_signal,
                 on_background_request=_register_from_signal,
                 allowed_tool_names=allowed_tool_names,
-            )
+                owner_run_ctx=owner_run_ctx,
+            ),
+            owner_run_ctx=owner_run_ctx,
         )
 
     def _resolve_parent_workspace_cfg(
@@ -739,13 +751,15 @@ class SubagentOrchestrator:
         model: Any,
         allowed_tool_names: set[str],
     ) -> Any:
+        owner_run_ctx = get_run_context()
         return _run_coroutine_sync(
             run_subagent(
                 ctx=subagent_ctx,
                 loader=loader,
                 model=model,
                 allowed_tool_names=allowed_tool_names,
-            )
+            ),
+            owner_run_ctx=owner_run_ctx,
         )
 
     async def run_isolated(

{langchain-agentx-python-1.9.0 → langchain-agentx-python-1.9.2}/langchain_agentx/loop/subagent/runner.py

@@ -39,6 +39,7 @@ from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
 
 from langchain_agentx.loop.exit.reason_codes import TERMINAL_REASON_GRAPH_RUNTIME_ERROR
 from langchain_agentx.loop.exit.terminal import apply_terminal_reason_projection, read_terminal_reason
+from langchain_agentx.loop.run_context import register_spawned_task, register_spawned_thread
 from langchain_agentx.loop.stream.loop_driver import LoopStreamDriver
 from langchain_agentx.loop.subagent.context import (
     SubagentContext,
@@ -90,7 +91,7 @@ _LOOP_SNAPSHOT_KEYS = (
 )
 
 
-def _run_coroutine_sync(coro: Any) -> Any:
+def _run_coroutine_sync(coro: Any, *, owner_run_ctx: Any | None = None) -> Any:
     """在同步上下文运行协程；若当前已有事件循环则转到子线程执行。"""
     try:
         asyncio.get_running_loop()
@@ -106,6 +107,8 @@ def _run_coroutine_sync(coro: Any) -> Any:
             fut.set_exception(exc)
 
     thread = threading.Thread(target=_runner, daemon=True)
+    if owner_run_ctx is not None:
+        register_spawned_thread(thread, owner=owner_run_ctx)
     thread.start()
     thread.join()
     return fut.result()
@@ -732,15 +735,18 @@ async def run_subagent_with_background_signal(
     background_signal: asyncio.Event | None = None,
     on_background_request: Callable[[SubagentContext], str] | None = None,
     allowed_tool_names: set[str] | None = None,
+    owner_run_ctx: Any | None = None,
 ) -> SubagentResult | BackgroundLaunchedResult:
     """同步执行中监听后台化信号（CC Promise.race 语义）。"""
     agent_task = asyncio.create_task(
         run_subagent(ctx=ctx, loader=loader, model=model, allowed_tool_names=allowed_tool_names)
     )
+    register_spawned_task(agent_task, owner=owner_run_ctx)
     if background_signal is None:
         return await agent_task
 
     signal_task = asyncio.create_task(background_signal.wait())
+    register_spawned_task(signal_task, owner=owner_run_ctx)
     done, pending = await asyncio.wait(
         {agent_task, signal_task},
         return_when=asyncio.FIRST_COMPLETED,