# Portabilität: UNIVERSAL
# Version: 1.0.0
# Zuletzt validiert: 2026-03-04

SANDBOX HANDLER
===============

BESCHREIBUNG
============
Isolierte Code-Ausführung für Python-Skripte, Code-Evaluationen, Unit-Tests und
Shell-Befehle. Ersetzt E2B MCP. Alle Operationen laufen mit 30 Sekunden Timeout und
PYTHONIOENCODING=utf-8. Ausgaben werden auf max. 3000 Zeichen (stdout) bzw. 1000 Zeichen
(stderr) begrenzt.


OPERATIONEN
===========

RUN
---
Führt Python-Datei in Sandbox-Prozess aus.

Syntax: bach sandbox run <datei> [arg1] [arg2] ...

Parameter:
  <datei>     - Absolute oder relative Pfad zur .py-Datei (relativ zu system/)
  [arg1...]   - Optional: Argumente werden sys.argv weitergeleitet

Exit-Code: 0 bei Erfolg, >0 bei Fehler

cwd wird auf Verzeichnis der Datei gesetzt.


EVAL
----
Evaluiert Python-Ausdruck in isoliertem Prozess.

Syntax: bach sandbox eval "<code>"

Parameter:
  <code>      - Python-Expression oder Statement (in Anfuehrungszeichen)

Besonderheit: Versucht zuerst eval(), fällt auf exec() zurück (für Statements).
Rückgabewert (wenn nicht None) wird zu stdout gedruckt.

cwd wird auf temp-Verzeichnis gesetzt.


TEST
----
Führt pytest auf Python-Datei aus.

Syntax: bach sandbox test <datei>

Parameter:
  <datei>     - Absolute oder relative Pfad zur Test-.py-Datei

Flags: -v (verbose), --tb=short (kurze Tracebacks)

Timeout: 60 Sekunden (doppelt gegenüber run/eval)

cwd wird auf system/-Verzeichnis gesetzt.


SHELL
-----
Führt Shell-Befehl in isoliertem Verzeichnis aus.

Syntax: bach sandbox shell "<cmd>"

Parameter:
  <cmd>       - Beliebiger Shell-Befehl (z.B. "ls -la", "pip list")

cwd wird auf temporaeres leeres Verzeichnis gesetzt (Cleanup nach Ausführung).


BEISPIELE
=========

# Python-Datei mit Parametern ausführen:
bach sandbox run tools/data_processor.py input.csv output.json

# Ausdruck evaluieren:
bach sandbox eval "import json; json.dumps({'test': 123})"

# Unit-Tests ausführen:
bach sandbox test tools/test_handler.py

# Shell-Befehl mit Timeout:
bach sandbox shell "pip list | grep requests"


DATEIEN
=======
hub/sandbox.py          - Handler-Implementation
docs/help/sandbox.txt   - Diese Datei


SIEHE AUCH
==========
hub/base.py             - BaseHandler (Basisklasse)
tools/                  - Zielverzeichnis für Skripte
TIMEOUT                 - 30 Sekunden Standard, 60 Sekunden für Test
PYTHONIOENCODING        - utf-8 (Windows-kompatibel)
