3 · The Main Loop ★

agent/conversation_loop.py, 8,676 lines. The core function, run_conversation, starts at line 1,834.

3.1 The Loop Entry: A Triple Budget Gate

while (api_call_count < agent.max_iterations              # call count under the hard cap
       and agent.iteration_budget.remaining > 0)          # iteration budget still has balance
      or agent._budget_grace_call:                        # or: one "grace call" left

hermes-agent/agent/conversation_loop.py:2029

What each of the three conditions does:

How the grace call is implemented

if agent._budget_grace_call:
    agent._budget_grace_call = False               # ★ consume the flag; the next iteration must exit
elif not agent.iteration_budget.consume():         # try to deduct one unit of budget; nothing left
    _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 Per-Turn Preparation: build_turn_context

Before the loop starts there is a long “per-turn prologue,” which the source pulls out into agent/turn_context.py:

Taking those nine items one at a time:

“Restore or build” for the system prompt

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

The existence of these three functions tells you: the system prompt is cached and reused across turns, and there is a check that “verifies it still matches the current runtime configuration.”

Why verify? Because the runtime configuration may have changed — the user switched models, enabled a new toolset, edited SOUL.md. Then the cached prompt is stale and must be rebuilt. But if nothing changed, it must not be rebuilt — rebuilding could produce different bytes and break the prompt cache.

3.3 Mid-Turn Interjection: /steer

This is one of Hermes's distinctive capabilities: while the model is thinking, the user can slip in a line, and that line takes effect within the current turn.

Two hard parts

The solution: append to the end of the most recent tool-result message

_pre_api_steer = agent._drain_pending_steer()          # take the pending interjection
if _pre_api_steer:
    _injected = False
    for _si in range(len(messages) - 1, -1, -1):       # search backward from the last message
        _sm = messages[_si]
        if isinstance(_sm, dict) and _sm.get("role") == "tool":   # found the most recent tool message
            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      # ★ append; don't add a new message
            else:
                # multimodal content blocks — append a text block
                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:
        # no tool message yet (first iteration) — put it back in the queue
        # and inject it when the next batch of tool results appears.
        # Injecting a user message would break role alternation, and there's no tool output to ride on yet
        agent._pending_steer = _pre_api_steer

hermes-agent/agent/conversation_loop.py · draining interjections before the API call

And a stronger one: redirect

_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}"     # the user's mid-turn correction
        )
    agent._persist_session(messages, conversation_history)

A “redirect” is stronger than an “interjection”: it modifies the record of the “original user message,” attaching the correction to it. That way, even if compaction happens later, the correction survives in the material the summary is built from — because it has become part of the user's request.

3.4 The Wall-Clock Budget Wrap-Up Reminder

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

The function's comment explains the mechanism: one-shot — when a run budget (--run-budget) is active and 80% of it has been consumed, remind the model to start wrapping up and deliver with the state it already has. Uses the same cache-safe channel as /steer (appended to the latest tool result); fully dormant when no budget is set.

3.5 The Interrupt Check

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 uses flag polling: an interrupt request sets a boolean flag, and the loop checks it once at the top of each iteration.

There is a finer-grained interrupt type too — the input budget of a review task running out:

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

The comment explains where it fits: “An aggregate input budget for detached background review tasks: compaction limits a single request, while this limits the whole review task. It fires between iterations — the request that crossed the budget line has already completed (its tool writes have landed), and then the tool loop stops before the next model call, matching how the iteration budget exits.”

3.6 The Step Callback: An Observation Point for the Gateway

if agent.step_callback is not None:
    try:
        prev_tools = []
        # search backward for the most recent model message that carried tool calls
        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 = {}
                # collect all the tool results that immediately follow it
                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)

This callback lets the gateway know in real time “which step the agent is on, which tools the last step used, and what the results were,” so it can push progress to the chat window.

Notice the whole block is wrapped in try/except, and a failure is logged only at debug level. That is correct: observation code must never affect the main flow. If step_callback throws because of a network problem, the agent should not stop working over it.

3.7 Other State Inside the Loop

The long comment at the top of the loop reveals the state maintained across iterations:

That “re-arming” mechanism deserves a closer look

3.8 Why the Loop Exited

The values of _turn_exit_reason we've already seen in the code:

Like the step callback in section 3.6, this field exists purely for observability — it plays no part in business logic, but it turns “why did this agent stop” into a data field you can query directly, instead of something you infer by digging through logs.

3.9 An Optional Bypass: The Codex App Server Runtime

# Optional opt-in runtime: if api_mode == codex_app_server,
# hand this turn to the codex app server subprocess (terminal operations, file operations,
# and patching all happen inside Codex). The default Hermes path is bypassed entirely.

This is a very thorough extension point: the entire main loop can be taken over by an external subprocess.

Its existence reveals a Hermes stance: not even the “agent loop” itself has to be implemented in-house. If a user wants a different agent runtime (here, OpenAI's Codex), Hermes can shrink down to a shell of “gateway + session management + memory.”