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

langchain_agentx/loop/context/stages/microcompact.py

@@ -0,0 +1,76 @@
+"""
+Microcompact 阶段：对 `ToolMessage` 做轻量规范化（对齐 CC microcompact「块级收紧」的低成本子集）。
+
+与 Claude Code 对齐：
+- 对应 `query.ts` 传入 `deps.microcompact` 的意图：在 snip 之后进一步去掉 tool 输出中的冗余空白，降低无效 token；
+- `ctx.query_source in microcompact_skip_query_sources` 时跳过，避免递归压缩路径（如 `compact`）死循环。
+
+设计要点：
+- 不调用 LLM；仅 `ToolMessage` 参与，避免改写 `AIMessage` 中 JSON tool_calls 结构；
+- 使用 `model_copy` 保持 LangChain 消息字段完整。
+
+注意：
+- 不依赖 LangGraph；不修改 `should_end` / `finish_reason`。
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from langchain_core.messages import ToolMessage
+
+from ..message_utils import estimate_tokens_from_chars, stringify_content
+from ..settings import CompactionSettings, get_active_compaction_settings
+from ..types import ContextCompactionContext, StageResult
+from .base import CompactionStage
+
+
+_BLANK_RUN = re.compile(r"\n{3,}")
+
+
+def _normalize_tool_text(text: str) -> str:
+    lines = [ln.rstrip() for ln in text.splitlines()]
+    joined = "\n".join(lines)
+    return _BLANK_RUN.sub("\n\n", joined)
+
+
+class MicrocompactStage(CompactionStage):
+    """CC 阶段 ③：microcompact（轻量规范化）。"""
+
+    def __init__(self, settings: CompactionSettings | None = None) -> None:
+        self._settings_override = settings
+
+    def _effective_settings(self) -> CompactionSettings:
+        return self._settings_override or get_active_compaction_settings()
+
+    @property
+    def name(self) -> str:
+        return "microcompact"
+
+    def run(self, messages: list[Any], ctx: ContextCompactionContext) -> StageResult:
+        s = self._effective_settings()
+        if ctx.query_source in s.microcompact_skip_query_sources:
+            return StageResult(messages=messages, tokens_freed=0)
+        changed = False
+        out: list[Any] = []
+        freed_chars = 0
+        for m in messages:
+            if not isinstance(m, ToolMessage):
+                out.append(m)
+                continue
+            text = stringify_content(m.content)
+            new_text = _normalize_tool_text(text)
+            if new_text == text:
+                out.append(m)
+                continue
+            freed_chars += len(text) - len(new_text)
+            out.append(m.model_copy(update={"content": new_text}))
+            changed = True
+        if not changed:
+            return StageResult(messages=messages, tokens_freed=0)
+        return StageResult(
+            messages=out,
+            tokens_freed=estimate_tokens_from_chars(freed_chars, s.num_chars_per_token),
+            extra={"microcompact_normalized": True},
+        )

langchain_agentx/loop/context/stages/noop.py

@@ -0,0 +1,33 @@
+"""
+泛型占位阶段：无操作，仅透传 messages。
+
+与 Claude Code 对齐：
+- 不对应单一 TS 步骤；用于单测或临时将某一槽位替换为恒等映射，而不引入真实 `ToolResultBudgetStage` 等实现。
+
+设计要点：
+- 通过构造参数 `name` 区分阶段名，便于日志；**默认 CC 五段请使用 `stages/*.py` 中独立类**，而非本泛型类。
+
+注意：
+- 生产默认流水线见 `DefaultCompactionStages.build()` / `ContextPipeline.with_default_stages()`（五段具名类）。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..types import ContextCompactionContext, StageResult
+from .base import CompactionStage
+
+
+class NoOpCompactionStage(CompactionStage):
+    """透传消息列表，不修改内容。"""
+
+    def __init__(self, name: str) -> None:
+        self._name = name
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def run(self, messages: list[Any], ctx: ContextCompactionContext) -> StageResult:
+        return StageResult(messages=messages, tokens_freed=0)

langchain_agentx/loop/context/stages/snip.py

@@ -0,0 +1,71 @@
+"""
+Snip 紧凑化阶段：对「非尾部」窗口内的超大 `ToolMessage` 截断（对齐 CC `snipCompactIfNeeded` 意图）。
+
+与 Claude Code 对齐：
+- 对应 `snipCompactIfNeeded` / `services/compact/snipCompact.ts`：优先裁剪历史中早期 tool 大块，保留尾部对话连贯性；
+- `StageResult.tokens_freed` 供 `ContextPipeline` 累加到 `ctx.snip_tokens_freed_carry`，与 CC `snipTokensFreed` 传入 autocompact 同向。
+
+设计要点：
+- 仅截断索引 `< len(messages) - snip_preserve_tail_messages` 的 `ToolMessage`；
+- 截断后内容 + `snip_suffix`，仍保留同一条 `ToolMessage`（不删消息条数，避免破坏 tool_calls 对齐）。
+
+注意：
+- 不依赖 LangGraph；不修改 exit 相关 state 字段。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.messages import ToolMessage
+
+from ..message_utils import estimate_tokens_from_chars, stringify_content
+from ..settings import CompactionSettings, get_active_compaction_settings
+from ..types import ContextCompactionContext, StageResult
+from .base import CompactionStage
+
+
+class SnipCompactStage(CompactionStage):
+    """CC 阶段 ②：历史侧 tool 内容 snip。"""
+
+    def __init__(self, settings: CompactionSettings | None = None) -> None:
+        self._settings_override = settings
+
+    def _effective_settings(self) -> CompactionSettings:
+        return self._settings_override or get_active_compaction_settings()
+
+    @property
+    def name(self) -> str:
+        return "snip_compact"
+
+    def run(self, messages: list[Any], ctx: ContextCompactionContext) -> StageResult:
+        _ = ctx
+        s = self._effective_settings()
+        if not messages:
+            return StageResult(messages=messages, tokens_freed=0)
+        n = len(messages)
+        preserve = min(max(0, s.snip_preserve_tail_messages), n)
+        cutoff = n - preserve
+        changed = False
+        out: list[Any] = []
+        freed_chars = 0
+        for i, m in enumerate(messages):
+            if i >= cutoff or not isinstance(m, ToolMessage):
+                out.append(m)
+                continue
+            text = stringify_content(m.content)
+            cap = s.snip_max_tool_content_chars
+            if len(text) <= cap:
+                out.append(m)
+                continue
+            new_text = text[:cap] + s.snip_suffix
+            freed_chars += len(text) - len(new_text)
+            out.append(m.model_copy(update={"content": new_text}))
+            changed = True
+        if not changed:
+            return StageResult(messages=messages, tokens_freed=0)
+        return StageResult(
+            messages=out,
+            tokens_freed=estimate_tokens_from_chars(freed_chars, s.num_chars_per_token),
+            extra={"snip_compact_applied": True},
+        )

langchain_agentx/loop/context/stages/tool_result_budget.py

@@ -0,0 +1,69 @@
+"""
+工具结果预算阶段：对单条 `ToolMessage` 做软字符上限（对齐 CC `applyToolResultBudget` 意图）。
+
+与 Claude Code 对齐：
+- 对应 `query.ts` 中 `messagesForQuery` 链上的 `applyToolResultBudget`：在会话级流水线入口收紧超大 tool 输出，避免单条结果撑爆窗口。
+
+设计要点：
+- 仅处理 `langchain_core.messages.ToolMessage`；`name` 落在 `CompactionSettings.prune_protected_tools` 的不截断（如 CC 侧 skill 类结果）；
+- 使用 `model_copy(update={"content": ...})` 保持 `tool_call_id` / `name` 与 LangChain 消息契约一致。
+
+注意：
+- 与 `tool_runtime` 单条落盘截断分工见设计文档；此处是会话 `messages` 级预算。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.messages import ToolMessage
+
+from ..message_utils import estimate_tokens_from_chars, stringify_content
+from ..settings import CompactionSettings, get_active_compaction_settings
+from ..types import ContextCompactionContext, StageResult
+from .base import CompactionStage
+
+
+class ToolResultBudgetStage(CompactionStage):
+    """CC 阶段 ①：tool result 软上限。"""
+
+    def __init__(self, settings: CompactionSettings | None = None) -> None:
+        self._settings_override = settings
+
+    def _effective_settings(self) -> CompactionSettings:
+        return self._settings_override or get_active_compaction_settings()
+
+    @property
+    def name(self) -> str:
+        return "tool_result_budget"
+
+    def run(self, messages: list[Any], ctx: ContextCompactionContext) -> StageResult:
+        _ = ctx
+        s = self._effective_settings()
+        changed = False
+        out: list[Any] = []
+        freed_chars = 0
+        for m in messages:
+            if not isinstance(m, ToolMessage):
+                out.append(m)
+                continue
+            tool_name = (m.name or "").strip()
+            if tool_name in s.prune_protected_tools:
+                out.append(m)
+                continue
+            text = stringify_content(m.content)
+            cap = s.tool_result_max_chars_per_message
+            if len(text) <= cap:
+                out.append(m)
+                continue
+            new_text = text[:cap] + s.tool_result_budget_suffix
+            freed_chars += len(text) - len(new_text)
+            out.append(m.model_copy(update={"content": new_text}))
+            changed = True
+        if not changed:
+            return StageResult(messages=messages, tokens_freed=0)
+        return StageResult(
+            messages=out,
+            tokens_freed=estimate_tokens_from_chars(freed_chars, s.num_chars_per_token),
+            extra={"tool_result_budget_truncated": True},
+        )

langchain_agentx/loop/context/types.py

@@ -0,0 +1,79 @@
+"""
+上下文压缩流水线的共享类型（ContextCompactionContext、StageResult 等）。
+
+与 Claude Code 对齐：
+- `ContextCompactionContext` 承载 `query.ts` 中传入 `deps.microcompact` / `deps.autocompact` 的
+  同类信息（model、snip 释放 token 累计、query_source 递归防护等），随阶段演进补齐。
+
+设计要点：
+- 使用 dataclass，避免裸 dict 魔法键；
+- 不依赖 LangGraph；不修改 should_end / finish_reason。
+
+注意：
+- `TokenWarningState` 供 `blocking_guard` 与 `compaction_pipeline_meta` 观测对齐 CC token 告警语义。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Mapping
+
+TokenWarningLevel = Literal["ok", "warn", "block_compact_llm", "block_main_model"]
+
+
+@dataclass
+class CompactionConfig:
+    """各阶段阈值与开关占位；后续与环境变量 / feature flag 对齐 CC。"""
+
+    # 预留：如 AUTOCOMPACT_BUFFER_TOKENS 等价项
+    pass
+
+
+@dataclass
+class ContextCompactionContext:
+    """单轮 `prune_and_compress` 节点执行时的流水线上下文。"""
+
+    model: Any | None = None
+    snip_tokens_freed_carry: int = 0
+    query_source: str | None = None
+    config: CompactionConfig = field(default_factory=CompactionConfig)
+
+    @classmethod
+    def from_state(
+        cls, state: Mapping[str, Any], model: Any | None
+    ) -> ContextCompactionContext:
+        return cls(
+            model=model,
+            query_source=state.get("query_source")
+            if isinstance(state.get("query_source"), str)
+            else None,
+        )
+
+
+@dataclass(frozen=True)
+class StageResult:
+    """单阶段输出；messages 为下一阶段输入。"""
+
+    messages: list[Any]  # list[BaseMessage]，避免循环导入写 Any
+    tokens_freed: int = 0
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class TokenWarningState:
+    """启发式 token 体积告警（对齐 CC `calculateTokenWarningState` 一档语义）。"""
+
+    estimated_tokens: int
+    warn_threshold_tokens: int
+    block_compact_llm_threshold_tokens: int
+    block_main_model_threshold_tokens: int
+    level: TokenWarningLevel
+
+
+__all__ = [
+    "CompactionConfig",
+    "ContextCompactionContext",
+    "StageResult",
+    "TokenWarningLevel",
+    "TokenWarningState",
+]

langchain_agentx/loop/exit/__init__.py

@@ -0,0 +1 @@
+"""LangChain AgentX 退出语义与状态字段。"""

langchain_agentx/loop/exit/exit_logic.py

@@ -0,0 +1,320 @@
+"""
+Agent Loop 退出逻辑与扩展状态定义。
+
+本模块从 `factory.py` 中拆分出与 LangGraph 结构无关的纯业务逻辑：
+- 从 `AIMessage` 解析并标准化 `finish_reason`（与 LangChain AgentX 风格兼容）
+- `determine_should_end`：以 `finish_reason` 为主信号判断是否结束，直接返回 `terminal_reason`
+- `AgentLoopState`（别名 `LoopAgentStateFields`）：本框架在 LangGraph 状态中**额外**承载的字段契约（含 CC 对齐、withhold/恢复、task 观测等）
+
+方案B：`end_reason` 已删除，`terminal_reason` 是唯一对外终态标签（CC 对齐枚举）。
+三层职责：
+  - `finish_reason`：Provider 协议层，这一轮 completion 为何停
+  - `terminal_reason`：框架终态层，整次 run 为何结束（对外唯一）
+  - `transition`：控制流层，还要继续转哪条边
+
+与 LangChain 默认 agent 的主要区别：
+- 循环主信号为模型 `finish_reason`，而非仅「无 tool_calls」
+- 不支持 `return_direct` 式工具直出；工具执行后回模型，再由 `finish_reason` 决定下一步
+
+注意：仅包含与「是否继续/结束」及扩展状态形状相关的语义，不涉及图节点、middleware 或工具执行细节。
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+from langchain_core.messages import AIMessage
+
+from .reason_codes import (
+    TERMINAL_REASON_BLOCKING_LIMIT,
+    TERMINAL_REASON_COMPLETED,
+    TERMINAL_REASON_CONTENT_FILTER,
+    TERMINAL_REASON_ERROR,
+    TERMINAL_REASON_MAX_STEPS,
+    TERMINAL_REASON_MAX_TOKENS,
+    TERMINAL_REASON_MAX_TURNS,
+)
+from ..config.runtime_settings import UNBOUNDED_MAX_STEPS
+
+# 需要继续执行的 finish_reason 集合（与 OpenCode 一致）
+CONTINUE_FINISH_REASONS = frozenset({"tool-calls", "unknown"})
+# 可恢复终态集合（terminal_reason 枚举，先 withhold，由 loop_controller 走恢复链）
+RECOVERABLE_TERMINAL_REASONS = frozenset(
+    {
+        TERMINAL_REASON_MAX_TOKENS,
+    }
+)
+ESCALATED_MAX_OUTPUT_TOKENS = 64000
+MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3
+
+
+def resolve_escalated_max_output_tokens(max_output_tokens_cap: int | None) -> int:
+    """返回 max_tokens 恢复路径的实际升级值。
+
+    规则：
+        - 无模型上限时，沿用全局恢复上界 `ESCALATED_MAX_OUTPUT_TOKENS`
+        - 有模型上限时，取 `min(ESCALATED_MAX_OUTPUT_TOKENS, 模型上限)`
+    """
+    if max_output_tokens_cap is None:
+        return ESCALATED_MAX_OUTPUT_TOKENS
+    return min(ESCALATED_MAX_OUTPUT_TOKENS, int(max_output_tokens_cap))
+
+
+def extract_finish_reason(response: AIMessage | None) -> str | None:
+    """
+    从 LangChain `AIMessage` 中提取并标准化 `finish_reason`。
+
+    该实现与原始 LangChain AgentX 逻辑保持一致。
+    """
+    if response is None:
+        return None
+
+    meta = getattr(response, "response_metadata", None) or {}
+    if not isinstance(meta, dict):
+        meta = {}
+
+    raw_reason = (
+        meta.get("finish_reason")
+        or meta.get("stop_reason")
+        or meta.get("done_reason")
+    )
+
+    if raw_reason is None:
+        return None
+
+    finish_reason = str(raw_reason)
+
+    if finish_reason in {"tool_calls", "function_call", "tool_use"}:
+        return "tool-calls"
+    if finish_reason in {"content_filter", "content-filter"}:
+        return "content-filter"
+    if finish_reason in {"length", "max_tokens"}:
+        return "length"
+    if finish_reason in {"stop", "end_turn", "stop_sequence"}:
+        return "stop"
+    if finish_reason == "refusal":
+        return "content-filter"
+    if finish_reason == "error":
+        return "error"
+
+    return finish_reason
+
+
+def metadata_override_terminal_reason(response: AIMessage | None) -> str | None:
+    """Infer terminal_reason from response_metadata / provider error shape (PTL / media / blocking).
+
+    Convention:
+    - `langchain_agentx_terminal_reason`: explicit override (written by middleware/adapter), must be a TERMINAL_REASON_* value;
+    - `error`: common provider error code heuristic (explicit field takes precedence when both present).
+    """
+    if response is None:
+        return None
+    meta = getattr(response, "response_metadata", None) or {}
+    if not isinstance(meta, dict):
+        return None
+    xr = meta.get("langchain_agentx_terminal_reason")
+    if xr in (
+        TERMINAL_REASON_MAX_TOKENS,
+        TERMINAL_REASON_BLOCKING_LIMIT,
+    ):
+        return str(xr)
+    err = meta.get("error")
+    if isinstance(err, dict):
+        code = str(err.get("code") or err.get("type") or "").lower()
+        msg = str(err.get("message") or "").lower()
+        if "prompt" in code and "long" in code:
+            return TERMINAL_REASON_MAX_TOKENS
+        if "context_length" in code or "context window" in msg:
+            return TERMINAL_REASON_MAX_TOKENS
+        if "media" in code and "size" in code:
+            return TERMINAL_REASON_MAX_TOKENS
+    return None
+
+
+def determine_should_end(
+    state: dict[str, Any],
+    response: AIMessage | None,
+    max_steps: int | None = None,
+    max_turns: int | None = None,
+) -> tuple[bool, str | None]:
+    """判断当前这一步是否应该结束 Agent 循环。
+
+    max_steps: int | None — None 表示不限制步数。
+    返回 (should_end, terminal_reason)。
+    terminal_reason 是对外唯一终态标签（CC 对齐枚举），should_end=False 时为 None。
+    """
+    step = state.get("step", 0)
+    turn_count = int(state.get("turn_count", 0) or 0)
+
+    # max_turns 作为工具轮次上限（优先于 finish_reason 判定）
+    if max_turns is not None and turn_count >= max_turns:
+        return True, TERMINAL_REASON_MAX_TURNS
+
+    meta_tr = metadata_override_terminal_reason(response)
+    if meta_tr:
+        if max_steps is not None and step >= max_steps:
+            return True, TERMINAL_REASON_MAX_STEPS
+        return True, meta_tr
+
+    finish_reason = extract_finish_reason(response)
+
+    # 需要继续执行的 finish_reason，除非达到 max_steps
+    if finish_reason in CONTINUE_FINISH_REASONS:
+        if max_steps is not None and step >= max_steps:
+            return True, TERMINAL_REASON_MAX_STEPS
+        return False, None
+
+    # 明确的"结束"类 finish_reason → 直接映射 terminal_reason
+    if finish_reason == "stop":
+        return True, TERMINAL_REASON_COMPLETED
+    elif finish_reason == "length":
+        return True, TERMINAL_REASON_MAX_TOKENS
+    elif finish_reason == "content-filter":
+        return True, TERMINAL_REASON_CONTENT_FILTER
+
+    # 没有 finish_reason 时，使用 tool_calls 兜底逻辑
+    if finish_reason is None:
+        has_tool_calls = (
+            response is not None
+            and hasattr(response, "tool_calls")
+            and getattr(response, "tool_calls")
+            and len(response.tool_calls) > 0  # type: ignore[arg-type]
+        )
+        if not has_tool_calls:
+            return True, TERMINAL_REASON_COMPLETED
+        if max_steps is not None and step >= max_steps:
+            return True, TERMINAL_REASON_MAX_STEPS
+        return False, None
+
+    # 其他未知 finish_reason：一律视为结束
+    return True, TERMINAL_REASON_ERROR
+
+
+def create_initial_state(
+    max_steps: int | None = None,
+    max_turns: int | None = None,
+    messages: list[Any] | None = None,
+) -> dict[str, Any]:
+    """创建 Agent Loop 的初始状态（与 `AgentLoopState` / `LoopAgentStateFields` 键一致）。
+
+    max_steps / max_turns 仅保留为调用方兼容参数，不写入 state（已迁入 ``AgentLoopConfig``）。
+    """
+    return {
+        "messages": messages or [],
+        "step": 0,
+        "turn_count": 0,
+        "transition": None,
+        "terminal_reason": None,
+        "pending_task_batch_id": None,
+        "pending_task_command_ids": [],
+        "task_events": [],
+        # withhold 最小状态
+        "withheld_error": None,
+        "withhold_retry_count": 0,
+        # 恢复路径守卫状态
+        "collapse_retry_available": False,
+        "has_attempted_reactive_compact": False,
+        "compaction_pipeline_meta": None,
+        "max_output_tokens_override": None,
+        "max_output_tokens_recovery_count": 0,
+        "__hook_result__": None,
+        "_hook_engine": None,
+        "_hook_runner": None,
+        "_session_env": {},
+        "_trace_collector": None,
+        "_trace_loop_step_span_id": None,
+        "_run_id": None,
+        "token_budget_continuation_count": 0,
+        "token_budget_continue_requested": False,
+        # CC：流式/工具中断或 hook_stopped；由 middleware/tools 写入，loop_controller 消费后清空
+        "abort_terminal_reason": None,
+        "should_end": False,
+        "finish_reason": None,
+        "finish_reasons": [],
+        "section_cache": {},
+    }
+
+
+class AgentLoopState(TypedDict):
+    """Agent Loop 在 LangGraph 中扩展的状态字段（合并进总 state schema）。
+
+    方案B：end_reason 已删除，terminal_reason 是唯一对外终态标签（CC 对齐枚举）。
+    三层职责：
+      - finish_reason：Provider 协议层，这一轮 completion 为何停
+      - terminal_reason：框架终态层，整次 run 为何结束（对外唯一）
+      - transition：控制流层，还要继续转哪条边（路由观测）
+    """
+
+    step: int  # 当前步骤数（模型调用轮次）
+    turn_count: int  # 工具轮次（tools 回环计数）
+    pending_task_batch_id: str | None  # task_event_commit_ack 待确认批次
+    pending_task_command_ids: list[str]  # 待确认批次内 command_id 列表
+    task_events: list[dict[str, Any]]  # task runtime 观测事件（节点级）
+    transition: dict[str, Any] | None  # 路由观测：还要继续转哪条边；非终态时为 None
+    terminal_reason: str | None  # 对外唯一终态标签（CC 对齐枚举，should_end=False 时为 None）
+    withheld_error: dict[str, Any] | None  # 可恢复错误暂存（withhold）
+    withhold_retry_count: int  # withhold 已重试次数
+    collapse_retry_available: bool  # collapse_drain_retry 相关守卫
+    has_attempted_reactive_compact: bool  # reactive_compact 重试守卫
+    compaction_pipeline_meta: dict[str, Any] | None  # prune_and_compress 观测
+    max_output_tokens_override: int | None  # max_output_tokens 升档参数
+    max_output_tokens_recovery_count: int  # max_output_tokens 恢复计数
+    __hook_result__: dict[str, Any] | None  # 新 Hook 聚合结果（loop_controller 首选读取）
+    _hook_engine: Any | None  # Hook 引擎实例（hook 节点/edge 读取）
+    _hook_runner: Any | None  # Hook 执行协作者（hook 节点/edge 读取）
+    _session_env: dict[str, str]  # SESSION_START hook 注入的会话级环境变量
+    _trace_collector: Any | None  # 事件发射器可用的 TraceCollector 引用
+    _trace_loop_step_span_id: str | None  # before_model/after_model 闭环用的 loop_step span_id
+    _run_id: str | None  # 当前 run 标识（loop_start_node 注入）
+    token_budget_continuation_count: int  # CC：token budget nudge 已执行次数
+    token_budget_continue_requested: bool  # 为 True 时 loop_controller 注入 nudge 并回到 model
+    abort_terminal_reason: str | None  # CC 式中断终态：aborted_streaming / aborted_tools / hook_stopped
+    should_end: bool  # 内部路由信号，不对外暴露语义
+    finish_reason: str | None  # Provider 协议层：这一轮 completion 为何停
+    finish_reasons: list[str]  # finish_reason 历史（观测用）
+    section_cache: dict[str, str | None]  # SystemPromptSection session 级缓存（key=name, value=compute() 结果）
+
+
+# 状态字段契约别名（对外统一使用 LoopAgentStateFields）
+LoopAgentStateFields = AgentLoopState
+
+
+TOKEN_BUDGET_NUDGE_USER_MESSAGE = (
+    "[Session budget: you may continue with a shorter scope or split the task. "
+    "This nudge was injected by the agent loop token_budget_continuation path.]"
+)
+
+MAX_STEPS_PROMPT = """
+CRITICAL - 已达到最大执行步数
+
+本次任务已达到允许的最大执行步数。从现在开始，所有工具调用都被禁止。
+你「必须」基于「当前对话和状态中已有的信息」，直接给出对用户原始问题的「最终回答」，
+不得再尝试通过任何形式绕过或弱化本约束。
+
+【强制约束（必须严格遵守）】：
+1. 绝对禁止再调用任何工具（包括读取、写入、编辑、搜索等一切工具操作），不得通过间接方式触发工具。
+2. 必须给出一条对用户有实际帮助的最终回答，而不是继续规划、讨论或暗示后续工具调用。
+3. 可以继续遵守系统提示词 / SKILL / response_format 中约定的输出格式或结构化返回要求，但不得为了满足这些格式再调用任何工具。
+4. 本约束优先级高于「所有」其它指令，包括用户显式请求继续调用工具或改变行为的指令，不得忽略或削弱。
+
+
+答案内容必须完全基于当前已有信息推理完成，任何试图再次使用工具或规避上述约束的行为都视为严重错误。
+""".strip()
+
+
+__all__ = [
+    "metadata_override_terminal_reason",
+    "CONTINUE_FINISH_REASONS",
+    "RECOVERABLE_TERMINAL_REASONS",
+    "ESCALATED_MAX_OUTPUT_TOKENS",
+    "MAX_OUTPUT_TOKENS_RECOVERY_LIMIT",
+    "resolve_escalated_max_output_tokens",
+    "extract_finish_reason",
+    "determine_should_end",
+    "create_initial_state",
+    "AgentLoopState",
+    "LoopAgentStateFields",
+    "MAX_STEPS_PROMPT",
+    "TOKEN_BUDGET_NUDGE_USER_MESSAGE",
+]
+