hook_output_spill.py 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123
  1. """Spill oversized hook-injected context to disk with a preview placeholder.
  2. Hook ``{"context": ...}`` output rides EVERY subsequent API call, so a large blob
  3. inflates every turn and breaks the prompt-cache prefix. Above
  4. ``hooks.output_spill.max_chars`` (default 10000) the text is written under
  5. ``hooks.output_spill.directory`` (default ``<HERMES_HOME>/hook_outputs/<session>``)
  6. and the payload becomes a ``preview_head``/``preview_tail`` excerpt plus the path.
  7. ``enabled: false`` disables. Never raises: an I/O failure still returns a preview.
  8. """
  9. from __future__ import annotations
  10. import logging
  11. import os
  12. import uuid
  13. from pathlib import Path
  14. from typing import Any, Dict, Optional
  15. from tools.tool_output_limits import _coerce_int, _coerce_positive_int
  16. logger = logging.getLogger(__name__)
  17. DEFAULT_MAX_CHARS = 10_000
  18. DEFAULT_PREVIEW_HEAD = 500
  19. DEFAULT_PREVIEW_TAIL = 500
  20. DEFAULT_ENABLED = True
  21. def get_spill_config() -> dict[str, Any]:
  22. """Return resolved hook output-spill config. Never raises."""
  23. section: dict[str, Any] = {}
  24. try:
  25. from hermes_cli.config import load_config
  26. cfg = load_config() or {}
  27. hooks = cfg.get("hooks") if isinstance(cfg, dict) else None
  28. if isinstance(hooks, dict) and isinstance(hooks.get("output_spill"), dict):
  29. section = hooks["output_spill"]
  30. except Exception:
  31. section = {}
  32. enabled_raw = section.get("enabled", DEFAULT_ENABLED)
  33. directory = section.get("directory")
  34. return {
  35. "enabled": bool(enabled_raw) if enabled_raw is not None else DEFAULT_ENABLED,
  36. "max_chars": _coerce_positive_int(section.get("max_chars"), DEFAULT_MAX_CHARS),
  37. # head/tail allow zero (empty tail), max_chars must be positive.
  38. "preview_head": _coerce_int(section.get("preview_head"), DEFAULT_PREVIEW_HEAD, 0),
  39. "preview_tail": _coerce_int(section.get("preview_tail"), DEFAULT_PREVIEW_TAIL, 0),
  40. "directory": directory if isinstance(directory, str) else None,
  41. }
  42. def _resolve_spill_dir(directory_override: Optional[str], session_id: Optional[str]) -> Path:
  43. """Per-session spill directory; session id is sanitised so it can't escape ``base``."""
  44. if directory_override:
  45. base = Path(os.path.expanduser(directory_override))
  46. else:
  47. from hermes_constants import get_hermes_home
  48. base = Path(get_hermes_home()) / "hook_outputs"
  49. session_segment = (session_id or "no-session").replace("/", "_").replace("\\", "_").replace("..", "_")
  50. return base / session_segment
  51. def spill_if_oversized(
  52. text: str, *, session_id: Optional[str] = None, source: str = "hook", config: Optional[dict[str, Any]] = None,
  53. ) -> str:
  54. """Spill ``text`` to disk if it exceeds the configured cap.
  55. Returns ``text`` unchanged (under cap, disabled, or empty) or a preview
  56. string pointing at the full content. Non-string input is ``str()``-coerced;
  57. ``source`` labels the preview header; ``config`` overrides config.yaml.
  58. """
  59. if text is None:
  60. return ""
  61. if not isinstance(text, str):
  62. try:
  63. text = str(text)
  64. except Exception:
  65. return ""
  66. cfg = config if config is not None else get_spill_config()
  67. if not cfg.get("enabled", True):
  68. return text
  69. if len(text) <= int(cfg.get("max_chars") or DEFAULT_MAX_CHARS):
  70. return text
  71. head = int(cfg.get("preview_head") or 0)
  72. tail = int(cfg.get("preview_tail") or 0)
  73. # A disk failure must never blow up the turn — fall through to a preview
  74. # without a saved path.
  75. saved_path: Optional[str] = None
  76. try:
  77. spill_dir = _resolve_spill_dir(cfg.get("directory"), session_id)
  78. from tools.spill_safety import ensure_spill_dir, write_text_exclusive
  79. # Hook context may embed raw secrets: private perms + exclusive,
  80. # symlink-refusing create (the per-session dir is predictable).
  81. ensure_spill_dir(spill_dir, private=True)
  82. spill_path = spill_dir / f"{uuid.uuid4().hex}.txt"
  83. # Trailing newline so tail readers don't report "missing newline".
  84. write_text_exclusive(spill_path, text if text.endswith("\n") else text + "\n", private=True)
  85. saved_path = str(spill_path)
  86. except Exception as exc:
  87. logger.warning("hook output spill failed: %s", exc)
  88. total = len(text)
  89. parts = [
  90. f"[{source} output truncated — {total:,} chars; full content "
  91. + (f"saved to {saved_path}]" if saved_path else "unavailable — spill write failed]"),
  92. ]
  93. if head > 0 and text[:head]:
  94. parts.extend(["--- head ---", text[:head]])
  95. if tail > 0 and total > head:
  96. parts.extend(["--- tail ---", text[-tail:]])
  97. return "\n".join(parts)
  98. __all__ = [
  99. "DEFAULT_ENABLED",
  100. "DEFAULT_MAX_CHARS",
  101. "DEFAULT_PREVIEW_HEAD",
  102. "DEFAULT_PREVIEW_TAIL",
  103. "get_spill_config",
  104. "spill_if_oversized",
  105. ]