6 · Execution Environments

tools/environments/, 12 files. This chapter is about where tools actually run — which is the only truly hard boundary in the defense-in-depth stack.

6.1 Seven Environments to Choose From

Plus two supporting modules: base.py (68.3 KB, the abstract base class and shared logic) and file_sync.py (20.2 KB, file synchronization between the host and the environment).

6.2 One Thing That Has to Be Said Plainly

6.3 Shared Logic in the Abstract Base Class

base.py is 68.3 KB — it isn't just an interface definition; it also contains the implementation shared by every environment.

A dedicated exception for connection-class failures

class EnvironmentConnectionError(RuntimeError):
    """Infrastructure/connection-class failure of a terminal backend."""

    def __init__(self, reason: str, *, retry_hint: str = ""):
        ...

Why a separate exception type? Because two kinds of failure need to be told apart:

Without the distinction, the model receives “connection failed” and tries to “fix” it — but there's nothing it can do, and it just burns a few rounds of attempts. The retry_hint field shows that the exception also carries information about “how to retry.”

The bounded output collector

class _BoundedOutputCollector:
    """Retain a bounded 40/60 head-tail window of streamed text."""

    def __init__(self, max_chars: int, spill_path: "Path | None" = None): ...
    def _maybe_spill(self, text: str) -> None:
        """Tee ``text`` to the spill file (opened lazily on first overflow)."""
    def close_spill(self) -> "str | None":
        """Close the spill file and return its path if it was used."""
    def buffered_chars(self) -> int
    def total_chars(self) -> int
    def append(self, text: str) -> None
    def render(self, *, suffix: str = "") -> str:
        """Render within ``max_chars``, preserving a required status suffix."""

The design of _maybe_spill is also very practical: the full output beyond the window is written to a file, and the file is “opened lazily on the first overflow.” Most command output is short and never overflows — so no file I/O happens at all. When it really does overflow, the model gets the file path and can read the whole thing.

The “preserving a required status suffix” in render(suffix=...) also deserves attention: however the output is truncated, status information like “what was the command's exit code” must survive. It can't get cut off just because the output was too long.

The activity callback: a heartbeat for long commands

def set_activity_callback(cb: Callable[[str], None] | None) -> None:
    """Register a callback that _wait_for_process fires periodically."""
def get_activity_callback() -> Callable[[str], None] | None:
    """Return the thread-local activity callback…"""
def touch_activity_if_due(...):
    """Fire the activity callback at most once every ``state['interval']`` seconds."""

A command may run for minutes (compiling, testing, downloading). During that time:

• The user needs to know “still running, not dead”
• The gateway needs to update the status message in the chat window
• But not every second — that spams the channel and trips the platform's rate limits

touch_activity_if_due is the throttle: fire the callback at most once every N seconds. And it is thread-local — because several tools may be executing in parallel on different threads, and each needs its own callback.

The sandbox directory

def get_sandbox_dir() -> Path:
    """Return the host-side root for all sandbox storage (Docker workspaces, …)"""

All host-side sandbox storage lives under one root directory. That gives cleanup, backup, and disk-quota management a single entry point.

6.4 File Synchronization

file_sync.py (20.2 KB) solves a problem that is bound to come up: if tools execute inside a container or on a remote host, where are the files they read and write?

The existence of this layer explains why isolation has a cost: not just “containers are slow to start,” but ongoing file-sync overhead and consistency problems. That is also why local mode is the default — it's the fastest and simplest, at the price of no isolation.

6.5 When the Environment Is Chosen

The environment is configured per session/identity, not per tool call. There's a reason for that granularity:

• If the environment switched per call, a sequence like “write a file, then read it” would break across environments
• And every switch carries startup overhead

So the more sensible pattern is: high-trust situations (your own terminal) run local; low-trust situations (public webhooks, multi-user group chats) run in a container. And that judgment is the same axis as the toolset exposure in Chapter 4 — the trust boundary.