langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/loop/exit/reason_codes.py

@@ -0,0 +1,39 @@
+"""Reason code constants for loop transitions and termination."""
+
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# terminal_reason：对外唯一终态标签（CC 对齐枚举，写入 state）
+# ---------------------------------------------------------------------------
+TERMINAL_REASON_COMPLETED = "completed"
+TERMINAL_REASON_MAX_STEPS = "max_steps"
+TERMINAL_REASON_MAX_TURNS = "max_turns"
+TERMINAL_REASON_MAX_TOKENS = "max_tokens"
+TERMINAL_REASON_CONTENT_FILTER = "content_filter"
+TERMINAL_REASON_BLOCKING_LIMIT = "blocking_limit"
+TERMINAL_REASON_STOP_HOOK_PREVENTED = "stop_hook_prevented"
+TERMINAL_REASON_ERROR = "error"
+# CC queryLoop return.reason：中断 / hook 终局（middleware 或 tools 后写入 abort_terminal_reason）
+TERMINAL_REASON_ABORTED_STREAMING = "aborted_streaming"
+TERMINAL_REASON_ABORTED_TOOLS = "aborted_tools"
+TERMINAL_REASON_HOOK_STOPPED = "hook_stopped"
+
+# ---------------------------------------------------------------------------
+# transition.reason（控制流路由观测，不是终态）
+# ---------------------------------------------------------------------------
+TRANSITION_NEXT_TURN = "next_turn"
+TRANSITION_API_ERROR_TERMINAL = "api_error_terminal"
+TRANSITION_WITHHOLD_RECOVERY_RETRY = "withhold_recovery_retry"
+TRANSITION_WITHHOLD_RECOVERY_EXHAUSTED = "withhold_recovery_exhausted"
+TRANSITION_COLLAPSE_DRAIN_RETRY = "collapse_drain_retry"
+TRANSITION_REACTIVE_COMPACT_RETRY = "reactive_compact_retry"
+TRANSITION_MAX_OUTPUT_TOKENS_ESCALATE = "max_output_tokens_escalate"
+TRANSITION_MAX_OUTPUT_TOKENS_RECOVERY = "max_output_tokens_recovery"
+TRANSITION_MAX_OUTPUT_TOKENS_RECOVERY_EXHAUSTED = "max_output_tokens_recovery_exhausted"
+TRANSITION_TASK_NOTIFICATION_ARRIVED = "task_notification_arrived"
+TRANSITION_STOP_HOOK_PREVENTED = "stop_hook_prevented"
+TRANSITION_STOP_HOOK_BLOCKING = "stop_hook_blocking"
+TRANSITION_TOKEN_BUDGET_CONTINUATION = "token_budget_continuation"
+
+# token_budget continuation 默认上限（与 CC token budget nudge 次数护栏同向）
+DEFAULT_TOKEN_BUDGET_MAX_CONTINUATIONS = 3

langchain_agentx/loop/graph/__init__.py

@@ -0,0 +1,5 @@
+"""LangGraph 结构、factory、边与 middleware 组合。"""
+
+from .factory import create_loop_agent
+
+__all__ = ["create_loop_agent"]

langchain_agentx/loop/graph/builtin_loop_control.py

@@ -0,0 +1,197 @@
+"""
+内置 loop 控制：捕获 ``LoopAbortSignal``，写入 ``abort_terminal_reason``（及工具侧合成 ToolMessage）。
+
+始终由 ``create_loop_agent`` 注入到 ``wrap_model_call`` / ``wrap_tool_call`` 链的最外层，
+用户 middleware 在内层抛出 ``LoopAbortSignal`` 即可，无需手写 Command。
+"""
+
+from __future__ import annotations
+
+import copy
+import logging
+from typing import Any
+
+from langchain.agents.middleware.types import ExtendedModelResponse, ModelResponse
+from langchain_core.messages import AIMessage
+from langgraph.types import Command
+
+from ..exit.reason_codes import (
+    TERMINAL_REASON_ABORTED_STREAMING,
+    TERMINAL_REASON_ABORTED_TOOLS,
+    TERMINAL_REASON_HOOK_STOPPED,
+)
+from ..loop_abort import LoopAbortSignal
+from ..model.orphan_tool_results import synthetic_tool_messages_for_orphan_tool_calls
+from ...tool_runtime.permission_context import rotate_auto_approved_window
+
+logger = logging.getLogger(__name__)
+
+
+def _abort_model_content(reason: str, detail: str | None) -> str:
+    if detail:
+        return f"[Agent loop aborted: {reason}] {detail}"
+    return f"[Agent loop aborted: {reason}]"
+
+
+def _session_store_from_request(request: Any) -> Any | None:
+    try:
+        from langgraph.config import get_config
+
+        config = get_config()
+    except Exception as exc:
+        logger.debug("failed to fetch langgraph config for session store: %s", exc)
+        config = None
+    if isinstance(config, dict):
+        configurable = config.get("configurable", {}) or {}
+        return configurable.get("session_store")
+    return None
+
+
+class _LoopBuiltinModelControl:
+    """内部单例：捕获模型侧的 ``LoopAbortSignal``。"""
+
+    def wrap_model_call(self, request: Any, handler: Any) -> Any:
+        rotate_auto_approved_window(_session_store_from_request(request))
+        try:
+            return handler(request)
+        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}),
+            )
+
+    async def awrap_model_call(self, request: Any, handler: Any) -> Any:
+        rotate_auto_approved_window(_session_store_from_request(request))
+        try:
+            return await handler(request)
+        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}),
+            )
+
+
+_LOOP_BUILTIN_MODEL_SINGLETON = _LoopBuiltinModelControl()
+
+
+def get_loop_builtin_model_middleware() -> _LoopBuiltinModelControl:
+    """返回全局单例，避免重复计入用户 middleware 列表。"""
+    return _LOOP_BUILTIN_MODEL_SINGLETON
+
+
+def _model_for_agent_tool(state: Any) -> Any | None:
+    config: dict | None = None
+    try:
+        from langgraph.config import get_config
+
+        config = get_config()
+    except Exception as exc:
+        logger.debug("failed to fetch langgraph config for loop model: %s", exc)
+        config = None
+    loop_config = config.get("configurable", {}).get("loop_config") if config else None
+    model = getattr(loop_config, "model", None)
+    if isinstance(model, str):
+        return model
+    if model is None:
+        return None
+    model_name = getattr(model, "model_name", None)
+    return model_name if isinstance(model_name, str) else None
+
+
+def _with_injected_agent_tool_model(request: Any) -> Any:
+    """在 Agent 工具调用缺失 model 时显式注入父 loop 模型。"""
+    tool_call = getattr(request, "tool_call", None)
+    if not isinstance(tool_call, dict) or tool_call.get("name") != "Agent":
+        return request
+    args = tool_call.get("args")
+    if not isinstance(args, dict) or args.get("model"):
+        return request
+    model = _model_for_agent_tool(getattr(request, "state", None))
+    if model is None:
+        return request
+    patched_request = copy.copy(request)
+    patched_tool_call = dict(tool_call)
+    patched_args = dict(args)
+    patched_args["model"] = model
+    patched_tool_call["args"] = patched_args
+    patched_request.tool_call = patched_tool_call
+    return patched_request
+
+
+def builtin_sync_tool_wrapper(request: Any, handler: Any) -> Any:
+    try:
+        return handler(_with_injected_agent_tool_model(request))
+    except LoopAbortSignal as sig:
+        if sig.terminal_reason != TERMINAL_REASON_ABORTED_TOOLS:
+            raise
+        tc = request.tool_call
+        pending = [dict(tc)] if isinstance(tc, dict) else []
+        synth = (
+            synthetic_tool_messages_for_orphan_tool_calls(
+                pending_tool_calls=pending,
+                content_template=(
+                    "[Tool execution aborted; synthetic result.]"
+                    + (f" {sig.detail}" if sig.detail else "")
+                ),
+            )
+            if pending
+            else []
+        )
+        return Command(
+            update={
+                "abort_terminal_reason": TERMINAL_REASON_ABORTED_TOOLS,
+                "messages": synth,
+            }
+        )
+
+
+async def builtin_async_tool_wrapper(request: Any, handler: Any) -> Any:
+    try:
+        return await handler(_with_injected_agent_tool_model(request))
+    except LoopAbortSignal as sig:
+        if sig.terminal_reason != TERMINAL_REASON_ABORTED_TOOLS:
+            raise
+        tc = request.tool_call
+        pending = [dict(tc)] if isinstance(tc, dict) else []
+        synth = (
+            synthetic_tool_messages_for_orphan_tool_calls(
+                pending_tool_calls=pending,
+                content_template=(
+                    "[Tool execution aborted; synthetic result.]"
+                    + (f" {sig.detail}" if sig.detail else "")
+                ),
+            )
+            if pending
+            else []
+        )
+        return Command(
+            update={
+                "abort_terminal_reason": TERMINAL_REASON_ABORTED_TOOLS,
+                "messages": synth,
+            }
+        )
+
+
+__all__ = [
+    "builtin_async_tool_wrapper",
+    "builtin_sync_tool_wrapper",
+    "get_loop_builtin_model_middleware",
+]