nexus/docs/AGENT_FIRST_MISSION_CONTROL.md

Nexus Agent-First Mission Control

Status: Zielvertrag mit produktiv ausgeliefertem v0.2.59-Control-Plane-Slice; Gateway-Writes, credentialed Live-Abnahme und Lastnachweis offen Stand: 2026-07-31 Geltungsbereich: Produkt, Frontend, Backend, Runtime-Adapter und Agenten-Schnittstellen

Produktauftrag

Nexus ist die primäre Bedien- und Steuerungsoberfläche für den täglichen Agentenbetrieb. Für normale Betriebsaufgaben soll kein Wechsel in eine OpenClaw-Oberfläche erforderlich sein.

Nexus ist dabei keine bloße Kopie der OpenClaw-Oberfläche, sondern die eigenständige Produkt-Middleware und Control Plane über der verpflichtenden OpenClaw-Runtime:

• Nexus besitzt den kanonischen Zustand für Nutzer, Rollen, Projekte, fachliche Tasks, menschliche Freigaben, Produktziele und das Control-Plane-Audit.
• OpenClaw besitzt den kanonischen Runtimezustand für Agenten, Sessions, Subagenten, Tools, Agent-Memory/-Workspaces, Cron Jobs, Channels, Nodes und Modellrouting.
• OpenAI ist der primäre Modellprovider innerhalb von OpenClaw.
• Nexus ruft OpenAI nicht direkt auf und speichert keine OpenAI-Secrets.
• Frontend und Fachdomäne kennen keine OpenClaw-Transport- oder Providerdetails; ein typisierter Gateway-Layer übersetzt zwischen beiden Systemen.
• Browser-Clients sprechen ausschließlich mit Nexus.

Umsetzungscheckpoint 2026-07-30

Der lokale Agent-first-, Gateway-Hardening- und Attach-&-Adopt-Slice ist umgesetzt:

• Eine authentifizierte Fallback-Policy schützt die API standardmäßig. X-Agent-Id ist kein Credential; nur ein authentifizierter Service- oder privilegierter User-Principal darf einen allow-gelisteten Actor-Hinweis verwenden. Control- und Run-Mutationen bleiben owner-only.
• Der Gateway-Connector verwendet Protocol v4 und ist standardmäßig auf den bestätigten stabilen OpenClaw-Tag 2026.7.1 gepinnt. Nexus imitiert weder OpenClaws reserviertes gateway-client/backend noch CLI oder Control UI. Solange der gepinnte OpenClaw-Stand keine offizielle externe Nexus-/Generic-Operator-ID akzeptiert, bleibt der produktive Connector experimentell blockiert.
• Der owner-only Setup Center verwaltet genau ein persistiertes Profil primary: begrenzte Discovery, Endpoint-/TLS-/Versionsprüfung, flüchtiges Bootstrap-Secret, read-only Pairing, Live-Inventar, Adoption ohne Datenkopie und einen separaten Management-Scope-Upgrade.
• Device-Key und Device-Token bleiben serverseitig und an Endpoint, TLS-Fingerprint, Rolle und Scopes gebunden. Detach entfernt Profil, Managementfreigabe und gebundenen Token und schließt die aktive Verbindung.
• Agenten werden live über agents.list bezogen. Die UI erzeugt ihre Bootstrap-Datei-Tabs aus agents.files.list, liest/schreibt über agents.files.get/set mit Hashkonflikt und Read-back-Verifikation und zeigt zusätzliche Workspace-Dateien über agents.workspace.list/get read-only. Statische Agentenlisten und /mnt/workspace-{agentId}-Ableitungen sind keine Autorität mehr.
• Die owner-only Memory-, Docs- und Incident-Flächen lesen ebenfalls ausschließlich über confined OpenClaw-Workspace-RPCs. Sie liefern Quellagent und sicheren Workspace-Pfad als Provenienz und besitzen keinen beliebigen Workspace-Write-Vertrag.
• Ein schema-basierter OpenClaw-Konfigurationseditor verwendet config.schema.lookup, config.get und config.patch mit baseHash, Diff-Vorschau und replacePaths. Secretwerte werden nicht an den Browser projiziert. Agent-first Standing Orders werden als kontrollierter Abschnitt in AGENTS.md gepflegt.
• Cron Jobs bleiben vollständig in OpenClaw. Nexus bietet typisiertes Auflisten, Detail, Create, Edit, Enable/Disable, Delete, Sofortlauf und paginierte Run-Historie. Idempotenz, lokale Managementfreigabe und operator.admin schützen Mutationen; Edit, Delete und Sofortlauf benötigen zusätzlich den aktuellen Job-Hash. Command- und on-exit-Payloads bleiben standardmäßig deaktiviert.
• /models zeigt neben dem Live-Katalog nur die redigierte models.authStatus-Projektion. Profil-IDs, E-Mail-Adressen, Billing-/Usage-Fenster und Credentials verlassen den Backend-Layer nicht.
• Für ein neues, bereits sicher verbundenes OpenClaw rendert Nexus die offiziellen wizard.start/next/status/cancel-Schritte. Nexus installiert keine Pakete und führt weder Migrationen noch doctor --fix selbstständig aus.
• OpenClaw-Mutationen tragen Actor, Idempotency Key, Correlation ID und W3C traceparent. PostgreSQL OperationClaims speichert nur Metadaten und Schlüssel-Hashes, erkennt Replay und Intent-Konflikte und wiederholt einen unklaren in_doubt-Aufruf nicht automatisch. Eine vorhandene JSONL-Datei bleibt ausschließlich als unveränderliches Altarchiv bestehen.
• /api/v1/openclaw/events projiziert Gateway-Ereignisse als authentifizierten SSE-Stream mit Last-Event-ID, Connection-, Heartbeat- und Gap-Signalen. Run-, Session-, Tool-, Approval-, Artifact- und sonstige Gateway-Payloads werden redigiert. Dieser Stream bleibt eine Backend-Kompatibilitätsgrenze; das Frontend verarbeitet keine OpenClaw-Roh- oder Projektionspayloads direkt, sondern ausschließlich typisierte REST-Snapshots und Nexus-Domänendeltas.
• Runs werden vor Dispatch in PostgreSQL persistiert. /runs und /runs/:id bieten Start, exakten Stop, korrelierten Retry, Zustands- und Transition-Historie sowie Task-, Projekt-, Session-, Actor- und Trace-Bezug. Gateway-Ereignisse gleichen den dauerhaften Status ab und markieren Sequenzlücken. Ein Same-run-Resume wird bewusst als unsupported ausgewiesen, weil der gepinnte Gateway-Vertrag dafür keinen belegten RPC bereitstellt.
• Ctrl/Cmd+K öffnet auf jeder authentifizierten Route eine funktionale Command Palette. Sie navigiert zu Kernflächen und geladenen Objekten, startet für Tasks, Projekte und Agents einen vorausgefüllten korrelierten Run oder öffnet Iris mit begrenztem Seiten-/Objektkontext. Der Backend-Prompt kennzeichnet diesen Kontext ausdrücklich als nicht vertrauenswürdige Metadaten.
• Dashboard und Agentenansichten erfinden keine Thinking-Einträge, Fortschritte, Kosten, Laufzeiten oder nächsten Schritte mehr. Nicht von Task oder Gateway-Session gemeldete Werte bleiben sichtbar unbekannt.

Die exakten Abschlusswerte der finalen Backend-, Frontend- und Browserprüfung werden nach dem vollständigen Gesamtlauf im Attach-&-Adopt Implementation and Acceptance Report festgehalten. Dieser Zielvertrag übernimmt bewusst keine vorläufigen Testzahlen.

Nicht abgeschlossen ist der reale Produktionsnachweis: Eine tatsächliche Remote-Pairing- und Management-Scope-Upgrade-Sequenz mit einer offiziell unterstützten externen Nexus-/Generic-Client-ID, Live-Schreibtests an eindeutig benannten Testobjekten, ein kompletter Nexus -> OpenClaw -> OpenAI -> Nexus-Lauf, Event-Reconnect unter realem Gateway-Verkehr und der primäre OpenAI-Provider müssen in der Zielumgebung belegt werden. Die registrierte Idempotenzschicht verwendet bereits PostgreSQL-Transaktionen und Datenbank-Locks; horizontale API-Skalierung bleibt dennoch ein separates Betriebs- und Lasttestthema.

Performance-V2-Checkpoint 2026-07-30

Der nachfolgende Performance-V2-Slice verbindet die bisher getrennten Mission-Control-Flächen über gemeinsame Verträge und ein persistentes Ereignisrückgrat:

• ASP.NET Core erzeugt ein OpenAPI-3.1-Dokument; openapi-typescript und openapi-fetch liefern daraus die Frontend-Typen. ProblemDetails und ValidationProblemDetails bilden die gemeinsame Fehlergrenze und tragen eine Trace-ID.
• TanStack Vue Query ist der kanonische Cache für das Task Board, Projekte, Projekt-Tasks, Agent-Proposals, Activity und Notifications. Mehrere Verbraucher desselben Query Keys teilen einen Request, und sichtbare Daten bleiben während eines Background-Refresh erhalten.
• PostgreSQL enthält additive AgentProposals, AgentProvisionRequests, OperationClaims und OutboxEvents. Fachmutation und Outbox-Ereignis werden für die migrierten Nexus-Domänen in derselben EF-Transaktion gespeichert. Der Worker claimt fällige Arbeit lease-basiert mit FOR UPDATE SKIP LOCKED.
• GET /api/v1/events?afterSequence= ist der authentifizierte, content-minimierte Domänenstream. Er bietet globale Sequenzen, maximal 512 Replay-Deltas, resync_required, 24 Stunden und mindestens 10.000 Sequenzen Retention sowie Subscriber-Queues mit Kapazität 64. Das Frontend verwendet einen gemeinsamen authentifizierten Fetch-SSE-Hub mit Bearer-Refresh, Parserlimit, Heartbeat und Jitter-Backoff.
• Das Task Board lädt über GET /api/v1/tasks/board alle aktiven Karten und initial 50 Done-Karten. Done verwendet einen opaken stabilen Keyset-Cursor. Die EF-Abfrage ist AsNoTracking, direkt auf DTOs projiziert und benötigt höchstens drei SQL-Statements im Initialpfad. Task-Ereignisse lesen nur die betroffene Board-Karte zurück, statt den vollständigen Board-Snapshot zu ersetzen.
• Manuelle Agentenerstellung und Iris-Vorschläge münden in dieselbe dauerhafte Proposal-/Approval-/Provisioning-Zustandsmaschine. Iris darf nur vorschlagen und nachsehen. Erst eine explizite Owner-Freigabe prüft Management-Consent, externe Client-ID, Endpoint/TLS-Vertrauen, Capability, Scope, Revision und Idempotenz erneut.
• EntityRefDto, OperationResultDto und ein zentraler Frontend-Resolver verbinden strukturierte Resultate mit Agent-, Proposal-, Projekt-, Task-, Run-, Cron-, Incident-, Dokument-, Notification-, OpenClaw-Task-, Session-, Approval-, Konfigurations- und Agent-Datei-Zielen. Task-, Projekt-, Notification-, Cron-, Config-, Approval-, Session- und Agent-Datei- Mutationen liefern diesen Vertrag; ein globales Ergebnisfenster führt zum betroffenen Objekt und die Zielseite wählt das adressierte Ergebnis aus.
• OpenTelemetry erfasst ASP.NET Core, HttpClient, Npgsql und eigene Mission-Control-Aktivitäten. web-vitals liefert ausschließlich allow-gelistete Browsermetriken. Prompts, Chattexte, Markdown, Toolargumente, Secrets, Auth-Header, URL-Queries und Entity-Namen bleiben aus der Telemetrie entfernt.
• Sichere OpenClaw-Reads erhalten begrenzte Timeouts, Jitter-Retries und einen Circuit Breaker. Management-Mutationen und Chat/Run werden nicht automatisch wiederholt.

Die aktive Server-State-Migration ist abgeschlossen: OpenClaw-Übersicht, Agenten, Runs, Calendar, Models, Task Board, Projekte, Proposals, Activity, Notifications sowie die owner-only Memory-/Docs-/Incident-Reads verwenden gemeinsame Vue-Query-Schlüssel und typisierte API-Grenzen. Die alten Operations-/Task-/Notification-/Dashboard-Stores, statischen Agentquellen, doppelten Live-Sync-Dateien und Per-View-SSE-Parser wurden nach Paritätsprüfung entfernt. Pinia bleibt für Authentifizierung, UI-/Dialogzustand, Setup-/Wizard-Workflows, lokale Entwürfe und gemeinsame Command-Fassaden.

Die genauen Implementierungs-, Test- und Nichtnachweise stehen im Performance-V2 Implementation and Acceptance Report. Insbesondere sind vorhandene k6-, Promptfoo-, Testcontainers- und Toxiproxy-Artefakte nicht automatisch Live- oder Lastabnahme.

Agent-First-Prinzipien

1. Absicht vor Navigation. Jede Seite bietet einen globalen, funktionalen Einstieg, um Iris ein Ziel zu geben, statt den Nutzer zuerst durch Module zu zwingen.
2. Delegation am Objekt. Projekte, Tasks, Incidents, Dokumente und Zeitpläne besitzen kontextbezogene Aktionen wie „An Iris delegieren“, „Agent starten“ oder „Automatisieren“.
3. Durable Runs. Jede OpenClaw-Ausführung besitzt eine dauerhafte, wiederauffindbare Repräsentation. Nexus korreliert Session/Subagent, Task, Projekt, Freigaben, Artefakte, Usage und Audit, ohne einen zweiten Runtime Store aufzubauen.
4. Kontrollierbare Autonomie. Lange Ausführungen können pausiert, fortgesetzt, abgebrochen, wiederholt oder an einen Menschen eskaliert werden.
5. Explizite Freigaben. Riskante Tools, externe Datenweitergabe und irreversible Aktionen laufen über nachvollziehbare Approval Policies.
6. Gemeinsame Domänendienste. UI, MCP und Runtime-Adapter verwenden dieselben Backend-Services und Berechtigungsregeln.
7. Autoritative Ereignisse. Runtimeansichten werden aus OpenClaw-Ereignissen und -Zuständen gespeist; Nexus ergänzt dauerhafte Control-, Approval- und Domänenereignisse statt Betriebszustände rein präsentativ abzuleiten.
8. Messbare Agentenqualität. Tool-Auswahl, Argumente, Ergebnisqualität, Laufzeit, Kosten und Sicherheitsentscheidungen sind evaluiert und vergleichbar.

Domänenobjekte und Ownership

Objekt	Autorität	Mindestvertrag in Nexus
Agent	OpenClaw	Live-Inventar, Bootstrap-Dateien, Workspace, Rolle, Fähigkeiten, Modellpolicy, Tool-Rechte, Budget, Status
Run	OpenClaw + Nexus-Korrelation	Ziel, Session/Subagent, Task/Projekt, Status, Audit, Usage, Ergebnis
Session	OpenClaw	Verlauf, Kontext, Parent/Child, Wiederaufnahme, Freshness
Task	Nexus	Fachlicher Auftrag, Zuständigkeit, Status, Abhängigkeiten, Run-Bezug
Approval	Nexus	Aktion, Risiko, Antragsteller, Entscheider, Entscheidung, Audit
Tool	OpenClaw	Schema, Herkunft, effektive Rechte, Approval Policy, Version
Artifact	Nexus oder referenzierte Runtimequelle	Datei/Output, Herkunft, Run/Task, Version, Zugriff
Memory/Workspace	OpenClaw	Quellagent, sicherer Pfad, Herkunft/Run soweit geliefert, Freshness; keine konkurrierende Kopie
Event	jeweiliges Ursprungssystem	Typ, Actor, Korrelation, Quelle, Zeitpunkt, Retention
Policy	Nexus für Produktpolicy, OpenClaw für Runtimepolicy	Scope, Regel, Version, Durchsetzung, Ausnahme
Schedule	OpenClaw	CRUD, Trigger, Zeitzone, Ziel, Status, Ressourcenhash und Run-Historie

Zielarchitektur

flowchart LR
    U["Browser / Owner"] --> F["Nexus UI"]
    F --> N["Nexus API: Auth, RBAC, Policies, Approvals, Audit"]
    N --> D["Nexus: Projects, Tasks, Decisions, Product Goals"]
    N --> G["Typed OpenClaw Gateway facade"]
    G --> O["OpenClaw Gateway: Agents, Sessions, Tools, Cron, Channels, Nodes"]
    O --> R["OpenAI provider (primary)"]
    O --> X["Explicit fallback provider (optional)"]
    O --> M["Nexus MCP / TaskBridge"]
    M --> D

Empfohlene Umsetzung

• ASP.NET Core bleibt Nexus-Control-Plane und System of Record für die Nexus-Fachdomäne.
• OpenClaw bleibt die einzige Agentenruntime und Quelle für Sessions, Routing und Runtimezustand.
• IGatewayConnector bleibt der private Protocol-v4-Transport; IOpenClawControlService ist die browser-sichere, typisierte Read-/Control- Fassade. Setup, Agent-Dateien, Workspace, Config, Cron und Model-Authstatus liegen hinter typisierten Nexus-Services; weitere Verträge für Tools, Channels und Nodes werden hinter derselben Grenze ergänzt.
• Der generische Gatewayaufruf bleibt private Transportimplementierung und gelangt weder in Views noch in Fachservices.
• Jede Mutation erhält kleinstmöglichen Operator-Scope, Schemavalidierung, Idempotency Key, Correlation ID, Versionsprüfung, risikobasierte Freigabe und Audit.
• OpenAI-Credentials, Auth-Profile und exakte provider/model-Referenzen werden in OpenClaw verwaltet. Nexus zeigt Status und Policies, niemals Secretwerte.
• Nexus speichert höchstens zeitlich begrenzte Runtime-Projektionen mit Quelle und Freshness; bei Konflikten bleibt OpenClaw autoritativ. Nexus-eigene Workflow-, Approval-, Idempotenz- und Domänenereignisse liegen dagegen dauerhaft in PostgreSQL.

Attach & Adopt als Vertrauensaufbau

Discover -> Probe -> Attach read-only -> Verify -> Inventory -> Adopt
                                                     |
                                                     v
                               deliberate scope upgrade -> Management

„Automatisch erkennen“ bedeutet ausschließlich, bekannte Kandidaten vorzufüllen. Nexus pairt, importiert oder verändert niemals still. Adoption gibt das Live-Inventar zurück und persistiert nur Verbindungs-, Adoptions- und Capability-Metadaten; Agent-Dateien, Config, Cron Jobs, Modelle, Channels und Nodes bleiben in OpenClaw.

OpenClaw dokumentiert das Gateway als Quelle für Sessions, Routing und Channel-Verbindungen und verwendet explizite provider/model-Referenzen: Gateway protocol und models. OpenAI empfiehlt, API-Schlüssel ausschließlich serverseitig über Umgebungsvariablen oder Secret Manager zu verwalten: production best practices.

Verpflichtende Kontrollflächen

Nexus ersetzt den täglichen OpenClaw-Wechsel erst, wenn mindestens folgende Funktionen über Nexus verfügbar sind:

• Bestehendes OpenClaw sicher erkennen, read-only pairen, inventarisieren, adoptieren, bewusst auf Management erweitern und detachieren
• Agenten kontrolliert vorschlagen und nach Owner-Approval provisionieren; Proposal-, Approval- und partieller Recovery-Flow sind lokal umgesetzt, produktive Writes bleiben am externen Client-ID-Gate blockiert. Konfiguration, Bootstrap-Dateien und Standing Orders sind bereits live editierbar; Aktivieren, Deaktivieren, Neustarten und Löschen bleiben offen
• Runs und Sessions starten, verfolgen, pausieren, fortsetzen, abbrechen, wiederholen und verzweigen
• Subagenten und Handoffs verwalten
• Tool-Katalog, Rechte, Allowlisten und Approval Policies konfigurieren
• OpenAI-Verbindung, Modelle, Auth-Profile, Fallbacks, Budgets und Limits über OpenClaw verwalten
• Zeitpläne erstellen, bearbeiten, pausieren, sofort ausführen und löschen; der typisierte Kern-Lifecycle und die Run-Historie sind lokal umgesetzt, die Live-Schreibabnahme bleibt offen
• Memory und Dokumente aufnehmen, kuratieren, versionieren und testen
• Dateien und Artefakte hochladen, anzeigen, herunterladen und einem Run zuordnen
• Gateway-/Adapterzustand, Version, Konfiguration und kontrollierten Reload verwalten
• Benachrichtigungen, Incidents und Freigaben operativ bearbeiten
• Traces, Kosten, Tokens, Latenz, Tool-Aufrufe und Evals untersuchen
• Secrets und Connectoren sicher verwalten

Toolprofile und effektive Rechte müssen standardmäßig begrenzt und für risikoreiche Datenweitergabe freigabepflichtig sein: OpenClaw tool configuration und operator scopes.

Sicherheitsgrenze

Browser -> Nexus Auth/RBAC/Policy -> typed Gateway facade -> OpenClaw -> OpenAI/Tool

• Ein vom Aufrufer gesetzter Agentenname oder Header ist kein Authentifizierungsnachweis.
• Öffentliche Endpunkte sind explizite Ausnahmen; alle anderen Endpunkte sind standardmäßig authentifiziert.
• Provider-Secrets liegen in OpenClaw und werden weder an Nexus noch an Browser zurückgegeben. Nexus verwaltet nur Referenz, Status und erlaubte Mutation.
• Riskante Mutationen benötigen eine Policy-Entscheidung und einen Audit-Event.
• Externe Tool-Rückgaben gelten als nicht vertrauenswürdig und werden gegen Prompt Injection, Datenabfluss und überbreite Berechtigungen abgesichert.

Abnahmekriterien

Nexus gilt erst dann als Ersatz für den täglichen Wechsel in die OpenClaw-Oberfläche und als agent-first Control Plane, wenn:

1. ein Owner einen vollständigen Agentenlauf ausschließlich in Nexus starten, beobachten, freigeben, abbrechen und wiederaufnehmen kann;
2. alle sichtbaren Kernaktionen funktionieren und einen nachvollziehbaren Zustand oder Fehler zurückgeben;
3. OpenClaw-Session-, Tool- und Usage-Ereignisse mit Nexus-Tasks, Approvals und Audit dauerhaft korreliert sind;
4. jede Modellinferenz aus Nexus über OpenClaw läuft, OpenAI dort als primärer Provider nachgewiesen ist und Nexus keinen direkten OpenAI-Pfad besitzt;
5. jede privilegierte Route und jeder Agenten-/Service-Aufruf stark authentifiziert und negativ getestet ist;
6. Tool-Auswahl, Argumentgenauigkeit und funktionale Ergebnisse durch Evals abgedeckt sind: Evaluation best practices;
7. die verwendete externe Nexus-/Generic-Client-ID vom gepinnten OpenClaw offiziell unterstützt wird und reale Pairing-, Scope-Upgrade-, Config-/Agent-Datei- und Cron-Testmutationen erfolgreich abgenommen sind.

Die vollständige Abhängigkeits- und Featureplanung steht in der Mission Control Roadmap.