Skip to content

Hermes Agent context engine: the main model writes the compaction handoff on its cached prompt prefix

34.1 KB
Raw Blame
"""Builds and sends the warm request: the captured request prefix, the new rows, and one instruction."""

from __future__ import annotations

import collections
import copy
import json
import ssl
import time
import urllib.error
import urllib.parse
import urllib.request
from typing import Any
from collections.abc import Callable

from . import protocol
from .rows import (
    api_content, attr, compact_json, estimate_tokens, has_thought_signature, hermes_value, plain_text,
    reasoning_policy as _reasoning_policy, replay_details, reply_text, row_digest, tool_calls_of,
)

DEFAULT_RESERVE = 4096
# The reply limit of the handoff. The instruction asks for at most 600 words; the upper limit leaves room for a
# thinking model that counts its reasoning in the same limit.
HANDOFF_MIN_TOKENS = 2048
HANDOFF_MAX_TOKENS = 8192
TIMEOUT_S = 300.0
# Cloudflare-fronted routes reject Python's default "Python-urllib/x.y" User-Agent with
# HTTP 403 (error 1010). Send an explicit one, as the Hermes SDK client does.
USER_AGENT = "hermes-warm-compaction/0.2"
SAFETY = 1.1
SYSTEM_ROLES = ("system", "developer")
UNSUPPORTED_SETTINGS = ("response_format", "functions", "function_call", "modalities", "audio")

Post = Callable[[str, bytes, dict, float], tuple]


class WarmRefusal(Exception):
    """The warm request cannot run. The first argument is the refusal code."""

    @property
    def code(self) -> str:
        return str(self.args[0]) if self.args else "unknown"


def _matches_reply(row: Any, reply: dict[str, Any]) -> bool:
    if attr(row, "role") != "assistant":
        return False
    calls = [[call_id, name] for call_id, name, _arguments in tool_calls_of(row)]
    # Hermes can keep the sent reply text in api_content and leave content empty or normalized.
    text = reply_text(reply["content"])
    return calls == reply["tool_calls"] and text in (reply_text(attr(row, "content")), reply_text(api_content(row)))


def split_history(capture: dict[str, Any], messages: list) -> tuple[list, list]:
    """Return (new rows, trailing user rows) after the captured rows. Refuse a changed history."""
    digests = capture["digests"]
    count = len(digests)
    if len(messages) < count:
        raise WarmRefusal("history_changed:capture_ahead")
    if [row_digest(row) for row in messages[:count]] != digests:
        raise WarmRefusal("history_changed:digest")
    if len(messages) == count:
        raise WarmRefusal("history_changed:reply_missing")
    rest = messages[count:]
    if not _matches_reply(rest[0], capture["reply"]):
        raise WarmRefusal("history_changed:reply")
    # A multiset: one tool row for each tool call, also when an id repeats.
    expected = collections.Counter(call_id for call_id, _name in capture["reply"]["tool_calls"])
    answered: collections.Counter = collections.Counter()
    index = 1
    while index < len(rest) and attr(rest[index], "role") == "tool":
        call_id = attr(rest[index], "tool_call_id")
        if answered[call_id] >= expected[call_id]:
            raise WarmRefusal("history_changed:tool_extra")
        answered[call_id] += 1
        index += 1
    if answered != expected:
        raise WarmRefusal("history_changed:tool_count")
    trailing = rest[index:]
    if any(attr(row, "role") != "user" for row in trailing):
        raise WarmRefusal("history_changed:trailing")
    return rest[:index], trailing


def check_settings(body: dict[str, Any]) -> None:
    """Refuse request settings that the warm request cannot keep."""
    if not isinstance(body.get("messages"), list):
        raise WarmRefusal("settings_unsupported")
    if body.get("n") not in (None, 1):
        raise WarmRefusal("settings_unsupported")
    if body.get("tool_choice") not in (None, "auto", "none"):
        raise WarmRefusal("settings_unsupported")
    if any(body.get(key) is not None for key in UNSUPPORTED_SETTINGS):
        raise WarmRefusal("settings_unsupported")


def _shape(row: Any) -> tuple:
    calls = tuple((call_id, name) for call_id, name, _arguments in tool_calls_of(row))
    return attr(row, "role"), attr(row, "tool_call_id") or None, calls


def _is_text(part: Any) -> bool:
    return isinstance(part, str) or (
        isinstance(part, dict) and part.get("type", "text") == "text" and isinstance(part.get("text"), str))


def _parts(content: Any) -> tuple[list[str], list]:
    """Return the text runs between the non-text parts and the non-text parts, in order. A message with n image,
    audio, or file parts has n + 1 text runs. White space stays: it can change code, tables, or commands."""
    if not isinstance(content, list):
        return [plain_text(content)], []
    runs: list[str] = []
    media: list = []
    current: list[str] = []
    for part in content:
        if _is_text(part):
            current.append(part if isinstance(part, str) else part["text"])
        else:
            runs.append("\n".join(current))
            media.append(part)
            current = []
    runs.append("\n".join(current))
    return runs, media


def _arguments(value: Any) -> tuple[str, str]:
    """Return a canonical form of tool-call arguments: a change of spacing or key order is not a change, but a
    change of a JSON type is (true and 1 are different, which Python == does not see). Text that is not JSON
    stays as it is."""
    if isinstance(value, str):
        try:
            value = json.loads(value)
        except ValueError:
            return "text", value
    return "json", json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False, default=str)


def _same_row(wire: Any, row: Any) -> bool:
    """True when the sent row carries the stored row: the same shape; the same name (the Hermes transport
    removes the name from tool rows only); the same image, audio, and file parts in the same order; each stored
    text run equal to the sent text run at the same place, or a complete string with all trailing whitespace
    removed; and the same tool-call arguments. The stored text is the api_content sidecar when the row has
    one. Leading whitespace and whitespace in content lists must stay unchanged."""
    if _shape(wire) != _shape(row):
        return False
    name = attr(wire, "name")
    if name != attr(row, "name") and not (name is None and attr(row, "role") == "tool"):
        return False
    sent_content, stored_content = attr(wire, "content"), api_content(row)
    sent_runs, sent_media = _parts(sent_content)
    stored_runs, stored_media = _parts(stored_content)
    same_text = all(stored == sent for stored, sent in zip(stored_runs, sent_runs))
    # Hermes e36a8180 strips complete strings during request assembly. Allow only the trailing removal;
    # a change of leading whitespace can change code indentation. Do not normalize content lists.
    trailing_removed = (isinstance(sent_content, str) and isinstance(stored_content, str)
                        and sent_content == stored_content.rstrip())
    if sent_media != stored_media or not (same_text or trailing_removed):
        return False
    return [_arguments(arguments) for _id, _name, arguments in tool_calls_of(wire)] == [
        _arguments(arguments) for _id, _name, arguments in tool_calls_of(row)]


# Fields that Hermes adds to a sent row on some routes, apart from wire_row: the prompt caching marker.
TRANSPORT_FIELDS = frozenset({"cache_control"})


def _no_extra_fields(wire: Any, expected: dict[str, Any]) -> bool:
    """True when the sent row and its tool calls have no field that Hermes does not send for the stored row (a
    provider control that a middleware added, for example): the model reads it."""
    if not isinstance(wire, dict):
        return True
    if set(wire) - set(expected) - TRANSPORT_FIELDS:
        return False
    for call, want in zip(wire.get("tool_calls") or [], expected.get("tool_calls") or []):
        if isinstance(call, dict) and (set(call) - set(want) or (
                isinstance(call.get("function"), dict) and set(call["function"]) - set(want.get("function") or {}))):
            return False
        # The same keys with another type value: the provider reads another kind of call.
        if isinstance(call, dict) and "type" in call and call["type"] != want.get("type"):
            return False
    return True


def _same_replay_fields(wire: Any, expected: dict[str, Any]) -> bool:
    """True when the sent row has the reasoning fields and thought signatures that Hermes replays for the stored
    row on this route. The provider reads them, so a change makes a prefix that the history does not have."""
    if any(attr(wire, key) != expected.get(key) for key in ("reasoning_content", "reasoning_details")):
        return False
    return [attr(call, "extra_content") for call in attr(wire, "tool_calls") or []] == [
        call.get("extra_content") for call in expected.get("tool_calls") or []]


def check_source(body: dict[str, Any], history_rows: list, base_url: Any = None,
                 native_type: str | None = None) -> None:
    """Refuse a request whose messages are not system rows followed by the stored rows. A row that a hook or
    a middleware rewrote would make the handoff summarize text that is not in the history it replaces."""
    sent = body["messages"]
    offset = len(sent) - len(history_rows)
    if offset < 0 or any(attr(row, "role") not in SYSTEM_ROLES for row in sent[:offset]):
        raise WarmRefusal("source_transform_unsupported")
    if not all(_same_row(wire, row) for wire, row in zip(sent[offset:], history_rows)):
        raise WarmRefusal("source_transform_unsupported")
    # The replayed fields follow the captured request only: the new rows do not change what Hermes sent.
    echo = needs_reasoning_echo(body, [])
    for wire, row in zip(sent[offset:], history_rows):
        want = wire_row(row, echo, body.get("model"), base_url, native_type)
        # Hermes d4d2ab7b can send stored reasoning on local Chat Completions routes.
        # Accept this field only when the sent assistant text equals the stored text.
        reasoning = attr(row, "reasoning")
        if (attr(row, "role") == "assistant" and isinstance(reasoning, str)
                and attr(wire, "reasoning") == reasoning):
            want["reasoning"] = reasoning
        # A captured field on another row does not prove that every row needs a pad.
        # Do not require a new pad when neither this sent row nor its source has reasoning.
        if (attr(wire, "reasoning_content") is None and attr(row, "reasoning_content") is None
                and reasoning is None):
            want.pop("reasoning_content", None)
        if not (_same_replay_fields(wire, want) and _no_extra_fields(wire, want)):
            raise WarmRefusal("source_transform_unsupported")


def needs_reasoning_echo(body: dict[str, Any], rows: list) -> bool:
    """True when the route needs reasoning_content on assistant rows: Hermes sent it on a captured assistant row,
    or a new assistant row has it from the provider."""
    return any(isinstance(row, dict) and row.get("role") == "assistant" and "reasoning_content" in row
               for row in body.get("messages") or ()) or any(
        attr(row, "role") == "assistant" and isinstance(attr(row, "reasoning_content"), str) for row in rows)


def _model_consumes_thought_signature(model: Any) -> bool:
    """Hermes 45871e10 (agent.transports.chat_completions): Gemini and Gemma models need the tool-call
    extra_content replayed; other providers reject it."""
    name = str(model or "").lower()
    return "gemini" in name or "gemma" in name


def _signature(extra: Any) -> Any:
    """Return a copy of the tool-call extra_content when it has a usable thought signature, else None."""
    return copy.deepcopy(extra) if has_thought_signature(extra) else None


REPLAY_DETAILS_HOSTS = ("openrouter.ai", "nousresearch.com")
LIMIT_KEYS = ("max_tokens", "max_completion_tokens")


def _forces_completion_field(model: Any) -> bool:
    """Hermes 45871e10 (utils.model_forces_max_completion_tokens): OpenAI families that reject max_tokens."""
    name = str(model or "").strip().lower().rsplit("/", 1)[-1]
    return name.startswith(("gpt-4o", "gpt-4.1", "gpt-5", "o1", "o3", "o4"))


def limit_field(model: Any, base_url: Any) -> str:
    """The reply limit field that Hermes 45871e10 sends on the route (AIAgent._max_tokens_param):
    max_completion_tokens for OpenAI, Azure OpenAI, GitHub Copilot, and the newer OpenAI model families, else
    max_tokens."""
    host = (urllib.parse.urlparse(str(base_url or "")).hostname or "").lower()
    forces = hermes_value("utils", "model_forces_max_completion_tokens", _forces_completion_field)
    if (host == "api.openai.com" or host == "openai.azure.com" or host.endswith(".openai.azure.com")
            or host.endswith(".githubcopilot.com") or forces(model)):
        return "max_completion_tokens"
    return "max_tokens"


def _route_replays_reasoning_details(base_url: Any) -> bool:
    """Hermes 45871e10 (agent.transports.chat_completions): only OpenRouter and the Nous Portal read replayed
    reasoning_details; strict routes reject the field."""
    host = (urllib.parse.urlparse(str(base_url or "")).hostname or "").lower()
    return any(host == name or host.endswith("." + name) for name in REPLAY_DETAILS_HOSTS)


def native_details_type(provider: Any) -> str | None:
    """The native reasoning carrier type of the provider profile (native_reasoning_details_type of Hermes
    45871e10), or None. Hermes replays that carrier on every route of the provider."""
    try:
        from providers import get_provider_profile
        profile = get_provider_profile(provider) if provider else None
        value = getattr(profile, "native_reasoning_details_type", None)
    except Exception:
        return None
    return value if isinstance(value, str) and value else None


def _replay_details(details: Any, native_type: str | None = None) -> list | None:
    """A copy of rows.replay_details: reasoning_details without private native-assistant carriers, except the
    carrier of the provider profile, or None."""
    kept = replay_details(details, native_type)
    return copy.deepcopy(kept) if kept is not None else None


def wire_row(row: Any, reasoning_echo: bool = False, model: Any = None, base_url: Any = None,
             native_type: str | None = None) -> dict[str, Any]:
    """Return the wire form of a stored row, as Hermes sends it: only the fields that the API reads, the
    api_content sidecar of a user or assistant row in place of its content, reasoning_content on an assistant
    row when the route needs it, the thought signature (extra_content) of a tool call for a Gemini model, and
    reasoning_details of an assistant row on a route that replays it or for a provider profile with a native
    carrier type (native_type: that carrier only of the native carriers)."""
    wire: dict[str, Any] = {"role": attr(row, "role"), "content": copy.deepcopy(api_content(row))}
    for key in ("tool_call_id", "name"):
        value = attr(row, key)
        # The Hermes transport removes the name from tool rows; strict providers reject it there.
        if value is not None and not (key == "name" and attr(row, "role") == "tool"):
            wire[key] = value
    calls = tool_calls_of(row)
    if calls:
        wire["tool_calls"] = [
            {"id": call_id, "type": "function", "function": {
                "name": name,
                "arguments": arguments if isinstance(arguments, str) else compact_json(
                    arguments if arguments is not None else {}),
            }}
            for call_id, name, arguments in calls
        ]
        consumes = hermes_value("agent.transports.chat_completions", "_model_consumes_thought_signature",
                                _model_consumes_thought_signature)(model)
        stored = attr(row, "tool_calls") or []
        for call, source in zip(wire["tool_calls"], stored):
            extra = _signature(attr(source, "extra_content")) if consumes else None
            if extra is not None:
                call["extra_content"] = extra
    if attr(row, "role") == "assistant" and (native_type or hermes_value(
            "agent.transports.chat_completions", "_route_replays_reasoning_details",
            _route_replays_reasoning_details)(base_url)):
        details = _replay_details(attr(row, "reasoning_details"), native_type)
        if details is not None:
            wire["reasoning_details"] = details
    if isinstance(row, dict):
        policy = hermes_value("agent.message_sanitization", "apply_reasoning_content_policy", _reasoning_policy)
        policy(row, wire, reasoning_echo)
    return wire


def _join_content(first: Any, second: Any) -> Any:
    """The rule of Hermes 45871e10 (agent.agent_runtime_helpers._merge_user_content): two texts join with a blank
    line; lists append as separate parts. None for another shape."""
    if isinstance(first, str) and isinstance(second, str):
        return first + ("\n\n" if first and second else "") + second
    first_parts = first if isinstance(first, list) else [{"type": "text", "text": first}] if first else []
    second_parts = second if isinstance(second, list) else [{"type": "text", "text": second}] if second else []
    if not isinstance(first, (str, list)) or not isinstance(second, (str, list)):
        return None
    return [*first_parts, *second_parts]


def ends_with_instruction(row: Any, instruction: str) -> bool:
    """True when the row is a user row whose last block is the host instruction (it can join the last user row
    of the history; see _join_user_rows)."""
    if attr(row, "role") != "user":
        return False
    content = attr(row, "content")
    if isinstance(content, str):
        return content == instruction or content.endswith("\n\n" + instruction)
    return (isinstance(content, list) and bool(content) and isinstance(content[-1], dict)
            and content[-1].get("type") == "text" and content[-1].get("text") == instruction)


def _join_user_rows(rows: list, instruction: str) -> list:
    """Join adjacent user rows of the same author (no name, or the same name), then join the host instruction
    to the last user row (it keeps its name: the ordinary request also ended with that row). The ordinary
    request has no adjacent user rows (Hermes joins them), and strict chat templates refuse them. The
    instruction is the last block; it says that it comes from the host."""
    out: list = []
    for row in rows:
        last = out[-1] if out else None
        if (last is not None and last.get("role") == row.get("role") == "user" and last.get("name") == row.get("name")
                and set(last) <= {"role", "content", "name"} and set(row) <= {"role", "content", "name"}):
            joined = _join_content(last.get("content"), row.get("content"))
            if joined is not None:
                out[-1] = {**last, "content": joined}
                continue
        out.append(row)
    last = out[-1] if out else None
    if last is not None and last.get("role") == "user" and set(last) <= {"role", "content", "name"}:
        joined = _join_content(last.get("content"), instruction)
        if joined is not None:
            out[-1] = {**last, "content": joined}
            return out
    return [*out, {"role": "user", "content": instruction}]


def reply_reserve(body: Any) -> int:
    """The reply reserve of a request: the larger positive max_tokens or max_completion_tokens (a server can
    honor either), else DEFAULT_RESERVE."""
    values = [body.get(key) for key in ("max_tokens", "max_completion_tokens", "max_output_tokens")
              ] if isinstance(body, dict) else []
    values = [value for value in values if type(value) is int and value > 0]
    return max(values) if values else DEFAULT_RESERVE


def fits(body: dict[str, Any], context_length: int, measured_tokens: int | None = None,
         measured_rows: int = 0, api_mode: str = "chat_completions") -> bool:
    """Return True when the request size plus the reply reserve fits in the context window.

    When the server measured the prompt of the first measured_rows messages, use that count and estimate only
    the rows after them. Otherwise estimate all messages and tools.
    """
    if context_length <= 0:
        return True
    reserve = reply_reserve(body)
    field = protocol.history_key(api_mode)
    messages = body.get(field) or []
    if type(measured_tokens) is int and measured_tokens > 0 and 0 < measured_rows <= len(messages):
        size = measured_tokens + estimate_tokens({field: messages[measured_rows:]}) * SAFETY
    else:
        size = estimate_tokens({key: value for key, value in body.items()
                                if key == field or isinstance(value, (str, list, dict))}) * SAFETY
    if api_mode == "codex_responses" and not any(
            type(body.get(key)) is int and body[key] > 0 for key in ("max_output_tokens", "max_tokens")):
        reserve = max(DEFAULT_RESERVE, min(context_length // 4, 65_536))
    return size + int(reserve) <= context_length


def build_request(capture: dict[str, Any], messages: list, route: tuple, context_length: int,
                  instruction: str, native_type: str | None = None) -> dict[str, Any]:
    """Return the warm request body. Raise WarmRefusal when a condition is not true. native_type: the native
    reasoning carrier type of the provider profile (native_details_type)."""
    if route[2] == "codex_responses":
        from .responses import build_request as build_native
        return build_native(capture, messages, route, context_length, instruction, native_type)
    if route[2] == "anthropic_messages":
        from .anthropic import build_request as build_native
        return build_native(capture, messages, route, context_length, instruction, native_type)
    if route[2] != "chat_completions":
        raise WarmRefusal("api_mode_unsupported")
    if tuple(capture["route"]) != tuple(route):
        raise WarmRefusal("route_changed")
    body = capture.get("body")
    if body is None:
        raise WarmRefusal(capture.get("refusal") or "settings_unsupported")
    check_settings(body)
    new_rows, trailing = split_history(capture, messages)
    check_source(body, messages[: len(capture["digests"])], route[1], native_type)
    request = dict(body)
    # Send the trailing user rows too: the tail can keep only the newest of them, and compaction removes the others.
    echo = needs_reasoning_echo(body, new_rows)
    added = [wire_row(row, echo, body.get("model"), route[1], native_type) for row in (*new_rows, *trailing)]
    request["messages"] = [*body["messages"], *_join_user_rows(added, instruction)]
    request["stream"] = False
    request.pop("stream_options", None)
    # A stop sequence of the main request could cut the handoff after the handoff headings.
    request.pop("stop", None)
    # A web search costs a search and can bring text that is not in the conversation into the handoff.
    request.pop("web_search_options", None)
    # The reply limit of the main request is for another task: a small one cuts the handoff, a large one reserves
    # space that the handoff does not need. Keep the field that the route uses.
    for key in LIMIT_KEYS:
        value = body.get(key)
        if type(value) is int and value > 0:
            request[key] = min(max(value, HANDOFF_MIN_TOKENS), HANDOFF_MAX_TOKENS)
    # Without a limit the server default applies: a small one cuts the handoff, a large one can take more space
    # than the capacity check reserves. The handoff gets HANDOFF_MAX_TOKENS in the field of the route.
    if not any(type(body.get(key)) is int and body.get(key) > 0 for key in LIMIT_KEYS):
        request[limit_field(body.get("model"), route[1])] = HANDOFF_MAX_TOKENS
    if not fits(request, context_length, capture.get("prompt_tokens"), len(body["messages"])):
        raise WarmRefusal("capacity")
    return request


class _NoRedirect(urllib.request.HTTPRedirectHandler):
    """Do not follow a redirect. A followed redirect would send the Authorization header to another origin."""

    def redirect_request(self, req, fp, code, msg, headers, newurl):  # noqa: D102
        return None


# A reply is at most a few tens of kilobytes (the handoff gate allows 24 KB of text). A larger body is not read
# whole: a wrong endpoint or a gateway must not fill the memory of the Hermes process.
MAX_RESPONSE_BYTES = 1 << 20


def urllib_post(url: str, data: bytes, headers: dict[str, str], timeout_s: float,
                context: ssl.SSLContext | None = None) -> tuple[int, bytes]:
    """POST data with the standard library. Return (status, body). Raise TimeoutError on a time-out. A redirect
    is not followed: its status comes back, and the caller treats it as a provider error. context is the TLS
    context of the route (route_tls). The body is read to at most MAX_RESPONSE_BYTES + 1 bytes."""
    handlers: list = [urllib.request.ProxyHandler(urllib.request.getproxies_environment()), _NoRedirect()]
    if context is not None:
        handlers.append(urllib.request.HTTPSHandler(context=context))
    opener = urllib.request.build_opener(*handlers)
    request = urllib.request.Request(url, data=data, headers=headers, method="POST")
    try:
        with opener.open(request, timeout=timeout_s) as response:
            return response.status, response.read(MAX_RESPONSE_BYTES + 1)
    except urllib.error.HTTPError as error:
        # The error body is not used.
        error.close()
        return error.code, b""
    except urllib.error.URLError as error:
        if isinstance(error.reason, TimeoutError):
            raise TimeoutError(str(error.reason)) from error
        raise


def api_key_text(api_key: Any) -> str:
    """The key as text: the value of a key function now, or "" when it cannot be read."""
    if callable(api_key):
        try:
            api_key = api_key()
        except Exception:
            return ""
    return api_key if isinstance(api_key, str) else ""


_FINISH_ALIASES = {"max_tokens": "length", "end": "stop", "function_call": "tool_calls"}


def _normalize_finish_reason(raw: Any) -> Any:
    """The rule of Hermes 45871e10 (agent.message_sanitization.normalize_finish_reason): the lowercase OpenAI
    value, with the aliases of other providers. Hermes applies it in its transport; this request does not use it."""
    if not isinstance(raw, str) or not raw:
        return raw
    lowered = raw.lower()
    return _FINISH_ALIASES.get(lowered, lowered)


def route_headers(api_key: Any, base_url: Any, provider: Any,
                  api_mode: str = "chat_completions") -> dict[str, str]:
    """Return the default headers that the Hermes OpenAI client sends on this route, in the order of Hermes
    45871e10 (agent.agent_init): the host headers or the provider profile headers, then model.default_headers,
    then providers.<name>.extra_headers. Provider headers go with every request (attribution, a User-Agent for a
    WAF, gateway credentials). Raise WarmRefusal("headers_unknown") when a source cannot be read: a request
    without them can be refused or go to another cache. The engine adds supported per-request session headers
    from the capture after this step. The values can be credentials: never log them."""
    url = str(base_url or "")
    if api_mode == "anthropic_messages":
        try:
            from hermes_cli.config_providers import get_custom_provider_extra_headers
            headers = get_custom_provider_extra_headers(url) or {}
        except Exception as error:
            raise WarmRefusal("headers_unknown") from error
        return native_headers(api_key_text(api_key), url, provider, api_mode, dict(headers))
    try:
        from agent.agent_init import _host_default_headers_factory
        from agent.auxiliary_client import _apply_user_default_headers
        from hermes_cli.config_providers import get_custom_provider_extra_headers
        factory = _host_default_headers_factory(url)
        if factory is not None:
            headers = dict(factory(api_key_text(api_key), url) or {})
        else:
            from providers import get_provider_profile
            profile = get_provider_profile(provider) if provider else None
            headers = dict(getattr(profile, "default_headers", None) or {})
        headers = dict(_apply_user_default_headers(headers) or {})
        headers.update(get_custom_provider_extra_headers(url) or {})
    except Exception as error:
        raise WarmRefusal("headers_unknown") from error
    return {str(key): str(value) for key, value in headers.items()}


def route_tls(base_url: Any) -> ssl.SSLContext | None:
    """Return the TLS context of an https route as the Hermes client has it (ssl_ca_cert of a custom provider,
    through agent.ssl_verify.resolve_httpx_verify), or None for the default context. Raise
    WarmRefusal("tls_unknown") when the setting cannot be read: with another trust setting, the request fails
    or goes to a server that the main requests do not trust. Raise WarmRefusal("tls_unverified") for
    ssl_verify: false: the plugin does not send without certificate checks."""
    url = str(base_url or "")
    if not url.lower().startswith("https:"):
        return None
    try:
        from agent.ssl_verify import resolve_httpx_verify
        from hermes_cli.config_providers import get_custom_provider_tls_settings
        tls = get_custom_provider_tls_settings(url) or {}
        verify = resolve_httpx_verify(ca_bundle=tls.get("ssl_ca_cert"), ssl_verify=tls.get("ssl_verify"),
                                      base_url=url)
    except Exception as error:
        raise WarmRefusal("tls_unknown") from error
    if isinstance(verify, ssl.SSLContext):
        return verify
    if verify is False:
        # ssl_verify: false. The plugin does not send without certificate checks; the fallback runs.
        raise WarmRefusal("tls_unverified")
    if verify is True:
        return None
    raise WarmRefusal("tls_unknown")


def _optional_int(value: Any) -> int | None:
    return value if isinstance(value, int) and not isinstance(value, bool) else None


def native_headers(key: str, base_url: str, provider: str, api_mode: str, headers: dict) -> dict:
    """Resolve native authentication before the middleware sees a warm request."""
    if api_mode == "anthropic_messages":
        from .anthropic import route_headers as messages_headers
        return messages_headers(key, base_url, headers, provider)
    if api_mode == "codex_responses" and urllib.parse.urlsplit(base_url).hostname == "chatgpt.com":
        try:
            from agent.codex_headers import codex_cloudflare_headers
            required = codex_cloudflare_headers(key, base_url=base_url)
            names = {name.lower() for name in required}
            headers = {name: value for name, value in headers.items() if name.lower() not in names}
            return {**headers, **required}
        except Exception as error:
            raise WarmRefusal("headers_unknown") from error
    return headers


def send(body: dict[str, Any], base_url: str, api_key: Any, timeout_s: float = TIMEOUT_S,
         post: Post | None = None, extra_headers: dict[str, str] | None = None,
         ssl_context: ssl.SSLContext | None = None, api_mode: str = "chat_completions",
         provider: str = "") -> dict[str, Any]:
    """Send the warm request one time. Return the reply fields and the usage, or raise WarmRefusal.
    extra_headers are the client default headers of the route (route_headers); they win, as in the SDK."""
    if not base_url:
        raise WarmRefusal("provider_error")
    headers = {"Content-Type": "application/json", "Accept": "application/json",
               "User-Agent": USER_AGENT}
    key = api_key_text(api_key)
    if key and api_mode != "anthropic_messages":
        headers["Authorization"] = f"Bearer {key}"
    headers.update(extra_headers or {})
    headers = native_headers(key, base_url, provider, api_mode, headers)
    if api_mode == "codex_responses" and body.get("stream"):
        headers["Accept"] = "text/event-stream"
    data = json.dumps(body).encode("utf-8")
    started = time.monotonic()
    try:
        # The query of the route URL stays after the path: Hermes sends it as the client's default_query (the
        # api-version of an Azure route, for example).
        parts = urllib.parse.urlsplit(str(base_url))
        path = parts.path.rstrip("/")
        endpoint = "/chat/completions"
        if api_mode == "codex_responses":
            endpoint = "/responses"
        elif api_mode == "anthropic_messages":
            endpoint = "/messages" if path.endswith("/v1") else "/v1/messages"
        elif api_mode != "chat_completions":
            raise WarmRefusal("api_mode_unsupported")
        url = urllib.parse.urlunsplit(parts._replace(path=path + endpoint))
        if ssl_context is None:
            status, raw = (post or urllib_post)(url, data, headers, timeout_s)
        else:
            status, raw = (post or urllib_post)(url, data, headers, timeout_s, context=ssl_context)
    except TimeoutError as error:
        raise WarmRefusal("timeout") from error
    except Exception as error:
        raise WarmRefusal("provider_error") from error
    elapsed = time.monotonic() - started
    if not 200 <= int(status) < 300:
        raise WarmRefusal("provider_error")
    if len(raw) > MAX_RESPONSE_BYTES:
        raise WarmRefusal("response_too_large")
    try:
        if api_mode != "chat_completions":
            from . import anthropic, responses
            parser = responses.parse_reply if api_mode == "codex_responses" else anthropic.parse_reply
            result = parser(protocol.envelope(raw, api_mode))
            return {**result, "elapsed_s": round(elapsed, 3)}
        payload = json.loads(raw.decode("utf-8"))
        choice = payload["choices"][0]
        message = choice["message"]
        usage = payload.get("usage") or {}
        details = usage.get("prompt_tokens_details") or {}
        return {
            "content": message.get("content"),
            "finish_reason": hermes_value("agent.message_sanitization", "normalize_finish_reason",
                                          _normalize_finish_reason)(choice.get("finish_reason")),
            "tool_calls": bool(message.get("tool_calls")),
            "refusal": bool(message.get("refusal")),
            "prompt_tokens": _optional_int(usage.get("prompt_tokens")),
            "completion_tokens": _optional_int(usage.get("completion_tokens")),
            "cached_tokens": _optional_int(details.get("cached_tokens")),
            "elapsed_s": round(elapsed, 3),
        }
    except (ValueError, KeyError, IndexError, TypeError, AttributeError) as error:
        raise WarmRefusal("incomplete_response") from error