MODULE_04 · УРОК 4.3

In-memory overlay

Локальная песочница предельно честная: что агент попросил, то с вашими файлами и произошло. Иногда хочется другого - «пусть полазит, посмотрит, но репозиторий оставит в покое». Для этого нужен второй бэкенд, и устроен он смешно просто: копируем проект во временную папку, запускаем на копии ту же самую локальную песочницу, а в конце копию выбрасываем. Никакого настоящего overlay в памяти тут нет, зато всё понятно и работает с первого раза.

ЧТО ПОЛУЧИТСЯ Файл sandbox_memory.py и переключатель SANDBOX=local|memory. Один и тот же промпт поедет на двух разных бэкендах, а инструменты останутся ровно теми же.

Слова, которые встретятся

  • Copy-on-write (упрощённо) - читаем из оригинала, а пишем в копию, так что исходные файлы на диске остаются нетронутыми. В настоящих файловых системах это делают хитрее, нам хватит идеи.
  • Overlay - слой поверх реальных файлов. У нас в роли слоя выступает честная полная копия проекта в /tmp, и для учебных целей разницы вы не почувствуете.

Быстрый путь

  1. Создать sandbox_memory.py: скопировать проект во временную папку, обернуть уже готовый local-sandbox и в stop() удалить копию.
  2. В main.py выбирать песочницу по переменной окружения SANDBOX: без неё - как раньше, с SANDBOX=memory - работа на копии.
  3. Запустить один и тот же промпт дважды (обычный запуск и с SANDBOX=memory) и сравнить ответы.

Какие файлы трогаем

Файл Что делать
sandbox_memory.py Создать. Функция create_memory_sandbox копирует проект и отдаёт Sandbox.
main.py Править. Функция create_sandbox смотрит SANDBOX и выбирает local или memory.
sandbox_local.py Не трогать - memory-бэкенд вызывает его внутри.

Шаг 1. Memory-бэкенд

sandbox_memory.py

import shutil
import tempfile
from dataclasses import dataclass
from pathlib import Path

from sandbox_local import LocalSandbox, create_local_sandbox


@dataclass
class MemorySandbox:
    type: str
    working_directory: str
    _inner: LocalSandbox
    _tmp_root: Path

    async def read_file(self, path: str) -> str:
        return await self._inner.read_file(path)

    async def exec(self, command: str):
        return await self._inner.exec(command)

    async def stop(self) -> None:
        await self._inner.stop()
        shutil.rmtree(self._tmp_root, ignore_errors=True)


def create_memory_sandbox(source: Path) -> MemorySandbox:
    tmp_root = Path(tempfile.mkdtemp(prefix="harness-mem-"))
    project = tmp_root / "project"
    shutil.copytree(
        source.resolve(),
        project,
        ignore=shutil.ignore_patterns(".venv", "__pycache__", ".git"),
        dirs_exist_ok=True,
    )
    inner = create_local_sandbox(project)
    return MemorySandbox(
        type="memory",
        working_directory=inner.working_directory,
        _inner=inner,
        _tmp_root=tmp_root,
    )

Обратите внимание на список исключений при копировании: .venv, __pycache__ и .git мы не тащим. Копировать виртуальное окружение долго и бессмысленно, а ставить пакеты без спроса агенту всё равно запрещено разделом Guardrails. Самое приятное здесь - что новый бэкенд просто оборачивает старый: вся работа с диском по-прежнему в одном файле.

Шаг 2. Переключатель в main.py

import os
from sandbox_local import create_local_sandbox
from sandbox_memory import create_memory_sandbox

def create_sandbox(cwd: Path):
    mode = os.environ.get("SANDBOX", "local")
    if mode == "memory":
        return create_memory_sandbox(cwd)
    return create_local_sandbox(cwd)

sandbox = create_sandbox(cwd)
print(f"Sandbox: {sandbox.type}", file=sys.stderr)
print(sandbox.working_directory, file=sys.stderr)

Тут засада, и она стоит отдельного абзаца. В build_system_prompt должен уходить sandbox.working_directory, а не str(cwd). Промахнётесь - и модель увидит путь вашего настоящего репозитория, спокойно напишет echo hello > /ваш/проект/scratch.txt, и никакая копия в /tmp вас уже не спасёт: путь-то абсолютный.

КОПИЯ, НЕ МАГИЯ Настоящий overlay в оперативной памяти мы не строим и не собираемся: обычная копия в /tmp даёт то же главное свойство, исходный каталог остаётся нетронутым. Для учёбы этого достаточно, а на больших репозиториях вы просто увидите, что копирование не бесплатное.

Проверьте

Сначала убедимся, что чтение одинаковое на обоих бэкендах. Один и тот же промпт, разница только в переменной окружения:

uv run python main.py . "Прочитай AGENTS.md"
SANDBOX=memory uv run python main.py . "Прочитай AGENTS.md"

Ответы должны совпасть, а в stderr будет видно, кто отработал: Sandbox: local в первом случае и Sandbox: memory во втором. Чтение одинаковое - значит подмена бэкенда прошла честно.

Куда интереснее запись. Полноценный write появится позже, так что попробуем через bash, если шлюз пускает echo. Только сначала уберите scratch.txt, если он у вас случайно уже лежит в проекте, иначе результат будет непонятным:

rm -f scratch.txt
SANDBOX=memory uv run python main.py . "Создай файл scratch.txt через echo hello > scratch.txt"
ls scratch.txt

В stderr должен светиться путь вида /tmp/harness-mem-…/project, а не каталог вашего репозитория. Снаружи ls scratch.txt ответит «нет такого файла», и это успех: копия умерла в stop(), а оригинал никто не трогал. Вот если scratch.txt обнаружился рядом с main.py, значит пишем мы куда-то не туда. Причины обычно две:

  • В промпт всё ещё уходит str(cwd), а не sandbox.working_directory. Модель делает echo … > /полный/путь/проекта/scratch.txt - cwd копии тут ни при чём.
  • create_bash_tool(…) собрали от старого local-sandbox, а SANDBOX=memory только печатается в stderr. read смотрит в копию (файла нет), bash - в оригинал (файл есть). Модель тогда врёт про «кэш».
НЕ ВСЁ ПОРТИРУЕТСЯ С ПЕРВОГО РАЗА Абсолютные пути, зашитая рабочая директория, хитрый вызов grep - всё это на копии может повести себя иначе. Расстраиваться не нужно: memory-бэкенд заодно работает тестом на переносимость вашего интерфейса, и лучше узнать о проблеме здесь, чем в облаке.

Готово, если:

  • Есть create_memory_sandbox
  • SANDBOX=memory переключает бэкенд без правки tools
  • Read на обоих бэкендах даёт тот же текст
  • stop() удаляет временную папку