Hermes Agent context engine: the main model writes the compaction handoff on its cached prompt prefix
"""warm_compaction: a standalone context engine plugin for Hermes Agent."""
from __future__ import annotations
import importlib
import logging
from typing import Any
logger = logging.getLogger(__name__)
TASK = "warm_compaction"
HOOKS = ("pre_api_request", "post_api_request", "on_session_finalize", "on_session_reset")
MIDDLEWARE = "llm_execution"
CONTEXT_METHODS = (
"register_context_engine", "register_hook", "register_middleware", "register_auxiliary_task", "get_config",
)
# The Hermes context engine loader gives a context without these APIs. Hermes tries that loader first and then
# uses the engine that the enabled plugin registered through the full plugin API.
PLUGIN_SYSTEM_ONLY = ("register_middleware", "register_auxiliary_task", "get_config", "llm.complete")
HOST_PREFIXES = ("hook:", "middleware:", "agent.")
def _read(module: str, name: str) -> Any:
try:
return getattr(importlib.import_module(module), name)
except Exception:
return None
def missing_apis(ctx: Any) -> list[str]:
"""Return the names of the needed Hermes plugin APIs that are not available."""
missing = [name for name in CONTEXT_METHODS if not callable(getattr(ctx, name, None))]
try:
llm = ctx.llm
except Exception:
llm = None
if not callable(getattr(llm, "complete", None)):
missing.append("llm.complete")
hooks = _read("hermes_cli.plugins", "VALID_HOOKS") or ()
missing.extend(f"hook:{hook}" for hook in HOOKS if hook not in hooks)
if MIDDLEWARE not in (_read("hermes_cli.middleware", "VALID_MIDDLEWARE") or ()):
missing.append(f"middleware:{MIDDLEWARE}")
if _read("agent.context_engine", "ContextEngine") is None:
missing.append("agent.context_engine.ContextEngine")
return missing
def engine_loader_context(missing: list[str]) -> bool:
"""True when only the plugin-system APIs are missing, and this Hermes has the hooks and the middleware."""
return (all(name in missing for name in PLUGIN_SYSTEM_ONLY)
and not any(name.startswith(HOST_PREFIXES) for name in missing)
and "register_context_engine" not in missing)
def register(ctx: Any) -> None:
"""Hermes entry point: register the fallback task, the engine, the hooks, and the middleware."""
missing = missing_apis(ctx)
if missing and engine_loader_context(missing):
logger.debug("warm_compaction: this plugin context does not have these APIs: %s. The plugin registers "
"nothing in this context. The enabled plugin registers the engine through the full plugin "
"API.", ", ".join(missing))
return
if missing:
logger.warning("Hermes is missing plugin APIs that warm_compaction needs (%s); the plugin registers "
"nothing and Hermes keeps its built-in compressor", ", ".join(missing))
return
from .capture import CaptureStore
from .engine import WarmCompactionEngine, read_settings
settings = read_settings(ctx.get_config)
task: str | None = TASK
try:
# The task default follows the plugin time limit; each fallback call also sends its remaining time.
ctx.register_auxiliary_task(TASK, display_name="Warm compaction fallback",
description="Model for the warm_compaction fallback summary.",
defaults={"timeout": settings["timeout_s"]})
except Exception as error:
task = None
logger.warning("warm_compaction could not register its auxiliary task (%s); the fallback summary uses "
"the main model route", type(error).__name__)
store = CaptureStore()
engine = WarmCompactionEngine(store=store, llm=ctx.llm, settings=settings, task=task)
if ctx.register_context_engine(engine) is None:
logger.warning("Hermes did not accept the warm_compaction context engine; the plugin registers no hooks")
return
ctx.register_hook("pre_api_request", store.on_pre_api_request)
ctx.register_middleware(MIDDLEWARE, store.on_llm_execution)
ctx.register_hook("post_api_request", store.on_post_api_request)
ctx.register_hook("on_session_finalize", store.forget)
ctx.register_hook("on_session_reset", store.forget)
__all__ = ["engine_loader_context", "missing_apis", "register"]