file_tools_paths.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357
  1. """Path resolution for the file tools: task-aware base dir, ``~`` expansion, workspace-divergence warning.
  2. Core invariant: the base directory anchoring relative paths is ALWAYS absolute
  3. and derived from the task's terminal cwd, never from the process cwd unless no
  4. other anchor exists (a relative/sentinel ``TERMINAL_CWD`` would silently anchor
  5. edits to the agent process cwd, e.g. the main repo during a worktree session).
  6. """
  7. import logging
  8. import os
  9. import posixpath
  10. import sys
  11. import time
  12. from pathlib import Path, PurePosixPath
  13. from agent.runtime_self_protection import split_entry
  14. logger = logging.getLogger(__name__)
  15. # ``TERMINAL_CWD`` values that mean "not configured" ("." from a stale config;
  16. # "auto"/"cwd" are wizard placeholders). gateway/run.py sanitizes the same set.
  17. _TERMINAL_CWD_SENTINELS = frozenset({"", ".", "./", "auto", "cwd"})
  18. _CONTAINER_PATH_BACKENDS_FALLBACK = frozenset({"docker", "modal", "daytona", "vercel_sandbox"})
  19. # Backend name inferred from the live environment's class name (first match wins).
  20. _ENV_CLASS_NAME_HINTS = ("local", "ssh", "docker", "modal", "daytona")
  21. # Container task id -> monotonic time of the last failed environment bring-up in path resolution (an SSH
  22. # home, or a plugin sandbox's ``~`` home).
  23. _SSH_HOME_RETRY_AFTER = 30.0
  24. _ssh_home_failed_at: dict[str, float] = {}
  25. def _expand_tilde(path: str) -> str:
  26. """Expand ``~`` using the effective profile home (``get_subprocess_home``) so
  27. gateway/cron runs, whose process HOME may differ, agree with interactive CLI sessions.
  28. This mirrors ``hermes_constants.get_subprocess_home()`` so that ``~`` resolves consistently regardless
  29. of whether the tool runs interactively or inside a gateway-driven cron job (#48552).
  30. """
  31. if not path or "~" not in path:
  32. return path
  33. try:
  34. from hermes_constants import get_subprocess_home
  35. home = get_subprocess_home()
  36. except Exception:
  37. home = None
  38. if home and (path == "~" or path.startswith("~/")):
  39. return home if path == "~" else os.path.join(home, path[2:])
  40. return os.path.expanduser(path)
  41. def _terminal_env_type_for_task(task_id: str = "default") -> str:
  42. """Best-effort terminal backend type for path-resolution decisions."""
  43. try:
  44. from tools.terminal_tool import (
  45. _active_environments, _env_lock, _get_env_config, _resolve_container_task_id)
  46. try:
  47. container_key = _resolve_container_task_id(task_id)
  48. except Exception:
  49. container_key = task_id
  50. with _env_lock:
  51. env = _active_environments.get(container_key) or _active_environments.get(task_id)
  52. if env is not None:
  53. name = env.__class__.__name__.lower()
  54. hint = next((h for h in _ENV_CLASS_NAME_HINTS if h in name), None)
  55. stamped = getattr(env, "_hermes_backend_name", None)
  56. if hint or (isinstance(stamped, str) and stamped):
  57. return hint or stamped
  58. return str(_get_env_config().get("env_type") or os.getenv("TERMINAL_ENV") or "local").lower()
  59. except Exception:
  60. return str(os.getenv("TERMINAL_ENV") or "local").lower()
  61. def _uses_container_paths(task_id: str = "default") -> bool:
  62. env_type = _terminal_env_type_for_task(task_id)
  63. try:
  64. from tools.terminal_tool import _is_container_backend
  65. return _is_container_backend(env_type)
  66. except Exception:
  67. return env_type in _CONTAINER_PATH_BACKENDS_FALLBACK
  68. def container_backend_for_task(task_id: str = "default") -> str | None:
  69. """The task's backend name when its file paths belong to a container, else None."""
  70. return _terminal_env_type_for_task(task_id) if _uses_container_paths(task_id) else None
  71. def _normalize_without_host_deref(path: str | Path | PurePosixPath) -> PurePosixPath:
  72. """Normalize path syntax without following host symlinks: container paths are
  73. meaningful inside the sandbox, and a host-side ``/workspace`` symlink must not rewrite them."""
  74. return PurePosixPath(posixpath.normpath(str(path)))
  75. def _sentinel_free_abs_cwd(raw: str | None) -> str | None:
  76. """Return *raw* expanded when it is a non-sentinel ABSOLUTE anchor, else ``None``
  77. (a relative anchor is exactly the ambiguity that misroutes worktree edits)."""
  78. raw = str(raw or "").strip()
  79. if raw.lower() in _TERMINAL_CWD_SENTINELS:
  80. return None
  81. expanded = _expand_tilde(raw)
  82. return expanded if os.path.isabs(expanded) else None
  83. def _configured_terminal_cwd() -> str | None:
  84. """Return ``$TERMINAL_CWD`` only when it names a real (absolute, non-sentinel) anchor.
  85. Scope-aware: under gateway multiplexing the routed profile's cwd lives in the per-turn scope."""
  86. # See #68559.
  87. from agent.runtime_cwd import scope_terminal_cwd
  88. return _sentinel_free_abs_cwd(scope_terminal_cwd() or None)
  89. def _registered_task_cwd_override(task_id: str = "default") -> str | None:
  90. """Return a registered cwd override keyed by the RAW task id, when available.
  91. ``terminal_tool`` collapses CWD-only overrides to the shared ``"default"``
  92. env, but the cwd value stays keyed by the raw session id.
  93. """
  94. try:
  95. from tools.terminal_tool import resolve_task_overrides
  96. overrides = resolve_task_overrides(task_id)
  97. except Exception:
  98. return None
  99. return _sentinel_free_abs_cwd(overrides.get("cwd"))
  100. def _authoritative_workspace_root(task_id: str = "default") -> str | None:
  101. """Best-effort absolute workspace root, or ``None`` when no reliable anchor exists.
  102. Order: (1) the session's own cwd record (per-session, so one session's
  103. ``cd`` never leaks into another); (2) a registered raw-keyed cwd override
  104. (TUI/Desktop/ACP); (3) a sentinel-free absolute ``$TERMINAL_CWD``.
  105. """
  106. try:
  107. from tools.terminal_tool import get_session_cwd
  108. recorded = get_session_cwd(task_id)
  109. except Exception:
  110. recorded = None
  111. return recorded or _registered_task_cwd_override(task_id) or _configured_terminal_cwd()
  112. def _host_text(text: str, container_paths: bool) -> str:
  113. """Expand ``~``; on host backends also translate Git Bash ``/c/Users/...`` drive
  114. paths before Path sees them. Container/WSL Linux paths are never rewritten."""
  115. if not container_paths:
  116. from tools.environments.local import _msys_to_windows_path
  117. text = _msys_to_windows_path(text)
  118. return _expand_tilde(text)
  119. def _anchor(text: str, base, container_paths: bool) -> Path | PurePosixPath:
  120. """Return *text* as an absolute, normalized path, joining it onto ``base()`` when
  121. relative. Container: pure-posix, no host deref. Host: resolve() (win32: ntpath normpath)."""
  122. if container_paths:
  123. if not posixpath.isabs(text):
  124. text = posixpath.join(str(base()), text)
  125. return _normalize_without_host_deref(text)
  126. if sys.platform == "win32":
  127. import ntpath
  128. if not ntpath.isabs(text):
  129. text = ntpath.join(str(base()), text)
  130. return Path(ntpath.normpath(text))
  131. p = Path(text)
  132. if not p.is_absolute():
  133. p = Path(base()) / p
  134. return p.resolve()
  135. def _ssh_remote_anchor(task_id: str) -> str:
  136. """Working directory on the SSH target, read RAW: ``_authoritative_workspace_root``
  137. expands ``~`` on the Hermes host, which names a directory the remote does not have.
  138. Same precedence (session record, registered override, ``$TERMINAL_CWD``); a
  139. value that is neither ``~``-prefixed nor POSIX-absolute (a Windows or relative
  140. host path) is skipped. ``coerce_ssh_remote_cwd`` maps the host subprocess home back to ``~``.
  141. """
  142. from agent.runtime_cwd import scope_terminal_cwd
  143. from tools.terminal_tool import get_session_cwd, resolve_task_overrides
  144. from tools.terminal_tool_config import coerce_ssh_remote_cwd
  145. for raw in (get_session_cwd(task_id), resolve_task_overrides(task_id).get("cwd"), scope_terminal_cwd()):
  146. text = str(raw or "").strip()
  147. if text.lower() not in _TERMINAL_CWD_SENTINELS and (text.startswith("~") or posixpath.isabs(text)):
  148. return coerce_ssh_remote_cwd(text, "ssh")
  149. return "~"
  150. def _live_or_started_env(task_id: str):
  151. """The task's live terminal environment, else one brought up through the file tools' own creator. A failed
  152. bring-up is remembered briefly, so one tool call's several path resolutions don't each wait out the
  153. backend's connect timeout; the tool's own backend call reports the error."""
  154. from tools.file_tools import _get_file_ops
  155. from tools.terminal_tool import _resolve_container_task_id
  156. from tools.terminal_tool_lifecycle import get_active_env
  157. key = _resolve_container_task_id(task_id)
  158. env = get_active_env(task_id)
  159. if env is None:
  160. if time.monotonic() - _ssh_home_failed_at.get(key, float("-inf")) < _SSH_HOME_RETRY_AFTER:
  161. return None
  162. try:
  163. env = _get_file_ops(task_id).env
  164. except Exception: # health: allow BLE001 -- any backend's connect failure; the tool's own call reports it
  165. _ssh_home_failed_at[key] = time.monotonic()
  166. return None
  167. _ssh_home_failed_at.pop(key, None)
  168. return env
  169. def _ssh_remote_home(task_id: str) -> str | None:
  170. """The SSH user's home as detected at connect (``echo $HOME``), else None.
  171. Brings the environment up through the file tools' own creator (same cwd
  172. and cache as the call that follows) when none is live: they resolve before
  173. touching the backend, and a first call keyed ``~/x`` while later ones key
  174. ``/home/u/x`` splits read tracking and staleness checks for one file. A
  175. failed bring-up is remembered briefly so one tool call's several
  176. resolutions don't each wait out the SSH connect timeout; the tool's own
  177. backend call reports the error.
  178. """
  179. env = _live_or_started_env(task_id)
  180. if env is None:
  181. return None
  182. # A guessed /home/<user> (``echo $HOME`` failed) must not stand in for the real home.
  183. home = getattr(env, "_remote_home", None) if getattr(env, "_remote_home_detected", False) else None
  184. return home if isinstance(home, str) and posixpath.isabs(home) else None
  185. def _resolve_ssh_path(filepath: str, task_id: str) -> PurePosixPath:
  186. """Resolve *filepath* in the SSH target's namespace, never via the Hermes host
  187. (``Path.resolve()`` and ``get_subprocess_home()`` both name host directories).
  188. ``~`` becomes the remote home once the live environment has detected it, so the
  189. result is absolute and the write guards see the real target. Before that it stays
  190. ``~``-prefixed for the remote shell; ``~user`` always does.
  191. """
  192. text = str(filepath or "").strip()
  193. if not text.startswith("~") and not posixpath.isabs(text):
  194. text = posixpath.join(_ssh_remote_anchor(task_id), text)
  195. if text == "~" or text.startswith("~/"):
  196. home = _ssh_remote_home(task_id)
  197. text = home + text[1:] if home else text
  198. if not text.startswith("~"):
  199. return _normalize_without_host_deref(text)
  200. head, _, tail = text.partition("/")
  201. tail = posixpath.normpath(tail) if tail else "."
  202. return PurePosixPath(head if tail == "." else f"{head}/{tail}")
  203. def _ssh_path_escapes_home(resolved: str) -> bool:
  204. """True for a still-``~``-relative SSH path that climbs above ``~``: its absolute
  205. target is unknown until the remote home is, so no path guard can classify it."""
  206. tail = resolved.partition("/")[2] if resolved.startswith("~") else ""
  207. return tail == ".." or tail.startswith("../")
  208. def _resolve_base_dir(
  209. task_id: str = "default", *, container_paths: bool | None = None) -> Path | PurePosixPath:
  210. """Return the ABSOLUTE base directory for resolving relative paths:
  211. ``_authoritative_workspace_root``, else the process cwd as a last resort.
  212. SSH resolves in the remote namespace (callers passing *container_paths* have
  213. already ruled SSH out).
  214. """
  215. if container_paths is None:
  216. if _terminal_env_type_for_task(task_id) == "ssh":
  217. return _resolve_ssh_path(".", task_id)
  218. container_paths = _uses_container_paths(task_id)
  219. root = _authoritative_workspace_root(task_id) or (_container_default_cwd(task_id) if container_paths else None)
  220. # A backend's relative cwd is anchored to the process cwd once, here.
  221. return _anchor(_host_text(root or os.getcwd(), container_paths), os.getcwd, container_paths)
  222. def _container_default_cwd(task_id: str = "default") -> str | None:
  223. """A container backend's configured working directory (already sanitized to the backend default) when the
  224. session recorded none: the cwd its terminal commands start in (``_resolve_command_cwd``'s default). The process
  225. cwd is a host directory (``/opt/data`` in the Docker image) the sandbox does not have. The live env's cwd is NOT
  226. used: a shared env's cwd is wherever ANOTHER session last ``cd``'d."""
  227. try:
  228. from tools.terminal_tool import _get_env_config
  229. cwd = _get_env_config().get("cwd")
  230. if cwd == "~":
  231. # A plugin backend's sandbox home is known once its environment connects: bring it up as the
  232. # call that follows would, and use the home THAT environment resolved. When it can't connect,
  233. # relative paths fall back to the process cwd below; the file operation itself then fails on
  234. # the same connection, so nothing is read or written on the host.
  235. from tools.terminal_tool_config import plugin_sandbox_home
  236. env = _live_or_started_env(task_id)
  237. cwd = plugin_sandbox_home(env) if env is not None else None
  238. if isinstance(cwd, str) and posixpath.isabs(cwd):
  239. return cwd
  240. except Exception:
  241. # Path resolution must not fail on a broken terminal config; the caller falls back to the process cwd.
  242. logger.debug("container default cwd unavailable for task %s", task_id, exc_info=True)
  243. return None
  244. def _resolve_path_for_task(filepath: str, task_id: str = "default") -> Path | PurePosixPath:
  245. """Resolve *filepath* against the task's absolute base directory
  246. (absolute inputs are returned resolved-but-unanchored)."""
  247. if _terminal_env_type_for_task(task_id) == "ssh":
  248. return _resolve_ssh_path(filepath, task_id)
  249. container_paths = _uses_container_paths(task_id)
  250. return _anchor(_host_text(filepath, container_paths),
  251. lambda: _resolve_base_dir(task_id, container_paths=container_paths), container_paths)
  252. def _resolve_entry_for_task(filepath: str, task_id: str = "default") -> Path | PurePosixPath:
  253. """``_resolve_path_for_task`` for an operation on the directory entry itself (delete,
  254. rename): the parent is resolved, but a symlink in the last component is kept, since
  255. resolving it aims the operation at the file the link points to."""
  256. parent, name = split_entry(filepath)
  257. if name in ("", ".", "..") or (not parent and name.startswith("~")):
  258. return _resolve_path_for_task(filepath, task_id)
  259. return _resolve_path_for_task(parent or ".", task_id) / name
  260. def _path_resolution_warning(filepath: str, resolved: Path | PurePosixPath, task_id: str = "default") -> str | None:
  261. """Warn when a RELATIVE path resolved OUTSIDE the task's workspace root (the
  262. edit is about to land in a different checkout than the terminal's cwd).
  263. ``None`` for absolute paths, an unknown root, or a path under the root.
  264. SSH compares in the remote namespace, as ``_resolve_path_for_task`` resolved it."""
  265. try:
  266. if _terminal_env_type_for_task(task_id) == "ssh":
  267. if filepath.startswith("~") or posixpath.isabs(filepath):
  268. return None
  269. root = _resolve_ssh_path(".", task_id)
  270. else:
  271. if Path(_expand_tilde(filepath)).is_absolute():
  272. return None
  273. workspace_root = _authoritative_workspace_root(task_id)
  274. if not workspace_root:
  275. return None
  276. if _uses_container_paths(task_id):
  277. root = _normalize_without_host_deref(Path(_expand_tilde(workspace_root)))
  278. else:
  279. root = Path(_expand_tilde(workspace_root)).resolve()
  280. if resolved.is_relative_to(root):
  281. return None
  282. return (
  283. f"Relative path {filepath!r} resolved to {str(resolved)!r}, which is "
  284. f"OUTSIDE the active workspace ({str(root)!r}). The edit will land in "
  285. f"a different directory than the terminal's cwd. If this is not "
  286. f"intended (e.g. a git-worktree session writing into the main "
  287. f"checkout), pass an absolute path under the workspace instead.")
  288. except Exception:
  289. return None