Zum Inhalt springen

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.

Wir benötigen einen zuverlässigen Lifecycle für die Ausführung lang laufender Befehle über verschiedene Bereiche hinweg:

  • exec Foreground-Runs
  • exec Background-Runs
  • process Follow-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.

  • 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.
  • 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.
  1. Expliziter PTY-Command-Contract
  • SpawnInput ist jetzt eine Discriminated Union in src/process/supervisor/types.ts.
  • PTY-Runs erfordern ptyCommand, anstatt das generische argv wiederzuverwenden.
  • Der Supervisor baut PTY-Command-Strings nicht mehr aus argv-Joins in src/process/supervisor/supervisor.ts zusammen.
  • Die Exec-Runtime übergibt ptyCommand jetzt direkt in src/agents/bash-tools.exec-runtime.ts.
  1. Entkopplung der Prozess-Layer-Typen
  • Supervisor-Typen importieren kein SessionStdin mehr 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.ts
    • src/process/supervisor/adapters/pty.ts
  1. Verbesserung der Lifecycle-Ownership für Prozess-Tools
  • src/agents/bash-tools.process.ts fordert Cancellation jetzt zuerst über den Supervisor an.
  • process kill/remove nutzt jetzt ein Process-Tree-Fallback für die Terminierung, wenn der Supervisor-Lookup fehlschlägt.
  • remove behält ein deterministisches Verhalten bei, indem Einträge laufender Sessions sofort nach der Terminierungsanforderung gelöscht werden.
  1. Single Source für Watchdog-Defaults
  • Gemeinsame Defaults in src/agents/cli-watchdog-defaults.ts hinzugefügt.
  • src/agents/cli-backends.ts nutzt diese gemeinsamen Defaults.
  • src/agents/cli-runner/reliability.ts nutzt dieselben gemeinsamen Defaults.
  1. Bereinigung ungenutzter Helper
  • Der ungenutzte killSession Helper-Pfad wurde aus src/agents/bash-tools.shared.ts entfernt.
  1. Tests für direkte Supervisor-Pfade hinzugefügt
  • src/agents/bash-tools.process.supervisor.test.ts hinzugefügt, um Kill- und Remove-Routing über die Supervisor-Cancellation abzudecken.
  1. Lücken in der Zuverlässigkeit geschlossen
  • src/agents/bash-tools.process.ts fällt jetzt auf eine echte Terminierung auf OS-Ebene zurück, wenn der Supervisor-Lookup fehlschlägt.
  • src/process/supervisor/adapters/child.ts nutzt jetzt Process-Tree-Terminierungssemantik für Standard-Cancel/Timeout-Kill-Pfade.
  • Gemeinsames Process-Tree-Utility in src/process/kill-tree.ts hinzugefügt.
  1. Abdeckung von PTY-Contract-Sonderfällen hinzugefügt
  • src/process/supervisor/supervisor.pty-command.test.ts für die wortgetreue PTY-Befehlsweiterleitung und Ablehnung leerer Befehle hinzugefügt.
  • src/process/supervisor/adapters/child.test.ts für Process-Tree-Kill-Verhalten bei der Cancellation des Child-Adapters hinzugefügt.

Die zwei erforderlichen Lücken in der Zuverlässigkeit für diesen Durchgang sind nun geschlossen:

  • process kill/remove verfü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.

Das Restart-Verhalten ist jetzt explizit nur als In-Memory-Lifecycle definiert.

  • reconcileOrphans() bleibt in src/process/supervisor/supervisor.ts designbedingt 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.
  1. runExecProcess in src/agents/bash-tools.exec-runtime.ts kümmert sich noch um zu viele Aufgaben und kann in einem späteren Schritt in fokussierte Helper aufgeteilt werden.

Der Implementierungsschritt für die erforderliche Zuverlässigkeit und die Contract-Elemente ist abgeschlossen.

Abgeschlossen:

  • process kill/remove Fallback 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 runExecProcess in fokussierte Helper ohne Verhaltensänderung
  • 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 explizitem ptyCommand.
  • src/process/supervisor/adapters/child.ts und src/process/supervisor/adapters/pty.ts: Von Agent-Typen entkoppelt.
  • src/process/supervisor/registry.ts: Idempotente Finalisierung unverändert beibehalten.
  • 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.
  • src/agents/cli-watchdog-defaults.ts: Als gemeinsame Basis hinzugefügt.
  • src/agents/cli-backends.ts und src/agents/cli-runner/reliability.ts: Nutzen jetzt dieselben Defaults.

Unit-Tests:

Terminal-Fenster
pnpm vitest src/process/supervisor/registry.test.ts
pnpm vitest src/process/supervisor/supervisor.test.ts
pnpm vitest src/process/supervisor/supervisor.pty-command.test.ts
pnpm vitest src/process/supervisor/adapters/child.test.ts
pnpm vitest src/agents/cli-backends.test.ts
pnpm vitest src/agents/bash-tools.exec.pty-cleanup.test.ts
pnpm vitest src/agents/bash-tools.process.poll-timeout.test.ts
pnpm vitest src/agents/bash-tools.process.supervisor.test.ts
pnpm vitest src/process/exec.test.ts

E2E-Ziele:

Terminal-Fenster
pnpm vitest src/agents/cli-runner.test.ts
pnpm 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.ts

Hinweis zum Typecheck:

  • Nutze pnpm build (und pnpm check für den vollständigen Lint/Docs-Gate) in diesem Repo. Ältere Notizen, die pnpm tsgo erwähnen, sind veraltet.
  • 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.
  1. Der Supervisor ist der Lifecycle-Owner für verwaltete Runs.
  2. PTY-Spawn nutzt einen expliziten Command-Contract ohne argv-Rekonstruktion.
  3. Der Prozess-Layer hat keine Typ-Abhängigkeit zum Agent-Layer für Supervisor-Stdin-Contracts.
  4. Watchdog-Defaults stammen aus einer einzigen Quelle.
  5. Gezielte Unit- und E2E-Tests bleiben grün.
  6. Die Grenze für die Restart-Dauerhaftigkeit ist explizit dokumentiert.

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)
  • Schau dir die neuen ManagedRunStdin Typen an, um eigene Adapter zu bauen.
  • Prüfe die cli-watchdog-defaults.ts, wenn du Timeouts für neue CLI-Tools anpassen musst.

AI Setup Assistant

OpenClaw

OpenClaw Expert

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.