# Portability: UNIVERSAL
# Last validated: 2026-05-17
# Next review: 2027-05-17

ОБРАБОТЧИК SANDBOX
---------------

ОПИСАНИЕ
------------
Изолированное выполнение кода для скриптов Python, оценок кода, модульных тестов и
Команды оболочки. Заменяет E2B MCP. Все операции выполняются с таймаутом 30 секунд и
ПИТОНИОКОДИРОВАНИЕ=utf-8. Выходные данные ограничены максимум 3000 символами (стандартный вывод) или 1000 символами.
(stderr) ограничено.


ОПЕРАЦИИ
-----------

RUN
---
Запускает файл Python в песочнице.

Синтаксис: запуск песочницы bach <file> [arg1] [arg2] ...

Параметры:
  <файл> — абсолютный или относительный путь к файлу .py (относительно system/)
  [arg1...] - Необязательно: аргументы передаются в sys.argv

Код выхода: 0 в случае успеха, >0 в случае ошибки

cwd устанавливается в каталог файла.


EVAL
----
Оценивает выражение Python в изолированном процессе.

Синтаксис: bach sandbox eval "<code>"

Параметры:
  <код> — выражение или оператор Python (в кавычках)

Специальная функция: сначала пытается выполнить eval(), затем возвращается к exec() (для операторов).
Возвращаемое значение (если не None) выводится на стандартный вывод.

cwd установлен во временный каталог.


TEST
----
Запускает pytest для файла Python.

Синтаксис: тест в песочнице bach <file>

Параметры:
  <файл> — абсолютный или относительный путь для проверки файла .py

Флаги: -v (подробный), --tb=short (короткие обратные трассировки)

Таймаут: 60 секунд (в два раза по сравнению с run/eval)

cwd установлен в каталог system/.


SHELL
-----
Выполняет команду оболочки в изолированном каталоге.

Синтаксис: оболочка песочницы bach "<cmd>"

Параметры:
  <cmd> — любая команда оболочки (например, «ls -la», «pip list»)

cwd устанавливается во временный пустой каталог (очистка после выполнения).


ПРИМЕЧАНИЯ
---------

# Запуск файла Python с параметрами:
bach sandbox run tools/data_processor.py input.csv output.json

# Оценка выражения:
bach sandbox eval "import json; json.dumps({'test': 123})"

# Запуск модульных тестов:
bach sandbox test tools/test_handler.py

# Команда оболочки с таймаутом:
bach sandbox shell "pip list | grep requests"


ФАЙЛЫ
-------
hub/sandbox.py — реализация обработчика
docs/help/sandbox.txt — Этот файл


СМ. ТАКЖЕ
----------
hub/base.py — BaseHandler (базовый класс)
инструменты/ — целевой каталог для скриптов
ТАЙМ-АУТ — 30 секунд по умолчанию, 60 секунд для теста.
КОДИРОВАНИЕ PYTHONIO — utf-8 (совместимо с Windows)
