Sandbox i promocja#

Pipeline do bezpiecznego pisania kodu Lua przez agentów AI. Drafty są pisane do izolowanego workspace, testowane w sandboxie (bez efektów ubocznych), a potem promowane do produkcji z automatycznym backupem.

Pipeline#

graph LR
    A[draft_write] --> B[draft_validate]
    B --> C[draft_test]
    C --> D[draft_promote]

    A -.- A1["workspace<br/>(drafts/)"]
    B -.- B1["sprawdź<br/>składnię"]
    C -.- C1["sandbox<br/>(izolacja)"]
    D -.- D1["produkcja<br/>(backup + reload)"]

1. Write - AI pisze draft do modules/*.lua w workspace
2. Validate - sprawdzenie składni Lua + blocklist niebezpiecznych wywołań
3. Test - uruchomienie w izolowanym silniku Lua (bez realnych efektów ubocznych)
4. Promote - zamiana pliku produkcyjnego (z backupem) + automatyczny reload runtime

Narzędzia sandbox#

vclu_draft_write#

Zapisuje lub nadpisuje plik draft w workspace. Tylko ścieżki modules/*.lua.

{ "env": "workspace", "ok": true, "path": "modules/biuro_auto.lua", "size": 850 }

vclu_draft_read#

Odczytuje zawartość draftu.

vclu_draft_list#

Lista wszystkich draftów w workspace. Brak parametrów.

{ "env": "workspace", "drafts": [{ "path": "modules/biuro_auto.lua", "size": 850 }], "count": 1 }

vclu_draft_delete#

Usuwa draft z workspace.

vclu_draft_validate#

Sprawdza składnię Lua i listę zabronionych wywołań (blocklist).

{
  "env": "workspace",
  "path": "modules/biuro_auto.lua",
  "report": {
    "valid": true,
    "errors": [],
    "warnings": []
  }
}

vclu_draft_test#

Uruchamia draft(y) w izolowanym sandboxie. Sandbox to osobny silnik Lua - żadne zmiany stanu nie trafiają do produkcji, MQTT, HomeKit ani GPIO.

Każdy element inject_events:

Wynik testu#

{
  "env": "sandbox",
  "success": true,
  "state_changes": [
    { "path": "CLU220000592.DOU3328", "old_value": 0, "new_value": 1 }
  ],
  "blocked_calls": [
    { "type": "mqtt.publish", "args": { "topic": "grenton/biuro_led/state", "payload": "1" } }
  ],
  "logs": ["[BIURO_AUTO] Lights turned on"],
  "errors": [],
  "duration_ms": 45
}

• state_changes - zmiany stanu urządzeń (symulowane, nie realne)
• blocked_calls - wywołania MQTT, GPIO, HTTP itp. zablokowane przez sandbox
• errors - błędy Lua wykryte podczas uruchomienia

Test w sandboxie nie widzi plików produkcyjnych - testuje tylko drafty. Jeśli moduł wymaga innego modułu, oba muszą być w drafcie.

vclu_draft_promote#

Promuje draft(y) do produkcji. Tworzy backup istniejącego pliku, podmienia go na draft i automatycznie przeładowuje runtime Lua.

Atomowość#

Promocja wielu plików jest atomowa - jeśli jeden plik się nie powiedzie, wszystkie dotychczasowe zmiany są cofane (rollback).

{
  "ok": true,
  "paths": ["modules/biuro_auto.lua", "modules/init.lua"],
  "backups": ["modules/biuro_auto.lua.bak.20260302_183000", "modules/init.lua.bak.20260302_183000"]
}

Automatyczny reload#

Po promocji vCLU automatycznie przeładowuje runtime Lua - nowy kod działa natychmiast, bez restartu serwera.

vclu_diff#

Porównuje draft z plikiem produkcyjnym (unified diff).

{
  "env": "workspace",
  "path": "modules/init.lua",
  "diff": "--- a/modules/init.lua (production)\n+++ b/modules/init.lua (draft)\n@@ -1,2 +1,3 @@\n require(\"tasmota_biurko\")\n+require(\"biuro_auto\")\n print(\"[MODULES] User modules initialized\")"
}

vclu_audit_log#

Historia operacji Layer 2 (zapis draftów, walidacje, testy, promocje). Log jest persystowany na dysku w formacie JSONL - wpisy przeżywają restart serwera.

Pola wpisu#

Persystencja#

Audit log jest zapisywany na dysku jako pliki JSONL z automatyczną rotacją:

• audit.jsonl - aktywny plik (append-only, zero overhead w runtime)
• audit.1.jsonl, audit.2.jsonl - starsze rotacje
• Rotacja gdy plik przekroczy 1000 wpisów
• Łącznie do 3000 wpisów historii (~600 KB)

Historia jest też dostępna wizualnie w Edytorze Lua - tab History z widokiem timeline i pipeline per plik.

Pamięć agenta#

vclu_context_save#

Dopisuje notatki do trwałej pamięci agenta. Używany do zapisywania obserwacji, odkrytych ograniczeń i TODOs na kolejne sesje.

vclu_context_read#

Odczytuje notatki z poprzednich sesji. Brak parametrów.

Rate limits#

Bezpieczeństwo#

• Drafty mogą być pisane tylko do modules/*.lua - nigdy do a/om.lua, a/user.lua ani a/main.lua
• Walidacja blokuje niebezpieczne wywołania (np. os.execute, io.open)
• Sandbox jest izolowany - nie ma dostępu do sieci, GPIO ani MQTT
• Promocja tworzy backup z timestampem i może być cofnięta (rollback) - szczegóły w sekcji Kopie zapasowe
• Po promocji przez MCP uruchamiany jest watchdog - auto-rollback jeśli nowy kod generuje >3 błędy w ciągu 15s
• Audit log rejestruje każdą operację z nazwą bota i aktorem (bot vs człowiek)
• Historia persystowana na dysku (JSONL) - przeżywa restart serwera

Następny krok#

Edytor Lua - wbudowany edytor z zarządzaniem draftami i historią zmian