Skip to content
Python
23.5 KB
Raw Blame
"""The Workspace: the one thing tools use to touch files and run commands.

Two implementations:
- `DirectWorkspace`: today's behaviour, in this process. No runner, no JSON-RPC, no extra
  process. This is `direct` mode and the default, kept so that benchmark readings stay
  comparable. It reports enforcement `none`.
- `RunnerWorkspace`: a tool runner behind a provider (a sandbox, or `runner-local`).

Step 1 routes the shell through the workspace. The file, git and search tools follow in
step 2 (design doc, section 11).
"""

from __future__ import annotations

import os
import threading
import time
from abc import ABC, abstractmethod
from pathlib import Path
from typing import Any, Callable, Optional, Sequence

from .runner.executor import Executor
from .stages import StageLog

PROVIDER_ENV = "OPENWORKER_SANDBOX_PROVIDER"
DIRECT = "direct"
RUNNER_LOCAL = "runner-local"
OPENSHELL = "openshell"
SEATBELT = "seatbelt"
WINDOWS = "windows"

REGRANT_NOTICE = "The session's folders changed; the sandbox now covers the current list. Shells and variables were kept."
RESTART_NOTICE = (
    "The sandbox was restarted because the session's folders changed. The shell started again: "
    "variables and background tasks from before are gone, files are untouched."
)


class Workspace(ABC):
    @property
    @abstractmethod
    def executor(self) -> Executor: ...

    @abstractmethod
    def describe(self) -> dict[str, Any]:
        """Which provider this is and how much it enforces: `full`, `partial` or `none`."""

    def close(self) -> None:
        self.executor.close()


class DirectWorkspace(Workspace):
    def __init__(self, *, cwd: str | Path) -> None:
        from ..tools.shell import LocalExecutor  # here, not at the top: tools.shell imports us

        self._executor = LocalExecutor(cwd=cwd)

    @property
    def executor(self) -> Executor:
        return self._executor

    def describe(self) -> dict[str, Any]:
        return {"provider": DIRECT, "enforcement": "none", "reason": "commands run in the OpenWorker process, unconfined"}


class RunnerWorkspace(Workspace):
    """A workspace whose commands and file tools run in a sandbox, through the tool runner.

    `start=False` (a session's workspace): the sandbox is not made until something needs
    it, the first turn (TurnEngine starts it, so the session can say so) or, failing that,
    the first call to the runner. Opening a session, or picking its folder, builds nothing
    (seen 2026-09-28: every folder pick made a sandbox). The client and executor exist from
    the start, so the file tools are always routed to the runner, never run here."""

    def __init__(
        self,
        provider: Any,
        *,
        cwd: str | Path,
        shell: str = "main",
        registry: Any = None,
        session_id: str = "",
        agent: str = "",
        live_roots: Optional[list] = None,
        start: bool = True,
    ) -> None:
        from .client import RunnerClient
        from .executor import RunnerExecutor

        self.provider = provider
        self.registry = registry
        self._registered: Optional[str] = None
        self._session_id, self._agent = session_id, agent
        # The session's own RootDir list. It changes while the session runs (a folder is
        # granted or taken away); a sandbox's walls are fixed when it starts.
        self._live_roots = live_roots
        self._start_lock = threading.Lock()
        self.started = False
        self.hello: dict[str, Any] = {}
        self.client = RunnerClient(lambda: provider.open_runner())  # looked up when it connects
        self._executor = RunnerExecutor(
            self.client, cwd=str(Path(cwd).expanduser().resolve()), shell=shell, before_call=self.sync_roots, after_call=self.network_note
        )
        # Whether the agent can ask the person for a site (`request_network_access`): set by
        # the session's builder; false where nobody can answer (full access, no such tool).
        self.can_ask_network: Callable[[], bool] = lambda: False
        # Refusals up to here have been told to the agent. One that reaches us after its
        # command's result (OpenShell's log lags) is told with the next result, not lost.
        self._blocked_told = time.time()
        # What the recording hears of this sandbox (observability OB-13): `observer(event,
        # data)` with `setup_started`, `setup_ended` and `restarted`. Set by the engine; it
        # is called from whatever thread starts or restarts the sandbox.
        self.observer: Optional[Callable[[str, dict[str, Any]], None]] = None
        self.last_start: Optional[StageLog] = None
        self._restarts_seen = 0  # the client's restart count already told
        if start:
            self.ensure_started()
        else:
            self.client.starter = self.ensure_started

    def ensure_started(self, trigger: str = "first_tool") -> None:
        """Make the sandbox, connect to its runner and prove the wall. Once; a failure
        leaves nothing behind and the next call tries again. `trigger` is for the recording:
        `turn_start` when a turn starts it, `first_tool` when the first runner call does."""
        with self._start_lock:
            if self.started:
                return
            log = StageLog()
            self.last_start = log
            self._tell("setup_started", {"trigger": trigger, "log": log})
            try:
                self._start(log)
            except BaseException as exc:
                log.end(exc)
                self._tell("setup_ended", {"trigger": trigger, "log": log, "error": exc})
                raise
            finally:
                if getattr(self.provider, "stage_log", None) is log:
                    self.provider.stage_log = None  # a later restart's create is not this start
            log.end()
            self._restarts_seen = self.client.restarts
            self._tell("setup_ended", {"trigger": trigger, "log": log, "error": None})

    def _start(self, log: StageLog) -> None:
        # Providers that know their own inner stages report them through `stage_log`; for
        # the others the whole `create` is one stage.
        try:
            self.provider.stage_log = log
        except AttributeError:
            pass
        log.begin("preparing")
        registry = self.registry
        if registry is not None:
            registry.reap()  # sandboxes left behind by a server that is gone
            registry.check_room()
            # Reserve the name before the sandbox exists: engine builds run concurrently
            # (OPE-206), and another build's reap() would otherwise delete this one while
            # it is still provisioning, because it is not yet in the registry.
            self._record(state="creating")
        if not getattr(self.provider, "reports_stages", False):
            log.begin("create")
        try:
            self.provider.create()
        except Exception:
            self.provider.destroy()  # a half-made sandbox may already hold copied credentials
            if registry is not None and self._registered:
                registry.close(self._registered)
                self._registered = None
            raise
        try:
            log.begin("connect")
            self.hello = self.client.connect()
            self._after_connect(log)
        except Exception:
            self.client.detach()
            self.provider.destroy()
            if registry is not None and self._registered:
                registry.close(self._registered)
                self._registered = None
            raise
        self._record()
        self.started = True
        self.client.starter = None

    def _tell(self, event: str, data: dict[str, Any]) -> None:
        observer = self.observer
        if observer is None:
            return
        try:
            observer(event, data)
        except Exception:  # noqa: BLE001 - the recording never stops a sandbox
            pass

    def _record(self, state: str = "ready") -> None:
        """Enter this sandbox in the registry; after a restart that replaced it, under its
        new name. `state="creating"` reserves the name before the sandbox exists."""
        if self.registry is None:
            return
        info = self.provider.describe()
        name = str(info.get("sandbox") or f"{info['provider']}-{id(self):x}")
        if self._registered and self._registered != name:
            self.registry.close(self._registered)
        self._registered = name
        self.registry.record(
            name,
            provider=info["provider"],
            session_id=self._session_id,
            agent=self._agent,
            roots=getattr(self.provider, "roots", None),
            profile=getattr(self.provider, "profile", ""),
            enforcement=info.get("enforcement", ""),
            state=state,
        )

    def sync_roots(self) -> Optional[str]:
        """Restart the sandbox when the session's folders are no longer the ones it was
        started with (design ruling 15). Returns what to tell the agent, or None. Runs
        before every command, so it is also where a sandbox not yet started starts."""
        self.ensure_started()
        if self.client.restarts > self._restarts_seen:
            # The runner came back as a new instance on its own (a crash and reconnect).
            self._restarts_seen = self.client.restarts
            self._tell("restarted", {"reason": "runner_restarted", "how": "restart"})
        regrant = getattr(self.provider, "regrant", None)
        if regrant is None or self._live_roots is None:
            return None
        wanted = [{"path": str(r.path), "writable": bool(r.writable)} for r in self._live_roots]
        if not wanted or _same_roots(wanted, getattr(self.provider, "roots", [])):
            return None
        restarts = getattr(self.provider, "restarts_on_regrant", True)
        if restarts:
            self.client.detach()
            # Reserve the replacement's name before it exists, for the same reason as at
            # start: a concurrent build's reap() must not take it for an orphan.
            regrant(wanted, before_create=lambda: self._record(state="creating"))
            self.client.connect()  # a new runner: the client notes the restart
            self._after_connect()
            self._restarts_seen = self.client.restarts
        else:
            regrant(wanted)  # the same sandbox, re-granted in place (Windows: entries on folders)
            verify = getattr(self.provider, "verify", None)
            if verify is not None:
                verify(self.client)
        self._record()
        how = "restart" if restarts else "regrant"
        self._tell("restarted", {"reason": "folders_changed", "how": how})
        return RESTART_NOTICE if restarts else REGRANT_NOTICE

    def _after_connect(self, log: Optional[StageLog] = None) -> None:
        """What a provider does once it can talk to its runner: prove the wall is up, then
        put in what it could not put in before the runner existed (copies that must be
        owned by the sandbox's own account)."""
        verify = getattr(self.provider, "verify", None)
        if verify is not None:
            if log is not None:
                log.begin("verify")
            verify(self.client)  # e.g. every folder is really reachable inside
        provision = getattr(self.provider, "provision", None)
        if provision is not None:
            if log is not None:
                log.begin("copy_logins")
            provision(self.client)

    @property
    def executor(self) -> Executor:
        return self._executor

    def context(self) -> str:
        """What the agent is told about this sandbox each turn (ruling 21)."""
        from .credentials import context_lines

        text = context_lines(getattr(self.provider, "copied", None))
        notes = getattr(self.provider, "notes", None) or []
        return "\n".join(part for part in [text, *notes, self._network_context()] if part)

    def remove_hosts(self, hosts: Sequence[str]) -> None:
        """The person took a site back from this session: the sandbox stops letting it out."""
        with self._start_lock:
            self.provider.remove_hosts(hosts)

    def _asking(self) -> bool:
        try:
            return bool(self.can_ask_network())
        except Exception:  # noqa: BLE001
            return False

    def _network_context(self) -> str:
        """The allowed sites, told to the agent each turn from the live list (OPE-219): which
        sites its commands reach, and what to do about one that is blocked. Says nothing
        when the sandbox lets every site out."""
        if getattr(self.provider, "profile", "") != "allowlist":
            return ""
        sites = ", ".join(_site_name(h) for h in getattr(self.provider, "extra_hosts", None) or []) or "none yet"
        ask = (
            "If the task needs a blocked site, call request_network_access with the host and a one-line reason, then run the command again once it is allowed. Ask only for sites the task needs."
            if self._asking()
            else "The allowed sites cannot be changed from this session. If the task needs a blocked site, tell the user; they can add it in Settings > Sandbox > Choose sites."
        )
        return (
            f"Commands in this session run in a sandbox. They reach only these sites: {sites}. "
            "A command that tries another site fails, and its result may name the sites the sandbox blocked. "
            f"{ask} Do not retry a blocked command unchanged, and do not look for another route to a blocked site."
        )

    @property
    def reports_blocked(self) -> bool:
        """Whether this sandbox can say what it blocked. Where it cannot, nothing may be read
        into an empty answer."""
        return bool(getattr(self.provider, "reports_blocked", False))

    def blocked_since(self, since: float) -> list[tuple[float, str]]:
        """(time, "host:port") of the connections this session's sandbox refused since then."""
        ask = getattr(self.provider, "blocked_since", None)
        return list(ask(since)) if ask is not None else []

    def network_note(self, started: float, result: Optional[dict[str, Any]] = None) -> Optional[dict[str, Any]]:
        """What joins a command's result when the sandbox blocked something: the sites, and
        a note that says plainly what is and is not known. The attempts are tied to the time
        the command ran, not to the command.

        Where the sandbox reports late (`blocked_lag`), a failed command waits that long
        for its refusal, and leaves as soon as one arrives; a command that succeeded does
        not wait. A refusal that still arrives after its result is told with the next one."""
        new = self._blocked_untold()
        lag = float(getattr(self.provider, "blocked_lag", 0.0) or 0.0)
        failed = result is not None and (result.get("exit_code") != 0 or bool(result.get("timed_out")) or bool(result.get("error")))
        if not new and lag and failed and self.reports_blocked:
            deadline = time.time() + lag
            while not new and time.time() < deadline:
                time.sleep(0.05)
                new = self._blocked_untold()
        if not new:
            return None
        self._blocked_told = max(when for when, _ in new)
        counts: dict[str, int] = {}
        for _, entry in new:
            counts[entry] = counts.get(entry, 0) + 1
        late = any(when < started - 0.5 for when, _ in new)
        first: dict[str, float] = {}
        for when, entry in new:
            first[entry] = min(first.get(entry, when), when)
        # `_blocked` is for the recording's tool step (observability E13, V-04); the engine
        # takes it out of the result before the model sees it.
        blocked = [
            {**_host_port(entry), "count": n, "first_at": int(first[entry] * 1000),
             "late": first[entry] < started - 0.5, "uncertain": True}
            for entry, n in counts.items()
        ]
        return {"blocked_sites": list(counts), "network_note": network_note_text(counts, can_ask=self._asking(), late=late),
                "_blocked": blocked}

    def _blocked_untold(self) -> list[tuple[float, str]]:
        return [item for item in self.blocked_since(self._blocked_told) if item[0] > self._blocked_told]

    def describe(self) -> dict[str, Any]:
        return {**self.provider.describe(), "runner": {k: self.hello.get(k) for k in ("runner_version", "os", "machine", "instance_id")}}

    def add_hosts(self, hosts: Sequence[str]) -> None:
        """The person allowed a site (OPE-219): the sandbox's network list grows at once, for
        commands as well as the web tools. Under the start lock, so a sandbox being made
        takes the list as it stands afterwards."""
        with self._start_lock:
            self.provider.add_hosts(hosts)

    def close(self) -> None:
        if not self.started:
            self.client.close()
            try:
                self.provider.destroy()  # no sandbox was made; its private folder may have been
            except Exception:
                pass
            return
        try:
            self._executor.close()
        finally:
            try:
                # Ask the daemon to leave by itself first: it ends its shells and removes
                # what only it can (its folder, copies it was handed). The provider's
                # destroy() is the hard stop behind it.
                self.client.call("runner.shutdown", timeout=5)
            except Exception:
                pass
            self.client.close()
            self.provider.destroy()
            if self.registry is not None and self._registered:
                self.registry.close(self._registered)


_NOTE_SITES = 10  # more than this many blocked sites in one command are counted, not listed


def _site_name(entry: str) -> str:
    """"github.com:443" reads as "github.com": the port only matters when it is not the web's."""
    return entry[:-4] if entry.endswith(":443") else entry


def _host_port(entry: str) -> dict[str, Any]:
    """A blocked-site entry ("host:port", or a bare host) as the recording's {host, port}."""
    host, sep, port = str(entry).rpartition(":")
    if sep and port.isdigit() and host:
        return {"host": host.strip("[]"), "port": int(port)}
    return {"host": str(entry), "port": 443}


def network_note_text(counts: dict[str, int], *, can_ask: bool, late: bool = False) -> str:
    """The note itself (owner wording 2026-10-03: open about what the sandbox saw, and
    about not knowing whether it is what broke the command). `late`: some of the refusals
    happened before this command started and were only now reported."""
    lines = [f"  - {entry}" + (f" ({n} attempts)" if n > 1 else "") for entry, n in list(counts.items())[:_NOTE_SITES]]
    if len(counts) > _NOTE_SITES:
        lines.append(f"  - and {len(counts) - _NOTE_SITES} more")
    ask = (
        "If you think a blocked site caused the failure, ask the user to allow it with request_network_access(hosts, reason), then run the command again. Ask only for sites the task needs."
        if can_ask
        else "The allowed sites cannot be changed from this session. If a blocked site is needed, tell the user; they can add it in Settings > Sandbox > Choose sites."
    )
    return (
        "Note: this command ran in a sandbox, and the sandbox's network rules may have affected it.\n"
        + ("Since your previous command, the sandbox blocked connections to:\n" if late else "While it ran, the sandbox blocked connections to:\n")
        + "\n".join(lines)
        + "\n"
        "These attempts may have come from this command or from something else running in this session. " + ask
    )


def _same_roots(a: list, b: list) -> bool:
    def key(roots: list) -> set:
        return {(os.path.realpath(str(r["path"])), bool(r.get("writable"))) for r in roots}

    return key(a) == key(b)


def provider_name(explicit: Optional[str] = None) -> str:
    return (explicit or os.environ.get(PROVIDER_ENV) or DIRECT).strip().lower()


def open_workspace(
    *,
    cwd: str | Path,
    provider: Optional[str] = None,
    roots: Optional[list] = None,
    session_id: str = "",
    agent: str = "",
    credentials: Optional[list] = None,
    network_profile: Optional[str] = None,
    toolchains: Optional[list] = None,
    extra_hosts: Optional[list] = None,
    start: bool = True,
) -> Workspace:
    """The session's workspace for the configured provider. `credentials`: the machine's
    `sandbox_credentials` setting; the enabled entries are copied into the sandbox
    (design doc, section 11b). Ignored in `direct` mode, where nothing is hidden anyway. `direct` unless told otherwise.
    `extra_hosts`: the machine's `sandbox_network_hosts`, the sites an allow list lets through.
    `start=False`: make the sandbox on first use instead of now (a session's workspace).
    `toolchains`: the machine's `sandbox_toolchains` setting; the switched-on folders that
    exist are readable inside (Seatbelt, Windows full mode).
    `roots`: the session's RootDir list (primary first); without it the workspace folder is
    the only, writable, root. `session_id` and `agent` say who the sandbox is for; they go
    into the registry and onto the sandbox as a label."""
    name = provider_name(provider)
    if name == DIRECT:
        return DirectWorkspace(cwd=cwd)
    if name == RUNNER_LOCAL:
        from .providers.runner_local import RunnerLocalProvider

        # Like the real providers, it starts when the first turn needs it (`start`), so its
        # start is a turn's setup step too (observability OB-13).
        return RunnerWorkspace(RunnerLocalProvider(cwd=cwd), cwd=cwd, start=start)
    listed = [{"path": str(r.path), "writable": bool(r.writable)} for r in (roots or [])]
    listed = listed or [{"path": str(cwd), "writable": True}]
    from .credentials import granted

    grants = granted(credentials)
    from .network_profiles import check, clean_hosts, default_profile

    profile = check((network_profile or "").strip().lower() or default_profile())
    added = clean_hosts(extra_hosts)
    from . import toolchains as toolchain_list

    tool_dirs = toolchain_list.granted(toolchains)
    if name == SEATBELT:
        from .providers.seatbelt import SeatbeltProvider
        from .registry import SandboxRegistry

        return RunnerWorkspace(
            SeatbeltProvider(roots=listed, cwd=str(cwd), credentials=grants, profile=profile, tool_dirs=tool_dirs, extra_hosts=added),
            cwd=cwd,
            registry=SandboxRegistry(),
            session_id=session_id,
            agent=agent,
            live_roots=roots,
            start=start,
        )
    if name == OPENSHELL:
        from .providers.openshell import OpenShellProvider
        from .registry import SandboxRegistry

        label = "-".join(part for part in (session_id[:24], agent[:24]) if part)
        registry = SandboxRegistry()
        return RunnerWorkspace(
            OpenShellProvider(roots=listed, cwd=str(cwd), label=label, credentials=grants, profile=profile, extra_hosts=added, registry=registry.id),
            cwd=cwd,
            registry=registry,
            session_id=session_id,
            agent=agent,
            live_roots=roots,
            start=start,
        )
    if name == WINDOWS:
        from .providers.windows import WindowsProvider
        from .registry import SandboxRegistry

        return RunnerWorkspace(
            WindowsProvider(roots=listed, cwd=str(cwd), credentials=grants, profile=profile, tool_dirs=tool_dirs, extra_hosts=added),
            cwd=cwd,
            registry=SandboxRegistry(),
            session_id=session_id,
            agent=agent,
            live_roots=roots,
            start=start,
        )
    raise ValueError(f"unknown sandbox provider: {name!r} (known: {DIRECT}, {SEATBELT}, {WINDOWS}, {OPENSHELL}, {RUNNER_LOCAL})")