context_file_sources.py 6.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125
  1. """Per-file manifest of the context/instruction files behind the ``/context`` "Rules" figure.
  2. Read-only: enumerates the same candidates ``build_context_files_prompt`` loads (through
  3. ``agent.prompt_builder.discover_context_files`` — one discovery walk, so the listing cannot drift from the
  4. prompt) and reports, per file, its size and whether it was loaded, truncated over the context-file cap,
  5. shadowed by a higher-priority context type, blocked by the injection scan (or, for the user's own SOUL.md,
  6. flagged but loaded), empty/unreadable, or suppressed by the install-tree guard. Nothing here builds a prompt or touches the truncation-warning ContextVar, so it
  7. is free of cache impact.
  8. Approximations (the manifest re-derives, it does not re-render): the truncation check sizes the raw
  9. ``## label`` section, so a .hermes.md whose YAML frontmatter the builder strips can read a few chars larger
  10. here, and the AGENTS.md directory-chain cap (applied to the merged chain after per-file caps) is not modelled.
  11. """
  12. from __future__ import annotations
  13. import os
  14. from pathlib import Path
  15. from typing import Any, Dict, List, Optional
  16. from agent import prompt_builder as _pb
  17. from agent.model_metadata import estimate_tokens_rough
  18. # status -> (glyph, note shown after the token count; "" = none)
  19. _STATUS_DISPLAY = {
  20. "loaded": ("✓", ""),
  21. "truncated": ("◐", "truncated — over context_file_max_chars"),
  22. "shadowed": ("○", "not loaded — higher-priority context type wins"),
  23. "blocked": ("✗", "not loaded — blocked by the prompt-injection scan"),
  24. "flagged": ("⚠", "loaded — matched prompt-injection pattern(s); review the file"),
  25. "empty": ("○", "not loaded — empty file"),
  26. "unreadable": ("✗", "not loaded — could not be read"),
  27. "suppressed": ("○", "not loaded — cwd fell back to the Hermes install tree"),
  28. }
  29. def _entry(label: str, path: Path, content: str, status: str) -> dict[str, Any]:
  30. return {
  31. "label": label, "path": str(path), "chars": len(content), "est_tokens": estimate_tokens_rough(content),
  32. "loaded": status in ("loaded", "truncated", "flagged"), "status": status,
  33. }
  34. def _empty_status(path: Path) -> str:
  35. """A file the builder read as "" is either genuinely empty or unreadable (permissions, timeout)."""
  36. try:
  37. return "unreadable" if path.stat().st_size > 0 else "empty"
  38. except OSError:
  39. return "unreadable"
  40. def _loaded_status(content: str, rendered_len: int, max_chars: int, user_authored: bool = False) -> str:
  41. """Same scan the builder runs (``_scan_context_content``): a hit replaces a project file with a BLOCKED
  42. marker; the user's own SOUL.md (*user_authored*) still loads and is reported as ``flagged``."""
  43. if _pb._scan_for_threats(content.lstrip("\ufeff"), scope="context"):
  44. return "flagged" if user_authored else "blocked"
  45. return "truncated" if rendered_len > max_chars else "loaded"
  46. def list_context_file_sources(
  47. cwd: Optional[str] = None, context_length: Optional[int] = None, allow_install_tree_fallback: bool = False,
  48. home_override: Path | None = None, skip_soul: bool = False,
  49. ) -> list[dict[str, Any]]:
  50. """One dict per context file Hermes considered, in the builder's priority order.
  51. Same signature semantics as ``build_context_files_prompt`` (``cwd=None`` → launch dir, install-tree guard
  52. unless *allow_install_tree_fallback*). Keys: ``label``, ``path``, ``chars``, ``est_tokens``, ``loaded``
  53. and ``status`` ∈ loaded / truncated / flagged / shadowed / blocked / empty / unreadable / suppressed.
  54. """
  55. cwd_path = Path(cwd if cwd is not None else os.getcwd()).resolve()
  56. max_chars = _pb._get_context_file_max_chars(context_length)
  57. suppressed = _pb._project_context_suppressed(cwd, cwd_path, allow_install_tree_fallback)
  58. sources: list[dict[str, Any]] = []
  59. winner: Optional[str] = None
  60. for kind, label, path, content in _pb.discover_context_files(cwd_path):
  61. if not content:
  62. status = _empty_status(path)
  63. elif suppressed:
  64. status = "suppressed"
  65. elif winner in (None, kind):
  66. winner = kind
  67. # The builder caps the rendered ``## label`` section, not the raw file.
  68. status = _loaded_status(content, len(f"## {label}\n\n{content}"), max_chars)
  69. else:
  70. status = "shadowed"
  71. sources.append(_entry(label, path, content, status))
  72. if not skip_soul:
  73. home = Path(home_override) if home_override is not None else _pb.get_hermes_home()
  74. soul_path = home / "SOUL.md"
  75. if _pb._exists_or_denied(soul_path):
  76. content = _pb._read_context_file(soul_path)
  77. status = (_loaded_status(content, len(content), max_chars, user_authored=True) if content
  78. else _empty_status(soul_path))
  79. sources.append(_entry("SOUL.md", soul_path, content, status))
  80. return sources
  81. def context_file_sources_for_agent(agent: Any) -> list[dict[str, Any]]:
  82. """The manifest for a live agent, resolved exactly like ``agent.system_prompt._context_files_part``
  83. (session cwd, install-tree policy per platform, the agent's own profile home)."""
  84. if getattr(agent, "skip_context_files", False):
  85. return []
  86. from agent.runtime_cwd import resolve_context_cwd
  87. from agent.system_prompt import _agent_home
  88. launch_artifact = getattr(agent, "_context_cwd_is_launch_artifact", False)
  89. cwd = resolve_context_cwd(include_session_override=not launch_artifact)
  90. ctx_len = getattr(getattr(agent, "context_compressor", None), "context_length", None)
  91. return list_context_file_sources(
  92. cwd=str(cwd) if cwd is not None else None, context_length=ctx_len if isinstance(ctx_len, int) else None,
  93. allow_install_tree_fallback=getattr(agent, "platform", None) in ("cli", "tui"), home_override=_agent_home(agent),
  94. )
  95. def render_context_file_lines(sources: list[dict[str, Any]]) -> list[str]:
  96. """Plain-text ``Context files`` block for ``/context``; [] when nothing was found."""
  97. if not sources:
  98. return []
  99. width = max(len(str(src.get("label") or "")) for src in sources)
  100. lines = ["Context files"]
  101. for src in sources:
  102. glyph, note = _STATUS_DISPLAY.get(str(src.get("status") or ""), ("•", ""))
  103. suffix = f" ({note})" if note else ""
  104. lines.append(f"{glyph} {src.get('label') or ''!s:<{width}} ~{int(src.get('est_tokens') or 0):>9,} tokens{suffix}")
  105. return lines