zacmoltbot/openclaw-skill-long-task-control

Long Task Control

Diese Version konzentriert sich nicht darauf, einen weiteren Monitor hinzuzufügen, sondern die Architektur sauber zu trennen:

1. Observed Truth: Owner / Executor / externe Beobachtung liefern die Wahrheit zurück
2. Derived State: Das Skript erstellt eine deterministische Projektion aus der Wahrheit
3. Control Actions: Monitor / Owner / benutzerseitige Auslieferung handeln basierend auf dem abgeleiteten Zustand

Grundregel

• Ohne beobachtete Wahrheit nicht auf OK entscheiden
• STEP_PROGRESS ist nicht gleich STEP_COMPLETED
• TASK_COMPLETED darf nur durch die Abschlusswahrheit ausgelöst werden
• Der Monitor darf nicht mit widersprüchlichen Feldern fantasieren, dass „der Agent noch arbeitet / extern ausstehend ist“

Ereignismodell

Diese Ereignisse werden verwendet, nicht mehr CHECKPOINT:

• STARTED
• STEP_PROGRESS
• STEP_COMPLETED
• TASK_COMPLETED
• BLOCKED_CONFIRMED
• OWNER_RESUMED
• OWNER_REPLY_RECORDED
• EXTERNAL_OBSERVED
• DOWNLOAD_OBSERVED
• HEARTBEAT

Architekturübersicht

Observed Truth

Wird von Owner / Executor / externer Beobachtung zurückgeliefert:

• observations[]
• observed.steps.*
• observed.task_completion
• observed.block
• observed.owner
• observed.external_jobs
• observed.downloads

Derived State

Wird von task_ledger.py project_task() / monitor_nudge.py abgeleitet:

• derived.workflow
• derived.current_step
• derived.step_states
• derived.pending_external
• derived.truth_state
• derived.inconsistencies

Control Actions

• TRUTH_INCONSISTENT
• OWNER_RECONCILE
• NUDGE_MAIN_AGENT
• BLOCKED_ESCALATE
• STOP_AND_DELETE

Monitor-Priorität

1. Terminal → STOP_AND_DELETE
2. Wahrheit inkonsistent / verdächtige externe Behauptung → TRUTH_INCONSISTENT oder OWNER_RECONCILE
3. Blockiert bestätigt → zuerst erneuter Versuch prüfen → BLOCKED_ESCALATE
4. Kein wesentlicher Fortschrittsdelta / Heartbeat → NUDGE_MAIN_AGENT / STALE_PROGRESS / HEARTBEAT_DUE
5. Erst dann OK

Fortschrittsbasierter Überwachungsvertrag

• LTC ist kein wanduhrbasierter Task-TTL; nicht „Aufgabe nach 20 Minuten beenden“
• Der Monitor greift nur ein, wenn über längere Zeit kein wesentlicher Fortschrittsdelta vorliegt
• Fortschrittsdelta kann kommen von:
  • Neuem STEP_PROGRESS / STEP_COMPLETED / TASK_COMPLETED
  • Neuem Artefakt / Download-Beobachtung
  • Änderung des externen/provider-Job-Status
  • Erfolgreichem Heartbeat des Executors (z. B. executor_health.last_success_at)
• Solange die Langlaufaufgabe weiterhin diese Fortschrittssignale erzeugt, sollte sie nicht als Stop-Loss-Ziel betrachtet werden, selbst wenn sie mehrere Stunden läuft
• timeout_sec / nudge_after_sec haben in dieser Version die Semantik eines Fortschritts-Leerlauf-Schwellenwerts, nicht einer harten Tötungsfrist

Owner-Resume-Vertrag

Der Monitor verwendet sessions_send, um den Owner zu bitten:

• Zuerst zu beobachten
• Echte Daten zu ergänzen
• Dann fortzusetzen / abzuschließen / zu blocken

Nicht direkt halbfertige Zustände schreiben, die mit der deterministischen Projektion kollidieren.

Retry-First-Vertrag

DOWNLOAD_TIMEOUT / DOWNLOAD_INCOMPLETE / TRANSIENT_NETWORK / EXECUTION_ERROR / EXTERNAL_WAIT Müssen zuerst aus der beobachteten Wahrheit stammen. Erst danach kann der Monitor den Wiederholungszähler verwenden, um zwischen erneutem Versuch oder Eskalation zu entscheiden.

Primäre Befehle

python3 scripts/task_ledger.py --ledger state/long-task-ledger.json init <task_id> ...
python3 scripts/task_ledger.py --ledger state/long-task-ledger.json checkpoint <task_id> --event-type STEP_PROGRESS ...
python3 scripts/task_ledger.py --ledger state/long-task-ledger.json checkpoint <task_id> --event-type STEP_COMPLETED ...
python3 scripts/task_ledger.py --ledger state/long-task-ledger.json checkpoint <task_id> --event-type TASK_COMPLETED ...
python3 scripts/task_ledger.py --ledger state/long-task-ledger.json block <task_id> ...
python3 scripts/task_ledger.py --ledger state/long-task-ledger.json external-job <task_id> ...
python3 scripts/task_ledger.py --ledger state/long-task-ledger.json download-observed <task_id> ...
python3 scripts/task_ledger.py --ledger state/long-task-ledger.json owner-reply <task_id> --reply <A|B|C|D|E> ...
python3 scripts/monitor_nudge.py --ledger state/long-task-ledger.json --apply-supervision

Referenzen

• references/task-ledger-spec.md
• references/monitor-action-spec.md
• scripts/task_ledger.py
• scripts/monitor_nudge.py
• scripts/openclaw_ops.py

Warum diese Version existiert

Weil die alte Version deterministische Skripte und Agentenurteile vermischte, was zu Folgendem führte:

• CHECKPOINT bedeutete gleichzeitig Fortschritt und Abschluss
• Der Monitor entschied auf OK mit unvollständiger Wahrheit
• Externe ausstehende Behauptungen wurden ohne Beweise für bare Münze genommen
• Der nach einer Owner-Resume geschriebene Zustand kollidierte mit der Skriptprojektion

Diese Version trennt die Ursachen direkt und baut neu auf, anstatt das alte, vermischte Modell zu flicken.