middleware.py 8.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215
  1. """Hermes middleware contract helpers.
  2. Observer hooks report what happened. Middleware can change what happens by rewriting a request or
  3. wrapping the actual execution callback. Agent-loop call sites and plugins share this vocabulary.
  4. """
  5. from __future__ import annotations
  6. import logging
  7. from copy import deepcopy
  8. from dataclasses import dataclass, field
  9. from typing import Any, Callable, Dict, List
  10. logger = logging.getLogger(__name__)
  11. OBSERVER_SCHEMA_VERSION = "hermes.observer.v1"
  12. MIDDLEWARE_SCHEMA_VERSION = "hermes.middleware.v1"
  13. TOOL_REQUEST_MIDDLEWARE = "tool_request"
  14. TOOL_EXECUTION_MIDDLEWARE = "tool_execution"
  15. LLM_REQUEST_MIDDLEWARE = "llm_request"
  16. LLM_EXECUTION_MIDDLEWARE = "llm_execution"
  17. VALID_MIDDLEWARE: set[str] = {
  18. TOOL_REQUEST_MIDDLEWARE, TOOL_EXECUTION_MIDDLEWARE, LLM_REQUEST_MIDDLEWARE, LLM_EXECUTION_MIDDLEWARE,
  19. }
  20. @dataclass
  21. class RequestMiddlewareResult:
  22. """Result of applying request middleware to a mutable payload."""
  23. payload: Any
  24. original_payload: Any
  25. changed: bool = False
  26. trace: list[dict[str, Any]] = field(default_factory=list)
  27. def observer_payload(**kwargs: Any) -> dict[str, Any]:
  28. kwargs.setdefault("telemetry_schema_version", OBSERVER_SCHEMA_VERSION)
  29. return kwargs
  30. def middleware_payload(**kwargs: Any) -> dict[str, Any]:
  31. kwargs.setdefault("telemetry_schema_version", OBSERVER_SCHEMA_VERSION)
  32. kwargs.setdefault("middleware_schema_version", MIDDLEWARE_SCHEMA_VERSION)
  33. return kwargs
  34. def _safe_copy(payload: Any) -> Any:
  35. """Deep-copy a request payload, tolerating non-deepcopyable members.
  36. An LLM request can carry clients/callbacks/file handles; a hard ``deepcopy`` failure would
  37. otherwise abort the whole request-middleware pass.
  38. """
  39. try:
  40. return deepcopy(payload)
  41. except Exception as exc: # pragma: no cover - exercised via fallback test
  42. logger.debug("deepcopy failed for request payload (%s); using shallow copy", exc)
  43. return dict(payload) if isinstance(payload, dict) else payload
  44. def _apply_request_chain(
  45. kind: str, payload_key: str, trace: list[dict[str, Any]], original: Any, **kwargs: Any
  46. ) -> RequestMiddlewareResult:
  47. """Feed ``kwargs[payload_key]`` through every ``kind`` middleware; each may return ``{payload_key: {...}}``."""
  48. from hermes_cli.plugins import invoke_middleware
  49. current = kwargs[payload_key]
  50. for result in invoke_middleware(kind, _payload_key=payload_key, **middleware_payload(**kwargs)):
  51. if not isinstance(result, dict):
  52. continue
  53. next_payload = result.get(payload_key)
  54. if not isinstance(next_payload, dict):
  55. continue
  56. current = _safe_copy(next_payload)
  57. entry = {
  58. key: value
  59. for key in ("source", "reason", "name")
  60. if isinstance(value := result.get(key), str) and value
  61. }
  62. trace.append(entry or {"source": "plugin"})
  63. return RequestMiddlewareResult(
  64. payload=current, original_payload=original, changed=bool(trace), trace=trace,
  65. )
  66. def apply_llm_request_middleware(request: dict[str, Any], **context: Any) -> RequestMiddlewareResult:
  67. """Apply registered LLM request middleware; ``{"request": {...}}`` replaces the provider kwargs."""
  68. from hermes_cli.plugins import has_middleware
  69. if not has_middleware(LLM_REQUEST_MIDDLEWARE):
  70. return RequestMiddlewareResult(payload=request, original_payload=request)
  71. original_request = _safe_copy(request)
  72. return _apply_request_chain(
  73. LLM_REQUEST_MIDDLEWARE, "request", [], original_request,
  74. request=_safe_copy(original_request), original_request=original_request, **context,
  75. )
  76. def apply_tool_request_middleware(
  77. tool_name: str, args: dict[str, Any], *, original_args: dict[str, Any] | None = None, **context: Any
  78. ) -> RequestMiddlewareResult:
  79. """Apply registered tool request middleware; ``{"args": {...}}`` replaces the effective tool
  80. arguments before hooks, guardrails, approvals, and execution see them. ``original_args`` is the
  81. model's pre-Relay call when ``args`` already carries Relay rewrites (defaults to ``args``)."""
  82. original_args = _safe_copy(args if original_args is None else original_args)
  83. current_args = _safe_copy(args)
  84. trace: list[dict[str, Any]] = []
  85. session_id = str(context.get("session_id") or "")
  86. skip_relay = bool(context.pop("skip_relay", False))
  87. if session_id and not skip_relay:
  88. from agent import relay_runtime
  89. relay_args = relay_runtime.apply_tool_request_intercepts(
  90. session_id=session_id, tool_name=tool_name, args=current_args)
  91. if relay_args != current_args:
  92. current_args = _safe_copy(relay_args)
  93. trace.append({"source": "nemo_relay"})
  94. from hermes_cli.plugins import has_middleware
  95. if not has_middleware(TOOL_REQUEST_MIDDLEWARE):
  96. return RequestMiddlewareResult(
  97. payload=args if not trace else current_args, original_payload=args,
  98. changed=bool(trace), trace=trace,
  99. )
  100. return _apply_request_chain(
  101. TOOL_REQUEST_MIDDLEWARE, "args", trace, original_args,
  102. tool_name=tool_name, args=current_args, original_args=original_args, **context,
  103. )
  104. def run_llm_execution_middleware(
  105. request: dict[str, Any], next_call: Callable[[dict[str, Any]], Any], **context: Any) -> Any:
  106. """Run provider execution through registered LLM execution middleware."""
  107. return _run_execution_chain(
  108. LLM_EXECUTION_MIDDLEWARE, next_call,
  109. request=request, original_request=context.pop("original_request", request), **context)
  110. def run_tool_execution_middleware(
  111. tool_name: str, args: dict[str, Any], next_call: Callable[[dict[str, Any]], Any], **context: Any,
  112. ) -> Any:
  113. """Run tool execution through registered tool execution middleware."""
  114. return _run_execution_chain(
  115. TOOL_EXECUTION_MIDDLEWARE, next_call,
  116. tool_name=tool_name, args=args, original_args=context.pop("original_args", args), **context)
  117. class _DownstreamExecutionError(Exception):
  118. """Marks an exception raised BELOW a middleware frame so the frame's own failure handling
  119. (skip-and-continue) doesn't swallow it."""
  120. def __init__(self, original: BaseException) -> None:
  121. super().__init__(str(original))
  122. self.original = original
  123. def _run_execution_chain(kind: str, terminal_call: Callable[[Any], Any], **kwargs: Any) -> Any:
  124. from hermes_cli.plugins import _delivery_manager
  125. payload_key = "request" if "request" in kwargs else "args"
  126. manager = _delivery_manager()
  127. callbacks = list(manager._middleware.get(kind, []))
  128. if not callbacks:
  129. return terminal_call(kwargs[payload_key])
  130. def call_at(index: int, payload: Any) -> Any:
  131. if index >= len(callbacks):
  132. return terminal_call(payload)
  133. callback = callbacks[index]
  134. next_called = False
  135. next_succeeded = False
  136. next_result: Any = None
  137. def next_call(next_payload: Any = None) -> Any:
  138. nonlocal next_called, next_succeeded, next_result
  139. # Single-use per frame: a second call would re-run the downstream provider/tool, so it
  140. # is a contract violation, not a retry.
  141. if next_called:
  142. raise RuntimeError(
  143. f"Middleware '{kind}' callback "
  144. f"{getattr(callback, '__name__', repr(callback))} called "
  145. "next_call() more than once; downstream execution is single-use"
  146. )
  147. next_called = True
  148. try:
  149. next_result = call_at(index + 1, payload if next_payload is None else next_payload)
  150. next_succeeded = True
  151. return next_result
  152. except Exception as exc:
  153. raise _DownstreamExecutionError(exc) from exc
  154. call_kwargs = middleware_payload(**kwargs)
  155. call_kwargs[payload_key] = payload
  156. call_kwargs["next_call"] = next_call
  157. try:
  158. return callback(**call_kwargs)
  159. except _DownstreamExecutionError as exc:
  160. raise exc.original
  161. except Exception as exc:
  162. # Runs once per tool/LLM call: a mis-declared callback fails identically every time,
  163. # so it goes through the manager's warn-once reporter (#111922).
  164. manager._report_hook_failure(kind, callback, call_kwargs, exc, surface="Middleware")
  165. if next_succeeded:
  166. return next_result
  167. if next_called:
  168. raise
  169. return call_at(index + 1, payload)
  170. return call_at(0, kwargs[payload_key])