Files
nexus/docs/AGENT_FIRST_MISSION_CONTROL.md
T

367 lines
20 KiB
Markdown

# Nexus Agent-First Mission Control
**Status:** Zielvertrag mit produktiv deploytem v0.2.60-Stabilitätsfundament; 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](audits/2026-07-30/openclaw-attach-adopt/IMPLEMENTATION_AND_ACCEPTANCE.md)
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](audits/2026-07-30/agent-first-performance-v2/IMPLEMENTATION_AND_ACCEPTANCE.md).
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
```mermaid
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
```text
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](https://docs.openclaw.ai/gateway/protocol) und
[models](https://docs.openclaw.ai/models).
OpenAI empfiehlt, API-Schlüssel ausschließlich serverseitig über
Umgebungsvariablen oder Secret Manager zu verwalten:
[production best practices](https://developers.openai.com/api/docs/guides/production-best-practices#api-keys).
## 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](https://docs.openclaw.ai/gateway/config-tools)
und
[operator scopes](https://docs.openclaw.ai/gateway/operator-scopes).
## Sicherheitsgrenze
```text
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](https://developers.openai.com/api/docs/guides/evaluation-best-practices#single-agent-architectures);
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](MISSION_CONTROL_ROADMAP.md).