Hermes Agent context engine: the main model writes the compaction handoff on its cached prompt prefix
"""Build a bounded warm request for the Anthropic Messages API."""
from __future__ import annotations
import copy
import json
from typing import Any
from urllib.parse import urlsplit
from .rows import api_content, attr, tool_calls_of
from .warm import HANDOFF_MAX_TOKENS, HANDOFF_MIN_TOKENS, WarmRefusal, fits, split_history
COMMON_BETAS = "interleaved-thinking-2025-05-14,fine-grained-tool-streaming-2025-05-14"
OPAQUE_ROWS = ("reasoning_details", "reasoning_content", "anthropic_content_blocks", "_anthropic_content_blocks")
SETTINGS = {"model", "messages", "system", "tools", "tool_choice", "max_tokens", "stream", "stop_sequences",
"thinking", "output_config", "temperature", "top_p", "top_k", "metadata", "service_tier",
"cache_control"}
def _refuse() -> None:
raise WarmRefusal("source_transform_unsupported")
def _text(content: Any, *, empty: str = "") -> list[dict]:
if content is None:
content = ""
if isinstance(content, str):
text = content if content.strip() else empty
return [{"type": "text", "text": text}] if text else []
if isinstance(content, list) and all(isinstance(p, dict) and p.get("type") == "text"
and isinstance(p.get("text"), str)
and set(p) <= {"type", "text", "cache_control"} for p in content):
# Hermes 6e7b83a drops blank text blocks. Keep all bytes of each nonblank block.
blocks = [{"type": "text", "text": p["text"]} for p in content if p["text"].strip()]
return blocks or ([{"type": "text", "text": empty}] if empty else [])
_refuse()
def _id(value: Any) -> str:
if not isinstance(value, str) or not value or any(not (c.isascii() and (c.isalnum() or c in "_-")) for c in value):
_refuse()
return value
def _thinking(blocks: Any) -> list[dict]:
if blocks is None:
return []
if not isinstance(blocks, list):
_refuse()
result = []
for block in blocks:
if not isinstance(block, dict):
_refuse()
fields = {"thinking": {"type", "thinking", "signature"}, "redacted_thinking": {"type", "data"}}
kind = block.get("type")
if kind not in fields or set(block) != fields[kind] or any(type(v) is not str for v in block.values()):
_refuse()
if not block.get("signature" if kind == "thinking" else "data"):
_refuse()
result.append(copy.deepcopy(block))
return result
def _assistant_blocks(row: Any, text: list[dict], calls: list[dict], base_url: Any) -> list[dict]:
if attr(row, "_anthropic_content_blocks"):
_refuse()
details = _thinking(attr(row, "reasoning_details"))
mirror = attr(row, "reasoning_content")
if mirror and (not details or mirror != "\n\n".join(b["thinking"] for b in details if b["type"] == "thinking")):
_refuse()
ordered = attr(row, "anthropic_content_blocks")
if ordered:
if not isinstance(ordered, list):
_refuse()
clean = []
for block in ordered:
if not isinstance(block, dict):
_refuse()
kind = block.get("type")
if kind in ("thinking", "redacted_thinking"):
clean.extend(_thinking([block]))
elif kind == "text":
clean.extend(_text([block]))
elif kind == "tool_use" and set(block) == {"type", "id", "name", "input"}:
clean.append(copy.deepcopy(block))
else:
_refuse()
if ([b for b in clean if b["type"] == "tool_use"] != calls
or "\n".join(b["text"] for b in clean if b["type"] == "text") != "\n".join(b["text"] for b in text)
or [b for b in clean if b["type"] in ("thinking", "redacted_thinking")] != details):
_refuse()
else:
clean = [*details, *text, *calls]
host = (urlsplit(str(base_url or "https://api.anthropic.com")).hostname or "").lower()
if details and host != "api.anthropic.com":
# Generic gateways can strip or reject native signatures. That renderer is not reproduced here.
_refuse()
return clean
def _rows(rows: list, *, new: bool = False, base_url: Any = None) -> list[dict]:
result: list[dict] = []
pending: set[str] = set()
seen: set[str] = set()
for row in rows:
role = attr(row, "role")
if role in ("system", "developer"):
if new:
_refuse()
continue
if role != "assistant" and any(attr(row, key) for key in OPAQUE_ROWS):
_refuse()
if role == "tool":
call_id = _id(attr(row, "tool_call_id"))
if call_id not in pending or not isinstance(attr(row, "content"), str):
_refuse()
pending.remove(call_id)
content = [{"type": "tool_result", "tool_use_id": call_id,
"content": attr(row, "content") or "(no output)"}]
role = "user"
elif role in ("user", "assistant"):
if pending:
_refuse()
content = _text(api_content(row), empty="(empty message)" if role == "user" else "")
calls = []
for call_id, name, arguments in tool_calls_of(row):
if role != "assistant" or not isinstance(name, str) or not name:
_refuse()
call_id = _id(call_id)
if call_id in seen:
_refuse()
try:
args = json.loads(arguments) if isinstance(arguments, str) else arguments
except (TypeError, ValueError):
_refuse()
if not isinstance(args, dict):
_refuse()
calls.append({"type": "tool_use", "id": call_id, "name": name, "input": args})
pending.add(call_id)
seen.add(call_id)
if role == "assistant":
content = _assistant_blocks(row, content, calls, base_url)
content = content or [{"type": "text", "text": "(empty)" if role == "assistant" else "(empty message)"}]
else:
_refuse()
if result and result[-1]["role"] == role:
if role == "assistant" and any(b["type"] in ("thinking", "redacted_thinking") for b in content):
_refuse()
result[-1]["content"].extend(content)
else:
result.append({"role": role, "content": content})
if pending:
_refuse()
return result
def _native_rows(rows: Any) -> list[dict]:
if not isinstance(rows, list):
_refuse()
normalized = []
for row in rows:
if not isinstance(row, dict) or set(row) != {"role", "content"} or row["role"] not in ("user", "assistant"):
_refuse()
blocks = _text(row["content"]) if isinstance(row["content"], str) else row["content"]
if not isinstance(blocks, list):
_refuse()
clean = []
for block in blocks:
if not isinstance(block, dict):
_refuse()
part = {k: v for k, v in block.items() if k != "cache_control"}
kind = part.get("type")
if kind in ("thinking", "redacted_thinking") and row["role"] == "assistant":
clean.extend(_thinking([part]))
continue
fields = {"text": {"type", "text"}, "tool_use": {"type", "id", "name", "input"},
"tool_result": {"type", "tool_use_id", "content"}}
if kind not in fields or set(part) != fields[kind]:
_refuse()
clean.append(part)
normalized.append({"role": row["role"], "content": clean})
return normalized
def check_source(body: dict[str, Any], history: list, base_url: Any = None, native_type: str | None = None) -> None:
"""Check that the text and tool data in the captured prefix describe the stored history."""
del native_type
expected = _rows(history, base_url=base_url)
actual = _native_rows(body.get("messages"))
if actual != expected:
_refuse()
def build_request(capture: dict[str, Any], messages: list, route: tuple, context_length: int,
instruction: str, native_type: str | None = None) -> dict[str, Any]:
"""Keep the native prefix and append a text and tool handoff turn."""
del native_type
if route[2] != "anthropic_messages":
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")
if set(body) - SETTINGS or not isinstance(body.get("messages"), list):
raise WarmRefusal("settings_unsupported")
if isinstance(body.get("output_config"), dict) and set(body["output_config"]) - {"effort"}:
raise WarmRefusal("settings_unsupported")
choice = body.get("tool_choice")
if choice is not None and choice not in ({"type": "auto"}, {"type": "none"}):
raise WarmRefusal("settings_unsupported")
if any(not isinstance(t, dict) or "input_schema" not in t or t.get("type") for t in body.get("tools", [])):
raise WarmRefusal("settings_unsupported")
new_rows, trailing = split_history(capture, messages)
check_source(body, messages[:len(capture["digests"])], route[1])
added = _rows([*new_rows, *trailing], new=True, base_url=route[1])
block = {"type": "text", "text": instruction}
if added and added[-1]["role"] == "user":
added[-1]["content"].append(block)
else:
added.append({"role": "user", "content": [block]})
if body["messages"] and added and body["messages"][-1]["role"] == added[0]["role"]:
# Merging into the old turn would change its cache boundary or a thinking signature.
_refuse()
request = copy.deepcopy(body)
request["messages"].extend(added)
request["stream"] = False
request.pop("stop_sequences", None)
limit = body.get("max_tokens")
limit = limit if type(limit) is int and limit > 0 else HANDOFF_MAX_TOKENS
request["max_tokens"] = min(max(limit, HANDOFF_MIN_TOKENS), HANDOFF_MAX_TOKENS)
thinking = request.get("thinking")
if isinstance(thinking, dict) and thinking.get("type") == "enabled":
budget = thinking.get("budget_tokens")
if type(budget) is not int or budget <= 0:
raise WarmRefusal("settings_unsupported")
request["max_tokens"] = max(request["max_tokens"], budget + HANDOFF_MIN_TOKENS)
if not fits(request, context_length, capture.get("prompt_tokens"), len(body["messages"]),
api_mode="anthropic_messages"):
raise WarmRefusal("capacity")
return request
def route_headers(key: str, base_url: Any, existing_headers: dict, provider: str = "") -> dict[str, str]:
"""Use API-key auth for native Anthropic and ordinary Messages gateways. Refuse other auth routes."""
url = urlsplit(str(base_url or "https://api.anthropic.com"))
host = (url.hostname or "").lower()
oauth = key and not key.startswith("sk-ant-api") and key.startswith(("sk-ant-", "eyJ", "cc-"))
if oauth or provider in {"bedrock", "nous"}:
raise WarmRefusal("auth_unsupported")
if any(part in host for part in ("minimax", "moonshot", "kimi", "azure", "anthropic.aws")):
raise WarmRefusal("auth_unsupported")
if any(host == name or host.endswith("." + name) for name in (
"api.commandcode.ai", "palantirfoundry.com", "inference-api.nousresearch.com")):
raise WarmRefusal("auth_unsupported")
for name, value in existing_headers.items():
if name.lower() == "authorization":
raise WarmRefusal("auth_unsupported")
if name.lower() == "x-api-key" and value != key:
raise WarmRefusal("auth_unsupported")
headers = {k: v for k, v in existing_headers.items() if k.lower() not in ("authorization", "x-api-key")}
if not any(k.lower() == "anthropic-version" for k in headers):
headers["anthropic-version"] = "2023-06-01"
if not any(k.lower() == "anthropic-beta" for k in headers):
headers["anthropic-beta"] = COMMON_BETAS
if key:
headers["x-api-key"] = key
return headers
def parse_reply(payload: dict) -> dict[str, Any]:
"""Read the completed native message and its optional token counters."""
try:
if payload.get("type") != "message" or payload.get("role") != "assistant":
raise ValueError
blocks = payload["content"]
if not isinstance(blocks, list) or any(not isinstance(b, dict) for b in blocks):
raise ValueError
text = []
for block in blocks:
if block.get("type") == "text":
if not isinstance(block.get("text"), str):
raise ValueError
text.append(block["text"])
reason = payload.get("stop_reason")
finish = {"end_turn": "stop", "stop_sequence": "stop", "max_tokens": "length",
"model_context_window_exceeded": "length", "tool_use": "tool_calls",
"refusal": "content_filter"}.get(reason)
usage = payload.get("usage")
usage = {} if usage is None else usage
if not isinstance(usage, dict):
raise ValueError
counters = [usage.get(k) for k in ("input_tokens", "cache_read_input_tokens", "cache_creation_input_tokens")]
def count(value):
return value if type(value) is int and value >= 0 else None
prompt = sum(counters) if all(count(v) is not None for v in counters) else None
return {"content": "\n".join(text), "finish_reason": finish,
"tool_calls": any(b.get("type") not in ("text", "thinking", "redacted_thinking") for b in blocks),
"refusal": reason == "refusal", "prompt_tokens": prompt,
"completion_tokens": count(usage.get("output_tokens")),
"cached_tokens": count(usage.get("cache_read_input_tokens"))}
except (TypeError, ValueError, KeyError, AttributeError) as error:
raise WarmRefusal("incomplete_response") from error