3 · 主循环 ★

agent/conversation_loop.py，8,676 行。核心函数 run_conversation 从第 1,834 行开始。

3.1 循环入口：三重预算闸门

while (api_call_count < agent.max_iterations              # 调用次数没超上限
       and agent.iteration_budget.remaining > 0)          # 迭代预算还有余额
      or agent._budget_grace_call:                        # 或者：还有一次"宽限调用"

hermes-agent/agent/conversation_loop.py:2029

三个条件的分工：

宽限调用的实现

if agent._budget_grace_call:
    agent._budget_grace_call = False               # ★ 消费掉标记，下轮必退出
elif not agent.iteration_budget.consume():         # 尝试扣一次预算，扣不动了
    _turn_exit_reason = "budget_exhausted"
    if not agent.quiet_mode:
        agent._safe_print(f"\n⚠️  Iteration budget exhausted "
                          f"({agent.iteration_budget.used}/{agent.iteration_budget.max_total} "
                          f"iterations used)")
    break

3.2 每轮的准备工作：build_turn_context

循环开始前有一大段「每轮序章」，源码把它抽到了 agent/turn_context.py：

逐项解释这九件事：

系统提示词的「恢复或构建」

def _restore_or_build_system_prompt(agent, system_message, conversation_history)
def _stored_prompt_matches_runtime(agent, prompt: str) -> bool
def _ensure_cached_system_prompt_static(agent, system_message=None) -> None

这三个函数的存在说明：系统提示词是被缓存并跨轮次复用的，而且有一个「校验它是否还和当前运行时配置一致」的检查。

为什么要校验？因为运行时配置可能变了 —— 用户换了模型、启用了新工具集、编辑了 SOUL.md。这时缓存的提示词就过期了，必须重建。但如果没变，就绝不能重建 —— 重建可能产生不同的字节，破坏提示词缓存。

3.3 中途插话：/steer

这是 Hermes 一个很有特色的能力：模型正在思考时，用户可以插一句话，而且这句话在本轮就生效。

两个难点

解法：追加到最新一条工具结果消息的末尾

_pre_api_steer = agent._drain_pending_steer()          # 取出待处理的插话
if _pre_api_steer:
    _injected = False
    for _si in range(len(messages) - 1, -1, -1):       # 从最后一条往前找
        _sm = messages[_si]
        if isinstance(_sm, dict) and _sm.get("role") == "tool":   # 找到最近的工具消息
            from agent.prompt_builder import format_steer_marker
            marker = format_steer_marker(_pre_api_steer)
            existing = _sm.get("content", "")
            if isinstance(existing, str):
                _sm["content"] = existing + marker      # ★ 追加，不新增消息
            else:
                # 多模态内容块 —— 追加一个文本块
                try:
                    blocks = list(existing) if existing else []
                    blocks.append({"type": "text", "text": marker})
                    _sm["content"] = blocks
                except Exception:
                    pass
            _injected = True
            break
    if not _injected:
        # 还没有任何工具消息（第一轮）—— 放回队列，
        # 等下一批工具结果出现时再注入。
        # 注入用户消息会破坏角色交替，而现在没有工具输出可以搭载
        agent._pending_steer = _pre_api_steer

hermes-agent/agent/conversation_loop.py · 调用接口前排空插话

还有一个更强的：重定向

_redirect_text = agent._drain_pending_redirect()
if _redirect_text:
    _apply_active_turn_redirect(agent, messages, _redirect_text)
    if isinstance(original_user_message, str):
        original_user_message = (
            f"{original_user_message}\n\n"
            f"User correction during the turn: {_redirect_text}"     # 用户在本轮中的更正
        )
    agent._persist_session(messages, conversation_history)

「重定向」比「插话」更强：它会修改「原始用户消息」的记录，把更正内容附加上去。这样即使后面发生压缩，这条更正也会被保留在摘要的依据里 —— 因为它成了用户请求的一部分。

3.4 墙上时钟预算的收尾提醒

if getattr(agent, "run_budget_seconds", None):
    _maybe_inject_run_budget_wrapup(agent, messages)

对应的函数注释说明了机制：一次性的 —— 当运行预算（--run-budget）激活且已消耗 80% 时，提醒模型开始收尾、用手头已有的状态交付。走和 /steer 相同的缓存安全通道（追加到最新的工具结果上）；没设预算时完全休眠。

3.5 中断检查

if agent._interrupt_requested:
    interrupted = True
    _turn_exit_reason = "interrupted_by_user"
    if not agent.quiet_mode:
        agent._safe_print("\n⚡ Breaking out of tool loop due to interrupt...")
    break

Hermes 用的是标记位轮询：中断请求设置一个布尔标记，循环每轮开头检查一次。

还有一个更细的中断类型 —— 审查任务的输入预算耗尽：

if _review_input_budget_exhausted(agent):
    _turn_exit_reason = "review_input_budget_exhausted"
    if not agent.quiet_mode:
        agent._safe_print(
            f"\n⏹️  Review input budget exhausted "
            f"({int(agent.session_input_tokens):,} tokens) — stopping "
            f"the review tool loop before the next provider call.")
    break

注释解释了它的定位：「为分离出去的后台审查任务准备的聚合输入预算：压缩限制的是单次请求，而这个限制的是整个审查任务。它在两次迭代之间触发 —— 跨越预算线的那次请求已经完成（它的工具写入已经落地），然后工具循环在下一次调用模型之前停下，和迭代预算的退出方式一致。」

3.6 步骤回调：给网关的观测点

if agent.step_callback is not None:
    try:
        prev_tools = []
        # 从后往前找最近一条带工具调用的模型消息
        for _idx, _m in enumerate(reversed(messages)):
            if _m.get("role") == "assistant" and _m.get("tool_calls"):
                _fwd_start = len(messages) - _idx
                _results_by_id = {}
                # 收集紧随其后的所有工具结果
                for _tm in messages[_fwd_start:]:
                    if _tm.get("role") != "tool": break
                    _tcid = _tm.get("tool_call_id")
                    if _tcid: _results_by_id[_tcid] = _tm.get("content", "")
                prev_tools = [
                    { "name":      tc["function"]["name"],
                      "result":    _results_by_id.get(tc.get("id")),
                      "arguments": tc["function"].get("arguments") }
                    for tc in _m["tool_calls"] if isinstance(tc, dict)
                ]
                break
        agent.step_callback(api_call_count, prev_tools)
    except Exception as _step_err:
        logger.debug("step_callback error (iteration %s): %s", api_call_count, _step_err)

这个回调让网关能实时知道「智能体走到第几步了、上一步用了哪些工具、结果是什么」，用于向聊天窗口推送进度。

注意整段被 try/except 包住，而且失败只记 debug 级日志。这是正确的：观测代码绝不能影响主流程。如果 step_callback 因为网络问题抛异常，智能体不该因此停止工作。

3.7 循环里的其他状态

从循环开头那一大段注释可以看出跨轮次维护的状态：

那个「重新武装」的机制值得展开

3.8 循环退出原因

已经在代码里见到的 _turn_exit_reason 取值：

这个字段和第 3.6 节的步骤回调一样，是纯粹为了可观测而存在的 —— 它不参与业务逻辑，但让「这个智能体为什么停了」变成一个可以直接查询的数据字段，而不需要去翻日志推断。

3.9 一个可选的旁路：Codex 应用服务运行时

# 可选的加入式运行时：如果 api_mode == codex_app_server，
# 把这一轮交给 codex 应用服务子进程处理（终端操作、文件操作、打补丁
# 全部在 Codex 内部完成）。默认的 Hermes 路径被完全绕过。

这是一个很彻底的扩展点：整个主循环可以被一个外部子进程接管。

它的存在说明了 Hermes 的一个立场：连「智能体循环」本身都不是必须由自己实现的。如果用户想用另一套智能体运行时（这里是 OpenAI 的 Codex），Hermes 可以退化成一个「网关 + 会话管理 + 记忆」的壳。