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

{langchain-agentx-python-2.1.6/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.6
+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.6 → langchain-agentx-python-2.1.7}/langchain_agentx/__init__.py

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

{langchain-agentx-python-2.1.6 → 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.6 → 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.6 → langchain-agentx-python-2.1.7}/langchain_agentx/loop/subagent/async_runner.py

@@ -13,6 +13,7 @@ loop/subagent/async_runner.py — 子 Agent 异步生命周期管理
 
 当前裁剪范围：
   P0：删除 C4；后台仅 C3。P2：killAll 仅遍历 _BACKGROUND_HANDLES（可 Task.cancel）。
+  P2 投影：lifecycle / _mark_cancelled_terminal → OOB task-notification（D-EVT-5）。
 """
 
 from __future__ import annotations
@@ -22,7 +23,7 @@ import logging
 import os
 import uuid
 from dataclasses import dataclass
-from typing import Any
+from typing import Any, Literal
 
 from langchain_agentx.loop.exit.reason_codes import (
     TERMINAL_REASON_ABORTED_STREAMING,
@@ -106,11 +107,34 @@ def _is_cancel_like_result(result: Any) -> bool:
     return getattr(result, "error_kind", None) == "aborted"
 
 
+def _emit_task_notification_bookend(
+    *,
+    task_id: str,
+    status: Literal["completed", "failed", "stopped"],
+    output_file: str = "",
+    summary: str = "",
+    agent_id: str | None = None,
+    terminal_reason: str | None = None,
+) -> None:
+    """D-EVT-5：后台终态 OOB bookend；同 task_id 去重在 sink 内完成。"""
+    from langchain_agentx.observability.events.oob_event_sink import get_oob_event_sink
+
+    get_oob_event_sink().emit_task_notification(
+        task_id=task_id,
+        status=status,
+        output_file=output_file,
+        summary=summary,
+        agent_id=agent_id,
+        terminal_reason=terminal_reason,
+    )
+
+
 def _mark_cancelled_terminal(
     *,
     task_id: str,
     output_file: str,
     task_runtime: Any | None,
+    agent_id: str | None = None,
 ) -> None:
     """写 cancelled 输出 + TaskRuntime STOPPED（对齐 TaskRuntime.cancel / CC killed）。"""
     try:
@@ -119,18 +143,27 @@ def _mark_cancelled_terminal(
             fp.write("cancelled")
     except Exception:
         logger.debug("failed to write cancelled output for task_id=%s", task_id, exc_info=True)
-    if task_runtime is None:
-        return
-    try:
-        task_runtime.mark_terminal(
-            task_id,
-            TaskStatus.STOPPED,
-            "subagent cancelled",
-            output_file=output_file,
-            terminal_reason="cancelled",
-        )
-    except Exception:
-        logger.debug("failed to mark cancelled terminal for task_id=%s", task_id, exc_info=True)
+    if task_runtime is not None:
+        try:
+            task_runtime.mark_terminal(
+                task_id,
+                TaskStatus.STOPPED,
+                "subagent cancelled",
+                output_file=output_file,
+                terminal_reason="cancelled",
+            )
+        except Exception:
+            logger.debug(
+                "failed to mark cancelled terminal for task_id=%s", task_id, exc_info=True
+            )
+    _emit_task_notification_bookend(
+        task_id=task_id,
+        status="stopped",
+        output_file=output_file,
+        summary="cancelled",
+        agent_id=agent_id,
+        terminal_reason="cancelled",
+    )
 
 
 async def _execute_background_lifecycle(
@@ -146,6 +179,7 @@ async def _execute_background_lifecycle(
     """共享后台生命周期：run_subagent → 写 output → task_runtime 终态。"""
     execution_ctx = ctx
     execution_ctx.is_async = False
+    agent_id = getattr(ctx, "agent_id", None)
     try:
         result = await run_subagent(
             ctx=execution_ctx,
@@ -160,37 +194,64 @@ async def _execute_background_lifecycle(
                 task_id=task_id,
                 output_file=output_file,
                 task_runtime=task_runtime,
+                agent_id=agent_id,
             )
             return
         with open(output_file, "w", encoding="utf-8") as fp:
             fp.write(result.content)
+        summary = (
+            result.content[:500]
+            if result.content
+            else (result.error_message or "subagent completed")
+        )
+        notif_status: Literal["completed", "failed"] = (
+            "completed" if result.status == "completed" else "failed"
+        )
         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"),
+                summary,
                 output_file=output_file,
                 terminal_reason=result.terminal_reason or None,
             )
+        _emit_task_notification_bookend(
+            task_id=task_id,
+            status=notif_status,
+            output_file=output_file,
+            summary=summary,
+            agent_id=agent_id,
+            terminal_reason=result.terminal_reason or None,
+        )
     except asyncio.CancelledError:
         _mark_cancelled_terminal(
             task_id=task_id,
             output_file=output_file,
             task_runtime=task_runtime,
+            agent_id=agent_id,
         )
         raise
     except Exception as exc:
         with open(output_file, "w", encoding="utf-8") as fp:
             fp.write(str(exc))
+        summary = f"Subagent background lifecycle failed: {exc}"
         if task_runtime is not None:
             task_runtime.mark_terminal(
                 task_id,
                 TaskStatus.FAILED,
-                f"Subagent background lifecycle failed: {exc}",
+                summary,
                 output_file=output_file,
                 terminal_reason=TERMINAL_REASON_GRAPH_RUNTIME_ERROR,
             )
+        _emit_task_notification_bookend(
+            task_id=task_id,
+            status="failed",
+            output_file=output_file,
+            summary=summary,
+            agent_id=agent_id,
+            terminal_reason=TERMINAL_REASON_GRAPH_RUNTIME_ERROR,
+        )
 
 
 def register_background_agent(
@@ -309,6 +370,7 @@ def kill_background_agent(task_id: str) -> bool:
         task_id=task_id,
         output_file=handle.output_file,
         task_runtime=handle.task_runtime,
+        agent_id=handle.agent_id,
     )
     return True
 

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

@@ -10,13 +10,21 @@ from .events import (
     LangchainAgentEvent,
     LangchainAgentEventType,
     LangGraphToLangchainAgentEventAdapter,
+    OOB_EVENT_QUEUE_CAP,
+    OobEventSink,
     RecoveryAction,
     RecoveryActionResolver,
     RecoveryPolicy,
     RecoveryPolicyMode,
     coerce_recovery_policy,
     create_langgraph_event_adapter,
+    drain_oob_events,
     enrich_run_result,
+    ensure_oob_event_sink,
+    get_oob_event_sink,
+    install_oob_event_sink,
+    reset_oob_event_sink,
+    teardown_oob_event_sink,
 )
 from .replay.service import (
     export_call_chain,
@@ -62,6 +70,8 @@ __all__ = [
     "LogContext",
     "LoggingConfigBuilder",
     "OBS_SCHEMA_VERSION",
+    "OOB_EVENT_QUEUE_CAP",
+    "OobEventSink",
     "ObservabilityLoggerAdapter",
     "build_log_context",
     "configure_logging_once",
@@ -69,6 +79,12 @@ __all__ = [
     "LangchainAgentEventType",
     "LangGraphToLangchainAgentEventAdapter",
     "create_langgraph_event_adapter",
+    "drain_oob_events",
+    "ensure_oob_event_sink",
+    "get_oob_event_sink",
+    "install_oob_event_sink",
+    "reset_oob_event_sink",
+    "teardown_oob_event_sink",
     "RecoveryAction",
     "RecoveryActionResolver",
     "RecoveryPolicy",

{langchain-agentx-python-2.1.6 → langchain-agentx-python-2.1.7}/langchain_agentx/observability/events/__init__.py

@@ -22,6 +22,16 @@ from .factory import (
     ILangGraphEventAdapter,
     create_langgraph_event_adapter,
 )
+from .oob_event_sink import (
+    OOB_EVENT_QUEUE_CAP,
+    OobEventSink,
+    drain_oob_events,
+    ensure_oob_event_sink,
+    get_oob_event_sink,
+    install_oob_event_sink,
+    reset_oob_event_sink,
+    teardown_oob_event_sink,
+)
 
 __all__ = [
     "LangchainAgentEventType",
@@ -40,4 +50,12 @@ __all__ = [
     "enrich_run_result",
     "ILangGraphEventAdapter",
     "create_langgraph_event_adapter",
+    "OOB_EVENT_QUEUE_CAP",
+    "OobEventSink",
+    "drain_oob_events",
+    "ensure_oob_event_sink",
+    "get_oob_event_sink",
+    "install_oob_event_sink",
+    "reset_oob_event_sink",
+    "teardown_oob_event_sink",
 ]

{langchain-agentx-python-2.1.6 → langchain-agentx-python-2.1.7}/langchain_agentx/observability/events/agent_event_projector.py

@@ -139,6 +139,8 @@ class LangchainAgentEventType(Enum):
     TASK_NOTIFICATION_ENQUEUED = "task-notification-enqueued"
     TASK_NOTIFICATION_CONSUMED = "task-notification-consumed"
     TASK_TERMINATED = "task-terminated"
+    # D-EVT-5：OOB 后台终态书档（对标 CC system/task_notification）
+    TASK_NOTIFICATION = "task-notification"
 
 
 @dataclass
@@ -1249,6 +1251,22 @@ class AgentEventProjector:
                 tool_name=name,
                 session_id=str(child_session_id) if child_session_id else None,
             )
+            # D-EVT-5′：图内 SUBAGENT_END 覆盖时登记；若 payload 含 task_id 则抑制同 id OOB
+            end_task_id: str | None = None
+            if isinstance(output, dict):
+                raw_tid = output.get("task_id")
+                if not isinstance(raw_tid, str):
+                    artifact = output.get("artifact")
+                    if isinstance(artifact, dict):
+                        raw_tid = artifact.get("task_id")
+                if isinstance(raw_tid, str) and raw_tid.strip():
+                    end_task_id = raw_tid.strip()
+            if end_task_id:
+                from langchain_agentx.observability.events.oob_event_sink import (
+                    get_oob_event_sink,
+                )
+
+                get_oob_event_sink().note_terminal_projected(end_task_id)
             self._on_subagent_end_boundary()
 
         self.state.current_tool = None

{langchain-agentx-python-2.1.6 → langchain-agentx-python-2.1.7}/langchain_agentx/observability/events/finish_event_payload_composer.py

@@ -11,6 +11,7 @@ finish_event_payload_composer.py — finish 事件 data 组装协作者
 当前裁剪范围：
     - 不发射事件、不读 LangGraph raw event
     - 不处理 SubAgent 终态；model_retry 进度见 retry_progress.py（Phase 6）
+    - INTERRUPT 文案仅经 display_interrupt_text 投影（D-EVT-4），不入 messages
 """
 
 from __future__ import annotations
@@ -22,8 +23,11 @@ from langchain_core.messages import AIMessage
 
 from langchain_agentx.loop.exit.reason_codes import (
     ERROR_TERMINAL_REASONS,
+    TERMINAL_REASON_ABORTED_STREAMING,
+    TERMINAL_REASON_ABORTED_TOOLS,
     TERMINAL_REASON_COMPLETED,
     TERMINAL_REASON_ERROR,
+    TERMINAL_REASON_HOOK_STOPPED,
     TERMINAL_REASON_MAX_TOKENS,
     TRANSITION_API_ERROR_TERMINAL,
     TRANSITION_CONTEXT_WINDOW_RECOVERY_EXHAUSTED,
@@ -32,6 +36,7 @@ from langchain_agentx.loop.exit.reason_codes import (
 )
 from langchain_agentx.loop.exit.terminal import read_terminal_reason
 from langchain_agentx.loop.exit.withheld_error import resolve_overflow_kind
+from langchain_agentx.loop.run_context import get_run_context
 
 _RECOVERY_EXHAUSTED_TRANSITIONS = frozenset(
     {
@@ -41,6 +46,17 @@ _RECOVERY_EXHAUSTED_TRANSITIONS = frozenset(
     }
 )
 
+# D-EVT-2/4：用户取消 display 文案（对齐 CC INTERRUPT；禁止注入 messages）
+DEFAULT_DISPLAY_INTERRUPT_TEXT = "[Request interrupted by user]"
+ERROR_KIND_USER_CANCELLED = "user_cancelled"
+ERROR_KIND_HOOK_STOPPED = "hook_stopped"
+_USER_CANCELLED_TERMINAL_REASONS = frozenset(
+    {
+        TERMINAL_REASON_ABORTED_STREAMING,
+        TERMINAL_REASON_ABORTED_TOOLS,
+    }
+)
+
 _SENSITIVE_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = (
     (re.compile(r"sk-[a-zA-Z0-9_-]{8,}", re.I), "<redacted_api_key>"),
     (re.compile(r"bearer\s+\S+", re.I), "Bearer <redacted>"),
@@ -157,7 +173,7 @@ class FinishEventPayloadComposer:
             messages=messages,
         )
 
-        return {
+        payload: dict[str, Any] = {
             "graph_name": graph_name,
             "answer": answer,
             "terminal_reason": terminal_reason,
@@ -168,6 +184,10 @@ class FinishEventPayloadComposer:
             "error_kind": error_kind,
             "recovery_exhausted": recovery_exhausted,
         }
+        if error_kind == ERROR_KIND_USER_CANCELLED:
+            payload["display_interrupt_text"] = DEFAULT_DISPLAY_INTERRUPT_TEXT
+            payload["cancel_source"] = self._resolve_cancel_source(snap)
+        return payload
 
     @staticmethod
     def _resolve_terminal_reason(
@@ -265,6 +285,25 @@ class FinishEventPayloadComposer:
         if terminal_reason == TERMINAL_REASON_COMPLETED:
             return "unknown"
 
+        if terminal_reason in _USER_CANCELLED_TERMINAL_REASONS:
+            return ERROR_KIND_USER_CANCELLED
+
+        if terminal_reason == TERMINAL_REASON_HOOK_STOPPED:
+            return ERROR_KIND_HOOK_STOPPED
+
+        return "unknown"
+
+    @staticmethod
+    def _resolve_cancel_source(snap: dict[str, Any]) -> str:
+        """D-EVT-6：宿主写入优先；缺省 unknown；禁止猜测反推。"""
+        raw = snap.get("cancel_source")
+        if raw is not None and str(raw):
+            return str(raw)
+        ctx = get_run_context()
+        if ctx is not None:
+            source = getattr(ctx, "cancel_source", None)
+            if source is not None and str(source):
+                return str(source)
         return "unknown"
 
     @staticmethod
@@ -323,6 +362,9 @@ class FinishEventPayloadComposer:
 
 
 __all__ = [
+    "DEFAULT_DISPLAY_INTERRUPT_TEXT",
+    "ERROR_KIND_HOOK_STOPPED",
+    "ERROR_KIND_USER_CANCELLED",
     "FinishEventPayloadComposer",
     "sanitize_finish_error_message",
 ]

{langchain-agentx-python-2.1.6 → langchain-agentx-python-2.1.7}/langchain_agentx/observability/events/finish_outcome.py

@@ -20,8 +20,15 @@ from dataclasses import dataclass
 from enum import Enum
 from typing import Any, Literal
 
+from langchain_agentx.loop.exit.reason_codes import (
+    TERMINAL_REASON_ABORTED_STREAMING,
+    TERMINAL_REASON_ABORTED_TOOLS,
+    TERMINAL_REASON_HOOK_STOPPED,
+)
 from langchain_agentx.loop.exit.terminal import read_terminal_reason
 from langchain_agentx.observability.events.finish_event_payload_composer import (
+    ERROR_KIND_HOOK_STOPPED,
+    ERROR_KIND_USER_CANCELLED,
     FinishEventPayloadComposer,
 )
 
@@ -53,6 +60,27 @@ FINISH_OUTCOME_KEYS = frozenset(
 
 RecoveryPolicyMode = Literal["interactive", "auto"]
 
+_CANCEL_ERROR_KINDS = frozenset(
+    {
+        ERROR_KIND_USER_CANCELLED,
+        ERROR_KIND_HOOK_STOPPED,
+    }
+)
+_CANCEL_TERMINAL_REASONS = frozenset(
+    {
+        TERMINAL_REASON_ABORTED_STREAMING,
+        TERMINAL_REASON_ABORTED_TOOLS,
+        TERMINAL_REASON_HOOK_STOPPED,
+    }
+)
+
+
+def _is_cancel_outcome(outcome: "FinishOutcome") -> bool:
+    """用户取消 / hook 终局：禁止建议 compact（D-EVT-2 / CLI 投影）。"""
+    if outcome.error_kind in _CANCEL_ERROR_KINDS:
+        return True
+    return outcome.terminal_reason in _CANCEL_TERMINAL_REASONS
+
 
 @dataclass(frozen=True)
 class RecoveryPolicy:
@@ -149,6 +177,7 @@ class FinishOutcomeParser:
         snap = dict(state or {})
         terminal = snap.get("terminal") if isinstance(snap.get("terminal"), dict) else None
         if terminal is not None and "is_error" in terminal:
+            # from_terminal 已对缺失 error_kind 做 composer 对齐补推（D-EVT-2）
             return self.from_terminal(terminal, answer=answer)
         msgs = messages if messages is not None else snap.get("messages")
         if not isinstance(msgs, list):
@@ -178,11 +207,23 @@ class FinishOutcomeParser:
         *,
         answer: str = "",
     ) -> FinishOutcome:
+        terminal_reason = _optional_str(read_terminal_reason(terminal))
+        is_error = bool(terminal.get("is_error"))
+        error_kind = _optional_str(terminal.get("error_kind"))
+        if is_error and error_kind is None:
+            error_kind = FinishEventPayloadComposer._infer_error_kind(
+                terminal_reason=terminal_reason,
+                is_error=True,
+                withheld_error=None,
+                transition_reason=None,
+                terminal=terminal,
+                messages=None,
+            )
         return FinishOutcome(
-            terminal_reason=_optional_str(read_terminal_reason(terminal)),
-            is_error=bool(terminal.get("is_error")),
+            terminal_reason=terminal_reason,
+            is_error=is_error,
             recoverable=bool(terminal.get("recoverable")),
-            error_kind=_optional_str(terminal.get("error_kind")),
+            error_kind=error_kind,
             recovery_exhausted=bool(terminal.get("recovery_exhausted")),
             errors=tuple(str(e) for e in (terminal.get("errors") or []) if e),
             answer=answer,
@@ -220,6 +261,8 @@ class RecoveryActionResolver:
     ) -> RecoveryAction:
         if not outcome.is_error:
             return RecoveryAction.NONE
+        if _is_cancel_outcome(outcome):
+            return RecoveryAction.FAIL
         if not outcome.recoverable:
             return RecoveryAction.FAIL
 
@@ -242,12 +285,13 @@ class RecoveryActionResolver:
 
     @staticmethod
     def blocks_auto_compact(outcome: FinishOutcome) -> bool:
-        """Workflow 门禁：recovery_exhausted 后禁止再次 auto-compact（Phase 5.5）。"""
+        """Workflow 门禁：cancel / recovery_exhausted 后禁止再次 auto-compact。"""
         if not outcome.is_error:
             return False
+        if _is_cancel_outcome(outcome):
+            return True
         return outcome.recovery_exhausted
 
-
 def enrich_run_result(
     result: dict[str, Any],
     *,

{langchain-agentx-python-2.1.6 → langchain-agentx-python-2.1.7}/langchain_agentx/observability/events/langchain_agentx_event_adapter.py

@@ -28,6 +28,7 @@ from langchain_agentx.observability.events.agent_event_projector import (
     LangchainAgentEvent,
     LangchainAgentEventType,
 )
+from langchain_agentx.observability.events.oob_event_sink import drain_oob_events
 
 
 class LangGraphToLangchainAgentEventAdapter:
@@ -51,12 +52,19 @@ class LangGraphToLangchainAgentEventAdapter:
     async def adapt(
         self, events: AsyncIterator[Dict[str, Any]]
     ) -> AsyncIterator[LangchainAgentEvent]:
-        """主转换函数：将 LangGraph 事件流转换为 LangChain AgentX 风格事件流。"""
+        """主转换函数：将 LangGraph 事件流转换为 LangChain AgentX 风格事件流。
+
+        每批 raw 事件后合并 OOB task-notification（D-EVT-5 / D-EVT-10）。
+        """
         self._projector.reset_stream_closeout_diagnostics()
         try:
             async for event in events:
                 async for oc_event in self._projector.consume(event):
                     yield oc_event
+                for oob in drain_oob_events():
+                    yield oob
+            for oob in drain_oob_events():
+                yield oob
         finally:
             self._projector.log_stream_closeout_diagnostics()