placement.py 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102
  1. """Where this profile's desktop lives: the gateway host or inside the configured terminal backend.
  2. ``bot_desktop.placement``:
  3. ``auto`` (default) follow the terminal backend when it is a sandbox that can host a stream
  4. (docker / ssh, or a plugin backend declaring ``supports_streams``); the
  5. gateway host when ``terminal.backend`` is local. A
  6. sandbox backend that CANNOT host one (modal, daytona, vercel) resolves to ``refused``:
  7. the user chose a sandbox for the agent's actions, so quietly running the screen, cua-driver
  8. and the browser on the host beside it would hand the agent a desktop outside that sandbox.
  9. ``terminal`` always the terminal backend; error when it cannot host one.
  10. ``gateway`` always the gateway host (the pre-#108914 behaviour for sandboxed users, now an explicit
  11. opt-in because it is the boundary-crossing shape).
  12. ``resolve()`` is pure config + backend-class reasoning: it never starts a sandbox. ``terminal_environment()``
  13. does acquire the profile's terminal environment (creating the container if needed) because a screen cannot
  14. exist before the sandbox does.
  15. """
  16. from __future__ import annotations
  17. import logging
  18. from dataclasses import dataclass
  19. from typing import Any, Optional
  20. logger = logging.getLogger(__name__)
  21. GATEWAY = "gateway"
  22. TERMINAL = "terminal"
  23. REFUSED = "refused"
  24. _STREAM_BACKENDS = ("docker", "ssh")
  25. @dataclass(frozen=True)
  26. class Placement:
  27. where: str # GATEWAY | TERMINAL | REFUSED
  28. backend: str # terminal.backend as configured
  29. reason: str = "" # human sentence when REFUSED (or why TERMINAL was not possible)
  30. def _setting() -> str:
  31. from hermes_cli.config import load_config_readonly
  32. cfg = load_config_readonly().get("bot_desktop") or {}
  33. value = str(cfg.get("placement") or "auto").strip().lower()
  34. return value if value in ("auto", TERMINAL, GATEWAY) else "auto"
  35. def _terminal_backend() -> str:
  36. from tools.terminal_tool import _get_env_config
  37. return str(_get_env_config().get("env_type") or "local")
  38. def _plugin_streams(backend: str) -> bool:
  39. from tools.terminal_tool_config import _plugin_env_flag
  40. return _plugin_env_flag(backend, "supports_streams") is True
  41. def _plugin_host_isolated() -> bool:
  42. # Under host isolation a plugin's environment object reaches Hermes as an opaque placeholder, so its
  43. # exec_prefix() is unreachable. (No bundled plugin backend declares supports_streams, so bundled
  44. # plugins, which stay in-process, are not a case here.)
  45. from hermes_cli.plugin_isolation import ISOLATION_HOST, isolation_mode
  46. return isolation_mode() == ISOLATION_HOST
  47. def resolve() -> Placement:
  48. # Backend first (env only): a local terminal IS the gateway host whatever the setting says, and that is
  49. # the common case — it must not cost a config load (this runs on every browser / cua-driver spawn).
  50. backend = _terminal_backend()
  51. if backend == "local":
  52. return Placement(GATEWAY, backend, "terminal.backend is local, so the terminal IS the gateway host")
  53. setting = _setting()
  54. if setting == GATEWAY:
  55. return Placement(GATEWAY, backend)
  56. if backend in _STREAM_BACKENDS:
  57. return Placement(TERMINAL, backend)
  58. if _plugin_streams(backend):
  59. if not _plugin_host_isolated():
  60. return Placement(TERMINAL, backend)
  61. return Placement(REFUSED, backend, (
  62. f"terminal.backend is {backend}, a plugin that runs in the plugin host (plugins.isolation: host), "
  63. f"and the host cannot hand its sandbox's exec channel to Hermes, so the screen cannot follow it. "
  64. f"Set plugins.isolation: in_process, or bot_desktop.placement: gateway to run the desktop on the "
  65. f"gateway host."))
  66. reason = (f"terminal.backend is {backend}, which cannot host a screen yet, and running the desktop on the "
  67. f"gateway host would put the agent's screen, browser and computer_use outside the sandbox you chose "
  68. f"for it. Set bot_desktop.placement: gateway to allow that explicitly.")
  69. return Placement(REFUSED, backend, reason)
  70. def terminal_environment(*, create: bool = True) -> Optional[Any]:
  71. """This profile's terminal environment object (the one ``terminal`` runs commands in). ``create=False``
  72. only returns an already-running one."""
  73. from tools import terminal_tool as tt
  74. task_id = tt._resolve_container_task_id(None)
  75. with tt._env_lock:
  76. env = tt._lookup_active_env(task_id, None)
  77. if env is not None or not create:
  78. return env
  79. # Acquire through the same planner the terminal tool uses so the container carries the same mounts,
  80. # limits and identity label; a trivial command warms it.
  81. tt.terminal_tool("true", task_id=None)
  82. with tt._env_lock:
  83. return tt._lookup_active_env(task_id, None)