langchain-agentx-python 2.1.5__tar.gz → 2.1.7__tar.gz

{langchain-agentx-python-2.1.5/langchain_agentx_python.egg-info → langchain-agentx-python-2.1.7}/PKG-INFO

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

{langchain-agentx-python-2.1.5 → langchain-agentx-python-2.1.7}/langchain_agentx/__init__.py

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

{langchain-agentx-python-2.1.5 → langchain-agentx-python-2.1.7}/langchain_agentx/loop/__init__.py

@@ -35,13 +35,14 @@ for chunk in agent.stream({"messages": [{"role": "user", "content": "Hello"}]}):
 from .graph.factory import (
     create_loop_agent,
 )
-from .loop_abort import LoopAbortSignal
+from .loop_abort import LoopAbortSignal, raise_if_cancel_requested
 from .config import build_agent_config
 
 __all__ = [
     # 主要接口
     "create_loop_agent",
     "LoopAbortSignal",
+    "raise_if_cancel_requested",
     # 配置助手
     "build_agent_config",
 ]

{langchain-agentx-python-2.1.5 → langchain-agentx-python-2.1.7}/langchain_agentx/loop/exit/reason_codes.py

@@ -48,6 +48,7 @@ TRANSITION_TOKEN_BUDGET_CONTINUATION = "token_budget_continuation"
 DEFAULT_TOKEN_BUDGET_MAX_CONTINUATIONS = 3
 
 # 错误结束 terminal_reason 集合（finish payload is_error 判据）
+# D-EVT-3：含 aborted_* / hook_stopped，与 build_loop_terminal 对齐
 ERROR_TERMINAL_REASONS = frozenset(
     {
         TERMINAL_REASON_ERROR,
@@ -60,6 +61,9 @@ ERROR_TERMINAL_REASONS = frozenset(
         TERMINAL_REASON_MAX_TOKENS,
         TERMINAL_REASON_BLOCKING_LIMIT,
         TERMINAL_REASON_CLASSIFIER_DENIAL_LIMIT,
+        TERMINAL_REASON_ABORTED_STREAMING,
+        TERMINAL_REASON_ABORTED_TOOLS,
+        TERMINAL_REASON_HOOK_STOPPED,
     }
 )
 

{langchain-agentx-python-2.1.5 → langchain-agentx-python-2.1.7}/langchain_agentx/loop/graph/builtin_loop_control.py

@@ -1,12 +1,14 @@
 """
 内置 loop 控制：捕获 ``LoopAbortSignal``，写入 ``abort_terminal_reason``（及工具侧合成 ToolMessage）。
 
-始终由 ``create_loop_agent`` 注入到 ``wrap_model_call`` / ``wrap_tool_call`` 链的最外层，
-用户 middleware 在内层抛出 ``LoopAbortSignal`` 即可，无需手写 Command。
+由 ModelNode / RuntimeToolsNode 在 invoke 路径最外层调用；handler 前读
+``raise_if_cancel_requested``（Doc-35 P1 / D-ABORT-1）。用户侧抛出 ``LoopAbortSignal``
+即可，无需手写 Command。
 """
 
 from __future__ import annotations
 
+import asyncio
 import copy
 import logging
 from typing import Any
@@ -21,7 +23,7 @@ from ..exit.reason_codes import (
     TERMINAL_REASON_CLASSIFIER_DENIAL_LIMIT,
     TERMINAL_REASON_HOOK_STOPPED,
 )
-from ..loop_abort import LoopAbortSignal
+from ..loop_abort import LoopAbortSignal, raise_if_cancel_requested
 from ..model.orphan_tool_results import synthetic_tool_messages_for_orphan_tool_calls
 from ...tool_runtime.classifier_denial_limit import ClassifierDenialLimitAbort
 from ...tool_runtime.permission_context import clear_auto_approved_window
@@ -50,46 +52,51 @@ def _session_store_from_request(request: Any) -> Any | None:
     return None
 
 
+def _model_abort_response(sig: LoopAbortSignal) -> ExtendedModelResponse:
+    ai = AIMessage(
+        content=_abort_model_content(sig.terminal_reason, sig.detail),
+        response_metadata={"finish_reason": "stop"},
+    )
+    return ExtendedModelResponse(
+        model_response=ModelResponse(result=[ai], structured_response=None),
+        command=Command(update={"abort_terminal_reason": sig.terminal_reason}),
+    )
+
+
 class _LoopBuiltinModelControl:
-    """内部单例：捕获模型侧的 ``LoopAbortSignal``。"""
+    """内部单例：协作读停令 + 捕获模型侧的 ``LoopAbortSignal``。"""
 
     def wrap_model_call(self, request: Any, handler: Any) -> Any:
         clear_auto_approved_window(_session_store_from_request(request))
         try:
+            raise_if_cancel_requested(phase="model")
             return handler(request)
+        except asyncio.CancelledError:
+            raise_if_cancel_requested(phase="model")
+            raise
         except LoopAbortSignal as sig:
             if sig.terminal_reason not in (
                 TERMINAL_REASON_ABORTED_STREAMING,
                 TERMINAL_REASON_HOOK_STOPPED,
             ):
                 raise
-            ai = AIMessage(
-                content=_abort_model_content(sig.terminal_reason, sig.detail),
-                response_metadata={"finish_reason": "stop"},
-            )
-            return ExtendedModelResponse(
-                model_response=ModelResponse(result=[ai], structured_response=None),
-                command=Command(update={"abort_terminal_reason": sig.terminal_reason}),
-            )
+            return _model_abort_response(sig)
 
     async def awrap_model_call(self, request: Any, handler: Any) -> Any:
         clear_auto_approved_window(_session_store_from_request(request))
         try:
+            raise_if_cancel_requested(phase="model")
             return await handler(request)
+        except asyncio.CancelledError:
+            raise_if_cancel_requested(phase="model")
+            raise
         except LoopAbortSignal as sig:
             if sig.terminal_reason not in (
                 TERMINAL_REASON_ABORTED_STREAMING,
                 TERMINAL_REASON_HOOK_STOPPED,
             ):
                 raise
-            ai = AIMessage(
-                content=_abort_model_content(sig.terminal_reason, sig.detail),
-                response_metadata={"finish_reason": "stop"},
-            )
-            return ExtendedModelResponse(
-                model_response=ModelResponse(result=[ai], structured_response=None),
-                command=Command(update={"abort_terminal_reason": sig.terminal_reason}),
-            )
+            return _model_abort_response(sig)
 
 
 _LOOP_BUILTIN_MODEL_SINGLETON = _LoopBuiltinModelControl()
@@ -173,8 +180,12 @@ def _tool_abort_command(
 
 def builtin_sync_tool_wrapper(request: Any, handler: Any) -> Any:
     try:
+        raise_if_cancel_requested(phase="tools")
         result = handler(_with_injected_agent_tool_model(request))
         return apply_tool_message_status_to_result(result)
+    except asyncio.CancelledError:
+        raise_if_cancel_requested(phase="tools")
+        raise
     except ClassifierDenialLimitAbort as exc:
         return _tool_abort_command(
             request,
@@ -192,8 +203,12 @@ def builtin_sync_tool_wrapper(request: Any, handler: Any) -> Any:
 
 async def builtin_async_tool_wrapper(request: Any, handler: Any) -> Any:
     try:
+        raise_if_cancel_requested(phase="tools")
         result = await handler(_with_injected_agent_tool_model(request))
         return apply_tool_message_status_to_result(result)
+    except asyncio.CancelledError:
+        raise_if_cancel_requested(phase="tools")
+        raise
     except ClassifierDenialLimitAbort as exc:
         return _tool_abort_command(
             request,
@@ -209,8 +224,33 @@ async def builtin_async_tool_wrapper(request: Any, handler: Any) -> Any:
         )
 
 
+def tools_batch_abort_command(
+    tool_calls: list[dict[str, Any]],
+    *,
+    terminal_reason: str = TERMINAL_REASON_ABORTED_TOOLS,
+    content_template: str | None = None,
+) -> Command:
+    """tools 节点批次入口 abort：合成 orphan ToolMessage + abort_terminal_reason。"""
+    synth = (
+        synthetic_tool_messages_for_orphan_tool_calls(
+            pending_tool_calls=list(tool_calls),
+            reason="user_interrupted",
+            content_template=content_template,
+        )
+        if tool_calls
+        else []
+    )
+    return Command(
+        update={
+            "abort_terminal_reason": terminal_reason,
+            "messages": synth,
+        }
+    )
+
+
 __all__ = [
     "builtin_async_tool_wrapper",
     "builtin_sync_tool_wrapper",
     "get_loop_builtin_model_middleware",
+    "tools_batch_abort_command",
 ]

{langchain-agentx-python-2.1.5 → langchain-agentx-python-2.1.7}/langchain_agentx/loop/graph/runtime_tools_node.py

@@ -9,17 +9,21 @@ loop/graph/runtime_tools_node.py — 新 tools 执行 graph bridge
 
 当前裁剪范围：
     Phase 4 readonly_parallel 由 engine 对 safe_group 受控并发；exclusive 仍串行。
+    P1：批次入口读 cancel_requested → LoopAbortSignal 单轨（D-ABORT-1）。
 """
 
 from __future__ import annotations
 
+import asyncio
 from typing import Any, MutableMapping
 
 from langchain_core.messages import AIMessage, ToolMessage
 from langchain_core.runnables import Runnable, RunnableConfig
 from langchain_core.tools import BaseTool
+from langgraph.types import Command
 
 from ...tool_runtime.adapter import LangChainAdapter
+from ...tool_runtime.classifier_denial_limit import ClassifierDenialLimitAbort
 from ...tool_runtime.execution import (
     EngineConfig,
     EnginePolicy,
@@ -29,6 +33,12 @@ from ...tool_runtime.execution import (
 )
 from ...tool_runtime.pipeline import ToolExecutorPipeline
 from ...tool_runtime.registry import RuntimeToolRegistry
+from ..exit.reason_codes import (
+    TERMINAL_REASON_ABORTED_TOOLS,
+    TERMINAL_REASON_CLASSIFIER_DENIAL_LIMIT,
+)
+from ..loop_abort import LoopAbortSignal, raise_if_cancel_requested
+from .builtin_loop_control import tools_batch_abort_command
 
 
 class RuntimeToolsNode(Runnable):
@@ -87,35 +97,71 @@ class RuntimeToolsNode(Runnable):
         self,
         state: MutableMapping[str, Any],
         config: RunnableConfig | None,
-    ) -> dict[str, Any]:
+    ) -> dict[str, Any] | Command:
         _ai_message, tool_calls = _extract_tool_calls(state)
         if not tool_calls:
             return {}
-        batches = self._planner.plan(tool_calls)
-        records = self._engine.execute_turn(
-            batches=batches,
-            state=state,
-            config=config,
-        )
-        tool_messages = self._message_adapter.records_to_graph_messages(records)
-        return {"messages": tool_messages}
+        try:
+            raise_if_cancel_requested(phase="tools")
+            batches = self._planner.plan(tool_calls)
+            records = self._engine.execute_turn(
+                batches=batches,
+                state=state,
+                config=config,
+            )
+            tool_messages = self._message_adapter.records_to_graph_messages(records)
+            return {"messages": tool_messages}
+        except asyncio.CancelledError:
+            raise_if_cancel_requested(phase="tools")
+            raise
+        except ClassifierDenialLimitAbort as exc:
+            return tools_batch_abort_command(
+                tool_calls,
+                terminal_reason=TERMINAL_REASON_CLASSIFIER_DENIAL_LIMIT,
+                content_template=exc.message,
+            )
+        except LoopAbortSignal as sig:
+            if sig.terminal_reason != TERMINAL_REASON_ABORTED_TOOLS:
+                raise
+            return tools_batch_abort_command(
+                tool_calls,
+                terminal_reason=TERMINAL_REASON_ABORTED_TOOLS,
+            )
 
     async def _arun(
         self,
         state: MutableMapping[str, Any],
         config: RunnableConfig | None,
-    ) -> dict[str, Any]:
+    ) -> dict[str, Any] | Command:
         _ai_message, tool_calls = _extract_tool_calls(state)
         if not tool_calls:
             return {}
-        batches = self._planner.plan(tool_calls)
-        records = await self._engine.aexecute_turn(
-            batches=batches,
-            state=state,
-            config=config,
-        )
-        tool_messages = self._message_adapter.records_to_graph_messages(records)
-        return {"messages": tool_messages}
+        try:
+            raise_if_cancel_requested(phase="tools")
+            batches = self._planner.plan(tool_calls)
+            records = await self._engine.aexecute_turn(
+                batches=batches,
+                state=state,
+                config=config,
+            )
+            tool_messages = self._message_adapter.records_to_graph_messages(records)
+            return {"messages": tool_messages}
+        except asyncio.CancelledError:
+            raise_if_cancel_requested(phase="tools")
+            raise
+        except ClassifierDenialLimitAbort as exc:
+            return tools_batch_abort_command(
+                tool_calls,
+                terminal_reason=TERMINAL_REASON_CLASSIFIER_DENIAL_LIMIT,
+                content_template=exc.message,
+            )
+        except LoopAbortSignal as sig:
+            if sig.terminal_reason != TERMINAL_REASON_ABORTED_TOOLS:
+                raise
+            return tools_batch_abort_command(
+                tool_calls,
+                terminal_reason=TERMINAL_REASON_ABORTED_TOOLS,
+            )
 
 
 def _extract_tool_calls(

langchain-agentx-python-2.1.7/langchain_agentx/loop/loop_abort.py

@@ -0,0 +1,67 @@
+"""流式 / 工具 / hook 中断信号：由业务 middleware 或工具抛出，由内置 wrapper 转为 state 契约。
+
+P1（Doc-35 D-ABORT-1）：``raise_if_cancel_requested`` 读 ``RunContext.cancel_requested``，
+真则抛既有 ``LoopAbortSignal``（单轨）；禁止平行 Abort 异常族。
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from .exit.reason_codes import (
+    TERMINAL_REASON_ABORTED_STREAMING,
+    TERMINAL_REASON_ABORTED_TOOLS,
+    TERMINAL_REASON_HOOK_STOPPED,
+)
+
+CancelAbortPhase = Literal["model", "tools"]
+
+
+class LoopAbortSignal(Exception):
+    """请求以 CC 式 abort 终局结束（写入 ``abort_terminal_reason``）。
+
+    - ``aborted_streaming`` / ``hook_stopped``：在 ``wrap_model_call`` / ``awrap_model_call`` 中抛出，
+      由 ``_LoopBuiltinModelControl`` 捕获并合成 AIMessage + Command。
+    - ``aborted_tools``：在工具执行或 ``wrap_tool_call`` 中抛出，由内置 tool wrapper 捕获并
+      注入合成 ``ToolMessage`` + ``abort_terminal_reason``。
+    """
+
+    __slots__ = ("terminal_reason", "detail")
+
+    def __init__(self, terminal_reason: str, *, detail: str | None = None) -> None:
+        if terminal_reason not in (
+            TERMINAL_REASON_ABORTED_STREAMING,
+            TERMINAL_REASON_ABORTED_TOOLS,
+            TERMINAL_REASON_HOOK_STOPPED,
+        ):
+            msg = f"Invalid LoopAbortSignal terminal_reason: {terminal_reason!r}"
+            raise ValueError(msg)
+        self.terminal_reason = terminal_reason
+        self.detail = detail
+        super().__init__(detail or terminal_reason)
+
+
+def raise_if_cancel_requested(*, phase: CancelAbortPhase) -> None:
+    """若当前 ``RunContext.cancel_requested`` 为真，抛既有 ``LoopAbortSignal``。
+
+    对齐 CC ``query.ts`` 读 ``signal.aborted``；SDK 原语为 bool（D-SEM-1），
+    退出语义仅走 ``LoopAbortSignal`` → ``builtin_loop_control``（D-ABORT-1）。
+    无 RunContext 时 no-op。
+    """
+    from .run_context import get_run_context
+
+    ctx = get_run_context()
+    if ctx is None or not ctx.cancel_requested:
+        return
+    if phase == "tools":
+        raise LoopAbortSignal(
+            TERMINAL_REASON_ABORTED_TOOLS,
+            detail="cancel_requested",
+        )
+    raise LoopAbortSignal(
+        TERMINAL_REASON_ABORTED_STREAMING,
+        detail="cancel_requested",
+    )
+
+
+__all__ = ["CancelAbortPhase", "LoopAbortSignal", "raise_if_cancel_requested"]

{langchain-agentx-python-2.1.5 → langchain-agentx-python-2.1.7}/langchain_agentx/loop/model/model_node.py

@@ -338,55 +338,103 @@ class ModelNode(Runnable):
 
     def _run(self, state: dict, config: RunnableConfig) -> dict:
         """核心同步执行逻辑。"""
-        runtime = config.get("configurable", {}).get("__pregel_runtime")
-        request = self._build_request(state, runtime, config=config)
+        from langchain.agents.middleware.types import ExtendedModelResponse
+        from langgraph.types import Command
 
-        synth = _model_response_if_context_token_blocked(
-            state_messages=state.get("messages", []),
-            name=self._name,
-            initial_response_format=self._initial_response_format,
-            structured_output_tools=self._structured_output_tools,
-            compaction_settings=self._compaction_settings,
-            query_source=state.get("query_source")
-            if isinstance(state.get("query_source"), str)
-            else None,
+        from langchain_agentx.loop.graph.builtin_loop_control import (
+            get_loop_builtin_model_middleware,
         )
-        if synth is not None:
-            model_response = synth
+
+        runtime = config.get("configurable", {}).get("__pregel_runtime")
+        request = self._build_request(state, runtime, config=config)
+        mw = get_loop_builtin_model_middleware()
+
+        def _handler(req: Any) -> Any:
+            synth = _model_response_if_context_token_blocked(
+                state_messages=state.get("messages", []),
+                name=self._name,
+                initial_response_format=self._initial_response_format,
+                structured_output_tools=self._structured_output_tools,
+                compaction_settings=self._compaction_settings,
+                query_source=state.get("query_source")
+                if isinstance(state.get("query_source"), str)
+                else None,
+            )
+            if synth is not None:
+                return synth
+            model_response, _ = self._run_sync(req, state, config=config)
+            return model_response
+
+        wrapped = mw.wrap_model_call(request, _handler)
+        abort_reason: str | None = None
+        if isinstance(wrapped, ExtendedModelResponse):
+            model_response = wrapped.model_response
+            cmd = wrapped.command
+            if isinstance(cmd, Command) and isinstance(cmd.update, dict):
+                reason = cmd.update.get("abort_terminal_reason")
+                if isinstance(reason, str):
+                    abort_reason = reason
         else:
-            model_response, _ = self._run_sync(request, state, config=config)
+            model_response = wrapped
 
-        return self._build_state_update(
+        updates = self._build_state_update(
             state=state,
             model_response=model_response,
             mode="sync",
         )
+        if abort_reason:
+            return list(updates) + [Command(update={"abort_terminal_reason": abort_reason})]
+        return updates
 
     async def _arun(self, state: dict, config: RunnableConfig) -> dict:
         """核心异步执行逻辑。"""
-        runtime = config.get("configurable", {}).get("__pregel_runtime")
-        request = self._build_request(state, runtime, config=config)
+        from langchain.agents.middleware.types import ExtendedModelResponse
+        from langgraph.types import Command
 
-        synth = _model_response_if_context_token_blocked(
-            state_messages=state.get("messages", []),
-            name=self._name,
-            initial_response_format=self._initial_response_format,
-            structured_output_tools=self._structured_output_tools,
-            compaction_settings=self._compaction_settings,
-            query_source=state.get("query_source")
-            if isinstance(state.get("query_source"), str)
-            else None,
+        from langchain_agentx.loop.graph.builtin_loop_control import (
+            get_loop_builtin_model_middleware,
         )
-        if synth is not None:
-            model_response = synth
+
+        runtime = config.get("configurable", {}).get("__pregel_runtime")
+        request = self._build_request(state, runtime, config=config)
+        mw = get_loop_builtin_model_middleware()
+
+        async def _handler(req: Any) -> Any:
+            synth = _model_response_if_context_token_blocked(
+                state_messages=state.get("messages", []),
+                name=self._name,
+                initial_response_format=self._initial_response_format,
+                structured_output_tools=self._structured_output_tools,
+                compaction_settings=self._compaction_settings,
+                query_source=state.get("query_source")
+                if isinstance(state.get("query_source"), str)
+                else None,
+            )
+            if synth is not None:
+                return synth
+            model_response, _ = await self._arun_async(req, state, config=config)
+            return model_response
+
+        wrapped = await mw.awrap_model_call(request, _handler)
+        abort_reason: str | None = None
+        if isinstance(wrapped, ExtendedModelResponse):
+            model_response = wrapped.model_response
+            cmd = wrapped.command
+            if isinstance(cmd, Command) and isinstance(cmd.update, dict):
+                reason = cmd.update.get("abort_terminal_reason")
+                if isinstance(reason, str):
+                    abort_reason = reason
         else:
-            model_response, _ = await self._arun_async(request, state, config=config)
+            model_response = wrapped
 
-        return self._build_state_update(
+        updates = self._build_state_update(
             state=state,
             model_response=model_response,
             mode="async",
         )
+        if abort_reason:
+            return list(updates) + [Command(update={"abort_terminal_reason": abort_reason})]
+        return updates
 
     # ===== 请求构建 =====
 

{langchain-agentx-python-2.1.5 → langchain-agentx-python-2.1.7}/langchain_agentx/loop/run_context.py

@@ -42,6 +42,9 @@ class RunContext:
     child_tasks: set[asyncio.Task] = field(default_factory=set)
     child_threads: set[threading.Thread] = field(default_factory=set)
     cancel_requested: bool = False
+    # D-EVT-6：宿主在 cancel_tree / killAll 时写入；finish 投影读取；缺省 unknown。
+    # 取值：escape | workflow_stop | kill_agents | unknown；禁止从「是否有后台」猜测。
+    cancel_source: str | None = None
 
     def register_child(self, task: asyncio.Task) -> None:
         self.child_tasks.add(task)

{langchain-agentx-python-2.1.5 → langchain-agentx-python-2.1.7}/langchain_agentx/loop/subagent/__init__.py

@@ -28,7 +28,10 @@ from langchain_agentx.loop.subagent.forked_runner import (
 )
 from langchain_agentx.loop.subagent.async_runner import (
     BackgroundAgentHandle,
+    BackgroundAgentLoopRequiredError,
     get_background_agent_handle,
+    kill_all_background_agents,
+    kill_background_agent,
     register_background_agent,
     run_async_agent_lifecycle,
 )
@@ -67,7 +70,10 @@ __all__ = [
     "_run_coroutine_sync",
     "register_background_agent",
     "get_background_agent_handle",
+    "kill_background_agent",
+    "kill_all_background_agents",
     "BackgroundAgentHandle",
+    "BackgroundAgentLoopRequiredError",
     "run_async_agent_lifecycle",
     "JsonlTranscriptStore",
     "SubagentTranscriptManager",