"""Terminal Environment Provider ABC. Pluggable-backend interface for terminal execution environments (cloud sandboxes, remote runners). Providers register via :meth:`PluginContext.register_terminal_environment_provider`; :func:`tools.terminal_tool_backends._create_environment` consults the registry for any ``TERMINAL_ENV`` / ``terminal.backend`` value that is not a built-in (built-ins stay in ``tools/environments/``; third-party sandbox vendors do NOT have to live in core). :meth:`create_environment` returns any ``BaseEnvironment`` duck type (``execute()``, ``cleanup()`` …); the factory stamps ``_hermes_backend_name`` on the result so file-path resolution can identify plugin backends. """ from __future__ import annotations import abc from typing import Any, Dict, List, Optional, Tuple from agent.provider_base import ProviderBase class TerminalEnvironmentProvider(ProviderBase): """Abstract base class for a pluggable terminal execution backend. :attr:`name` is the ``terminal.backend`` / ``TERMINAL_ENV`` value (``[a-z0-9_]``); the registry rejects built-in backend names. Classification contract — each core policy decision that was historically a frozenset of built-in names is a declarative attribute so a new backend cannot silently miss one: * ``is_remote`` — commands run off-host: suppresses host OS/home/cwd hints in the system prompt, the host Python probe, and remote-aware skill env handling. * ``is_container`` — own filesystem rooted away from the host: container resource config passed through, host-looking cwds sanitized, file tools use container path resolution. * ``skip_container_guards`` — sandbox disposable enough to skip dangerous-command approval prompts. Defaults to ``is_container``; backends that can mount host paths override to False. * ``cache_path_base`` — where auto-synced ``~/.hermes/cache`` files land inside the backend (``"~/.hermes"``, ``"/root/.hermes"``), or ``None`` when host paths remain correct. * ``strip_env_keys`` — vendor credential env vars, stripped from every subprocess the agent spawns so a model-authored command can never read them. * ``session_isolated_when_nonpersistent`` — non-persistent mode gives each session its own sandbox identity; opt in when a shared name would let two ephemeral runs destroy each other. * ``default_cwd`` — where commands start when ``terminal.cwd`` is unset or unusable there: an absolute in-sandbox path, or ``"~"`` for each sandbox's own home. With ``"~"``, ``create_environment`` receives ``cwd="~"`` (never expanded on the host) and the environment sets ``self.cwd`` to the absolute home it resolved; commands may also arrive with ``cwd="~"``. ``None`` keeps the generic ``/root``. * ``supports_streams`` — environments implement ``exec_prefix(*, user=None, interactive=True)``: a local argv that runs its remainder (``bash -c