api_request_hooks.py 8.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198
  1. """Lifecycle-hook payloads for ``AIAgent`` API requests.
  2. JSON-safe coercion, secret-key redaction, size caps, and the ``api_request_error`` hook dispatch.
  3. Extracted from ``run_agent.py``; every method resolves through ``AIAgent``'s MRO unchanged.
  4. """
  5. import json
  6. import os
  7. import time
  8. from contextlib import suppress
  9. from types import SimpleNamespace
  10. from typing import Any, Dict, Optional
  11. from agent.usage_pricing import normalize_usage
  12. _SENSITIVE_HOOK_KEYS = {"api_key", "authorization", "proxy_authorization", "cookie", "set_cookie"}
  13. def _model_dump(value: Any) -> Any:
  14. """``value.model_dump(mode="json")`` with graceful degradation for older pydantic signatures.
  15. warnings=False: pydantic UserWarnings on generic-union SDK models would leak to the terminal.
  16. """
  17. try:
  18. return value.model_dump(mode="json", warnings=False)
  19. except TypeError:
  20. try:
  21. return value.model_dump(mode="json")
  22. except TypeError:
  23. return value.model_dump()
  24. class ApiRequestHooksMixin:
  25. """Hook payload sanitising + ``api_request_error`` dispatch (see module docstring)."""
  26. def _usage_summary_for_api_request_hook(self, response: Any) -> Optional[dict[str, Any]]:
  27. """Token buckets for ``post_api_request`` plugins (no raw ``response`` object)."""
  28. if response is None:
  29. return None
  30. raw_usage = getattr(response, "usage", None)
  31. if not raw_usage:
  32. return None
  33. from dataclasses import asdict
  34. cu = normalize_usage(raw_usage, provider=self.provider, api_mode=self.api_mode)
  35. summary = asdict(cu)
  36. summary.pop("raw_usage", None)
  37. summary["prompt_tokens"] = cu.prompt_tokens
  38. summary["total_tokens"] = cu.total_tokens
  39. return summary
  40. @staticmethod
  41. def _hook_payload_max_chars() -> int:
  42. raw = os.getenv("HERMES_PLUGIN_PAYLOAD_MAX_CHARS", "50000")
  43. try:
  44. return max(1000, int(raw))
  45. except (TypeError, ValueError):
  46. return 50000
  47. @staticmethod
  48. def _is_sensitive_hook_key(key: Any) -> bool:
  49. if not isinstance(key, str):
  50. return False
  51. lowered = key.lower().replace("-", "_")
  52. return lowered in _SENSITIVE_HOOK_KEYS or lowered.endswith("_api_key")
  53. @classmethod
  54. def _hook_jsonable(
  55. cls, value: Any, *, depth: int = 0, max_depth: int = 8, max_string: int = 8000,
  56. max_sequence: int = 200,
  57. ) -> Any:
  58. if depth > max_depth:
  59. return f"<{type(value).__name__} depth limit>"
  60. if value is None or isinstance(value, (bool, int, float)):
  61. return value
  62. if isinstance(value, str):
  63. if len(value) > max_string:
  64. return value[:max_string] + f"...[truncated {len(value) - max_string} chars]"
  65. return value
  66. if isinstance(value, (bytes, bytearray)):
  67. return f"<{len(value)} bytes>"
  68. def recurse(item):
  69. return cls._hook_jsonable(
  70. item, depth=depth + 1, max_depth=max_depth, max_string=max_string,
  71. max_sequence=max_sequence,
  72. )
  73. if isinstance(value, dict):
  74. out: dict[str, Any] = {}
  75. for idx, (key, item) in enumerate(value.items()):
  76. if idx >= max_sequence:
  77. out["_truncated_items"] = len(value) - max_sequence
  78. break
  79. str_key = str(key)
  80. out[str_key] = "<redacted>" if cls._is_sensitive_hook_key(str_key) else recurse(item)
  81. return out
  82. if isinstance(value, (list, tuple, set)):
  83. seq = list(value)
  84. out = [recurse(item) for item in seq[:max_sequence]]
  85. if len(seq) > max_sequence:
  86. out.append({"_truncated_items": len(seq) - max_sequence})
  87. return out
  88. with suppress(Exception):
  89. if hasattr(value, "model_dump"):
  90. return recurse(_model_dump(value))
  91. with suppress(Exception):
  92. from dataclasses import asdict, is_dataclass
  93. if is_dataclass(value):
  94. return recurse(asdict(value))
  95. if isinstance(value, SimpleNamespace):
  96. return recurse(vars(value))
  97. if hasattr(value, "__dict__"):
  98. with suppress(Exception):
  99. return recurse({k: v for k, v in vars(value).items() if not str(k).startswith("_")})
  100. return str(value)[:max_string]
  101. @classmethod
  102. def _sanitize_hook_payload(cls, value: Any) -> Any:
  103. """JSON-able payload under the size cap: full → reduced caps → truncated preview."""
  104. limit = cls._hook_payload_max_chars()
  105. encoded = ""
  106. for caps in ({}, {"max_string": 1000, "max_sequence": 50}):
  107. payload = cls._hook_jsonable(value, **caps)
  108. try:
  109. encoded = json.dumps(payload, ensure_ascii=False, default=str)
  110. except Exception:
  111. return str(payload)[:limit]
  112. if len(encoded) <= limit:
  113. return payload
  114. return {
  115. "_truncated": True, "original_type": type(value).__name__, "preview": encoded[:limit]
  116. }
  117. def _api_request_payload_for_hook(self, api_kwargs: Optional[dict[str, Any]]) -> dict[str, Any]:
  118. body = {
  119. key: value
  120. for key, value in (api_kwargs or {}).items()
  121. if key not in {"timeout", "http_client"}
  122. }
  123. return self._sanitize_hook_payload({"method": "POST", "body": body})
  124. def _api_response_payload_for_hook(
  125. self, response: Any, assistant_message: Any, *, finish_reason: Optional[str]
  126. ) -> dict[str, Any]:
  127. # Raw provider SDK tool_call objects are handed to the sanitizer on purpose; `_hook_jsonable` must
  128. # keep normalising them (model_dump / __dict__ / dataclass) or subscribers get str() blobs.
  129. tool_calls = getattr(assistant_message, "tool_calls", None) or []
  130. return self._sanitize_hook_payload(
  131. {
  132. "model": getattr(response, "model", None),
  133. # Downstream that served the call (relays re-roll it per request; #90216).
  134. "upstream_provider": getattr(response, "provider", None),
  135. "finish_reason": finish_reason,
  136. "assistant_message": {
  137. "role": getattr(assistant_message, "role", "assistant"),
  138. "content": getattr(assistant_message, "content", None),
  139. "tool_calls": tool_calls,
  140. },
  141. "usage": self._usage_summary_for_api_request_hook(response),
  142. }
  143. )
  144. def _invoke_api_request_error_hook(
  145. self, *, task_id: str, turn_id: str, api_request_id: str, api_call_count: int,
  146. api_start_time: float, api_kwargs: Optional[dict[str, Any]], error_type: str,
  147. error_message: str, status_code: Optional[int] = None, retry_count: Optional[int] = None,
  148. max_retries: Optional[int] = None, retryable: Optional[bool] = None,
  149. reason: Optional[str] = None,
  150. ) -> None:
  151. # Lazy module import (not from-import) so tests can replace lifecycle dispatch at this call site.
  152. with suppress(Exception):
  153. from hermes_cli import lifecycle as _lifecycle
  154. if not _lifecycle.has_hook("api_request_error"):
  155. return
  156. ended_at = time.time()
  157. _lifecycle.invoke_hook(
  158. "api_request_error",
  159. task_id=task_id,
  160. turn_id=turn_id,
  161. api_request_id=api_request_id,
  162. session_id=self.session_id or "",
  163. platform=self.platform or "",
  164. model=self.model,
  165. provider=self.provider,
  166. base_url=self.base_url,
  167. api_mode=self.api_mode,
  168. api_call_count=api_call_count,
  169. api_duration=ended_at - api_start_time,
  170. started_at=api_start_time,
  171. ended_at=ended_at,
  172. status_code=status_code,
  173. retry_count=retry_count,
  174. max_retries=max_retries,
  175. retryable=retryable,
  176. reason=reason,
  177. error={"type": error_type, "message": error_message},
  178. request=self._api_request_payload_for_hook(api_kwargs),
  179. )