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

langchain_agentx/loop/graph/graph_edges.py

@@ -0,0 +1,820 @@
+"""
+LangChain AgentX agent 的图路由与条件边构建。
+
+本模块从 `factory.py` 中拆分出与具体业务无关的 LangGraph 结构逻辑：
+- 基于 OpenCode 状态字段（例如 `should_end`、`structured_response`）决定下一跳节点
+- 构建 model ↔ tools ↔ hook 主链 之间的条件边
+- 封装 middleware `jump_to` 语义到统一的 `_resolve_jump` 辅助函数
+
+与 LangChain 官方 agent 的差异在于：
+- 这里的边逻辑假设退出由 LangChain AgentX 的状态/finish_reason 控制，
+  而不是传统的"是否还有 tool_calls 或 recursion_limit"模式。
+
+可观测性：
+- loop_controller 边函数中采集 loop.decision 事件（含 reason_code / evidence）
+- 通过 event_emitter 统一发射事件，避免直接依赖 TraceCollector
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, List, Tuple
+
+from langchain.agents.middleware.types import (
+    AgentState,
+    ContextT,
+    JumpTo,
+    ResponseT,
+    _InputAgentState,
+    _OutputAgentState,
+)
+from langchain.agents.structured_output import OutputToolBinding
+from langchain_core.messages import AIMessage, AnyMessage, HumanMessage, ToolMessage
+from langgraph._internal._runnable import RunnableCallable
+from langgraph.graph.state import StateGraph
+from langgraph.prebuilt.tool_node import ToolCallWithContext, ToolNode
+from langgraph.types import Send
+from ..hook.async_hook_runner import AsyncHookRunner
+from ..hook.types import HookContext, HookEvent
+
+# 导入事件发射器（CLI Phase 1A 骨架）
+from ...observability.trace.event_emitter import emit_loop_decision_event
+
+from ..exit.exit_logic import (
+    ESCALATED_MAX_OUTPUT_TOKENS,
+    MAX_OUTPUT_TOKENS_RECOVERY_LIMIT,
+    MAX_STEPS_PROMPT,
+    TOKEN_BUDGET_NUDGE_USER_MESSAGE,
+    resolve_escalated_max_output_tokens,
+)
+from ..exit.reason_codes import (
+    DEFAULT_TOKEN_BUDGET_MAX_CONTINUATIONS,
+    TERMINAL_REASON_ABORTED_STREAMING,
+    TERMINAL_REASON_ABORTED_TOOLS,
+    TERMINAL_REASON_COMPLETED,
+    TERMINAL_REASON_HOOK_STOPPED,
+    TERMINAL_REASON_MAX_STEPS,
+    TERMINAL_REASON_MAX_TOKENS,
+    TERMINAL_REASON_STOP_HOOK_PREVENTED,
+    TRANSITION_API_ERROR_TERMINAL,
+    TRANSITION_COLLAPSE_DRAIN_RETRY,
+    TRANSITION_MAX_OUTPUT_TOKENS_ESCALATE,
+    TRANSITION_MAX_OUTPUT_TOKENS_RECOVERY,
+    TRANSITION_MAX_OUTPUT_TOKENS_RECOVERY_EXHAUSTED,
+    TRANSITION_REACTIVE_COMPACT_RETRY,
+    TRANSITION_STOP_HOOK_BLOCKING,
+    TRANSITION_STOP_HOOK_PREVENTED,
+    TRANSITION_TASK_NOTIFICATION_ARRIVED,
+    TRANSITION_TOKEN_BUDGET_CONTINUATION,
+    TRANSITION_WITHHOLD_RECOVERY_RETRY,
+)
+
+_ABORT_TERMINAL_REASONS = frozenset(
+    {
+        TERMINAL_REASON_ABORTED_STREAMING,
+        TERMINAL_REASON_ABORTED_TOOLS,
+        TERMINAL_REASON_HOOK_STOPPED,
+    }
+)
+
+
+def _execute_hook_common(
+    state: dict[str, Any],
+    *,
+    event: HookEvent,
+    tool_name: str | None = None,
+    tool_input: dict[str, Any] | None = None,
+    tool_result: Any = None,
+) -> dict[str, Any] | None:
+    hook_engine = state.get("_hook_engine")
+    if hook_engine is None:
+        return None
+    hook_runner = state.get("_hook_runner")
+    if not isinstance(hook_runner, AsyncHookRunner):
+        hook_runner = AsyncHookRunner()
+    ctx_kwargs: dict[str, Any] = {
+        "event": event,
+        "state": state,
+        "session_id": state.get("_run_id"),
+    }
+    if tool_name is not None:
+        ctx_kwargs["tool_name"] = tool_name
+    if tool_input is not None:
+        ctx_kwargs["tool_input"] = tool_input
+    if tool_result is not None:
+        ctx_kwargs["tool_result"] = tool_result
+    ctx = HookContext(**ctx_kwargs)
+    result = hook_runner.run(hook_engine, ctx)
+    return {
+        "prevent_continuation": bool(result.prevent_continuation),
+        "blocking_errors": list(result.blocking_errors) or None,
+        "permission_behavior": result.permission_behavior,
+        "hook_permission_decision_reason": result.hook_permission_decision_reason,
+        "updated_input": result.updated_input,
+    }
+
+
+def _execute_hook_for_tool(
+    state: dict[str, Any],
+    *,
+    event: HookEvent,
+    tool_name: str,
+    tool_input: dict[str, Any] | None,
+    tool_result: Any = None,
+) -> dict[str, Any] | None:
+    return _execute_hook_common(
+        state,
+        event=event,
+        tool_name=tool_name,
+        tool_input=tool_input,
+        tool_result=tool_result,
+    )
+
+
+def _execute_hook_inline(
+    state: dict[str, Any],
+    *,
+    event: HookEvent,
+) -> dict[str, Any] | None:
+    """执行非工具类 hook 事件（如 STOP_FAILURE），不改变既有路由语义。"""
+    return _execute_hook_common(
+        state,
+        event=event,
+        tool_name=None,
+        tool_input=None,
+        tool_result=None,
+    )
+
+
+def _is_api_error_assistant_message(msg: AIMessage | None) -> bool:
+    """CC §5.7 优先级 4：API/鉴权类错误应跳过 stop hooks，直接终局。"""
+    if msg is None:
+        return False
+    meta = getattr(msg, "response_metadata", None) or {}
+    if not isinstance(meta, dict):
+        return False
+    if meta.get("langchain_agentx_api_error") is True:
+        return True
+    err = meta.get("error")
+    return isinstance(err, dict) and bool(err)
+
+
+def _resolve_jump(
+    jump_to: JumpTo | None,
+    *,
+    model_destination: str,
+    end_destination: str,
+) -> str | None:
+    if jump_to == "model":
+        return model_destination
+    if jump_to == "end":
+        return end_destination
+    if jump_to == "tools":
+        return "tools"
+    return None
+
+
+def _fetch_last_ai_and_tool_messages(
+    messages: List[AnyMessage],
+) -> Tuple[AIMessage | None, List[ToolMessage]]:
+    """Return the last AI message and any subsequent tool messages."""
+    for i in range(len(messages) - 1, -1, -1):
+        if isinstance(messages[i], AIMessage):
+            last_ai_message = messages[i]
+            tool_messages = [m for m in messages[i + 1 :] if isinstance(m, ToolMessage)]
+            return last_ai_message, tool_messages
+
+    return None, []
+
+
+class LoopControllerEdge:
+    """Loop controller 边决策器。"""
+
+    def __init__(
+        self,
+        *,
+        model_destination: str,
+        tools_destination: str,
+        structured_output_tools: dict[str, OutputToolBinding[Any]],
+        end_destination: str,
+        max_output_tokens_cap: int | None = None,
+        task_reconcile_destination: str | None = None,
+        has_pending_task_notifications: Callable[[dict[str, Any]], bool] | None = None,
+        token_budget_max_continuations: int | None = None,
+    ) -> None:
+        self._model_destination = model_destination
+        self._tools_destination = tools_destination
+        self._structured_output_tools = structured_output_tools
+        self._end_destination = end_destination
+        self._max_output_tokens_cap = max_output_tokens_cap
+        self._task_reconcile_destination = task_reconcile_destination
+        self._has_pending_task_notifications = has_pending_task_notifications
+        self._tb_max_cap = int(
+            token_budget_max_continuations
+            if token_budget_max_continuations is not None
+            else DEFAULT_TOKEN_BUDGET_MAX_CONTINUATIONS
+        )
+
+    def __call__(self, state: dict[str, Any]) -> str | List[Send] | None:
+        jump_result = self._handle_jump(state)
+        if jump_result is not None:
+            return jump_result
+        abort_result = self._handle_abort(state)
+        if abort_result is not None:
+            return abort_result
+        withheld_result = self._handle_withheld_error(state)
+        if withheld_result is not None:
+            return withheld_result
+        if bool(state.get("should_end")):
+            return self._handle_terminal(state)
+        return self._handle_continue(state)
+
+    def _handle_jump(self, state: dict[str, Any]) -> str | None:
+        if jump_to := state.get("jump_to"):
+            resolved = _resolve_jump(
+                jump_to,
+                model_destination=self._model_destination,
+                end_destination=self._end_destination,
+            )
+            emit_loop_decision_event(
+                state=state,
+                decision="jump_to",
+                selected_edge=resolved,
+                reason_code="middleware_jump_to",
+                evidence={"jump_to": jump_to, "step": state.get("step", 0)},
+            )
+            return resolved
+        return None
+
+    def _task_reconcile_or_end(self, state: dict[str, Any]) -> str:
+        if (
+            self._task_reconcile_destination
+            and self._has_pending_task_notifications
+            and self._has_pending_task_notifications(state)
+        ):
+            state["transition"] = {"reason": TRANSITION_TASK_NOTIFICATION_ARRIVED}
+            emit_loop_decision_event(
+                state=state,
+                decision="task_reconcile",
+                selected_edge=self._task_reconcile_destination,
+                reason_code="pending_task_notifications",
+                evidence={
+                    "should_end": state.get("should_end"),
+                    "terminal_reason": state.get("terminal_reason"),
+                    "step": state.get("step", 0),
+                },
+            )
+            return self._task_reconcile_destination
+        emit_loop_decision_event(
+            state=state,
+            decision="terminal",
+            selected_edge=self._end_destination,
+            reason_code="should_end_terminal",
+            evidence={
+                "should_end": state.get("should_end"),
+                "terminal_reason": state.get("terminal_reason"),
+                "step": state.get("step", 0),
+            },
+        )
+        return self._end_destination
+
+    def _handle_abort(self, state: dict[str, Any]) -> str | None:
+        abort_tr = state.get("abort_terminal_reason")
+        if abort_tr not in _ABORT_TERMINAL_REASONS:
+            return None
+        state["should_end"] = True
+        state["terminal_reason"] = abort_tr
+        state["abort_terminal_reason"] = None
+        state["transition"] = {"reason": abort_tr}
+        emit_loop_decision_event(
+            state=state,
+            decision="terminal",
+            selected_edge=(
+                self._end_destination
+                if not self._task_reconcile_destination
+                else "task_reconcile_or_end"
+            ),
+            reason_code=abort_tr,
+            evidence={
+                "abort_terminal_reason": abort_tr,
+                "step": state.get("step", 0),
+            },
+        )
+        return self._task_reconcile_or_end(state)
+
+    def _handle_withheld_error(self, state: dict[str, Any]) -> str | None:
+        withheld_error = state.get("withheld_error")
+        if not withheld_error:
+            return None
+        if withheld_error.get("reason") == TERMINAL_REASON_MAX_TOKENS:
+            return self._handle_max_tokens_recovery(state, withheld_error)
+        return self._handle_generic_withheld(state, withheld_error)
+
+    def _handle_max_tokens_recovery(
+        self,
+        state: dict[str, Any],
+        withheld_error: dict[str, Any],
+    ) -> str:
+        override = state.get("max_output_tokens_override")
+        recovery_count = int(state.get("max_output_tokens_recovery_count", 0) or 0)
+        if override is None:
+            escalated_override = resolve_escalated_max_output_tokens(self._max_output_tokens_cap)
+            state["max_output_tokens_override"] = escalated_override
+            state["transition"] = {
+                "reason": TRANSITION_MAX_OUTPUT_TOKENS_ESCALATE,
+                "error_reason": TERMINAL_REASON_MAX_TOKENS,
+                "override": escalated_override,
+            }
+            emit_loop_decision_event(
+                state=state,
+                decision="continue",
+                selected_edge=self._model_destination,
+                reason_code="max_output_tokens_escalate",
+                evidence={
+                    "withheld_error": withheld_error,
+                    "override": escalated_override,
+                    "step": state.get("step", 0),
+                },
+            )
+            return self._model_destination
+        if recovery_count < MAX_OUTPUT_TOKENS_RECOVERY_LIMIT:
+            state["max_output_tokens_recovery_count"] = recovery_count + 1
+            state["transition"] = {
+                "reason": TRANSITION_MAX_OUTPUT_TOKENS_RECOVERY,
+                "error_reason": TERMINAL_REASON_MAX_TOKENS,
+                "attempt": recovery_count + 1,
+            }
+            emit_loop_decision_event(
+                state=state,
+                decision="continue",
+                selected_edge=self._model_destination,
+                reason_code="max_output_tokens_recovery",
+                evidence={
+                    "withheld_error": withheld_error,
+                    "recovery_count": recovery_count + 1,
+                    "step": state.get("step", 0),
+                },
+            )
+            return self._model_destination
+        state["withheld_error"] = None
+        state["should_end"] = True
+        state["terminal_reason"] = TERMINAL_REASON_MAX_TOKENS
+        state["transition"] = {
+            "reason": TRANSITION_MAX_OUTPUT_TOKENS_RECOVERY_EXHAUSTED,
+            "error_reason": TERMINAL_REASON_MAX_TOKENS,
+            "attempt": recovery_count,
+        }
+        emit_loop_decision_event(
+            state=state,
+            decision="terminal",
+            selected_edge=self._end_destination,
+            reason_code="max_output_tokens_recovery_exhausted",
+            evidence={
+                "withheld_error": withheld_error,
+                "recovery_count": recovery_count,
+                "step": state.get("step", 0),
+            },
+        )
+        return self._end_destination
+
+    def _handle_generic_withheld(
+        self,
+        state: dict[str, Any],
+        withheld_error: dict[str, Any],
+    ) -> str:
+        prev_transition = state.get("transition")
+        prev_transition_reason = (
+            prev_transition.get("reason") if isinstance(prev_transition, dict) else None
+        )
+        if (
+            state.get("collapse_retry_available")
+            and prev_transition_reason != TRANSITION_COLLAPSE_DRAIN_RETRY
+        ):
+            state["collapse_retry_available"] = False
+            state["transition"] = {
+                "reason": TRANSITION_COLLAPSE_DRAIN_RETRY,
+                "error_reason": withheld_error.get("reason"),
+            }
+            emit_loop_decision_event(
+                state=state,
+                decision="continue",
+                selected_edge=self._model_destination,
+                reason_code="collapse_drain_retry",
+                evidence={"withheld_error": withheld_error, "step": state.get("step", 0)},
+            )
+            return self._model_destination
+        if not state.get("has_attempted_reactive_compact", False):
+            state["has_attempted_reactive_compact"] = True
+            state["transition"] = {
+                "reason": TRANSITION_REACTIVE_COMPACT_RETRY,
+                "error_reason": withheld_error.get("reason"),
+            }
+            emit_loop_decision_event(
+                state=state,
+                decision="continue",
+                selected_edge=self._model_destination,
+                reason_code="reactive_compact_retry",
+                evidence={"withheld_error": withheld_error, "step": state.get("step", 0)},
+            )
+            return self._model_destination
+        state["transition"] = {
+            "reason": TRANSITION_WITHHOLD_RECOVERY_RETRY,
+            "error_reason": withheld_error.get("reason"),
+            "attempt": state.get("withhold_retry_count"),
+        }
+        emit_loop_decision_event(
+            state=state,
+            decision="continue",
+            selected_edge=self._model_destination,
+            reason_code="withhold_recovery_retry",
+            evidence={
+                "withheld_error": withheld_error,
+                "withhold_retry_count": state.get("withhold_retry_count"),
+                "step": state.get("step", 0),
+            },
+        )
+        return self._model_destination
+
+    def _handle_terminal(self, state: dict[str, Any]) -> str:
+        terminal_reason = state.get("terminal_reason")
+        last_ai_message, _ = _fetch_last_ai_and_tool_messages(state["messages"])
+        tb_count = int(state.get("token_budget_continuation_count", 0) or 0)
+        tb_max = self._tb_max_cap
+        max_steps_result = self._handle_max_steps_terminal(state, terminal_reason)
+        if max_steps_result is not None:
+            return max_steps_result
+        api_error_result = self._handle_api_error_terminal(state, last_ai_message)
+        if api_error_result is not None:
+            return api_error_result
+        sh_blk = state.get("__hook_result__")
+        stop_hook_result = self._handle_stop_hook_terminal(state, sh_blk)
+        if stop_hook_result is not None:
+            return stop_hook_result
+        token_budget_result = self._handle_token_budget_continuation(state, tb_count, tb_max)
+        if token_budget_result is not None:
+            return token_budget_result
+        return self._task_reconcile_or_end(state)
+
+    def _handle_max_steps_terminal(
+        self,
+        state: dict[str, Any],
+        terminal_reason: Any,
+    ) -> str | None:
+        if terminal_reason != TERMINAL_REASON_MAX_STEPS:
+            return None
+        messages = list(state.get("messages") or [])
+        messages.append(AIMessage(content=MAX_STEPS_PROMPT))
+        state["messages"] = messages
+        state["should_end"] = False
+        state["terminal_reason"] = None
+        state["force_text_exit"] = True
+        emit_loop_decision_event(
+            state=state,
+            decision="continue",
+            selected_edge=self._model_destination,
+            reason_code="max_steps_force_text_exit",
+            evidence={"terminal_reason": terminal_reason, "step": state.get("step", 0)},
+        )
+        return self._model_destination
+
+    def _handle_api_error_terminal(
+        self,
+        state: dict[str, Any],
+        last_ai_message: AIMessage | None,
+    ) -> str | None:
+        if not _is_api_error_assistant_message(last_ai_message):
+            return None
+        _execute_hook_inline(state, event=HookEvent.STOP_FAILURE)
+        state["terminal_reason"] = TERMINAL_REASON_COMPLETED
+        state["__hook_result__"] = None
+        state["transition"] = {"reason": TRANSITION_API_ERROR_TERMINAL}
+        emit_loop_decision_event(
+            state=state,
+            decision="terminal",
+            selected_edge=(
+                self._end_destination
+                if not self._task_reconcile_destination
+                else "task_reconcile_or_end"
+            ),
+            reason_code="api_error_terminal",
+            evidence={"step": state.get("step", 0)},
+        )
+        return self._task_reconcile_or_end(state)
+
+    def _handle_stop_hook_terminal(
+        self,
+        state: dict[str, Any],
+        sh_blk: Any,
+    ) -> str | None:
+        if not isinstance(sh_blk, dict):
+            return None
+        if sh_blk.get("prevent_continuation") is True or sh_blk.get("prevented") is True:
+            state["terminal_reason"] = TERMINAL_REASON_STOP_HOOK_PREVENTED
+            state["transition"] = {"reason": TRANSITION_STOP_HOOK_PREVENTED}
+            emit_loop_decision_event(
+                state=state,
+                decision="terminal",
+                selected_edge=(
+                    self._end_destination
+                    if not self._task_reconcile_destination
+                    else "task_reconcile_or_end"
+                ),
+                reason_code="stop_hook_prevented",
+                evidence={"hook_result": sh_blk, "step": state.get("step", 0)},
+            )
+            return self._task_reconcile_or_end(state)
+        if sh_blk.get("blocking_errors"):
+            errs = list(sh_blk.get("blocking_errors") or [])
+            new_sh = dict(sh_blk)
+            new_sh["blocking_errors"] = None
+            state["__hook_result__"] = new_sh
+            state["max_output_tokens_recovery_count"] = 0
+            state["should_end"] = False
+            state["terminal_reason"] = None
+            state["transition"] = {"reason": TRANSITION_STOP_HOOK_BLOCKING, "errors": errs}
+            emit_loop_decision_event(
+                state=state,
+                decision="continue",
+                selected_edge=self._model_destination,
+                reason_code="stop_hook_blocking_retry",
+                evidence={"blocking_errors": errs, "step": state.get("step", 0)},
+            )
+            return self._model_destination
+        return None
+
+    def _handle_token_budget_continuation(
+        self,
+        state: dict[str, Any],
+        tb_count: int,
+        tb_max: int,
+    ) -> str | None:
+        if not state.get("token_budget_continue_requested") or tb_count >= tb_max:
+            return None
+        messages_tb = list(state.get("messages") or [])
+        messages_tb.append(HumanMessage(content=TOKEN_BUDGET_NUDGE_USER_MESSAGE))
+        state["messages"] = messages_tb
+        state["token_budget_continue_requested"] = False
+        state["should_end"] = False
+        state["terminal_reason"] = None
+        state["token_budget_continuation_count"] = tb_count + 1
+        state["transition"] = {
+            "reason": TRANSITION_TOKEN_BUDGET_CONTINUATION,
+            "attempt": tb_count + 1,
+        }
+        emit_loop_decision_event(
+            state=state,
+            decision="continue",
+            selected_edge=self._model_destination,
+            reason_code="token_budget_continuation",
+            evidence={"attempt": tb_count + 1, "max": tb_max, "step": state.get("step", 0)},
+        )
+        return self._model_destination
+
+    def _handle_continue(self, state: dict[str, Any]) -> str | List[Send]:
+        last_ai_message, tool_messages = _fetch_last_ai_and_tool_messages(state["messages"])
+        no_message_result = self._handle_missing_last_ai_message(state, last_ai_message)
+        if no_message_result is not None:
+            return no_message_result
+        tool_message_ids = [m.tool_call_id for m in tool_messages]
+        pending_tool_calls = [
+            c
+            for c in last_ai_message.tool_calls
+            if c["id"] not in tool_message_ids and c["name"] not in self._structured_output_tools
+        ]
+        pending_tools_result = self._handle_pending_tool_calls(state, pending_tool_calls)
+        if pending_tools_result is not None:
+            return pending_tools_result
+        structured_result = self._handle_structured_response_ready(state)
+        if structured_result is not None:
+            return structured_result
+        task_reconcile_result = self._handle_task_reconcile_continue(state)
+        if task_reconcile_result is not None:
+            return task_reconcile_result
+        emit_loop_decision_event(
+            state=state,
+            decision="terminal",
+            selected_edge=self._end_destination,
+            reason_code="no_tools_and_not_continue",
+            evidence={"step": state.get("step", 0)},
+        )
+        return self._end_destination
+
+    def _handle_missing_last_ai_message(
+        self,
+        state: dict[str, Any],
+        last_ai_message: AIMessage | None,
+    ) -> str | None:
+        if last_ai_message is not None:
+            return None
+        emit_loop_decision_event(
+            state=state,
+            decision="terminal",
+            selected_edge=self._end_destination,
+            reason_code="no_last_ai_message",
+            evidence={"step": state.get("step", 0)},
+        )
+        return self._end_destination
+
+    def _handle_pending_tool_calls(
+        self,
+        state: dict[str, Any],
+        pending_tool_calls: list[dict[str, Any]],
+    ) -> str | list[Send] | None:
+        if not pending_tool_calls:
+            return None
+        sends: list[Send] = []
+        blocked_tool_messages: list[ToolMessage] = []
+        for tool_call in pending_tool_calls:
+            hook_handled = self._prepare_single_tool_dispatch(state, tool_call)
+            if hook_handled["blocked_message"] is not None:
+                blocked_tool_messages.append(hook_handled["blocked_message"])
+                continue
+            sends.append(
+                Send(
+                    self._tools_destination,
+                    ToolCallWithContext(
+                        __type="tool_call_with_context",
+                        tool_call=hook_handled["tool_call"],
+                        state=state,
+                    ),
+                )
+            )
+        if blocked_tool_messages:
+            state["messages"] = list(state.get("messages") or []) + blocked_tool_messages
+        emit_loop_decision_event(
+            state=state,
+            decision="tool_dispatch",
+            selected_edge=self._tools_destination,
+            reason_code="pending_tool_calls",
+            evidence={
+                "pending_count": len(pending_tool_calls),
+                "tool_names": [c.get("name") for c in pending_tool_calls],
+                "step": state.get("step", 0),
+            },
+        )
+        return sends if sends else self._end_destination
+
+    def _prepare_single_tool_dispatch(
+        self,
+        state: dict[str, Any],
+        tool_call: dict[str, Any],
+    ) -> dict[str, Any]:
+        tool_name = str(tool_call.get("name") or "")
+        tool_args = tool_call.get("args")
+        hook_result = _execute_hook_for_tool(
+            state,
+            event=HookEvent.PRE_TOOL_USE,
+            tool_name=tool_name,
+            tool_input=tool_args if isinstance(tool_args, dict) else {},
+        )
+        next_tool_call = tool_call
+        blocked_message: ToolMessage | None = None
+        if isinstance(hook_result, dict):
+            state["__hook_result__"] = hook_result
+            if isinstance(hook_result.get("updated_input"), dict):
+                patched_tool_call = dict(tool_call)
+                patched_tool_call["args"] = dict(hook_result["updated_input"])
+                next_tool_call = patched_tool_call
+            if hook_result.get("permission_behavior") == "deny":
+                blocked_message = ToolMessage(
+                    content=(
+                        hook_result.get("hook_permission_decision_reason")
+                        or "Tool call denied by PRE_TOOL_USE hook"
+                    ),
+                    tool_call_id=str(next_tool_call.get("id") or ""),
+                )
+        return {"tool_call": next_tool_call, "blocked_message": blocked_message}
+
+    def _handle_structured_response_ready(self, state: dict[str, Any]) -> str | None:
+        if "structured_response" not in state:
+            return None
+        emit_loop_decision_event(
+            state=state,
+            decision="terminal",
+            selected_edge=self._end_destination,
+            reason_code="structured_response_ready",
+            evidence={"step": state.get("step", 0)},
+        )
+        return self._end_destination
+
+    def _handle_task_reconcile_continue(self, state: dict[str, Any]) -> str | None:
+        if not (
+            self._task_reconcile_destination
+            and self._has_pending_task_notifications
+            and self._has_pending_task_notifications(state)
+        ):
+            return None
+        state["transition"] = {"reason": TRANSITION_TASK_NOTIFICATION_ARRIVED}
+        emit_loop_decision_event(
+            state=state,
+            decision="task_reconcile",
+            selected_edge=self._task_reconcile_destination,
+            reason_code="pending_task_notifications",
+            evidence={"step": state.get("step", 0)},
+        )
+        return self._task_reconcile_destination
+
+
+def _make_loop_controller_edge(
+    *,
+    model_destination: str,
+    tools_destination: str,
+    structured_output_tools: dict[str, OutputToolBinding[Any]],
+    end_destination: str,
+    max_output_tokens_cap: int | None = None,
+    task_reconcile_destination: str | None = None,
+    has_pending_task_notifications: Callable[[dict[str, Any]], bool] | None = None,
+    token_budget_max_continuations: int | None = None,
+) -> Callable[[dict[str, Any]], str | List[Send] | None]:
+    """LangChain AgentX 的 loop_controller 条件边工厂。"""
+    return LoopControllerEdge(
+        model_destination=model_destination,
+        tools_destination=tools_destination,
+        structured_output_tools=structured_output_tools,
+        end_destination=end_destination,
+        max_output_tokens_cap=max_output_tokens_cap,
+        task_reconcile_destination=task_reconcile_destination,
+        has_pending_task_notifications=has_pending_task_notifications,
+        token_budget_max_continuations=token_budget_max_continuations,
+    )
+
+
+def _make_model_to_model_edge(
+    *,
+    model_destination: str,
+    end_destination: str,
+) -> Callable[[dict[str, Any]], str | List[Send] | None]:
+    """model → model/END 条件边，用于仅依赖结构化输出的场景。"""
+
+    def model_to_model(
+        state: dict[str, Any],
+    ) -> str | List[Send] | None:
+        # 优先遵循中间件显式 jump_to 指令。
+        if jump_to := state.get("jump_to"):
+            return _resolve_jump(
+                jump_to,
+                model_destination=model_destination,
+                end_destination=end_destination,
+            )
+
+        # 产出结构化响应后结束。
+        if "structured_response" in state:
+            return end_destination
+
+        # 默认继续下一轮 model，处理结构化输出可能的重试场景。
+        return model_destination
+
+    return model_to_model
+
+
+def _make_tools_to_model_edge(
+    *,
+    tool_node: ToolNode,
+    model_destination: str,
+    structured_output_tools: dict[str, OutputToolBinding[Any]],
+    end_destination: str,
+) -> Callable[[dict[str, Any]], str | None]:
+    """LangChain AgentX 的 tools → model 条件边。
+
+    总是返回 model，不支持 return_direct 退出。
+    让 LLM 处理工具结果后决定是否结束。
+    """
+
+    def tools_to_model(state: dict[str, Any]) -> str | None:
+        messages = list(state.get("messages") or [])
+        last_ai_message, tool_messages = _fetch_last_ai_and_tool_messages(messages)
+        if last_ai_message is not None and tool_messages:
+            tool_call_map = {
+                str(tc.get("id")): tc for tc in (last_ai_message.tool_calls or []) if isinstance(tc, dict)
+            }
+            for tm in tool_messages:
+                tc = tool_call_map.get(str(getattr(tm, "tool_call_id", "")))
+                if not tc:
+                    continue
+                is_failure = getattr(tm, "status", "success") == "error"
+                event = HookEvent.POST_TOOL_USE_FAILURE if is_failure else HookEvent.POST_TOOL_USE
+                hook_result = _execute_hook_for_tool(
+                    state,
+                    event=event,
+                    tool_name=str(tc.get("name") or ""),
+                    tool_input=tc.get("args") if isinstance(tc.get("args"), dict) else {},
+                    tool_result=getattr(tm, "content", None),
+                )
+                if isinstance(hook_result, dict):
+                    state["__hook_result__"] = hook_result
+        # Phase 1：记录工具轮次（不参与任何分支判断）
+        # 语义：tools 节点完成一次执行回到 model 之前，算一次 turn。
+        state["turn_count"] = int(state.get("turn_count", 0) or 0) + 1
+
+        # 注意：return_direct 和结构化输出工具不会直接退出
+        # LLM 会在 model_node 中通过 finish_reason 决定是否结束
+        return model_destination
+
+    return tools_to_model
+
+
+__all__ = [
+    "_make_model_to_model_edge",
+    "_make_tools_to_model_edge",
+    "_make_loop_controller_edge",
+]
+