OpenClaw Prozess-Supervisor: Zuverlässige Steuerung in 5 Min
Kennst du das? Du startest einen Prozess im Hintergrund, aber dein Tool verliert irgendwie die Kontrolle darüber. Am Ende hast du Zombie-Prozesse, Timeouts, die nicht greifen, oder ein PTY-Handling, das sich jedes Mal anders verhält. Das ist frustrierend und macht dein System instabil.
Wir brauchen eine Lösung, die Schluss mit unsicheren Heuristiken macht und dir die volle Kontrolle über deine Prozesse gibt. Hier ist der Plan, wie wir PTY und die Prozess-Supervision auf ein neues Level heben.
1. Problem und Ziel
Abschnitt betitelt „1. Problem und Ziel“Wir benötigen einen zuverlässigen Lifecycle für die Ausführung lang laufender Befehle über verschiedene Bereiche hinweg:
execForeground-RunsexecBackground-RunsprocessFollow-up-Aktionen (poll,log,send-keys,paste,submit,kill,remove)- CLI-Agent-Runner-Subprozesse
Das Ziel ist nicht bloß die Unterstützung von PTY. Es geht um vorhersehbare Ownership, Cancellation, Timeouts und Cleanup ohne unsichere Heuristiken beim Process-Matching.
2. Umfang und Grenzen
Abschnitt betitelt „2. Umfang und Grenzen“- Die Implementierung bleibt intern in
src/process/supervisor. - Es wird kein neues Package dafür erstellt.
- Die Kompatibilität zum aktuellen Verhalten wird beibehalten, wo es praktikabel ist.
- Der Scope wird nicht auf Terminal-Replay oder Session-Persistenz im Stil von tmux ausgeweitet.
3. In diesem Branch implementiert
Abschnitt betitelt „3. In diesem Branch implementiert“Supervisor-Basis bereits vorhanden
Abschnitt betitelt „Supervisor-Basis bereits vorhanden“- Das Supervisor-Modul ist unter
src/process/supervisor/*einsatzbereit. - Exec-Runtime und CLI-Runner werden bereits über Supervisor-Spawn und -Wait geleitet.
- Die Registry-Finalisierung ist idempotent.
Dieser Durchgang abgeschlossen
Abschnitt betitelt „Dieser Durchgang abgeschlossen“- Expliziter PTY-Command-Contract
SpawnInputist jetzt eine Discriminated Union insrc/process/supervisor/types.ts.- PTY-Runs erfordern
ptyCommand, anstatt das generischeargvwiederzuverwenden. - Der Supervisor baut PTY-Command-Strings nicht mehr aus
argv-Joins insrc/process/supervisor/supervisor.tszusammen. - Die Exec-Runtime übergibt
ptyCommandjetzt direkt insrc/agents/bash-tools.exec-runtime.ts.
- Entkopplung der Prozess-Layer-Typen
- Supervisor-Typen importieren kein
SessionStdinmehr von den Agents. - Der lokale Stdin-Contract für Prozesse liegt in
src/process/supervisor/types.ts(ManagedRunStdin). - Adapter hängen jetzt nur noch von Typen auf Prozessebene ab:
src/process/supervisor/adapters/child.tssrc/process/supervisor/adapters/pty.ts
- Verbesserung der Lifecycle-Ownership für Prozess-Tools
src/agents/bash-tools.process.tsfordert Cancellation jetzt zuerst über den Supervisor an.process kill/removenutzt jetzt ein Process-Tree-Fallback für die Terminierung, wenn der Supervisor-Lookup fehlschlägt.removebehält ein deterministisches Verhalten bei, indem Einträge laufender Sessions sofort nach der Terminierungsanforderung gelöscht werden.
- Single Source für Watchdog-Defaults
- Gemeinsame Defaults in
src/agents/cli-watchdog-defaults.tshinzugefügt. src/agents/cli-backends.tsnutzt diese gemeinsamen Defaults.src/agents/cli-runner/reliability.tsnutzt dieselben gemeinsamen Defaults.
- Bereinigung ungenutzter Helper
- Der ungenutzte
killSessionHelper-Pfad wurde aussrc/agents/bash-tools.shared.tsentfernt.
- Tests für direkte Supervisor-Pfade hinzugefügt
src/agents/bash-tools.process.supervisor.test.tshinzugefügt, um Kill- und Remove-Routing über die Supervisor-Cancellation abzudecken.
- Lücken in der Zuverlässigkeit geschlossen
src/agents/bash-tools.process.tsfällt jetzt auf eine echte Terminierung auf OS-Ebene zurück, wenn der Supervisor-Lookup fehlschlägt.src/process/supervisor/adapters/child.tsnutzt jetzt Process-Tree-Terminierungssemantik für Standard-Cancel/Timeout-Kill-Pfade.- Gemeinsames Process-Tree-Utility in
src/process/kill-tree.tshinzugefügt.
- Abdeckung von PTY-Contract-Sonderfällen hinzugefügt
src/process/supervisor/supervisor.pty-command.test.tsfür die wortgetreue PTY-Befehlsweiterleitung und Ablehnung leerer Befehle hinzugefügt.src/process/supervisor/adapters/child.test.tsfür Process-Tree-Kill-Verhalten bei der Cancellation des Child-Adapters hinzugefügt.
4. Verbleibende Lücken und Entscheidungen
Abschnitt betitelt „4. Verbleibende Lücken und Entscheidungen“Status der Zuverlässigkeit
Abschnitt betitelt „Status der Zuverlässigkeit“Die zwei erforderlichen Lücken in der Zuverlässigkeit für diesen Durchgang sind nun geschlossen:
process kill/removeverfügt über einen echten OS-Terminierungs-Fallback, falls der Supervisor-Lookup fehlschlägt.- Child-Cancel/Timeout nutzt jetzt die Process-Tree-Kill-Semantik für den Standard-Kill-Pfad.
- Regressions-Tests für beide Verhaltensweisen wurden hinzugefügt.
- Die Fehlerbehandlung bei fehlgeschlagenen Lookups wurde stabilisiert.
Dauerhaftigkeit und Startup-Abgleich
Abschnitt betitelt „Dauerhaftigkeit und Startup-Abgleich“Das Restart-Verhalten ist jetzt explizit nur als In-Memory-Lifecycle definiert.
reconcileOrphans()bleibt insrc/process/supervisor/supervisor.tsdesignbedingt ein No-op.- Aktive Runs werden nach einem Prozess-Neustart nicht wiederhergestellt.
- Diese Grenze ist für diesen Implementierungsschritt beabsichtigt, um Risiken durch partielle Persistenz zu vermeiden.
Wartungs-Follow-ups
Abschnitt betitelt „Wartungs-Follow-ups“runExecProcessinsrc/agents/bash-tools.exec-runtime.tskümmert sich noch um zu viele Aufgaben und kann in einem späteren Schritt in fokussierte Helper aufgeteilt werden.
5. Implementierungsplan
Abschnitt betitelt „5. Implementierungsplan“Der Implementierungsschritt für die erforderliche Zuverlässigkeit und die Contract-Elemente ist abgeschlossen.
Abgeschlossen:
process kill/removeFallback für echte Terminierung- Process-Tree-Cancellation für den Child-Adapter-Kill-Pfad
- Regressions-Tests für Fallback-Kill und Child-Adapter-Kill-Pfad
- PTY-Command-Sonderfall-Tests unter explizitem
ptyCommand - Explizite In-Memory-Restart-Grenze mit
reconcileOrphans()No-op
Optionales Follow-up:
- Aufteilung von
runExecProcessin fokussierte Helper ohne Verhaltensänderung
6. Datei-Übersicht
Abschnitt betitelt „6. Datei-Übersicht“Prozess-Supervisor
Abschnitt betitelt „Prozess-Supervisor“src/process/supervisor/types.ts: Aktualisiert mit Discriminated Spawn-Input und lokalem Stdin-Contract für Prozesse.src/process/supervisor/supervisor.ts: Aktualisiert auf die Verwendung von explizitemptyCommand.src/process/supervisor/adapters/child.tsundsrc/process/supervisor/adapters/pty.ts: Von Agent-Typen entkoppelt.src/process/supervisor/registry.ts: Idempotente Finalisierung unverändert beibehalten.
Exec- und Prozess-Integration
Abschnitt betitelt „Exec- und Prozess-Integration“src/agents/bash-tools.exec-runtime.ts: Aktualisiert, um PTY-Befehle explizit zu übergeben und den Fallback-Pfad zu behalten.src/agents/bash-tools.process.ts: Aktualisiert für Cancellation via Supervisor mit echtem Process-Tree-Fallback.src/agents/bash-tools.shared.ts: Direkter Kill-Helper-Pfad entfernt.
CLI-Zuverlässigkeit
Abschnitt betitelt „CLI-Zuverlässigkeit“src/agents/cli-watchdog-defaults.ts: Als gemeinsame Basis hinzugefügt.src/agents/cli-backends.tsundsrc/agents/cli-runner/reliability.ts: Nutzen jetzt dieselben Defaults.
7. Validierungslauf in diesem Durchgang
Abschnitt betitelt „7. Validierungslauf in diesem Durchgang“Unit-Tests:
pnpm vitest src/process/supervisor/registry.test.tspnpm vitest src/process/supervisor/supervisor.test.tspnpm vitest src/process/supervisor/supervisor.pty-command.test.tspnpm vitest src/process/supervisor/adapters/child.test.tspnpm vitest src/agents/cli-backends.test.tspnpm vitest src/agents/bash-tools.exec.pty-cleanup.test.tspnpm vitest src/agents/bash-tools.process.poll-timeout.test.tspnpm vitest src/agents/bash-tools.process.supervisor.test.tspnpm vitest src/process/exec.test.tsE2E-Ziele:
pnpm vitest src/agents/cli-runner.test.tspnpm vitest run src/agents/bash-tools.exec.pty-fallback.test.ts src/agents/bash-tools.exec.background-abort.test.ts src/agents/bash-tools.process.send-keys.test.tsHinweis zum Typecheck:
- Nutze
pnpm build(undpnpm checkfür den vollständigen Lint/Docs-Gate) in diesem Repo. Ältere Notizen, diepnpm tsgoerwähnen, sind veraltet.
8. Erhaltene betriebliche Garantien
Abschnitt betitelt „8. Erhaltene betriebliche Garantien“- Das Hardening-Verhalten der Exec-Umgebung ist unverändert.
- Approval- und Allowlist-Flows sind unverändert.
- Output-Sanitization und Output-Caps sind unverändert.
- Der PTY-Adapter garantiert weiterhin die Wait-Abwicklung bei erzwungenem Kill und Listener-Bereinigung.
9. Definition of Done
Abschnitt betitelt „9. Definition of Done“- Der Supervisor ist der Lifecycle-Owner für verwaltete Runs.
- PTY-Spawn nutzt einen expliziten Command-Contract ohne
argv-Rekonstruktion. - Der Prozess-Layer hat keine Typ-Abhängigkeit zum Agent-Layer für Supervisor-Stdin-Contracts.
- Watchdog-Defaults stammen aus einer einzigen Quelle.
- Gezielte Unit- und E2E-Tests bleiben grün.
- Die Grenze für die Restart-Dauerhaftigkeit ist explizit dokumentiert.
10. Zusammenfassung
Abschnitt betitelt „10. Zusammenfassung“Dieser Branch bietet jetzt eine kohärente und sicherere Struktur für die Supervision:
- Expliziter PTY-Contract
- Saubereres Prozess-Layering
- Supervisor-gesteuerter Cancellation-Pfad für Prozess-Operationen
- Echte Fallback-Terminierung, wenn der Supervisor-Lookup fehlschlägt
- Process-Tree-Cancellation für Child-Run-Kill-Pfade
- Vereinheitlichte Watchdog-Defaults
- Explizite In-Memory-Restart-Grenze (kein Abgleich von Waisen über Neustarts hinweg in diesem Durchgang)
Nächste Schritte
Abschnitt betitelt „Nächste Schritte“- Schau dir die neuen
ManagedRunStdinTypen an, um eigene Adapter zu bauen. - Prüfe die
cli-watchdog-defaults.ts, wenn du Timeouts für neue CLI-Tools anpassen musst.
OpenClaw Expert
Noch festgefahren?
Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.