MODULE_04 · УРОК 4.5

Lifecycle hooks

Создать песочницу - это только полдела. Свежая облачная виртуалка ничего о вас не знает: ни имени для git-коммитов, ни установленных зависимостей, ни файла .env. Перед работой её надо обжить, а перед выключением - успеть сохранить незакоммиченное и, если умеет, снять снимок диска. Иначе полчаса работы агента уедут в никуда вместе с машиной. Места для этих двух дел и называются lifecycle hooks: локально они останутся пустыми заглушками, а в облаке без них начинается настоящая боль.

ЧТО ПОЛУЧИТСЯ Класс EmptyLifecycle в sandbox.py и его вызовы в main.py вокруг agent.run. С пустыми методами агент ведёт себя как раньше, а стоит подставить логирующую версию - и порядок вызовов видно прямо в консоли.

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

  • Lifecycle hook - функция, которую обвязка вызывает в определённый момент жизни песочницы: на старте, перед остановкой, по таймауту.
  • after_start - песочница готова, агент ещё не начал работать. Самое время для git config, uv sync и переноса переменных окружения.
  • before_stop - последний вагон перед выключением: коммит недоделанного, снимок диска, запись в лог.
  • on_timeout - то же самое, но по будильнику expires_at, который дёрнет облако. Полноценно займёмся им в модуле 7, а сегодня метод будет пустым.

Быстрый путь

  1. Добавить EmptyLifecycle в sandbox.py.
  2. В main.py: try/finally + hooks.
  3. Временно повесить print-hooks и прогнать промпт.

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

Файл Что делать
sandbox.py Править. Класс EmptyLifecycle с тремя методами.
main.py Править. Вызов hooks + finally.
lifecycle.py Не нужен сейчас. Позже, когда появятся cloud-hooks, можно перенести их из main.py в этот файл.

Шаг 1. Класс hooks

Всего три метода, и для локальной песочницы все три с пустым телом: вызовы происходят, работы никакой. Кажется бесполезным, но так мы избавляемся от проверок в духе «а есть ли у этого объекта такой метод» через hasattr. Зовём всегда все три, а пустой честно ничего не делает.

sandbox.py - добавить в конец файла

class EmptyLifecycle:
    async def after_start(self, sandbox: Sandbox) -> None:
        pass

    async def before_stop(self, sandbox: Sandbox) -> None:
        pass

    async def on_timeout(self, sandbox: Sandbox) -> None:
        pass

Класс самый обычный, без @dataclass: полей у него нет, так что и декоратору тут делать нечего. Главное, что у любого lifecycle будут те же три метода, и обвязка сможет звать их не задумываясь, кто перед ней.

НЕ КОПИРУЙТЕ @dataclass С LOCAL В уроке 4.2 у LocalSandbox декоратор нужен - там есть поля. У EmptyLifecycle полей нет. Если уже написали @dataclass над этим классом - уберите декоратор. Импорт from dataclasses import dataclass для lifecycle тоже не нужен. Иначе будет NameError: name 'dataclass' is not defined (забыли импорт) или просто лишний шум в файле.

Шаг 2. Обернуть agent.run в finally

main.py - main()

lifecycle = EmptyLifecycle()

async def main() -> None:
    await lifecycle.after_start(sandbox)
    try:
        result = await agent.run(prompt, deps=sandbox)
        print(result.output)
    finally:
        await lifecycle.before_stop(sandbox)
        await sandbox.stop()

finally здесь не для красоты: агент может упасть на середине задачи, а уборка должна случиться всё равно. Именно в этом блоке позже окажутся и проверка незакоммиченных изменений, и снимок диска.

Как выглядел бы cloud lifecycle (иллюстрация)

В проект это копировать не нужно, у нас всё равно нет облачной машины. Смотрим на код только чтобы понять, чем наполняются те же три метода, когда за песочницей стоит чужая виртуалка:

class CloudLifecycle:
    async def after_start(self, sandbox: Sandbox) -> None:
        await sandbox.exec('git config user.name "Agent"')
        await sandbox.exec("uv sync")

    async def before_stop(self, sandbox: Sandbox) -> None:
        status = await sandbox.exec("git status --porcelain")
        if status["stdout"].strip():
            await sandbox.exec('git add -A && git commit -m "WIP: auto-save"')
        # snapshot есть не у всех sandbox - у local его нет
        snap = getattr(sandbox, "snapshot", None)
        if snap is not None:
            await snap()

    async def on_timeout(self, sandbox: Sandbox) -> None:
        await self.before_stop(sandbox)
ПОЧЕМУ ДЛЯ LOCAL ПУСТЫЕ МЕТОДЫ На вашем ноутбуке git config давно настроен, а uv sync вы делали руками, так что настраивать нечего. И всё-таки хуки вызываются, потому что путь в коде должен быть один: и локальная песочница, и облачная проходят через after_start и before_stop.

Проверьте

Пустые методы проверить нечем, поэтому на минуту сделаем их болтливыми. В main.py вместо lifecycle = EmptyLifecycle() подставьте логирующий класс, объявить его можно прямо над этой строкой:

class LoggingLifecycle:
    async def after_start(self, sandbox: Sandbox) -> None:
        print(f"[lifecycle] after_start: {sandbox.type}", file=sys.stderr)

    async def before_stop(self, sandbox: Sandbox) -> None:
        print(f"[lifecycle] before_stop: {sandbox.type}", file=sys.stderr)

    async def on_timeout(self, sandbox: Sandbox) -> None:
        pass

lifecycle = LoggingLifecycle()
uv run python main.py . "Прочитай pyproject.toml"

В консоли должны появиться две строки, и стоять они будут по обе стороны от ответа агента: сначала after_start, потом работа, потом before_stop. Порядок увидели - возвращайте EmptyLifecycle. Снова тишина, поведение прежнее, зато точки для настройки и уборки теперь есть.

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

  • Есть тип/класс lifecycle с after_start / before_stop
  • after_start вызывается до agent.run
  • before_stop и sandbox.stop() - в finally
  • С пустым lifecycle агент ведёт себя как в 4.3
  • С logging lifecycle виден порядок вызовов
ДАЛЬШЕ - МОДУЛЬ 5 С песочницами закончили: интерфейс есть, три бэкенда есть, точки настройки и уборки тоже. Следующая боль ждёт с другой стороны - контекст разговора растёт с каждым вызовом инструмента. В модуле 5 будем его подрезать и учиться держать вывод в рамках.