media_fetch.py 6.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120
  1. """Deliver ``MEDIA:<path>`` files that live inside a remote terminal sandbox (#466).
  2. ``validate_media_delivery_path`` only accepts files on the gateway host. When the terminal backend
  3. is ssh / daytona / vercel (any backend that reports its ``_remote_home``), the agent's artifact is
  4. on another filesystem, so the tag was silently dropped. This module pulls the file through the
  5. active environment's ``fetch_file`` into the document cache (already an allowlisted delivery root)
  6. and hands back the host copy. Backends without a known remote home (docker outside its mounts,
  7. modal, plugin sandboxes) still get the conservative any-component denylist, so a ``/root/...`` artifact
  8. there is not fetched — set ``_remote_home`` on the environment to opt in.
  9. The remote path is screened against the same denylist as local deliveries BEFORE any bytes move,
  10. and again after ``readlink -f`` (fail closed when it cannot resolve) — a remote fetch must never
  11. become a bypass of the host denylist. Strict mode (``HERMES_MEDIA_DELIVERY_STRICT``) keeps its
  12. pre-existing behaviour: nothing is fetched, since a fetched copy would land in an allowlisted root
  13. and skip the recency gate strict mode exists for.
  14. """
  15. from __future__ import annotations
  16. import logging
  17. import os
  18. import posixpath
  19. import re
  20. import uuid
  21. from pathlib import Path, PurePosixPath
  22. from typing import Optional
  23. from gateway.platforms.base import (
  24. _MEDIA_DELIVERY_DENIED_HOME_SUBPATHS, _MEDIA_DELIVERY_DENIED_PREFIXES, _ROOT_CREDENTIAL_PATHS)
  25. logger = logging.getLogger(__name__)
  26. # Telegram bot uploads cap at 50 MB; the other platforms are in the same range. Independent of
  27. # tools.image_source._MAX_HOST_READ_BYTES (250 MiB, local reads): do not sync the two.
  28. _FETCH_MAX_BYTES = 50 * 1024 * 1024
  29. _DENIED_PREFIXES = tuple(PurePosixPath(p) for p in _MEDIA_DELIVERY_DENIED_PREFIXES)
  30. # Credential dirs under the sandbox home plus the Hermes stores, which live at ``~/.hermes`` there.
  31. _DENIED_HOME_RELATIVE = tuple(PurePosixPath(s) for s in _MEDIA_DELIVERY_DENIED_HOME_SUBPATHS) + tuple(
  32. PurePosixPath(".hermes", *PurePosixPath(rel.replace(os.sep, "/")).parts) for rel in _ROOT_CREDENTIAL_PATHS)
  33. def remote_path_is_denied(path: str, remote_home: Optional[str]) -> bool:
  34. """Pure string check (the remote fs can't be stat'd from here) applying the host denylist to a
  35. sandbox path. Unknown home ⇒ home-relative entries match ANY path component (conservative)."""
  36. target = PurePosixPath(posixpath.normpath(path))
  37. if not target.is_absolute():
  38. return True
  39. home = PurePosixPath(posixpath.normpath(remote_home)) if remote_home else None
  40. def _under(root: PurePosixPath) -> bool:
  41. return target == root or root in target.parents
  42. # The sandbox's own home may be a denied system prefix (/root); its credential subpaths are
  43. # separate, more specific entries — same exception as _path_under_denied_prefix.
  44. if any(_under(p) for p in _DENIED_PREFIXES if p != home):
  45. return True
  46. if home is not None:
  47. return any(_under(home / rel) for rel in _DENIED_HOME_RELATIVE)
  48. parts = target.parts
  49. return any(parts[i:i + len(rel.parts)] == rel.parts
  50. for rel in _DENIED_HOME_RELATIVE for i in range(len(parts) - len(rel.parts) + 1))
  51. def _active_remote_env():
  52. """The live remote BaseEnvironment for the current session, or None (local backend / no env yet).
  53. Keyed by the session id the turn registered its sandbox under (falls back to the session key)."""
  54. from agent.prompt_builder import _REMOTE_TERMINAL_BACKENDS, _plugin_backend_is_remote
  55. from gateway.platforms.base import _tenv
  56. from gateway.session_context import get_session_env
  57. from tools.terminal_tool_lifecycle import get_active_env
  58. backend = _tenv("TERMINAL_ENV", "local").strip().lower()
  59. if backend not in _REMOTE_TERMINAL_BACKENDS and not _plugin_backend_is_remote(backend):
  60. return None
  61. return get_active_env(get_session_env("HERMES_SESSION_ID") or get_session_env("HERMES_SESSION_KEY") or "default")
  62. def fetch_remote_media(path: str) -> Optional[str]:
  63. """Host path of a validated copy of sandbox file ``path``, or None (never raises). Only fires
  64. when a remote backend is active; the caller has already failed local validation."""
  65. from gateway.media_policy import media_delivery_strict
  66. if media_delivery_strict():
  67. return None
  68. env = _active_remote_env()
  69. if env is None:
  70. return None
  71. from gateway.platforms.base import (
  72. DOCUMENT_CACHE_DIR, _log_safe_path, _normalize_media_tag_path, validate_media_delivery_path)
  73. from tools.environments.base import FileFetchError
  74. remote_home = getattr(env, "_remote_home", None)
  75. candidate = posixpath.normpath(_normalize_media_tag_path(str(path)) or "")
  76. if candidate == "~" or candidate.startswith("~/"):
  77. if not remote_home:
  78. return None
  79. candidate = posixpath.normpath(posixpath.join(remote_home, candidate[2:]))
  80. if not candidate.startswith("/") or remote_path_is_denied(candidate, remote_home):
  81. return None
  82. try:
  83. # ``[ -f ]`` in fetch_file follows symlinks, so the link TARGET is what gets screened;
  84. # an unresolvable path fails closed rather than trusting the unresolved name.
  85. resolved = env.fetch_realpath(candidate)
  86. if resolved is None or remote_path_is_denied(resolved, remote_home):
  87. return None
  88. basename = re.sub(r"[^\w.\-]", "_", posixpath.basename(resolved)) or "file"
  89. dest = Path(DOCUMENT_CACHE_DIR) / f"remote_{uuid.uuid4().hex[:12]}_{basename}"
  90. dest.parent.mkdir(parents=True, exist_ok=True)
  91. env.fetch_file(resolved, dest, max_bytes=_FETCH_MAX_BYTES)
  92. except FileFetchError as exc:
  93. logger.warning("Remote media fetch of %s skipped: %s", _log_safe_path(candidate), exc)
  94. return None
  95. except Exception:
  96. logger.warning("Remote media fetch of %s failed", _log_safe_path(candidate), exc_info=True)
  97. return None
  98. validated = validate_media_delivery_path(str(dest))
  99. if not validated:
  100. dest.unlink(missing_ok=True)
  101. return None
  102. logger.info("Fetched remote media %s from the %s sandbox", _log_safe_path(candidate), type(env).__name__)
  103. return validated