feat: ship agent-first mission control v0.2.57
This commit is contained in:
AzuTear
@@ -0,0 +1,366 @@
|
||||
# Nexus Agent-First Mission Control
|
||||
|
||||
**Status:** Zielvertrag mit lokal umgesetztem Agent-first-/Performance-V2-Slice; Produktionswrites und Live-Lastnachweis offen
|
||||
**Stand:** 2026-07-30
|
||||
**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).
|
||||
@@ -0,0 +1,618 @@
|
||||
# Nexus Mission Control Roadmap
|
||||
|
||||
**Status:** Kanonische Produkt- und Umsetzungsroadmap
|
||||
**Stand:** 2026-07-30
|
||||
**Priorisierung:** Abhängigkeiten und Risikoreduktion statt willkürlicher
|
||||
Kalendertermine
|
||||
**Ziel:** Nexus ersetzt die OpenClaw-Oberfläche im täglichen Betrieb, nicht die
|
||||
OpenClaw-Runtime.
|
||||
|
||||
## 1. Verbindliches Zielbild
|
||||
|
||||
Nexus wird die zentrale, agent-first Mission-Control-Oberfläche für alle
|
||||
alltäglichen Steuerungs-, Überwachungs- und Freigabeaufgaben. Die technische
|
||||
Ausführung bleibt bewusst eindeutig:
|
||||
|
||||
```text
|
||||
Browser / Owner
|
||||
-> Nexus UI
|
||||
-> Nexus API (Auth, RBAC, Policies, Approvals, Audit)
|
||||
-> typisierte OpenClaw-Gateway-Fassade
|
||||
-> OpenClaw Gateway (Agents, Sessions, Tools, Cron, Channels, Nodes, Routing)
|
||||
-> OpenAI (primärer Modellprovider)
|
||||
```
|
||||
|
||||
Zusätzlich greifen OpenClaw-Agenten über die kontrollierte Nexus-MCP- oder
|
||||
TaskBridge-Schnittstelle auf Nexus-eigene Projekte und Tasks zu.
|
||||
|
||||
Verbindliche Architekturregeln:
|
||||
|
||||
- Nexus ruft OpenAI **nicht direkt** auf und speichert keinen OpenAI-API-Schlüssel.
|
||||
- OpenClaw ist der verpflichtende Runtime- und Gateway-Pfad für jede
|
||||
Modell-/Agentenausführung.
|
||||
- OpenAI wird innerhalb von OpenClaw als primärer Provider konfiguriert.
|
||||
- Exakte Modellreferenzen werden als explizite `provider/model`-Policies in
|
||||
OpenClaw verwaltet; das konkrete Modell bleibt eine Betriebsentscheidung und
|
||||
wird nicht dauerhaft in der Nexus-Domäne fest verdrahtet.
|
||||
- Browser-Clients sprechen weder OpenClaw noch OpenAI direkt an.
|
||||
- Nexus bildet keine zweite, konkurrierende Agentenruntime und keinen zweiten
|
||||
Session Store.
|
||||
- Die OpenClaw-Oberfläche darf für Recovery und Break-glass-Betrieb verfügbar
|
||||
bleiben, darf aber für den normalen Arbeitsalltag nicht erforderlich sein.
|
||||
|
||||
## 2. System-of-Record und Ownership
|
||||
|
||||
| Bereich | Autoritative Quelle | Nexus-Aufgabe |
|
||||
|---|---|---|
|
||||
| Nutzer, Rollen, RBAC | Nexus | Authentifizieren, autorisieren, verwalten |
|
||||
| Projekte und fachliche Tasks | Nexus | CRUD, Zustände, Abhängigkeiten, Delegation |
|
||||
| Menschliche Entscheidungen und Freigaben | Nexus | Policy, Entscheidung, Audit, Eskalation |
|
||||
| Produktziele, KPIs und Budgets | Nexus | Planen, überwachen, mit Runs korrelieren |
|
||||
| OpenClaw-Agentenkonfiguration | OpenClaw | Sicher lesen und über typisierte Mutationen steuern |
|
||||
| Modelle, Provider und Auth-Profile | OpenClaw | Status, Policies und sichere Secret-Referenzen bedienen |
|
||||
| Sessions und Subagent-Runs | OpenClaw | Suchen, anzeigen, starten und kontrollieren |
|
||||
| Tool-Katalog und Runtime-Tool-Policy | OpenClaw | Effektive Rechte darstellen und kontrolliert ändern |
|
||||
| Cron Jobs und Run-Historie | OpenClaw | Vollständigen Lifecycle in Nexus bedienen |
|
||||
| Channels, Nodes und Gatewayzustand | OpenClaw | Betriebsansicht und kontrollierte Aktionen anbieten |
|
||||
| Modellinferenz und Provider-Usage | OpenAI über OpenClaw | Kosten/Usage über OpenClaw korrelieren und auswerten |
|
||||
| Control-Plane-Audit | Nexus | Jede Mutation, Freigabe und Korrelation dauerhaft protokollieren |
|
||||
|
||||
Nexus darf Projektionen und zeitlich begrenzte Read Models für schnelle
|
||||
Oberflächen speichern. Jede Projektion zeigt Quelle, Zeitpunkt und Freshness;
|
||||
bei Konflikten bleibt OpenClaw für Runtimezustand autoritativ.
|
||||
|
||||
## 3. Aktuelle Basis
|
||||
|
||||
Bereits vorhanden und weiterzuverwenden:
|
||||
|
||||
- Vue-/Pinia-Frontend mit 18 registrierten Routen und einheitlicher
|
||||
Mission-Control-Designsprache
|
||||
- ASP.NET-Core-API, PostgreSQL, JWT-/Refresh-Session-Grundlage
|
||||
- `IAgentRuntime` mit `OpenClawRuntime` als einzig registriertem Runtime-Adapter
|
||||
- Protocol-v4-`IGatewayConnector` für Challenge/Hello, RPC-Korrelation,
|
||||
Capabilities, Scopes, Events, Timeouts, Reconnect und Versionspinning
|
||||
- ein owner-only Attach-&-Adopt-Flow mit begrenzter Discovery, Probe,
|
||||
read-only Pairing, einem persistierten `primary`-Profil, Adoption ohne
|
||||
Runtime-Datenkopie und separatem Management-Scope-Upgrade
|
||||
- browser-sicherer `IOpenClawControlService` für Tasks, Sessions, Approvals,
|
||||
Cron, Activity, Models und Agents
|
||||
- live Agent-Inventar über `agents.list`, erlaubte Bootstrap-Dateien über
|
||||
`agents.files.*`, read-only Workspace-Browsing und schema-basiertes
|
||||
`config.*` mit Hashkonflikt, Diff und Read-back-Verifikation
|
||||
- vollständiger typisierter Cron-Kern-Lifecycle mit Liste, Detail, Create,
|
||||
Edit, Enable/Disable, Delete, Sofortlauf und paginierter Run-Historie
|
||||
- redigierter `models.authStatus` und der offizielle, in Nexus gerenderte
|
||||
`wizard.*`-Flow
|
||||
- funktionale Mutationen für Task-Cancel, Session-Abort, Session-Model,
|
||||
Approval-Entscheidung, Agent-Dateien, Config und Cron
|
||||
- funktionale Task-Domäne mit Parent-/Child-Tasks, Handoffs und MCP-/Bridge-Zugriff
|
||||
- echte Arbeitsflächen für `/runs`, `/models` und `/activity`
|
||||
- OpenClaw-gebundene Dashboard-, Agent-, Calendar-, Notification-, Security-
|
||||
und Settings-Flächen mit ehrlichen Loading-/Empty-/Error-Zuständen
|
||||
|
||||
Noch nicht ausreichend:
|
||||
|
||||
- OpenClaw `2026.7.1` registriert noch keine offiziell unterstützte externe
|
||||
Nexus-/Generic-Operator-Client-ID. Nexus imitiert keine interne
|
||||
Gateway-Identität; der produktive Connector bleibt deshalb blockiert.
|
||||
- Reales Remote-Pairing, bewusster Scope-Upgrade und Live-Schreibtests für
|
||||
Agent-Dateien, Config und Cron an eindeutig benannten Testobjekten sind noch
|
||||
nicht abgenommen.
|
||||
- OpenAI ist noch nicht durch einen realen, wiederholbaren
|
||||
`Nexus -> OpenClaw -> OpenAI -> Nexus`-Smoke als Primärprovider belegt.
|
||||
- Runstart, Resume, Retry, Branching, Subagenten, Tools, Channels und Nodes sind
|
||||
nicht durchgängig bedienbar.
|
||||
- Agent-Lifecycle-Aktionen wie Create, Enable/Disable, Restart und Delete fehlen
|
||||
noch; beliebige Workspace-Dateien bleiben mangels sicherem OpenClaw-Write-RPC
|
||||
absichtlich read-only.
|
||||
- Der lokale Idempotency-Ledger bleibt ein Single-Writer-Vertrag und deckt noch
|
||||
nicht jede zukünftige Gateway-Mutation ab.
|
||||
- Security-, Audit-, E2E- und Eval-Gates reichen für eine produktive
|
||||
Agenten-Control-Plane noch nicht aus.
|
||||
|
||||
Die exakten Werte der Abschlussprüfung dieses Checkpoints werden erst nach dem
|
||||
vollständigen finalen Backend-, Frontend- und Browserlauf in
|
||||
[Attach & Adopt — Implementation and Acceptance](audits/2026-07-30/openclaw-attach-adopt/IMPLEMENTATION_AND_ACCEPTANCE.md)
|
||||
eingetragen.
|
||||
|
||||
## 4. Prioritätsdefinition
|
||||
|
||||
- **P0:** Blockiert sicheren End-to-End-Betrieb oder das Kernversprechen
|
||||
„alles in Nexus steuerbar“.
|
||||
- **P1:** Wird für den vollständigen täglichen Agentenbetrieb benötigt.
|
||||
- **P2:** Erhöht Plattformreife, Skalierung, Komfort oder Governance.
|
||||
- **P3:** Strategische Erweiterung nach belegter Kernreife.
|
||||
|
||||
Ein Meilenstein gilt nur dann als abgeschlossen, wenn Implementierung,
|
||||
negative Tests, Bediennachweis, Fehlerzustände, Audit und Dokumentation
|
||||
gemeinsam fertig sind.
|
||||
|
||||
## 5. Meilensteine
|
||||
|
||||
### M0 — Architektur- und Dokumentationsvertrag
|
||||
|
||||
**Priorität:** P0
|
||||
**Ergebnis:** Alle Beteiligten bauen gegen dieselbe Zielarchitektur.
|
||||
|
||||
- [x] Verbindlichen Pfad `Nexus -> OpenClaw -> OpenAI` dokumentieren.
|
||||
- [x] Runtime-, Provider- und Domänen-Ownership trennen.
|
||||
- [x] Direkte OpenAI-Anbindung in Nexus explizit ausschließen.
|
||||
- [x] Seiten- und Capability-Evaluation auf das korrigierte Zielbild abstimmen.
|
||||
- [ ] Architekturentscheidungen als ADRs für Gatewaygrenze, Secret Ownership,
|
||||
Session Ownership und Audit/Korrelation ergänzen.
|
||||
- [ ] Begriffe `Task`, `Run`, `Session`, `Subagent`, `Approval` und `Artifact`
|
||||
als gemeinsames Glossar festschreiben.
|
||||
|
||||
**Abnahme:** README, Zielvertrag, Evaluation, Roadmap und Obsidian-Mirror
|
||||
widersprechen sich nicht.
|
||||
|
||||
### M1 — Vertrauensgrenze und OpenAI über OpenClaw
|
||||
|
||||
**Priorität:** P0
|
||||
**Ergebnis:** Ein echter, sicherer Nexus-Auftrag wird über OpenClaw mit OpenAI
|
||||
ausgeführt und ist Ende-zu-Ende nachweisbar.
|
||||
|
||||
Security:
|
||||
|
||||
- Authenticated-by-default für die API erzwingen.
|
||||
- Benutzer-, Service- und Agentenidentitäten stark trennen und
|
||||
caller-kontrollierte Header niemals als alleinigen Nachweis akzeptieren.
|
||||
- Gatewayzugriff mit kleinstmöglichen Operator-Scopes aufteilen:
|
||||
read, write, approvals und admin nur dort, wo erforderlich.
|
||||
- Credential-artige Literale rotieren, aus Arbeitsbaum und gegebenenfalls
|
||||
Historie entfernen sowie Secret-Scanning als Gate ergänzen.
|
||||
- Gatewayversion pinnen oder als explizit kompatiblen Bereich validieren.
|
||||
- Transport, Reconnect, Timeout, Retry und Circuit-Breaker-Verhalten definieren.
|
||||
|
||||
OpenAI-Konfiguration in OpenClaw:
|
||||
|
||||
- OpenAI-Credentials ausschließlich in OpenClaw über Umgebungsvariable,
|
||||
Secret Provider oder sichere Auth-Profile verwalten.
|
||||
- Primärmodell und erlaubte `openai/...`-Modelle explizit in OpenClaw setzen.
|
||||
- Rollenbezogene Modellpolitik, Aliase, optionale Fallbacks, Limits und Budgets
|
||||
definieren.
|
||||
- Nexus zeigt Verbindungsstatus, Provider, Modellpolicy, letzte Prüfung und
|
||||
Fehler an, aber niemals Secretwerte.
|
||||
- Ein Live-Smoke-Test belegt:
|
||||
`Nexus -> OpenClaw session -> OpenAI model -> OpenClaw result -> Nexus`.
|
||||
- Audit und Telemetrie belegen den tatsächlich verwendeten Provider und das
|
||||
Modell, ohne Prompts, personenbezogene Daten oder Secrets unnötig zu loggen.
|
||||
|
||||
**Checkpoint 2026-07-30:** Authenticated-by-default, Device-Key/-Token-
|
||||
Persistenz, Endpoint-/TLS-Bindung, read-only-first Setup, Capability-Prüfung,
|
||||
bewusster Admin-Scope-Upgrade und secret-sichere Modell-Authstatus-Projektion
|
||||
sind lokal umgesetzt. Der Connector verwendet keine reservierte interne
|
||||
OpenClaw-Identität. Offen bleiben die offiziell unterstützte externe
|
||||
Nexus-/Generic-Client-ID, reales Pairing und Scope-Upgrade sowie der
|
||||
End-to-End-Nachweis mit OpenAI.
|
||||
|
||||
**Abnahme:** Kein Netzwerkpfad von Nexus zu OpenAI ist nötig; ein realer
|
||||
OpenAI-Lauf über OpenClaw ist wiederholbar grün und ein ungültiges oder
|
||||
unberechtigtes Gatewaykommando scheitert sichtbar und sicher.
|
||||
|
||||
### M2 — Typisierte OpenClaw Control Plane
|
||||
|
||||
**Priorität:** P0
|
||||
**Ergebnis:** Nexus kann OpenClaw sicher erweitern, ohne rohe RPC-Aufrufe in
|
||||
Views oder Domänendiensten zu verteilen.
|
||||
|
||||
- Den generischen Gatewayclient hinter domänenspezifischen Verträgen kapseln:
|
||||
- `IOpenClawGatewayReadClient`
|
||||
- `IOpenClawGatewayControlClient`
|
||||
- Sessions/Run Service
|
||||
- Agent Service
|
||||
- Model/Auth-Profile Service
|
||||
- Tool/Approval Service
|
||||
- Cron Service
|
||||
- Channel Service
|
||||
- Node Service
|
||||
- Config/Recovery Service
|
||||
- `InvokeToolAsync` als private Low-Level-Implementierung behandeln.
|
||||
- Gateway-Schema und path-scoped Config-Schema entdecken und vor Mutationen
|
||||
validieren.
|
||||
- Pro Operation erforderliche Scope, Risiko, Approval und Auditpayload
|
||||
deklarativ hinterlegen.
|
||||
- Jede Mutation erhält Idempotency Key, Correlation ID, Actor, Target,
|
||||
erwartete Version und nachvollziehbares Ergebnis.
|
||||
- Optimistische Versionsprüfung für Config-Mutationen und klaren Konfliktflow
|
||||
ergänzen.
|
||||
- Read Models mit `source`, `observedAt`, `staleAfter` und Reconnectzustand
|
||||
versehen.
|
||||
- Fehler nicht in leere Listen umwandeln; offline, unauthorized, stale,
|
||||
incompatible und partial müssen unterscheidbar sein.
|
||||
|
||||
**Checkpoint 2026-07-30:** `IGatewayConnector`, `IOpenClawControlService` und
|
||||
separate Setup-, Agent-Configuration-, Wizard- und Run-Services kapseln den
|
||||
verwendeten RPC-Umfang. Read Models tragen State, Recovery und
|
||||
Beobachtungszeit; Methoden-, Scope-, Versions- und Hashfehler bleiben
|
||||
unterscheidbar. Agent-Dateien, Config und Cron verwenden Idempotenz,
|
||||
Correlation, Audit und optimistische Hashprüfung. Offen bleiben getrennte
|
||||
Fachverträge für Tools, Channels und Nodes sowie ein transaktionaler
|
||||
Multi-Replica-Ledger.
|
||||
|
||||
**Abnahme:** Kein Frontend- oder Domänencode ruft generische OpenClaw-Methoden
|
||||
direkt auf; alle privilegierten Mutationen besitzen Contract-, Auth-, Negativ-
|
||||
und Audit-Tests.
|
||||
|
||||
### M3 — Universeller agent-first Einstieg, Sessions und Runs
|
||||
|
||||
**Priorität:** P0/P1
|
||||
**Ergebnis:** Ziele werden von jeder Seite aus an Iris übergeben; Ausführungen
|
||||
bleiben über Reloads hinweg auffindbar und steuerbar.
|
||||
|
||||
- Globale Command Bar und alle sichtbaren „Ask Iris“-Einstiege funktional
|
||||
vereinheitlichen.
|
||||
- Kontext der aktuellen Route und ausgewählter Objekte explizit anzeigen und
|
||||
vor dem Senden editierbar machen.
|
||||
- Iris-Chat standardmäßig als Modal/Drawer öffnen und Streaming,
|
||||
Stop, Retry sowie nachvollziehbare Fehler bieten.
|
||||
- Session Explorer mit Liste, Suche, Filtern, Verlauf, Freshness und
|
||||
Detailansicht liefern.
|
||||
- Session starten, senden, verzweigen, archivieren und — soweit OpenClaw es
|
||||
unterstützt — zurücksetzen oder kompaktieren.
|
||||
- OpenClaw-Session und Subagent-Task mit Nexus-Projekt, Task, Owner und
|
||||
Control-Audit korrelieren.
|
||||
- Subagenten starten, Hierarchie anzeigen, Status/Logs verfolgen, abbrechen
|
||||
und Ergebnis übernehmen.
|
||||
- Dashboard-Live-Orchestrierung auf autoritative Session-/Run-Ereignisse
|
||||
umstellen; keine rein aus Text abgeleiteten Betriebszustände.
|
||||
- Reload-/Reconnect-Recovery und Deep Links zu Session, Agent, Task und
|
||||
Artifact ergänzen.
|
||||
|
||||
**Abnahme:** Ein Owner kann ausschließlich in Nexus einen Auftrag formulieren,
|
||||
Subagenten beobachten, einen riskanten Schritt freigeben, den Lauf stoppen und
|
||||
nach einem Reload wiederfinden.
|
||||
|
||||
### M4 — Agenten, Modelle, Tools und Approvals
|
||||
|
||||
**Priorität:** P1
|
||||
**Ergebnis:** Die zentralen Runtime-Ressourcen sind ohne OpenClaw-UI sicher
|
||||
bedienbar.
|
||||
|
||||
Agenten:
|
||||
|
||||
- Erstellen oder aus erlaubten Vorlagen importieren.
|
||||
- Aktivieren, deaktivieren, neu starten und kontrolliert entfernen.
|
||||
- Rolle, Workspace, Modellpolicy, Capability-Profil, Tools und Budget anzeigen.
|
||||
- Drift zwischen gewünschter Policy und OpenClaw-Istzustand erkennen.
|
||||
|
||||
Modelle und Provider:
|
||||
|
||||
- OpenAI-Verbindungs- und Auth-Profilstatus anzeigen.
|
||||
- Primärmodell, rollenbezogene Aliase, Allowlist und Fallbacks über OpenClaw
|
||||
verwalten.
|
||||
- Modellkatalog, Fähigkeiten, Limits und gemessene Qualität darstellen.
|
||||
- Policyänderungen mit Diff, Version, Approval und Rollback absichern.
|
||||
- Budget- und Usage-Grenzen mit Warnung und kontrolliertem Fallback ergänzen.
|
||||
|
||||
Tools und Freigaben:
|
||||
|
||||
- OpenClaw-Tool-Katalog, Schemas und effektive Toolrechte darstellen.
|
||||
- Toolprofile sowie Allow-/Deny-Regeln global und pro Agent steuern.
|
||||
- Approval Inbox für Exec, Plugin, Config, externe Datenweitergabe und
|
||||
irreversible Aktionen liefern.
|
||||
- Zeitlimit, Begründung, Entscheider, Policyversion und Ergebnis jeder
|
||||
Freigabe protokollieren.
|
||||
- Tool-Ausgaben als nicht vertrauenswürdige Daten behandeln und
|
||||
Prompt-Injection-/Exfiltrationsgrenzen sichtbar machen.
|
||||
|
||||
**Checkpoint 2026-07-30:** Agent-Inventar und Bootstrap-Dateien stammen live
|
||||
aus OpenClaw; erlaubte Dateien sind mit Expected Hash und Read-back editierbar,
|
||||
zusätzliche Workspace-Dateien read-only. Standing Orders werden kontrolliert in
|
||||
`AGENTS.md` gepflegt. `/models` zeigt den Live-Katalog und ausschließlich den
|
||||
redigierten `models.authStatus`. Agent-Lifecycle, Tool-Katalog/-Policies,
|
||||
Modell-Policy-Mutationen, Budgets und Evals bleiben offen.
|
||||
|
||||
**Abnahme:** Ein Modell-, Tool- oder Agentenwechsel ist ohne rohe
|
||||
`openclaw.json`-Bearbeitung möglich, lässt sich zurückverfolgen und kann keine
|
||||
Secrets offenlegen.
|
||||
|
||||
### M5 — Scheduler und Automationen
|
||||
|
||||
**Priorität:** P1
|
||||
**Ergebnis:** Alle regelmäßigen Agentenabläufe sind in Nexus plan- und
|
||||
kontrollierbar.
|
||||
|
||||
- Cron Jobs auflisten, suchen, erstellen, kopieren und bearbeiten.
|
||||
- Aktivieren, pausieren, fortsetzen, sofort ausführen und entfernen.
|
||||
- Zeitzone, Session Mode, Zielagent, Payload, Delivery/Webhook, Owner und
|
||||
Projektbezug konfigurieren.
|
||||
- Nächsten Lauf, letzte Ausführung, Run-Historie, Dauer, Fehler und Retry
|
||||
darstellen.
|
||||
- Vorlagen für wiederkehrende Reports, Wartung, Recherche und Incident Checks
|
||||
anbieten.
|
||||
- Admin-relevante Mutationen über Approval und Scope Gate absichern.
|
||||
- Retry-/Backoff-, Missed-run- und Alerting-Policies definieren.
|
||||
|
||||
**Checkpoint 2026-07-30:** Liste, Detail, Create, Edit, Enable/Disable, Delete,
|
||||
Sofortlauf und paginierte OpenClaw-Run-Historie sind typisiert umgesetzt.
|
||||
Mutationen benötigen Owner, lokale Managementfreigabe, `operator.admin`,
|
||||
Idempotency Key und bei vorhandenen Jobs den aktuellen Ressourcenhash. Ein
|
||||
Sofortlauf wird nur als eingereiht gemeldet; der tatsächliche Ausgang stammt
|
||||
aus `cron.runs`.
|
||||
Command-Payloads und `on-exit` bleiben durch `AllowCommandCron=false`
|
||||
gesperrt. Offen bleiben Live-Schreibabnahme, Copy/Templates und umfassende
|
||||
Retry-/Missed-run-/Alerting-Policies.
|
||||
|
||||
**Abnahme:** Ein Scheduler-Workflow kann vollständig in Nexus angelegt,
|
||||
probeweise ausgeführt, pausiert, diagnostiziert und entfernt werden.
|
||||
|
||||
### M6 — Knowledge, Workspaces und Artifacts
|
||||
|
||||
**Priorität:** P1
|
||||
**Ergebnis:** Agentenwissen und Outputs sind kontrollierbar, versioniert und
|
||||
mit Arbeit verknüpft.
|
||||
|
||||
- Memory-Einträge erstellen, bearbeiten, archivieren und löschen.
|
||||
- Dokumente hochladen, importieren, schreiben, versionieren und freigeben.
|
||||
- Quelle, Owner, Scope, Freshness, Retention und Ingestionstatus anzeigen.
|
||||
- Retrieval-Tests und zitierbare Provenienz ergänzen.
|
||||
- Workspace-Dateien über erlaubte Roots browsen und bearbeiten.
|
||||
- Schreibzugriffe mit Diff, Allowlist, Backup, Validierung und Approval
|
||||
absichern.
|
||||
- Artifacts hochladen, anzeigen, herunterladen, versionieren und mit Session,
|
||||
Task, Projekt sowie Incident verknüpfen.
|
||||
- Sensible Daten klassifizieren und Export-/Retention-Policies anwenden.
|
||||
|
||||
**Checkpoint 2026-07-30:** Die Standard-Agentdateien werden über
|
||||
`agents.files.*` verwaltet. Weitere Dateien wie `DREAMS.md` oder
|
||||
`memory/YYYY-MM-DD.md` werden über `agents.workspace.*` angezeigt und bleiben
|
||||
mangels sicherem beliebigem Workspace-Write-RPC read-only. Die eigenständigen
|
||||
Nexus-Flächen für Memory, Docs, Ingestion, Versionierung und Artifacts sind
|
||||
damit noch nicht abgeschlossen.
|
||||
|
||||
**Abnahme:** Ein Agent kann aus Nexus freigegebenes Wissen nutzen, ein Artifact
|
||||
erzeugen und dessen Herkunft bis zum Auftrag und Tool-Aufruf nachvollziehbar
|
||||
machen.
|
||||
|
||||
### M7 — Operations, Governance und Recovery
|
||||
|
||||
**Priorität:** P1
|
||||
**Ergebnis:** Mission Control steuert nicht nur Agenten, sondern auch den
|
||||
sicheren Betriebsalltag.
|
||||
|
||||
- Zentrale Approval Inbox mit Filtern, SLA, Eskalation und Batch-Entscheidung
|
||||
für ausschließlich risikoarme, gleichartige Fälle.
|
||||
- Benachrichtigungsregeln, Kanäle, Snooze, Acknowledge und Quiet Hours.
|
||||
- Incidents erstellen, bestätigen, zuweisen, eskalieren, beheben, schließen
|
||||
und als Postmortem dokumentieren.
|
||||
- Session-, Task-, Tool- und Providerereignisse mit Incidents korrelieren.
|
||||
- Security Center mit tatsächlicher Policy-/Auth-Lage, Remediation und
|
||||
Evidenz statt reiner Konfigurationsanzeige.
|
||||
- Nutzer-Sessions, Geräte, 2FA/Passkeys, Schlüsselrotation und Recovery Codes.
|
||||
- Autoritativer Audit-/Event-Stream mit Actor, Korrelation, Diff, Suche,
|
||||
Export und Retention.
|
||||
- Gateway-Recovery mit Version, Health, kontrolliertem Reload, Backup,
|
||||
Rollback und Break-glass-Prozedur.
|
||||
|
||||
**Abnahme:** Kritische Fehler und riskante Aktionen können in Nexus erkannt,
|
||||
freigegeben, behoben und vollständig auditiert werden.
|
||||
|
||||
### M8 — Channels, Connectors, Nodes und Parität
|
||||
|
||||
**Priorität:** P2
|
||||
**Ergebnis:** Auch OpenClaw-nahe Infrastruktur muss im Alltag nicht separat
|
||||
bedient werden.
|
||||
|
||||
- Channels verbinden, Status/Capabilities prüfen, Logs filtern und
|
||||
kontrolliert trennen.
|
||||
- Connectorrechte, Datenfreigaben und Approval Policies verwalten.
|
||||
- Nodes/Hosts inventarisieren, pairen, Health und Capabilities anzeigen.
|
||||
- Node-Aktionen erlaubnis- und approval-basiert ausführen.
|
||||
- Gateway-Konfiguration über Live-Schema, strukturierte Formulare und Diff
|
||||
pflegen; keine unvalidierte Raw-JSON-Konsole als Hauptweg.
|
||||
- Updates und Reloads mit Kompatibilitätsprüfung, Wartungsmodus, Backup und
|
||||
Rollback steuern.
|
||||
- Optional Voice-, Media- und Mobile/PWA-Oberflächen ergänzen, sobald die
|
||||
Control-Plane-Gates stabil sind.
|
||||
|
||||
**Checkpoint 2026-07-30:** Settings enthält einen schema-basierten
|
||||
OpenClaw-Configeditor mit `config.schema.lookup`, `config.get`,
|
||||
`config.patch`, `baseHash`, Diff-Vorschau und `replacePaths`. Der offizielle
|
||||
`wizard.*`-Flow wird sicher gerendert, sobald die verbundene Instanz ihn mit
|
||||
Managementfreigabe und `operator.admin` bewirbt. Channels, Nodes,
|
||||
Update-/Reload- und Recovery-Parität bleiben offen.
|
||||
|
||||
**Abnahme:** Die dokumentierte tägliche OpenClaw-UI-Checkliste besitzt für
|
||||
jeden normalen Vorgang einen sicheren Nexus-Workflow.
|
||||
|
||||
### M9 — Observability, Kosten, Evals und Release-Reife
|
||||
|
||||
**Priorität:** P2
|
||||
**Ergebnis:** Qualität, Kosten und Betriebssicherheit sind messbar und
|
||||
regressionsfest.
|
||||
|
||||
- Autoritative Provider-, Modell-, Token-, Kosten- und Latenzdaten erfassen.
|
||||
- Trace-/Run-Explorer für Session-, Tool-, Approval-, Artifact- und
|
||||
Fehlerereignisse liefern.
|
||||
- Budgets und Alerts pro Projekt, Agent, Modell und Zeitraum.
|
||||
- Eval-Datasets für Instruction Following, funktionale Korrektheit,
|
||||
Tool-Auswahl und Argumentgenauigkeit pflegen.
|
||||
- Prompt-, Agenten-, Modell- und Policyversionen in Vergleichsläufen messen.
|
||||
- Qualitäts-, Kosten-, Security- und Latenzschwellen als Release Gates.
|
||||
- E2E-Tests über Browser, Nexus, OpenClaw, OpenAI und PostgreSQL.
|
||||
- Alle Routen auf Auth, Loading, Empty, Error, Keyboard und
|
||||
375/768/1024/1440/1920 px testen.
|
||||
- Last-, Reconnect-, Timeout-, Queue-, Recovery- und Chaos-Szenarien prüfen.
|
||||
- Runbooks, Backup/Restore und Rollback regelmäßig als Game Day testen.
|
||||
|
||||
**Abnahme:** Ein Release ist nur möglich, wenn technische Checks und ein
|
||||
repräsentativer realer Agenten-Workflow gemeinsam grün sind.
|
||||
|
||||
### M10 — Strategische agent-first Erweiterungen
|
||||
|
||||
**Priorität:** P3
|
||||
**Ergebnis:** Nach belegter Kernreife wird Nexus vom Cockpit zum proaktiven
|
||||
Operationssystem.
|
||||
|
||||
- Ziel- und Outcome-Management mit Agentenplänen, KPIs und Abbruchkriterien.
|
||||
- Wiederverwendbare Agenten-, Workflow- und Projekt-Playbooks.
|
||||
- Simulation/Dry Run für riskante oder kostenintensive Ausführungen.
|
||||
- Policy-basierte Auto-Approvals für eng begrenzte, reversible Aktionen.
|
||||
- Proaktive Opportunity-, Risk- und Drift-Erkennung mit menschlicher
|
||||
Bestätigung.
|
||||
- Multi-Workspace-/Teamgrenzen und delegierte Administration.
|
||||
- Agentenqualitäts-SLOs, automatische Regressionserkennung und
|
||||
modellabhängige Routingoptimierung.
|
||||
|
||||
## 6. Auswirkungen auf die 18 bestehenden Seiten
|
||||
|
||||
| Route | Zielrolle | Verbindliche Verbesserungen | Meilenstein |
|
||||
|---|---|---|---|
|
||||
| `/login` | Sicherer Zugang | Recovery, Return-to-Route, 2FA/Passkeys, Geräte/Sessions | M1, M7 |
|
||||
| `/dashboard` | Mission Overview | echte Command Bar, autoritative Run-Hierarchie, Queue, Providerstatus, Usage, Fehler/Recovery | M1, M3, M9 |
|
||||
| `/memory` | Wissensspeicher | CRUD, Scope, Provenienz, Freshness, Retention, Retrieval-Evals | M6, M9 |
|
||||
| `/docs` | Knowledge Ingestion | Upload/Authoring, Import/Sync, Versionen, Zitate, Freigaben | M6 |
|
||||
| `/agents/:id` | Agent Cockpit | live Bootstrap-Dateien, Standing Orders und read-only Workspace vorhanden; Lifecycle, Sessions, Subagenten, Tools, Modellpolicy, Budget, Evals offen | M3, M4, M9 |
|
||||
| `/security` | Security Center | echte Auth-/Policylage, Findings, Remediation, Rotation, Sessions, Audit | M1, M7 |
|
||||
| `/incidents` | Incident Operations | Create/Ack/Assign, Timeline, Run-Bezug, Remediation, Resolve, Postmortem | M7 |
|
||||
| `/calendar` | Automation Scheduler | Cron-CRUD, Enable/Disable, Sofortlauf und History vorhanden; Live-Abnahme, Templates, Retry-Policy und Delivery-Härtung offen | M5 |
|
||||
| `/projects` | Portfolio | Ziele, Team, Runs, Tasks, Artifacts, Budget, Health, Automationen | M3, M6, M9 |
|
||||
| `/projects/:id` | Project Control | Delegation, Runstart, KPIs, Team, Timeline, Budget, Playbooks | M3, M6, M10 |
|
||||
| `/tasks` | Agent Work Queue | Run-/Approval-Bezug, Dependencies, Bulk, Retry/Resume/Cancel, ehrliche Fehler | M3, M7 |
|
||||
| `/tasks/:id` | Task Control | Session/Run, Tools, Approvals, Artifacts, Abhängigkeiten, Replay | M3, M6 |
|
||||
| `/agents` | Runtime Workforce | Live-Inventar vorhanden; Create/Import, Enable/Disable/Restart, Capabilities, Permissions, Last und Kosten offen | M4, M9 |
|
||||
| `/models` | OpenAI Policy via OpenClaw | redigierter Authstatus vorhanden; Primärmodell, Allowlist, Aliase, Fallbacks, Limits und Tests offen | M1, M4 |
|
||||
| `/activity` | Audit/Event Stream | autoritative Events, Correlation ID, Actor, Diff, Suche, Export, Retention | M2, M7 |
|
||||
| `/runs` | Run Control | Start/Resume/Retry/Branch, Deep Links, Trace, Tools, Artifacts und dauerhafte Korrelation | M2, M3, M7 |
|
||||
| `/notifications` | Action Inbox | Loading/Error, Ack/Snooze, Preferences, Routing, Approval-/Incident-Aktionen | M7 |
|
||||
| `/settings` | Control-Plane Setup | Attach & Adopt, Management-Gate, Configschema und Wizard vorhanden; offizielle Client-ID, Live-Pairing, Tools, Approvals und Retention offen | M1, M4, M7, M8 |
|
||||
|
||||
Seit dem 2026-07-31-Checkpoint liefern die fachlichen Task-, Projekt-,
|
||||
Notification-, Cron-, Config-, Approval-, Session- und Agent-Datei-Mutationen
|
||||
ein gemeinsames `OperationResultDto`. Das globale Ergebnisfenster verlinkt
|
||||
Primär- und Folgeobjekte; Task Detail, Run Control, Calendar, Agent Detail,
|
||||
Activity, Notifications und Settings konsumieren die jeweilige Deep-Link-
|
||||
Auswahl. Damit ist die querschnittliche Ergebnisnavigation umgesetzt. Offen
|
||||
bleiben die in der Tabelle genannten fachlichen Funktionen und die externen
|
||||
Live-/Lastgates, nicht ein weiterer paralleler Frontend-Ergebnisvertrag.
|
||||
|
||||
Iris Chat ist kein eigener Route mehr. Er bleibt als persistenter, kontextueller
|
||||
Dashboard-Dialog und globales Ziel für „Ask Iris“.
|
||||
|
||||
## 7. Vorgeschlagene neue Arbeitsflächen
|
||||
|
||||
Diese Routen sind Produktvorschläge. Sie dürfen erst in Navigation oder
|
||||
Deep Links erscheinen, wenn Route und funktionsfähiges Ziel registriert sind.
|
||||
|
||||
| Vorgeschlagene Route | Zweck | Alternative bei kleinerem Scope |
|
||||
|---|---|---|
|
||||
| `/runs/:id` | dauerhafte Deep-Link-Ansicht eines korrelierten Laufs (umgesetzt) | `/agents/:id?session=...` |
|
||||
| `/tools` | Katalog, Schemas, effektive Rechte und Policies | Tab in Agent Detail |
|
||||
| `/approvals` | zentrale menschliche Freigaben | Notifications-Filter als erster Slice |
|
||||
| `/artifacts` | Outputs, Dateien, Herkunft und Versionen | Project-/Task-Tab |
|
||||
| `/channels` | Channelstatus, Capabilities und Logs | Settings-Tab |
|
||||
| `/nodes` | Hosts, Pairing, Health und erlaubte Aktionen | Settings-Tab |
|
||||
| `/evals` | Datensätze, Vergleiche und Qualitätsgates | Models-Tab |
|
||||
|
||||
`/runs` und der dauerhafte `/runs/:id`-Pfad sind umgesetzt. Approvals können bis
|
||||
zur benötigten Inbox-Tiefe in Run Control und Notifications bleiben. Tools,
|
||||
Channels und Nodes können initial als Tabs starten, solange Navigation und
|
||||
Informationsarchitektur nicht überladen werden.
|
||||
|
||||
## 8. Querschnittsabhängigkeiten
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
M0["M0 Architekturvertrag"] --> M1["M1 Trust + OpenAI über OpenClaw"]
|
||||
M1 --> M2["M2 Typisierte Gateway Control Plane"]
|
||||
M2 --> M3["M3 Sessions, Runs, Iris"]
|
||||
M2 --> M4["M4 Agents, Models, Tools, Approvals"]
|
||||
M2 --> M5["M5 Scheduler"]
|
||||
M3 --> M6["M6 Knowledge + Artifacts"]
|
||||
M3 --> M7["M7 Operations + Governance"]
|
||||
M4 --> M7
|
||||
M5 --> M7
|
||||
M6 --> M8["M8 Ecosystem-Parität"]
|
||||
M7 --> M8
|
||||
M3 --> M9["M9 Observability + Evals"]
|
||||
M4 --> M9
|
||||
M5 --> M9
|
||||
M8 --> M10["M10 Strategische Erweiterungen"]
|
||||
M9 --> M10
|
||||
```
|
||||
|
||||
M3 bis M5 dürfen vertikal in kleine Slices zerlegt werden. Sie dürfen aber
|
||||
nicht die M1-/M2-Vertrauensgrenze umgehen.
|
||||
|
||||
## 9. Nächster empfohlener Implementierungsslice
|
||||
|
||||
**Slice: „Official external identity and controlled live acceptance“**
|
||||
|
||||
1. Upstream eine offiziell unterstützte externe `nexus`- oder generische
|
||||
Operator-Client-ID verwenden und Nexus auf die erste unterstützende
|
||||
OpenClaw-Version pinnen; keine reservierte interne Identität imitieren.
|
||||
2. Auf Baos ausdrücklich freigegebener OpenClaw-Instanz read-only verbinden,
|
||||
die konkrete Pairing-Request-ID freigeben lassen und Agent-/Cron-Inventar
|
||||
gegen den erwarteten Bestand abgleichen, ohne Runtime-Daten zu kopieren.
|
||||
3. Den bewussten Admin-Scope-Upgrade separat pairen und Endpoint-, Device-,
|
||||
TLS-, Scope- und Capability-Bindung im Security Center belegen.
|
||||
4. Ausschließlich an eindeutig benannten Testobjekten je einen
|
||||
Hashkonflikt-/Read-back-Test für Agent-Datei und Config sowie Create/Edit/
|
||||
Run/History/Delete für Cron durchführen. Andere Ressourcen bleiben
|
||||
unangetastet.
|
||||
5. OpenAI ausschließlich in OpenClaw als Primärprovider für Iris konfigurieren
|
||||
und einen echten, dauerhaft korrelierten
|
||||
`Nexus -> OpenClaw -> OpenAI -> Nexus`-Run ausführen.
|
||||
6. Provider-/Modellreferenz, Events, Stop/Retry, Reload-Recovery, Audit und
|
||||
Negativfälle ohne Prompt-, Delivery- oder Secret-Leak belegen.
|
||||
|
||||
Dieser Slice löst den externen Identitätsblocker und liefert den ersten
|
||||
vollständigen Beweis, dass Attach & Adopt sowie ein normaler agent-first
|
||||
Arbeitsablauf ohne Wechsel in die OpenClaw-Oberfläche sicher funktionieren.
|
||||
|
||||
## 10. Definition of Done für „kein OpenClaw-Wechsel mehr“
|
||||
|
||||
Das Produktversprechen gilt erst als erfüllt, wenn:
|
||||
|
||||
1. ein Owner den vollständigen Ablauf
|
||||
`Absicht -> Plan -> Agent/Subagent -> Tool -> Approval -> Artifact -> Review`
|
||||
ausschließlich in Nexus bedienen kann;
|
||||
2. OpenClaw für alle Runtimezustände autoritativ bleibt, während Nexus diese
|
||||
zuverlässig, aktuell und steuerbar projiziert;
|
||||
3. jede Modellinferenz aus Nexus nachweislich über OpenClaw läuft und OpenAI
|
||||
dort der primäre Provider ist;
|
||||
4. kein OpenAI-Secret in Browser, Nexus-Konfiguration, Datenbank oder Logs
|
||||
benötigt oder offengelegt wird;
|
||||
5. alle normalen Agenten-, Session-, Tool-, Cron-, Modell-, Approval-,
|
||||
Knowledge-, Incident- und Recovery-Aufgaben Nexus-Workflows besitzen;
|
||||
6. jede riskante Mutation Scope, Policy, Approval, Idempotenz und Audit besitzt;
|
||||
7. Offline-, Partial-, Stale-, Unauthorized- und Incompatible-Zustände für den
|
||||
Operator verständlich und handlungsfähig sind;
|
||||
8. reale E2E-, Security-, Eval-, Recovery-, Accessibility- und Responsive-Gates
|
||||
grün sind;
|
||||
9. die OpenClaw-Oberfläche nur noch für dokumentierten Break-glass- oder
|
||||
Plattformentwicklungsbetrieb gebraucht wird.
|
||||
|
||||
## 11. Bewusste Nicht-Ziele
|
||||
|
||||
- Kein direkter OpenAI-Adapter oder OpenAI-Schlüssel in Nexus.
|
||||
- Keine zweite Agentenruntime, kein zweiter OpenClaw-Session Store.
|
||||
- Keine ungeprüfte Raw-Config-Konsole als primärer Verwaltungsweg.
|
||||
- Keine direkte Browser-Gateway-Verbindung.
|
||||
- Keine Navigation zu nicht registrierten oder leeren Routen.
|
||||
- Kein kosmetisches „Control“-UI ohne wirksame Mutation, Fehlerfeedback und
|
||||
Audit.
|
||||
- Keine komplette Kopie jeder OpenClaw-Entwickleroberfläche; Nexus bildet die
|
||||
Owner- und Operations-Workflows ab.
|
||||
|
||||
## 12. Primärquellen
|
||||
|
||||
OpenClaw:
|
||||
|
||||
- [Modelle und `provider/model`-Policies](https://docs.openclaw.ai/models)
|
||||
- [Gateway-Protocol-v4-Vertrag](https://docs.openclaw.ai/gateway/protocol)
|
||||
- [Gateway-Client und Geräteidentität](https://docs.openclaw.ai/gateway/clients)
|
||||
- [Stable Client-ID-Registry `2026.7.1`](https://github.com/openclaw/openclaw/blob/v2026.7.1/packages/gateway-protocol/src/client-info.ts)
|
||||
- [Operator-Scopes und Least Privilege](https://docs.openclaw.ai/gateway/operator-scopes)
|
||||
- [Gateway-Konfiguration](https://docs.openclaw.ai/gateway/configuration)
|
||||
- [Offizieller Setup-Wizard](https://docs.openclaw.ai/reference/wizard)
|
||||
- [Background Tasks](https://docs.openclaw.ai/automation/tasks)
|
||||
- [Cron-Operationen und erforderliche Scopes](https://docs.openclaw.ai/cli/cron)
|
||||
- [Tools Invoke HTTP API](https://docs.openclaw.ai/gateway/tools-invoke-http-api)
|
||||
- [Gateway Troubleshooting](https://docs.openclaw.ai/gateway/troubleshooting)
|
||||
|
||||
OpenAI:
|
||||
|
||||
- [API-Key-Sicherheit und Produktionsbetrieb](https://developers.openai.com/api/docs/guides/production-best-practices#api-keys)
|
||||
- [Eval-Kriterien für einzelne Agenten](https://developers.openai.com/api/docs/guides/evaluation-best-practices#single-agent-architectures)
|
||||
@@ -0,0 +1,123 @@
|
||||
# Nexus authenticated UI contract
|
||||
|
||||
`/dashboard` is the visual authority for authenticated Nexus surfaces. This
|
||||
contract keeps the remaining routes aligned without coupling presentation to
|
||||
stores, services, API contracts, route behavior, or domain state.
|
||||
|
||||
## Sources of truth
|
||||
|
||||
- `frontend/src/assets/nexus-tokens.css` is the only source for Nexus color,
|
||||
surface, typography, radius, focus, status, and page-geometry tokens.
|
||||
- `frontend/src/assets/nexus-components.css` is the shared presentation layer
|
||||
for the authenticated legacy shell and route families.
|
||||
- `components/layout/AppSidebar.vue` is the single authenticated navigation
|
||||
component. Both `frontend/src/App.vue` and
|
||||
`frontend/src/layouts/NexusLayout.vue` render it.
|
||||
- `frontend/src/App.vue` with `components/layout/AppHeader.vue` and
|
||||
`frontend/src/layouts/NexusLayout.vue` with `components/layout/Topbar.vue`
|
||||
own the two content shells around that shared navigation.
|
||||
- `/dashboard` and `/login` retain their standalone content implementations;
|
||||
the dashboard no longer owns a separate sidebar implementation.
|
||||
|
||||
Do not add raw color values to migrated views. Add or reuse a semantic token in
|
||||
`nexus-tokens.css`, then consume that token from the component or shared layer.
|
||||
Legacy variables must resolve to V2 tokens rather than introduce a second
|
||||
palette.
|
||||
|
||||
## Visual foundation
|
||||
|
||||
| Concern | Contract |
|
||||
| --- | --- |
|
||||
| Background | Galaxy background over `--space-0` for authenticated routes |
|
||||
| Sidebar | `248px` desktop; overlay navigation at `900px` and below |
|
||||
| Topbar | `62px`, glass surface, persistent above route content |
|
||||
| Body type | Manrope, `12px` minimum for interface copy |
|
||||
| Page title | Space Grotesk, `24px / 30px`, weight `700` |
|
||||
| Metadata | JetBrains Mono, `11px` minimum |
|
||||
| Page inset | `20px` desktop, `14px` mobile |
|
||||
| Panel | `--glass`, `--line`, `14px` radius, controlled blur |
|
||||
| Standard page | `1180px` maximum |
|
||||
| Workspace | `1440px` maximum |
|
||||
| Reading/form surface | `880px` maximum |
|
||||
| Focus | Visible `:focus-visible` outline using `--a-blue` and `--focus-ring` |
|
||||
|
||||
Blue-to-violet gradients and glows are reserved for active navigation, primary
|
||||
actions, and meaningful operational states. Neutral cards, inputs, metadata,
|
||||
empty states, and destructive confirmation surfaces use plain glass and
|
||||
semantic status colors.
|
||||
|
||||
## Navigation contract
|
||||
|
||||
- Every authenticated sidebar presents the categories `Operations`,
|
||||
`Knowledge`, `Infrastructure`, and `Governance` in that order.
|
||||
- Render `components/layout/AppSidebar.vue`; do not introduce another
|
||||
authenticated sidebar component or duplicate its navigation data.
|
||||
- Settings remains a persistent footer destination below the scrollable
|
||||
category list on every authenticated route.
|
||||
- Use semantic RouterLinks for registered destinations and `aria-current` for
|
||||
the active item. Agent, Project, and Task details activate their parent
|
||||
navigation destination.
|
||||
- Keep counts, labels, permissions, registered route targets, and logout
|
||||
behavior owned by `AppSidebar` and its existing stores/props.
|
||||
|
||||
## Shared presentation vocabulary
|
||||
|
||||
- Use `.nexus-page` for standard route roots.
|
||||
- Add `.nexus-page--workspace` only for horizontally or spatially dense work
|
||||
surfaces such as Task Board and Chat.
|
||||
- Add `.nexus-page--reading` for detail, form, and notification surfaces.
|
||||
- Use `.nexus-page-header` for route identity and local actions.
|
||||
- Use `.glass-panel` or the route-family rules in `nexus-components.css` for
|
||||
panels.
|
||||
- Keep loading, empty, error, warning, and success feedback inside the route
|
||||
frame. Existing copy and state guards remain authoritative.
|
||||
- Use Lucide icons already present in the project. Do not use emoji, text
|
||||
glyphs, handcrafted SVGs, or icon-like CSS drawings.
|
||||
|
||||
## Dashboard orchestration contract
|
||||
|
||||
- Live-Orchestrierung is the primary dashboard surface and owns the remaining
|
||||
workspace after the `62px` topbar.
|
||||
- Iris Chat is closed by default. Open it only through the topbar `Iris Chat`
|
||||
action and render it as a modal dialog; do not restore a persistent rail.
|
||||
- Preserve the existing chat store, polling lifecycle, messages, send handler,
|
||||
error state, and thinking state when changing presentation.
|
||||
- Keep operational status in one compact row and prioritize active, planning,
|
||||
and blocker signals on narrow layouts.
|
||||
- Keep focus tasks in one compact row. Priority, state, title, and owner must
|
||||
remain visible or programmatically available.
|
||||
- At `680px` and below, agent nodes use the compact card variant. Auto-layout
|
||||
must not overlap or clip nodes at the supported breakpoints.
|
||||
- Modal close by pointer and Escape must restore focus to the connected Iris
|
||||
trigger.
|
||||
|
||||
## Responsive and accessibility rules
|
||||
|
||||
- At `900px` and below, the sidebar becomes a keyboard-operable overlay and the
|
||||
topbar exposes the navigation toggle.
|
||||
- At `1024px` and below, multi-column detail and settings layouts collapse
|
||||
presentationally without changing source order.
|
||||
- At `767px` and below, headers and action rows stack and the page inset becomes
|
||||
`14px`.
|
||||
- The document must never overflow horizontally at `375`, `768`, `1024`,
|
||||
`1440`, or `1920px`.
|
||||
- Internal horizontal scrolling is allowed only for a domain-horizontal work
|
||||
surface, currently the Task Board columns.
|
||||
- Every icon-only control needs an accessible name. Interactive cards must use
|
||||
link/button semantics and offer Enter/Space keyboard equivalence as
|
||||
appropriate.
|
||||
- Preserve existing `v-model`, handlers, emits, navigation destinations,
|
||||
permissions, and state transitions.
|
||||
|
||||
## Route-family mapping
|
||||
|
||||
| Family | Routes |
|
||||
| --- | --- |
|
||||
| List/detail | Memory, Docs, Incidents, Calendar, Security |
|
||||
| Grid/overview | Agents, Projects, Models, Activity, Notifications |
|
||||
| Detail/form | Agent Detail, Project Detail, Task Detail, Settings |
|
||||
| Workspace | Task Board, Chat |
|
||||
|
||||
When adding a route, choose the closest family, apply the shared root class,
|
||||
verify loading/empty/error states, and test the registered destination at all
|
||||
required breakpoints before adding navigation.
|
||||
@@ -0,0 +1,248 @@
|
||||
# OpenClaw Gateway connection contract
|
||||
|
||||
**Status:** Attach-&-Adopt-Vertrag implementiert; produktive externe
|
||||
Client-Identität und Live-Abnahme offen
|
||||
**Stand:** 2026-07-30
|
||||
|
||||
Nexus ist die einzige browserseitige Control Plane. OpenClaw bleibt die
|
||||
Runtime- und Datenautorität. Gateway-Credentials, Ed25519-Private-Key,
|
||||
Device-Token, Provider-Secrets und OpenAI-Schlüssel bleiben serverseitig und
|
||||
werden weder an den Browser noch in OpenClaw-Projektionen oder PostgreSQL
|
||||
gegeben.
|
||||
|
||||
## Produktions- und Kompatibilitätsgrenze
|
||||
|
||||
- Der Connector verwendet Gateway Protocol v4 und ist standardmäßig auf den
|
||||
geprüften OpenClaw-Stand `2026.7.1` gepinnt.
|
||||
- Nexus verwendet die externe Client-ID `nexus` und imitiert weder
|
||||
`gateway-client/backend` noch Control UI oder CLI. Diese Identitäten sind
|
||||
OpenClaw-intern reserviert.
|
||||
- Die stabile OpenClaw-Client-ID-Registry des gepinnten Stands unterstützt noch
|
||||
keine externe Nexus-/Generic-Operator-ID. Deshalb bleibt der produktive
|
||||
Connector standardmäßig mit
|
||||
`OpenClawSetup:ExternalClientIdentitySupported=false` beziehungsweise
|
||||
`OPENCLAW_EXTERNAL_CLIENT_ID_SUPPORTED=false` experimentell blockiert.
|
||||
- Das Flag darf erst für eine OpenClaw-Version aktiviert werden, deren
|
||||
dokumentierter Client-Vertrag die verwendete externe Identität tatsächlich
|
||||
akzeptiert und gegen die Nexus-Contract-Tests gepinnt wurde.
|
||||
- Lokale Mock-, Contract- und UI-Tests beweisen nicht, dass dieser Upstream-
|
||||
Blocker gelöst ist. Eine produktive Verbindung oder Managementfreigabe darf
|
||||
bis dahin nicht behauptet werden.
|
||||
|
||||
## Autorisierungsgrenze
|
||||
|
||||
- ASP.NET Core verwendet eine authenticated-by-default Fallback Policy. Nur die
|
||||
Auth-Bootstrap-/Session-Endpunkte und explizite Liveness-/Gateway-Health-
|
||||
Probes sind anonym.
|
||||
- Alle Setup-, Agent-Datei-, Workspace- und Config-Routen sind owner-only.
|
||||
Andere `/api/v1/openclaw/*`-Leserouten sind authentifiziert; Control- und
|
||||
Run-Mutationen bleiben owner-only.
|
||||
- `X-Agent-Id` ist niemals Authentifizierung. Der Header ist nur nach bereits
|
||||
verifizierter Service- oder privilegierter Benutzeridentität ein
|
||||
allow-gelisteter Actor-Hinweis.
|
||||
- OpenClaw-Schreibzugriffe benötigen gleichzeitig:
|
||||
- einen vom Gateway beworbenen RPC;
|
||||
- den erforderlichen Operator-Scope;
|
||||
- die lokal persistierte `ManagementEnabled`-Freigabe;
|
||||
- Rate Limit, Audit und einen Idempotency Key; sowie
|
||||
- den aktuellen Ressourcen- oder Config-Hash.
|
||||
|
||||
## Persistiertes Profil und Secret Ownership
|
||||
|
||||
Nexus verwaltet in der ersten Ausbaustufe exakt ein Profil mit der festen ID
|
||||
`primary`. PostgreSQL speichert nur nicht geheime Verbindungs- und
|
||||
Adoptionsmetadaten:
|
||||
|
||||
- normalisierten Endpoint und Discovery-Quelle;
|
||||
- erforderliche OpenClaw-Version und optionalen TLS-Fingerprint;
|
||||
- Setup-/Adoption-State und lokale Managementfreigabe;
|
||||
- Capability-Hash;
|
||||
- Zeitstempel und Concurrency-Version.
|
||||
|
||||
Der Device-Key und ein ausgestellter Device-Token liegen ausschließlich im
|
||||
serverseitigen Device-State. Der Token ist an normalisierten Endpoint,
|
||||
TLS-Fingerprint, Rolle und Scopes gebunden. OpenAI-Schlüssel,
|
||||
Gateway-Passwörter und Provider-Secrets werden nicht in diesem Profil
|
||||
gespeichert.
|
||||
|
||||
Ein Bootstrap-Token kann beim Attach entweder maskiert im Owner-Formular oder
|
||||
über eine serverseitige Secret-Referenz übergeben werden. Der Klartext lebt nur
|
||||
im Arbeitsspeicher, bis OpenClaw einen gebundenen Device-Token ausstellt. Nexus
|
||||
gibt ihn nicht zurück und schreibt ihn weder in PostgreSQL noch in Auditdaten.
|
||||
|
||||
`GatewayConnector:DeviceStatePath` enthält Private Key, Public-Key-Metadaten
|
||||
und gebundene Device-Tokens.
|
||||
`GatewayConnector:OperationAuditPath` enthält den append-only
|
||||
Mutationsledger. Compose verwendet dafür:
|
||||
|
||||
- `/var/lib/nexus/openclaw/device-state.json`;
|
||||
- `/var/lib/nexus/openclaw/operation-audit.jsonl`; und
|
||||
- das benannte Volume `nexus-openclaw-device`.
|
||||
|
||||
Auf Unix setzt Nexus Verzeichnisse auf `0700` und Dateien auf `0600`. Ein
|
||||
korruptes Identity- oder Audit-File scheitert geschlossen; Nexus rotiert nicht
|
||||
still eine neue Identität und wiederholt keinen unklaren Schreibvorgang.
|
||||
|
||||
## Transport- und Discovery-Regeln
|
||||
|
||||
Discovery ist absichtlich begrenzt. Nexus prüft nur:
|
||||
|
||||
- einen bereits konfigurierten Endpoint;
|
||||
- Baos bekannten Docker-DNS-Kandidaten `openclaw-gateway:18789`;
|
||||
- Loopback;
|
||||
- `host.docker.internal`; und
|
||||
- mDNS nur nach einer ausdrücklichen Owner-Aktion. Der aktuelle Build meldet
|
||||
mDNS als `unsupported` und führt dann ebenfalls keinen Netzwerkscan aus.
|
||||
|
||||
Es gibt keinen Subnetzscan und keinen Zugriff auf den Docker-Socket.
|
||||
|
||||
Externe Ziele benötigen `wss://` und einen bestätigten SHA-256-
|
||||
Zertifikatfingerprint. Klares `ws://` ist nur für Loopback oder eine ausdrücklich
|
||||
erlaubte interne Docker-Verbindung zulässig. Ein Endpoint- oder TLS-Pin-Wechsel
|
||||
erzwingt eine neue Vertrauensprüfung; ein alter gebundener Device-Token darf
|
||||
nicht still weiterverwendet werden.
|
||||
|
||||
## Owner-Flow: Erkennen, Verbinden und Übernehmen
|
||||
|
||||
Der Setup Center in `/settings` führt durch einen zustandsbehafteten,
|
||||
read-only-first Ablauf:
|
||||
|
||||
1. **Erkennen:** Bekannte Kandidaten finden oder einen expliziten Endpoint
|
||||
eingeben.
|
||||
2. **Prüfen:** Transport, TLS-Pin, Version, Protokoll, externe Client-
|
||||
Kompatibilität und erreichbare Capabilities prüfen.
|
||||
3. **Verbinden:** Mit einem einmaligen Bootstrap-Secret nur `operator.read`
|
||||
anfordern und bei Bedarf die exakte `PAIRING_REQUIRED`-Request-ID anzeigen.
|
||||
4. **Verifizieren:** Nach externer Pairing-Freigabe Endpoint, Device, Rolle,
|
||||
Scopes und Capabilities erneut prüfen.
|
||||
5. **Read-only-Inventar:** Agenten, Agent-Dateien, Modelle, Cron Jobs und weitere
|
||||
beworbene Ressourcen live lesen.
|
||||
6. **Übernehmen:** Live-Inventar zurückgeben und nur Profilzustand,
|
||||
Capability-Hash und Adoptionszeitpunkte persistieren. Nexus kopiert keine
|
||||
Agent-Dateien, Cron Jobs, Channels, Nodes, Modelle oder
|
||||
Provider-Credentials.
|
||||
7. **Verwaltung freigeben:** In einer separaten, sichtbaren Aktion
|
||||
`operator.read` plus die tatsächlich benötigten Adminrechte anfordern. Die
|
||||
Scope-Erweiterung benötigt eine neue OpenClaw-Pairing-Freigabe. Erst danach
|
||||
kann die lokale `ManagementEnabled`-Freigabe aktiv werden.
|
||||
|
||||
Eine bereits mit Admin-Scope verbundene, aber noch nicht adoptierte Instanz
|
||||
erfüllt den read-only-first Vertrag nicht und kann nicht still übernommen
|
||||
werden.
|
||||
|
||||
## Setup-API
|
||||
|
||||
Alle Routen sind owner-only und für Mutationen rate-limited:
|
||||
|
||||
| Methode | Pfad | Zweck |
|
||||
|---|---|---|
|
||||
| `GET` | `/api/v1/openclaw/setup` | Profil-, Pairing-, Trust-, Scope- und Adoptionsstatus |
|
||||
| `POST` | `/api/v1/openclaw/setup/discover` | Ausschließlich bekannte Kandidaten ermitteln |
|
||||
| `POST` | `/api/v1/openclaw/setup/probe` | Endpoint und Vertrauensvertrag ohne Adoption prüfen |
|
||||
| `POST` | `/api/v1/openclaw/setup/attach` | Read-only-Verbindung mit flüchtigem Bootstrap-Secret beginnen |
|
||||
| `POST` | `/api/v1/openclaw/setup/verify` | Pairing, Scopes, Version und Capabilities neu verifizieren |
|
||||
| `POST` | `/api/v1/openclaw/setup/adopt` | Read-only-Live-Inventar und Fingerprints übernehmen |
|
||||
| `POST` | `/api/v1/openclaw/setup/management` | Bewussten Management-Scope-Upgrade starten oder bestätigen |
|
||||
| `DELETE` | `/api/v1/openclaw/setup/connection` | Bestätigt detachieren |
|
||||
|
||||
Detach verlangt den bestätigten Endpoint und die Device-ID. Nexus entfernt das
|
||||
`primary`-Profil, schließt den aktiven Socket, deaktiviert das lokale
|
||||
Management-Gate und entfernt den an diese Verbindung gebundenen Device-Token.
|
||||
Der langfristige Nexus-Device-Key bleibt bestehen. Ein separat konfiguriertes
|
||||
Bootstrap-Secret muss der Operator weiterhin an dessen serverseitiger Quelle
|
||||
entfernen.
|
||||
|
||||
## Offizieller OpenClaw-Wizard
|
||||
|
||||
Für ein erreichbares neues OpenClaw rendert Nexus den offiziellen Gateway-
|
||||
Wizard, statt Installations- oder Migrationslogik nachzubauen:
|
||||
|
||||
| Methode | Pfad | OpenClaw-RPC |
|
||||
|---|---|---|
|
||||
| `POST` | `/api/v1/openclaw/setup/wizard/start` | `wizard.start` |
|
||||
| `POST` | `/api/v1/openclaw/setup/wizard/next` | `wizard.next` |
|
||||
| `GET` | `/api/v1/openclaw/setup/wizard/{sessionId}` | `wizard.status` |
|
||||
| `POST` | `/api/v1/openclaw/setup/wizard/{sessionId}/cancel` | `wizard.cancel` |
|
||||
|
||||
Der Wizard ist nur für eine verbundene, management-freigegebene Instanz mit
|
||||
beworbenen `wizard.*`-Methoden und `operator.admin` verfügbar. Nexus erzwingt
|
||||
den Setup-Flow mit `installDaemon=false`, redigiert sensible Schritte und
|
||||
akzeptiert keine Secret-Antwort aus einem unsicheren Browserfeld. Nexus
|
||||
installiert keine Pakete, startet keine SSH-Installation und führt weder
|
||||
`migrate` noch `doctor --fix` automatisch aus.
|
||||
|
||||
## Runtime-, Config- und Cron-Autorität
|
||||
|
||||
Nach Adoption liest Nexus OpenClaw-Ressourcen weiterhin live:
|
||||
|
||||
- Agenten über `agents.list`;
|
||||
- erlaubte Bootstrap-Dateien über `agents.files.list/get/set`;
|
||||
- weitere Workspace-Dateien read-only über
|
||||
`agents.workspace.list/get`;
|
||||
- Konfiguration über `config.schema.lookup`, `config.get` und `config.patch`;
|
||||
- Cron Jobs und deren Run-Historie über die typisierten `cron.*`-RPCs; und
|
||||
- Modell-Authentifizierungsstatus über eine redigierte
|
||||
`models.authStatus`-Projektion.
|
||||
|
||||
Datei- und Config-Schreibvorgänge re-readen vor der Mutation, lehnen Drift mit
|
||||
`409` ab und verifizieren das Ergebnis anschließend durch erneutes Lesen. Die
|
||||
UI behauptet keinen Hot Reload, wenn OpenClaw ihn nicht ausdrücklich bestätigt.
|
||||
Secrets werden nie aus einem Config-Snapshot oder Modell-Authstatus projiziert.
|
||||
|
||||
## Mutation correlation und Idempotenz
|
||||
|
||||
Der Backend-Layer leitet oder akzeptiert:
|
||||
|
||||
- `Idempotency-Key`;
|
||||
- `X-Correlation-ID`;
|
||||
- W3C `traceparent`; und
|
||||
- den authentifizierten Actor (`sub`).
|
||||
|
||||
Actor, Ziel, Operationszustand, Intent-Fingerprint und ein SHA-256-Hash des
|
||||
Idempotency Keys werden lokal ohne Prompts, Dateiinhalt, Tool-Argumente,
|
||||
ungefilterte Ergebnisse oder Credentials auditiert. Unterstützt das gepinnte
|
||||
OpenClaw-Schema kein `idempotencyKey`, dedupliziert Nexus lokal und sendet kein
|
||||
undokumentiertes Feld. Ein unklarer `in_doubt`-Zustand wird nicht automatisch
|
||||
wiederholt.
|
||||
|
||||
Der JSONL-Ledger ist ein Single-Writer-Vertrag für genau eine Nexus-API-Instanz.
|
||||
Mehrere Replikas benötigen vor Schreibfreigabe einen gemeinsamen
|
||||
transaktionalen Ledger.
|
||||
|
||||
## Event- und Run-Projektionen
|
||||
|
||||
`GET /api/v1/openclaw/events` ist eine authentifizierte SSE-Projektion über den
|
||||
begrenzten Gateway-Eventpuffer. Sie unterstützt `Last-Event-ID`, Connection-,
|
||||
Heartbeat- und Gap-Signale und redigiert Payloads vor der Browsergrenze. Ein
|
||||
Cursor außerhalb des Puffers erzwingt einen autoritativen Refresh.
|
||||
|
||||
Nexus persistiert Durable Runs und ihre Transitionen in PostgreSQL, ohne
|
||||
OpenClaws Runtimezustand zu übernehmen. Start, exakter Stop und korrelierter
|
||||
Retry sind implementiert. Same-run Resume bleibt explizit `unsupported`, bis
|
||||
der gepinnte Gateway-Vertrag einen belegten RPC bereitstellt.
|
||||
|
||||
## Abnahmegrenze
|
||||
|
||||
Lokale Contract-, Backend-, Frontend- und Browserprüfungen können Routing,
|
||||
Validierung, Redaction, Least Privilege, Hashkonflikte, Idempotenz und
|
||||
UI-Zustände belegen. Sie beweisen nicht:
|
||||
|
||||
- eine offiziell unterstützte externe Nexus-/Generic-Client-ID;
|
||||
- eine reale Remote-Pairing- und Scope-Upgrade-Sequenz;
|
||||
- Live-Schreibvorgänge gegen eindeutig benannte Testobjekte auf Baos OpenClaw;
|
||||
oder
|
||||
- einen vollständigen `Nexus -> OpenClaw -> OpenAI -> Nexus`-Lauf.
|
||||
|
||||
Diese Nachweise sind verpflichtende Produktionsblocker. Live-Schreibtests,
|
||||
Pairing-Freigaben, OpenClaw-Patches, Deployment und Zugriffe außerhalb von
|
||||
Baos ausdrücklich freigegebenen Ressourcen gehören nicht zu diesem
|
||||
Implementierungscheckpoint.
|
||||
|
||||
## Offizielle Protokollquellen
|
||||
|
||||
- <https://github.com/openclaw/openclaw/blob/v2026.7.1/packages/gateway-protocol/src/client-info.ts>
|
||||
- <https://github.com/openclaw/openclaw/blob/v2026.7.1/docs/gateway/protocol.md>
|
||||
- <https://docs.openclaw.ai/gateway/operator-scopes>
|
||||
- <https://docs.openclaw.ai/gateway/configuration>
|
||||
- <https://docs.openclaw.ai/reference/wizard>
|
||||
- <https://docs.openclaw.ai/cli/cron>
|
||||
@@ -0,0 +1,224 @@
|
||||
# Nexus – Projektanalyse
|
||||
|
||||
**Analysestand:** 2026-07-26
|
||||
**Repository:** `https://git.noveria.net/bao/nexus.git`
|
||||
**Branch / Commit:** `main` / `3bc7622977f4a6c2f2e98ab4aa856a2e45c3cf49`
|
||||
**Version im Repository:** `0.2.56` (`v0.2.56-91-g3bc7622`)
|
||||
**Urteil:** Gute technische Grundlage, aber wegen zweier P0-Zugriffskontrollrisiken
|
||||
und schwerer Frontend-/Responsive-Brüche aktuell nicht produktionsreif.
|
||||
|
||||
## 1. Kurzfassung
|
||||
|
||||
Nexus ist deutlich mehr als ein UI-Prototyp: Das Repository enthält ein
|
||||
geschichtetes ASP.NET-Core-Backend, eine persistente PostgreSQL-Domäne,
|
||||
OpenClaw-Adapter, eine strukturierte Agent-Task-Bridge, eine Vue-Anwendung sowie
|
||||
CI-, Deployment-, Backup- und Rollback-Workflows. Die Backend- und
|
||||
Operations-Basis ist der stärkste Teil des Projekts.
|
||||
|
||||
Die aktuelle Produktqualität wird jedoch von vier systemischen Problemen
|
||||
bestimmt:
|
||||
|
||||
1. Die API hat keine globale Authentifizierungsanforderung. Mehrere Controller
|
||||
sind dadurch ohne Token erreichbar; darunter befindet sich ein mutierender
|
||||
Agent-Command-Endpunkt.
|
||||
2. Die öffentlich weitergeleitete Bridge akzeptiert eine bekannte
|
||||
`X-Agent-Id` allein als Identitätsnachweis.
|
||||
3. Das Frontend besteht aus zwei visuell und technisch auseinanderlaufenden
|
||||
Shells. Dashboard-Navigation, Dateninitialisierung und mobile Breakpoints
|
||||
sind nicht konsistent.
|
||||
4. Die Testabdeckung ist im Backend fokussiert, im Frontend mit einer
|
||||
Testdatei aber zu schmal für 18 registrierte Seiten und mehrere kritische
|
||||
Interaktionspfade.
|
||||
|
||||
Die vollständige Bewertung steht in
|
||||
[`PROJECT_EVALUATION_2026-07-26.md`](PROJECT_EVALUATION_2026-07-26.md), das
|
||||
visuelle Seitenaudit in
|
||||
[`audits/2026-07-26/PAGE_AUDIT.md`](audits/2026-07-26/PAGE_AUDIT.md), und die
|
||||
Zugriffskontrollanalyse in
|
||||
[`SECURITY_SPOT_CHECK_2026-07-26.md`](SECURITY_SPOT_CHECK_2026-07-26.md).
|
||||
|
||||
## 2. Technischer Bestand
|
||||
|
||||
| Bereich | Befund |
|
||||
|---|---|
|
||||
| Umfang | 253 getrackte Dateien |
|
||||
| Frontend | Vue 3, TypeScript, Pinia, Vue Router, Vite, Tailwind 4, Lucide |
|
||||
| Backend | ASP.NET Core 10, EF Core 10, PostgreSQL 17 |
|
||||
| Integration | `IAgentRuntime`, OpenClaw-Adapter, MCP- und HTTP-Task-Bridge |
|
||||
| Persistenz | 9 fachliche EF-Core-Migrationen |
|
||||
| Betrieb | Docker Compose, Nginx, Traefik, Gitea Actions |
|
||||
| Backend-Code | 107 C#-Dateien plus 12 C#-Testdateien |
|
||||
| Frontend-Code | 87 Dateien unter `frontend/src`, davon 51 Vue-Dateien |
|
||||
| Frontend-Tests | 1 Testdatei mit 2 Tests |
|
||||
| CI-Baseline | .NET 10, Node.js 24, pnpm 10.12.1 |
|
||||
|
||||
## 3. Architektur
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
UI["Vue SPA<br/>Routes, Views, Pinia"] -->|JWT / REST / SSE| API["ASP.NET Core API"]
|
||||
API --> CTRL["Controller"]
|
||||
CTRL --> SVC["Domain and application services"]
|
||||
SVC --> REPO["Repositories / EF Core"]
|
||||
REPO --> DB["PostgreSQL"]
|
||||
SVC --> RUNTIME["IAgentRuntime"]
|
||||
RUNTIME --> OPENCLAW["OpenClaw adapter"]
|
||||
GATEWAY["Trusted agent gateway"] -->|Bridge commands| BRIDGE["GatewayBridgeController"]
|
||||
BRIDGE --> TASKBRIDGE["ITaskBridgeService"]
|
||||
TASKBRIDGE --> REPO
|
||||
```
|
||||
|
||||
### Backend
|
||||
|
||||
Positiv:
|
||||
|
||||
- Controller, Services und Repositories sind klar getrennt.
|
||||
- Task-Mutationen werden über eine strukturierte
|
||||
`ITaskBridgeService`-Fassade gebündelt.
|
||||
- EF-Core-Migrationen, Health Checks und DTOs sind vorhanden.
|
||||
- JWT-Prüfung validiert Signatur, Issuer, Audience und Laufzeit.
|
||||
- Refresh Tokens werden rotiert und gehasht gespeichert.
|
||||
- Rate Limiting, CSP und weitere Security Header sind eingerichtet.
|
||||
|
||||
Risiken:
|
||||
|
||||
- `AddAuthorization()` besitzt keine Fallback Policy. Sicherheit hängt damit
|
||||
vollständig von jedem einzelnen `[Authorize]`-Attribut ab.
|
||||
- Das Backend targetiert `net10.0`, aber es gibt kein `global.json`, das die
|
||||
erwartete SDK-Familie lokal festlegt.
|
||||
- Produktionspfade für Workspace-Mounts und Deployment sind stark an einen
|
||||
konkreten Host gekoppelt.
|
||||
- Das einmalige Bootstrap-Passwort wird in den Prozess-Logs ausgegeben. Das ist
|
||||
operativ bequem, erzeugt aber einen sensiblen Log-Artefakt.
|
||||
|
||||
### Frontend
|
||||
|
||||
Positiv:
|
||||
|
||||
- API-Clients, Stores, Mapper, Views und UI-Komponenten sind grundsätzlich
|
||||
getrennt.
|
||||
- Es gibt eigenständige Oberflächen für Tasks, Agenten, Memory, Dokumente,
|
||||
Security, Incidents, Calendar, Notifications und Settings.
|
||||
- Settings und Teile der Legacy-Shell verhalten sich auf kleinen Viewports
|
||||
bereits brauchbar.
|
||||
|
||||
Risiken:
|
||||
|
||||
- `/dashboard` verwendet `NexusLayout` und `FlowBoard`; fast alle anderen
|
||||
Seiten verwenden `AppSidebar`, `AppHeader` und teils `ModuleView`. Das führt
|
||||
zu einem sichtbaren Design- und Navigationsbruch.
|
||||
- Die neue Sidebar verlinkt `/orchestration`, `/research`, `/hosts` und
|
||||
`/costs`, obwohl keine dieser Routen registriert ist. Der Wildcard-Redirect
|
||||
maskiert den Fehler und führt zurück zum Dashboard.
|
||||
- `AgentDetailView` navigiert über `/team`; auch diese Route existiert nicht.
|
||||
- Der Operations Store wird in `App.vue` nur beim ersten Mount aktualisiert,
|
||||
wenn zu diesem Zeitpunkt bereits Authentifizierung vorliegt. Nach normalem
|
||||
Login bleiben Projects, Models und Activity zunächst leer, bis der Nutzer
|
||||
manuell „Refresh“ auswählt.
|
||||
- `liveSync.ts` und `live-sync.ts` implementieren denselben Pinia-Store mit
|
||||
derselben ID. Das ist ein unnötiger Drift- und Importfehler-Risikofaktor.
|
||||
- Task-Daten unterstützen `Critical`; die Prioritätsauswahl in Task Board und
|
||||
Task Detail bietet aber nur High, Medium und Low. Ein bestehender
|
||||
`Critical`-Wert erscheint deshalb als leere Auswahl.
|
||||
- Mehrere sichtbare Controls sind Platzhalter: Suche, „Ask Iris“ und Logout in
|
||||
der neuen Dashboard-Shell haben keine vollständige Aktion.
|
||||
- Zahlreiche Icon-Buttons besitzen keinen zugänglichen Namen.
|
||||
|
||||
## 4. Daten- und Produktfluss
|
||||
|
||||
Der zentrale Betriebsfluss ist sinnvoll modelliert:
|
||||
|
||||
1. Das Frontend lädt einen Operations-Snapshot und spezialisierte
|
||||
Detailressourcen.
|
||||
2. Nutzer ändern Projekte und Tasks über authentifizierte API-Routen.
|
||||
3. Agenten sollen strukturierte Commands über die Bridge an
|
||||
`ITaskBridgeService` senden.
|
||||
4. Services validieren Zustände und schreiben über Repositories in PostgreSQL.
|
||||
5. Activity- und Live-Updates werden wieder in der Oberfläche dargestellt.
|
||||
|
||||
Die Schwäche liegt nicht im Domänenfluss, sondern an seinen Grenzen:
|
||||
Browser-Authentifizierung, Service-Authentifizierung und UI-Initialisierung
|
||||
sind nicht durchgehend als verbindliche Verträge umgesetzt.
|
||||
|
||||
## 5. Qualität nach Bereich
|
||||
|
||||
### Architektur und Wartbarkeit
|
||||
|
||||
Die Backend-Struktur ist nachvollziehbar und erweiterbar. Der aktuelle
|
||||
Frontend-Zustand deutet dagegen auf eine laufende V2-Migration ohne klares
|
||||
Migrationsende hin. Zwei Shells, tote Routen, ein verwaistes `TeamView` und
|
||||
doppelte Stores erhöhen die Änderungs- und Regressionkosten.
|
||||
|
||||
### Tests
|
||||
|
||||
Die zwölf Backend-Testdateien decken insbesondere Auth-, Task-, Bridge- und
|
||||
MCP-Verhalten ab. Die Frontend-Suite besteht aktuell aus einer Testdatei mit
|
||||
zwei Tests. Es fehlen mindestens:
|
||||
|
||||
- Router- und Navigationsverträge,
|
||||
- Store-Hydration nach Login,
|
||||
- Critical-Priority-Roundtrip,
|
||||
- Keyboard-/Accessible-Name-Prüfungen,
|
||||
- Komponenten- und Viewport-Regressionstests,
|
||||
- visuelle Smoke-Checks für alle Kernrouten.
|
||||
|
||||
### CI/CD und Betrieb
|
||||
|
||||
Die Gitea-Pipeline ist für die Projektgröße gut ausgebaut:
|
||||
|
||||
- getrennte Backend-, Frontend- und Security-Jobs,
|
||||
- Build und Tests vor Deployment,
|
||||
- serielles Production Deployment,
|
||||
- separate Backup- und Rollback-Workflows.
|
||||
|
||||
Der Security-Job sucht jedoch nur heuristisch nach Secrets. Er ersetzt weder
|
||||
Dependency-/Container-Scanning noch eine Zugriffskontrollprüfung. Außerdem
|
||||
deployt ein grüner Push auf `main` automatisch; deshalb müssen P0-Sicherheits-
|
||||
und UI-Regressionsgates vor einem Merge verbindlich sein.
|
||||
|
||||
### Dokumentation
|
||||
|
||||
README, Phasen-, Architektur- und Betriebsdokumentation sind umfangreich, aber
|
||||
teilweise nicht mehr synchron mit dem Code:
|
||||
|
||||
- README behauptet Authentifizierung für alle `/api/v1`-Operationsrouten, die
|
||||
Controller-Attribute erfüllen diesen Vertrag nicht.
|
||||
- Frontend-Routen und Komponentenbeschreibungen spiegeln die V2-/Legacy-Mischung
|
||||
nicht vollständig.
|
||||
- `VERSION` ist `0.2.56`, das Frontend-Paket meldet `0.1.0`, und der aktuelle
|
||||
Commit liegt 91 Commits hinter dem letzten Tag.
|
||||
|
||||
## 6. Validierungsstand
|
||||
|
||||
Erfolgreich ausgeführt:
|
||||
|
||||
- `pnpm test`: 1 Datei, 2 Tests bestanden.
|
||||
- `pnpm build`: TypeScript-/Vue-Typecheck und Vite-Production-Build bestanden.
|
||||
- `dotnet test` im offiziellen .NET-10-SDK-Container: 189 Tests bestanden,
|
||||
0 fehlgeschlagen, 0 übersprungen.
|
||||
- Browser-Audit aller 18 registrierten Seiten mit repräsentativen lokalen
|
||||
API-Fixtures.
|
||||
- Responsive Sichtprüfung bei 320, 375, 768, 1024, 1440 und 1920 Pixeln.
|
||||
|
||||
Nicht als bestanden gewertet:
|
||||
|
||||
- Kein Live-End-to-End-Test gegen PostgreSQL, OpenClaw, SSE und die
|
||||
Produktions-Proxykette.
|
||||
- Kein Penetrationstest und keine vollständige WCAG-Konformitätsprüfung.
|
||||
|
||||
Der Windows-Host stellt direkt nur .NET SDK 9.0.301 bereit. Der erfolgreiche
|
||||
Backend-Lauf erfolgte deshalb reproduzierbar im offiziellen
|
||||
`mcr.microsoft.com/dotnet/sdk:10.0`-Container.
|
||||
|
||||
## 7. Empfehlung
|
||||
|
||||
Nexus sollte nicht neu gebaut werden. Die vorhandene Backend- und
|
||||
Operationsbasis ist wertvoll. Sinnvoll ist eine fokussierte
|
||||
Stabilisierungsphase:
|
||||
|
||||
1. Zugriffskontrollen schließen und durch negative Tests absichern.
|
||||
2. Eine einzige Frontend-Shell und eine einzige kanonische Navigation festlegen.
|
||||
3. Login-Hydration, tote Routen, Critical-Priority und doppelte Stores beheben.
|
||||
4. Dashboard und Task Board für 375–1024 px strukturell neu ordnen.
|
||||
5. Frontend-Tests und visuelle Route-/Breakpoint-Gates etablieren.
|
||||
6. README, Versionierung und SDK-Pinning auf den tatsächlichen Stand bringen.
|
||||
@@ -0,0 +1,132 @@
|
||||
# Nexus – Projektevaluation
|
||||
|
||||
**Datum:** 2026-07-26
|
||||
**Commit:** `3bc7622977f4a6c2f2e98ab4aa856a2e45c3cf49`
|
||||
**Gesamtwertung:** **54 / 100**
|
||||
**Release-Entscheidung:** **No-Go für öffentlich erreichbare Produktion**, bis
|
||||
die P0-Zugriffskontrollen und die kritischen Navigations-/Responsive-Defekte
|
||||
geschlossen und regressionsgetestet sind.
|
||||
|
||||
## Bewertungsmodell
|
||||
|
||||
Die Gesamtwertung kombiniert Code- und Architekturprüfung, Test-/Build-Evidenz,
|
||||
Security-Spot-Check, vollständiges Route-Audit und responsive Sichtprüfung.
|
||||
Die Bewertung misst Release-Reife, nicht nur Code-Menge oder Feature-Umfang.
|
||||
|
||||
Validiert wurden 189 grüne Backend-Tests im offiziellen .NET-10-SDK-Container,
|
||||
2 grüne Frontend-Tests und ein erfolgreicher Frontend-Production-Build.
|
||||
|
||||
| Bereich | Gewicht | Wertung | Begründung |
|
||||
|---|---:|---:|---|
|
||||
| Architektur und Modularität | 15 % | 74 | Starke Backend-Schichtung und Integrationsabstraktionen; Frontend-Migration ohne klare Grenze |
|
||||
| Backend und Domäne | 15 % | 78 | Reife Services, Repositories, Migrationen und Task-Bridge |
|
||||
| Frontend Engineering | 15 % | 50 | Typisiert und buildbar, aber zwei Shells, tote Routen, doppelte Stores und Hydration-Fehler |
|
||||
| Security | 20 % | 30 | Gute kryptografische Bausteine, aber zwei strukturelle P0-Zugriffskontrolllücken |
|
||||
| UX und Product Design | 15 % | 41 | Gute Produktidentität, aber starke Kontrast-, Kohärenz- und Responsive-Probleme |
|
||||
| Tests und QA | 10 % | 55 | Fokussierte Backend-Tests; Frontend-Suite für 18 Seiten deutlich zu klein |
|
||||
| Delivery und Operations | 5 % | 82 | Gute CI/CD-, Backup- und Rollback-Basis |
|
||||
| Dokumentation und Wartbarkeit | 5 % | 48 | Umfangreich, aber wichtige Auth-, Route- und Versionsangaben sind veraltet |
|
||||
|
||||
Gewichtete, gerundete Gesamtwertung: **54 / 100**.
|
||||
|
||||
## Lunara Design Evaluation
|
||||
|
||||
**Briefqualität:** Nicht anwendbar – geprüft wurde eine bestehende
|
||||
Implementierung ohne neu gelieferten Design-Brief.
|
||||
**Qualitätsgate:** **41 / 100 – nicht bestanden**.
|
||||
**Evidenz:** [`audits/2026-07-26/PAGE_AUDIT.md`](audits/2026-07-26/PAGE_AUDIT.md)
|
||||
und die 29 zugehörigen Screenshots.
|
||||
|
||||
| # | Kategorie | 0–5 | Begründung |
|
||||
|---:|---|---:|---|
|
||||
| 1 | Produktspezifität | 4 | Klare Mission-Control-Identität und agentenspezifische Inhalte |
|
||||
| 2 | Informationshierarchie | 2 | Dichte Boards, sehr kleine Texte und konkurrierende Panels |
|
||||
| 3 | Aufgaben- und Handlungsklarheit | 2 | Mehrere Platzhalteraktionen und unklare Leerzustände |
|
||||
| 4 | Claim-/Evidenzintegrität | 2 | Security-Darstellung und README überzeichnen den tatsächlichen Schutz |
|
||||
| 5 | Komposition und Spacing | 2 | Überlappungen im Dashboard, zu große Leerflächen in Detailseiten |
|
||||
| 6 | Typografie | 2 | Wiederholt zu klein und zu schwach gewichtet |
|
||||
| 7 | Kontrast und Lesbarkeit | 1 | Breites systemisches Problem in Texten und Controls |
|
||||
| 8 | Iconografie | 3 | Lucide-Basis ist passend; Emoji und unlabeled Icons brechen die Konsistenz |
|
||||
| 9 | Komponenten- und Shell-Kohärenz | 1 | V2-Dashboard und Legacy-App wirken wie zwei Produkte |
|
||||
| 10 | Interaktionszustände | 2 | Basiszustände vorhanden, sichtbare Aktionen teils inert |
|
||||
| 11 | Motion-Disziplin | 3 | Keine übermäßige Animation; Statusmotion grundsätzlich zurückhaltend |
|
||||
| 12 | Responsive-Verhalten | 1 | Dashboard 375–1024 px kritisch defekt; Task Board mobil unzureichend |
|
||||
| 13 | Input-Anpassung | 2 | Settings brauchbar; Chat/Board und Touch-Flows schwach |
|
||||
| 14 | Semantik, Keyboard, Accessibility | 1 | Clickbare Articles, unlabeled Buttons, kleine Targets und Kontrast |
|
||||
| 15 | Kognitive Last und Recovery | 2 | Hohe Informationsdichte, versteckte Redirects, schwache Recovery |
|
||||
| 16 | Sprache und Content-Konsistenz | 2 | Deutsch/Englisch-Mix und uneinheitliche Mikrotexte |
|
||||
| 17 | Loading, Empty und Error | 2 | Teilweise vorhanden, aber leere Module und fehlende nächste Aktionen |
|
||||
| 18 | Laufzeitstabilität | 3 | Build stabil; Router- und Hydrationfehler bleiben |
|
||||
| 19 | Visual-QA-Reife | 1 | Mehrere offensichtliche Breakpoint-Regressionen |
|
||||
| 20 | Eigenständigkeit / Anti-Slop | 3 | Eigenständige Richtung, aber unfertige generische Module |
|
||||
| | **Gesamt** | **41 / 100** | **Hard Blocker vorhanden** |
|
||||
|
||||
## Stärken, die erhalten werden sollten
|
||||
|
||||
- Die Agent-/Task-Domäne ist konkret und nicht generisch.
|
||||
- Backend-Schichten und Runtime-Abstraktion bieten eine belastbare
|
||||
Weiterentwicklungsbasis.
|
||||
- Task-Bridge und Statusvalidierung sind ein sinnvoller Integrationskern.
|
||||
- Deployment, Backup und Rollback sind nicht nur als Wunsch, sondern als
|
||||
Workflows vorhanden.
|
||||
- Mehrere Detailseiten besitzen bereits eine brauchbare Informationsarchitektur.
|
||||
- Die violette Galaxy-Richtung des Dashboards ist grundsätzlich
|
||||
wiedererkennbar; sie muss responsiv und systemweit konsistent umgesetzt
|
||||
werden, nicht verworfen.
|
||||
|
||||
## Release-Blocker und Roadmap
|
||||
|
||||
### P0 – vor jeder öffentlichen Freigabe
|
||||
|
||||
- Globale authenticated-by-default Authorization Policy einführen; öffentliche
|
||||
Routen explizit markieren.
|
||||
- Agent-Command-Endpunkt rollen- oder policybasiert schützen.
|
||||
- Bridge nur mit stark authentifiziertem Service-Context zulassen; öffentliche
|
||||
Caller-Header am Proxy entfernen.
|
||||
- Negative End-to-End-Tests über die reale Proxygrenze hinzufügen.
|
||||
- Dashboard-Navigation auf registrierte Ziele begrenzen.
|
||||
- Dashboard bei 375, 768 und 1024 px ohne Überlappung, Abschneiden oder
|
||||
unzugängliche Kernaktion ausliefern.
|
||||
|
||||
### P1 – Stabilisierungsmeilenstein
|
||||
|
||||
- Eine kanonische App-Shell und ein gemeinsames Navigationsmodell festlegen.
|
||||
- Store-Hydration nach Login korrigieren.
|
||||
- `/team`-Backlink, tote V2-Links und Wildcard-Maskierung korrigieren.
|
||||
- `Critical` über Datenmodell, Mapper, Formulare und Tests konsistent
|
||||
roundtrip-fähig machen.
|
||||
- Doppelte Live-Sync-Store-Dateien konsolidieren.
|
||||
- Task Board für Mobilgeräte als Status-Segmente oder Liste gestalten.
|
||||
- Route-, Store-, Accessibility- und Responsive-Regressionstests ergänzen.
|
||||
|
||||
### P2 – Qualitäts- und Wartbarkeitspass
|
||||
|
||||
- Kontrast, Mindestschriftgrößen, Focus States und Accessible Names
|
||||
systematisch korrigieren.
|
||||
- Projects, Models, Activity und Chat aus dem generischen ModuleView lösen.
|
||||
- README, Route-Dokumentation, Versionen und Screenshots aktualisieren.
|
||||
- .NET SDK über `global.json` pinnen.
|
||||
- Produktionspfade konfigurierbar machen.
|
||||
- Bootstrap-Secrets aus persistenten Logs entfernen.
|
||||
|
||||
## Definition of Done für die nächste Evaluation
|
||||
|
||||
- Alle P0-Punkte sind in Code und Tests geschlossen.
|
||||
- `dotnet test` läuft mit .NET 10 vollständig grün.
|
||||
- `pnpm test` und `pnpm build` sind grün.
|
||||
- Jede registrierte Route hat einen automatisierten Smoke-Test.
|
||||
- Kein Navigationseintrag führt über den Wildcard-Redirect zurück.
|
||||
- Login lädt alle benötigten Stores ohne manuellen Refresh.
|
||||
- Dashboard und Task Board bestehen visuelle Prüfungen bei 375, 768, 1024,
|
||||
1440 und 1920 px.
|
||||
- Keyboard-Navigation, Accessible Names und Kontrast der Kernflows sind
|
||||
nachweisbar geprüft.
|
||||
- Ein Live-Smoke-Test bestätigt PostgreSQL, OpenClaw, SSE und Proxyverhalten.
|
||||
|
||||
## Schlussurteil
|
||||
|
||||
Nexus hat eine ernstzunehmende Backend- und Betriebsbasis und sollte
|
||||
weiterentwickelt, nicht ersetzt werden. Der nächste sinnvolle Schritt ist aber
|
||||
keine neue Feature-Runde. Zuerst braucht das Projekt eine kurze,
|
||||
evidenzgetriebene Stabilisierung, die Zugriffskontrolle, UI-Konvergenz,
|
||||
Responsive-Verhalten und Frontend-Regressionsschutz gemeinsam schließt.
|
||||
@@ -0,0 +1,185 @@
|
||||
# Nexus QA Automation
|
||||
|
||||
These checks are development and CI artifacts. They add no production
|
||||
dependency and must be run against an isolated Nexus test database unless a
|
||||
section explicitly says otherwise.
|
||||
|
||||
This document describes what each artifact can prove. A script being present,
|
||||
or its static preflight passing, is not acceptance evidence for a live
|
||||
OpenClaw, PostgreSQL, browser, or load-test boundary. Archive the command,
|
||||
versions, sanitized output, dataset provenance, and timestamp for every
|
||||
acceptance run.
|
||||
|
||||
## Task Board load gate
|
||||
|
||||
The full k6 profile holds ten virtual users for two minutes and fails when:
|
||||
|
||||
- initial Task Board request p95 is `>= 500 ms`;
|
||||
- Done-cursor request p95 is `>= 300 ms`;
|
||||
- initial or Done HTTP failures are `>= 1%`;
|
||||
- board-level failures are `>= 1%`;
|
||||
- board-contract failures are `>= 1%`; or
|
||||
- the acceptance dataset does not expose a Done continuation cursor; or
|
||||
- successful checks fall to `<= 99%`.
|
||||
|
||||
Acceptance preconditions are deliberately external to the load generator:
|
||||
|
||||
- use a disposable PostgreSQL database with a recorded seed of 1,000 Tasks and
|
||||
10,000 Activities;
|
||||
- include more than 50 Done Tasks so the cursor path receives samples;
|
||||
- record the exact seed command or fixture revision and verify row counts
|
||||
before k6; and
|
||||
- warm the service before capturing the two-minute result.
|
||||
|
||||
From the repository root:
|
||||
|
||||
```powershell
|
||||
$env:NEXUS_BASE_URL = "http://127.0.0.1:18880"
|
||||
$env:NEXUS_BEARER_TOKEN = "<fresh JWT>"
|
||||
k6 run scripts/qa/task-board.k6.js
|
||||
```
|
||||
|
||||
`NEXUS_API_KEY` can replace the bearer token for this authenticated read-only
|
||||
test. A ten-second one-VU diagnostic is available with
|
||||
`NEXUS_K6_SMOKE=1`; it is not acceptance evidence. The smoke profile does not
|
||||
require a Done cursor by default. `NEXUS_K6_REQUIRE_DONE_CURSOR=0` may also
|
||||
disable that gate for diagnostics, but any such run is non-acceptance.
|
||||
|
||||
Remote targets are blocked by default. An isolated remote target requires both
|
||||
`NEXUS_K6_ALLOW_REMOTE=1` and HTTPS. `NEXUS_INSECURE_TLS=1` is accepted only
|
||||
for loopback diagnostics. The base URL may not contain credentials, a path,
|
||||
query, or fragment.
|
||||
|
||||
### What k6 does not prove
|
||||
|
||||
- k6 cannot verify the 1,000/10,000 database row counts; preserve independent
|
||||
seed and count evidence.
|
||||
- `Server-Timing` proves only that the header exists. It does not prove the
|
||||
“at most three SQL statements” invariant.
|
||||
- Capture SQL-statement counts through a focused integration test or
|
||||
instrumented database trace, and archive
|
||||
`EXPLAIN (ANALYZE, BUFFERS)` for the initial and Done-cursor queries.
|
||||
- The “navigation until cards visible” p95 of 1.5 seconds is a browser budget,
|
||||
not an HTTP budget. It requires a repeated Playwright/browser performance
|
||||
run with the same recorded dataset. A functional Playwright pass or a k6
|
||||
result alone does not satisfy it.
|
||||
|
||||
## Agent-first Promptfoo cases
|
||||
|
||||
The cases run through Nexus `/api/v1/chat`, wait for the durable Protocol-v4
|
||||
run, and compare agent and proposal inventories before and after the run. They
|
||||
cover:
|
||||
|
||||
- literal observation of `nexus_propose_agent` plus matching proposal
|
||||
arguments;
|
||||
- attempted owner-approval bypass;
|
||||
- a server-rooted proposal after a workspace-traversal request; and
|
||||
- an explicit request to mutate OpenClaw without approval.
|
||||
|
||||
They intentionally create proposal-only records. Use a disposable database and
|
||||
a fresh owner JWT. Remote targets are blocked unless
|
||||
`NEXUS_EVAL_ALLOW_REMOTE=1` is explicitly set, and non-loopback targets must
|
||||
use HTTPS. Embedded URL credentials, paths, queries, and fragments are rejected.
|
||||
|
||||
The pinned configuration and provider can be validated without a token or live
|
||||
Nexus:
|
||||
|
||||
```powershell
|
||||
./scripts/qa/run-agent-first-evals.ps1 -ValidateOnly
|
||||
```
|
||||
|
||||
```powershell
|
||||
$env:NEXUS_EVAL_BASE_URL = "http://127.0.0.1:18880"
|
||||
$env:NEXUS_EVAL_BEARER_TOKEN = "<fresh owner JWT>"
|
||||
$env:NEXUS_EVAL_ALLOW_PROPOSALS = "1"
|
||||
./scripts/qa/run-agent-first-evals.ps1
|
||||
```
|
||||
|
||||
For the repeated release profile, use the same isolated fixture and run:
|
||||
|
||||
```powershell
|
||||
./scripts/qa/run-agent-first-evals.ps1 -Repeat 20
|
||||
```
|
||||
|
||||
The wrapper pins Promptfoo `0.121.19` without adding it to a production or
|
||||
frontend package manifest. Cases run serially because their durable
|
||||
before/after inventories must not overlap. Non-loopback targets require HTTPS.
|
||||
A successful run still leaves test proposals in the test database so their
|
||||
approval state can be inspected.
|
||||
|
||||
### Promptfoo evidence boundary
|
||||
|
||||
- Literal tool selection passes only when browser-safe Gateway history exposes
|
||||
`nexus_propose_agent`. A durable proposal is recorded separately and is not
|
||||
substituted as proof of a visible raw tool call.
|
||||
- The workspace case proves only that the resulting proposal path is under the
|
||||
server-advertised root, no new agent appears, and no dangerous mutation is
|
||||
visible in returned run history.
|
||||
- It cannot prove that a model or hidden tool never read a foreign filesystem
|
||||
path. Absence from redacted history is not evidence of absence. Server-side
|
||||
workspace-confinement, authorization, and audit tests remain mandatory.
|
||||
- One execution of four cases is not a statistically meaningful 95% tool- and
|
||||
argument-accuracy result. A release claim needs a recorded repeated run
|
||||
(at least 20 independent tool-selection samples, at least 19 correct) against
|
||||
a resettable isolated fixture. `-Repeat 20` repeats every case serially and
|
||||
therefore creates many proposal records; use it only with a resettable
|
||||
fixture. Promptfoo's default exit behavior is stricter and marks the command
|
||||
failed if any repeated case fails. The default one-repeat suite is a boundary
|
||||
regression gate, not that accuracy report.
|
||||
|
||||
## MCP 2.0 compatibility gate
|
||||
|
||||
The repository remains pinned to `ModelContextProtocol.AspNetCore` `1.4.1`.
|
||||
The default static gate verifies that pin plus the structured proposal-tool
|
||||
source/test markers and does not run those tests or need an SDK:
|
||||
|
||||
```powershell
|
||||
./scripts/qa/test-mcp2-compatibility.ps1
|
||||
```
|
||||
|
||||
With .NET SDK 10 installed, run the stable baseline:
|
||||
|
||||
```powershell
|
||||
./scripts/qa/test-mcp2-compatibility.ps1 -Mode Baseline
|
||||
```
|
||||
|
||||
The candidate mode first requires a green 1.4.1 baseline, then copies
|
||||
`backend/` and `backend-tests/` to a verified temporary directory, changes only
|
||||
that copy, restores the exact candidate and runs the backend test project:
|
||||
|
||||
```powershell
|
||||
./scripts/qa/test-mcp2-compatibility.ps1 `
|
||||
-Mode Candidate `
|
||||
-CandidateVersion "2.0.0"
|
||||
```
|
||||
|
||||
A preview or stable candidate can produce only an SDK compatibility-probe pass.
|
||||
It never opens the production promotion gate because this local probe does not
|
||||
exercise a real OpenClaw `tools/list`, external client identity, Streamable
|
||||
HTTP, or down-level negotiation. The original project file is hash-checked
|
||||
before and after the run and remains pinned to 1.4.1. A stable 2.x upgrade still
|
||||
requires live evidence against an isolated compatible OpenClaw plus a separate
|
||||
reviewed dependency change.
|
||||
|
||||
`Baseline` and `Candidate` report success when `dotnet test` exits successfully.
|
||||
Environment-gated Docker, Toxiproxy, and live OpenClaw tests can still be
|
||||
skipped; inspect and archive the test summary instead of describing the result
|
||||
as complete protocol compatibility.
|
||||
|
||||
## Local artifact preflight
|
||||
|
||||
The following checks are safe and do not contact Nexus, OpenClaw, Docker, or a
|
||||
k6 target. Promptfoo validation may download the pinned npm package when it is
|
||||
not already cached.
|
||||
|
||||
```powershell
|
||||
node --check scripts/qa/task-board.k6.js
|
||||
node --check scripts/qa/openclaw-ui-mock.mjs
|
||||
./scripts/qa/run-agent-first-evals.ps1 -ValidateOnly
|
||||
./scripts/qa/test-mcp2-compatibility.ps1 -Mode Pin
|
||||
```
|
||||
|
||||
PowerShell scripts should additionally be parsed with the PowerShell AST parser.
|
||||
These preflights validate syntax/configuration and static invariants only. They
|
||||
are not substitutes for k6, Promptfoo evaluation, browser budgets, database
|
||||
query-plan evidence, or live MCP/OpenClaw negotiation.
|
||||
@@ -0,0 +1,148 @@
|
||||
# Nexus – Security Spot Check
|
||||
|
||||
**Datum:** 2026-07-26
|
||||
**Commit:** `3bc7622977f4a6c2f2e98ab4aa856a2e45c3cf49`
|
||||
**Vertraulichkeit:** Intern
|
||||
**Scope:** Statische, risikoorientierte Prüfung von Authentifizierung,
|
||||
Autorisierung, Bridge-Identität, Proxyweiterleitung und Credential-Lifecycle.
|
||||
|
||||
> Dies ist kein vollständiger Security Scan und kein Penetrationstest. Die
|
||||
> Befunde sind codebasiert und müssen nach der Korrektur in einer realistischen
|
||||
> Proxy-/Containerumgebung negativ getestet werden.
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Zwei Zugriffskontrollbefunde blockieren eine verantwortbare
|
||||
Produktionsfreigabe:
|
||||
|
||||
- Die API verlangt nicht global Authentifizierung. Mehrere Controller sind
|
||||
dadurch standardmäßig öffentlich, darunter ein mutierender Agent-Endpunkt.
|
||||
- Die Agent-Bridge akzeptiert eine bekannte, vom Client gesetzte
|
||||
`X-Agent-Id` als ausreichenden Identitätsnachweis, während Nginx diesen Header
|
||||
öffentlich weiterleitet.
|
||||
|
||||
Beide Probleme sind strukturell. Einzelne zusätzliche `[Authorize]`-Attribute
|
||||
reichen nicht als dauerhafte Lösung; die sichere Voreinstellung muss
|
||||
„authenticated by default“ lauten.
|
||||
|
||||
## SEC-001 – Fehlende globale Authorization Policy
|
||||
|
||||
**Schweregrad:** P0 / kritisch
|
||||
**Konfidenz:** Hoch
|
||||
**Betroffene Grenze:** Öffentliches `/api/v1` -> Controller
|
||||
|
||||
### Evidenz
|
||||
|
||||
- `backend/Extensions/ServiceCollectionExtensions.cs` registriert
|
||||
`services.AddAuthorization()` ohne Fallback Policy.
|
||||
- `backend/Program.cs` mappt sämtliche Controller.
|
||||
- Mehrere Controller besitzen weder ein klassenweites `[Authorize]` noch
|
||||
vollständige methodenspezifische Attribute.
|
||||
- `backend/Controllers/AgentsController.cs` stellt
|
||||
`POST /api/v1/agents/{id}/command` nur unter Rate Limiting bereit; die Methode
|
||||
ruft den Agent Runtime Chat auf und schreibt einen Activity-Eintrag.
|
||||
- `frontend/nginx.conf` leitet `/api/` an das Backend weiter.
|
||||
- `README.md` behauptet gleichzeitig, alle `/api/v1`-Operationsrouten
|
||||
benötigten ein Access Token. Implementierung und dokumentierter Vertrag
|
||||
widersprechen sich.
|
||||
|
||||
### Auswirkung
|
||||
|
||||
Nicht authentifizierte Aufrufer können abhängig vom jeweiligen Controller
|
||||
Betriebsdaten lesen. Im schwerwiegendsten verifizierten Fall kann ein Aufrufer
|
||||
einem Agenten einen Command übermitteln und damit Laufzeit- und
|
||||
Ressourcennutzung auslösen.
|
||||
|
||||
### Korrektur
|
||||
|
||||
1. Eine globale Fallback Policy einführen, die einen authentifizierten Principal
|
||||
verlangt.
|
||||
2. Ausschließlich wirklich öffentliche Endpunkte explizit mit
|
||||
`[AllowAnonymous]` markieren, zum Beispiel Health und die notwendigen
|
||||
Login-/Refresh-Routen.
|
||||
3. Für mutierende oder sensitive Endpunkte zusätzlich Rollen-/Policy-Prüfungen
|
||||
definieren.
|
||||
4. Eine Controller-Inventur durchführen und jeden Endpunkt als public, owner,
|
||||
admin, agent-service oder internal klassifizieren.
|
||||
5. Negative Integrationstests hinzufügen: ohne Token muss jeder nicht
|
||||
freigegebene Endpunkt `401` oder `403` liefern.
|
||||
|
||||
## SEC-002 – Caller-controlled `X-Agent-Id` gilt als Authentifizierung
|
||||
|
||||
**Schweregrad:** P0 / kritisch
|
||||
**Konfidenz:** Hoch
|
||||
**Betroffene Grenze:** Öffentliches `/api/bridge` -> Agent-Service-Identität
|
||||
|
||||
### Evidenz
|
||||
|
||||
- `GatewayBridgeController.TryResolveAgentAsync` akzeptiert eine
|
||||
`X-Agent-Id`, sobald sie in der bekannten Actor-ID-Menge enthalten ist.
|
||||
- Ein API-Key oder ein kryptografisch authentifizierter Service Principal ist
|
||||
in diesem Pfad nicht erforderlich.
|
||||
- `frontend/nginx.conf` übernimmt `X-Agent-Id` direkt aus dem eingehenden
|
||||
Client-Header und leitet `/api/bridge/` weiter.
|
||||
- Die Bridge bietet lesende und mutierende Task-/Activity-/Handoff-Commands.
|
||||
- Bestehende Tests behandeln eine bekannte `X-Agent-Id` bewusst als
|
||||
erfolgreichen Authentifizierungsfall.
|
||||
|
||||
### Auswirkung
|
||||
|
||||
Wer eine gültige Agent-ID kennt oder errät, kann sich gegenüber der Bridge als
|
||||
dieser Agent ausgeben. Das gefährdet Task-Board-Integrität, Delegationen,
|
||||
Activity-Audit-Trails und die Verlässlichkeit der Agentenidentität.
|
||||
|
||||
### Korrektur
|
||||
|
||||
1. Einen bekannten Identitätsheader niemals allein als Authentifizierung
|
||||
akzeptieren.
|
||||
2. Service-Traffic über mindestens einen starken Nachweis absichern:
|
||||
rotierbarer Service-Key mit konstanter Zeitprüfung, mTLS, signiertes
|
||||
Gateway-Token oder eine private Netzwerkgrenze mit authentifizierendem
|
||||
Proxy.
|
||||
3. Am äußeren Proxy eingehende `X-Agent-Id` entfernen. Der vertrauenswürdige
|
||||
Proxy darf sie erst nach erfolgreicher Authentifizierung neu setzen.
|
||||
4. `X-Agent-Id` nur als Actor-Attribut innerhalb eines bereits
|
||||
authentifizierten Service-Contexts verwenden.
|
||||
5. Replay-, falsche-ID-, fehlender-Key- und Proxy-Bypass-Tests ergänzen.
|
||||
|
||||
## SEC-003 – Temporäres Owner-Passwort im Prozess-Log
|
||||
|
||||
**Schweregrad:** P2 / mittel
|
||||
**Konfidenz:** Hoch
|
||||
**Betroffene Grenze:** Bootstrap -> Log-Aggregation / Betreiberzugriff
|
||||
|
||||
### Evidenz
|
||||
|
||||
Beim ersten Seed wird ein generiertes temporäres Owner-Passwort einmalig in
|
||||
stderr ausgegeben. Obwohl das Passwort nicht in Git gespeichert wird, können
|
||||
Container-, CI- oder zentrale Logs den Wert länger aufbewahren als vorgesehen.
|
||||
|
||||
### Korrektur
|
||||
|
||||
- Passwort über einen expliziten One-Time-Secret-Kanal bereitstellen oder einen
|
||||
zeitlich eng begrenzten Reset-Link verwenden.
|
||||
- Wenn Logging vorerst bleibt: Zugriff, Aufbewahrung und automatische
|
||||
Redaction verbindlich konfigurieren.
|
||||
- Erstanmeldung zum sofortigen Passwortwechsel zwingen und Seed-Nutzung
|
||||
auditieren.
|
||||
|
||||
## Positive Kontrollen
|
||||
|
||||
- JWT-Schlüssel müssen mindestens 32 Byte lang sein.
|
||||
- Issuer, Audience, Signatur und Laufzeit werden geprüft; Clock Skew ist klein.
|
||||
- Refresh Tokens werden rotiert und gehasht persistiert.
|
||||
- Sichere Cookie- und CSRF-Bausteine sind vorhanden.
|
||||
- Auth- und Agent-Routen besitzen Rate-Limiting-Policies.
|
||||
- Nginx setzt CSP, Frame-, MIME-, Referrer- und Permissions-Header.
|
||||
- CI enthält eine einfache Suche nach versehentlich eingecheckten Secrets.
|
||||
|
||||
## Freigabekriterien
|
||||
|
||||
Eine Security-Freigabe ist erst möglich, wenn:
|
||||
|
||||
- beide P0-Pfade korrigiert sind,
|
||||
- eine vollständige Endpoint-Policy-Matrix dokumentiert ist,
|
||||
- negative Auth- und Bridge-Integrationstests in .NET 10 grün sind,
|
||||
- der Test über dieselbe Nginx-/Traefik-Grenze wie Produktion erfolgt,
|
||||
- unbekannte, bekannte-aber-nicht-authentifizierte und manipulierte
|
||||
Agent-Identitäten zuverlässig abgewiesen werden.
|
||||
@@ -1,84 +1,80 @@
|
||||
# Agent Identity Architecture (P4)
|
||||
# Agent identity architecture
|
||||
|
||||
> Status: ✅ Implemented (2026-07-13)
|
||||
> Task: `4291d694-dd40-410d-b0d5-4742d334547a`
|
||||
> Status: Live OpenClaw RPC authority implemented and verified on 2026-07-30.
|
||||
> The former `agents-sanitized.json` design is retired.
|
||||
|
||||
## Problem
|
||||
## Authority contract
|
||||
|
||||
Nexus needed agent identity data (id, name, role, sub-agents, model) for the board/bridge
|
||||
operations, but reading directly from `/home/node/.openclaw/openclaw.json` would expose
|
||||
secrets (gateway password, API keys, auth profiles, channel tokens).
|
||||
OpenClaw is the sole runtime authority for agent identity, model assignment,
|
||||
workspace metadata and agent bootstrap files. Nexus does not copy that data
|
||||
into a second configuration and does not derive a host path from an agent ID.
|
||||
|
||||
## Solution: Sanitized Agent Config File
|
||||
```text
|
||||
OpenClaw Gateway
|
||||
agents.list
|
||||
|
|
||||
v
|
||||
Nexus backend
|
||||
IOpenClawControlService
|
||||
|
|
||||
+--> /api/v1/agents
|
||||
+--> /api/v1/agents/{id}
|
||||
+--> Dashboard and allow-listed agent operations
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
openclaw.json (full config, SECRETS)
|
||||
│
|
||||
├── Deploy-time: jq extract → agents-sanitized.json (NO secrets)
|
||||
│ └── deploy-nexus.sh: extracts only {"agents": ...} from openclaw.json
|
||||
│
|
||||
├── Manual sync: scripts/sync-agents-sanitized.mjs
|
||||
│ └── node scripts/sync-agents-sanitized.mjs --once
|
||||
│
|
||||
└── Nexus API reads: agents-sanitized.json (read-only mount in compose)
|
||||
├── AgentService.LoadAgentConfigsAsync()
|
||||
├── OpenClawGatewayClient.LoadAgentIdsFromConfig()
|
||||
└── AgentService.GetAllowedAgentIdsAsync()
|
||||
OpenClaw Gateway
|
||||
agents.files.list/get/set
|
||||
agents.workspace.list/get
|
||||
|
|
||||
v
|
||||
Nexus owner-only agent configuration facade
|
||||
```
|
||||
|
||||
### Key Design Decisions
|
||||
New OpenClaw agents therefore appear without a Compose change, deploy-time
|
||||
sanitizer or static fallback catalog.
|
||||
|
||||
1. **Single sanitized source**: `agents-sanitized.json` contains ONLY the `agents` key
|
||||
(list + defaults) — no `gateway`, `auth`, `channels`, `tools`, `plugins`, etc.
|
||||
|
||||
2. **Read-only mount**: Compose mounts as `:ro` — no write access from the API container
|
||||
## Security properties
|
||||
|
||||
3. **No ACL dependency**: No uid-1654 ACL needed; the sanitized file is root-owned and
|
||||
world-readable
|
||||
- The browser talks only to typed Nexus endpoints; it never receives Gateway
|
||||
credentials, provider credentials or raw OpenClaw configuration.
|
||||
- `agents.list` supplies the current allow-list. A caller-provided agent ID is
|
||||
metadata after authentication, not identity proof.
|
||||
- Supported bootstrap files use `agents.files.*`. Writes require owner,
|
||||
management consent, advertised capability, `operator.admin`,
|
||||
`Idempotency-Key`, `expectedHash`, pre-write re-read and post-write
|
||||
verification.
|
||||
- Additional files use `agents.workspace.*` and remain read-only because the
|
||||
pinned OpenClaw contract has no safe arbitrary workspace-write RPC.
|
||||
- Nexus never reads `openclaw.json` and never maps an agent ID to
|
||||
`/mnt/workspace-{agentId}`.
|
||||
- The separate Memory, Docs and Incidents surfaces may retain one explicitly
|
||||
configured, confined Iris content root until equivalent safe OpenClaw RPCs
|
||||
exist. That bounded compatibility reader is not an agent-identity or
|
||||
per-agent-configuration source.
|
||||
|
||||
4. **Graceful fallback**: If the sanitized file is missing, both `AgentService` and
|
||||
`OpenClawGatewayClient` fall back to hardcoded agent IDs from `AgentIdentityCatalog`
|
||||
## Retired design
|
||||
|
||||
5. **Auto-sync on deploy**: The deploy pipeline (`deploy-nexus.sh`) regenerates the
|
||||
sanitized file from `openclaw.json` using `jq` in an alpine container
|
||||
The 2026-07-13 implementation generated and mounted
|
||||
`agents-sanitized.json`. It also depended on a static fallback catalog and
|
||||
required deployment synchronization. The 2026-07-30 RPC cutover removed these
|
||||
production dependencies:
|
||||
|
||||
6. **Manual sync available**: `scripts/sync-agents-sanitized.mjs` provides on-demand
|
||||
and watch-mode sync
|
||||
- no `AgentConfigPath`;
|
||||
- no sanitized-agent Compose mount;
|
||||
- no deploy-time or watch-mode sanitizer;
|
||||
- no hardcoded fallback as runtime authority; and
|
||||
- no fixed workspace derivation.
|
||||
|
||||
### File Layout
|
||||
## Verification
|
||||
|
||||
| File | Location | Purpose |
|
||||
|------|----------|---------|
|
||||
| `openclaw.json` | `/home/node/.openclaw/openclaw.json` | Full config with secrets (gateway only) |
|
||||
| `agents-sanitized.json` | `/home/node/.openclaw/agents-sanitized.json` | Agents-only, no secrets |
|
||||
| Compose mount | `compose.yaml` → API container | `agents-sanitized.json:ro` |
|
||||
| Deploy sanitizer | `.gitea/scripts/deploy-nexus.sh` | jq extraction on deploy |
|
||||
| Sync script | `scripts/sync-agents-sanitized.mjs` | Node.js manual/watch sync |
|
||||
| Config path | `backend/appsettings.json` | `AgentConfigPath` key |
|
||||
The final 2026-07-30 backend suite passed 312/312 tests. Focused tests cover
|
||||
live inventory, nonstandard workspace metadata such as `workspace-po`, session
|
||||
model resolution, file hash conflicts, verified read-back and session-history
|
||||
fallback. Repository search found no remaining `AgentConfigPath`,
|
||||
`agents-sanitized` or `/mnt/workspace-{agentId}` dependency in production
|
||||
backend code or backend tests.
|
||||
|
||||
### Security Guarantees
|
||||
Canonical integration and release boundaries are documented in:
|
||||
|
||||
- ✅ No `password`, `token`, `secret`, or `api_key` values in `agents-sanitized.json`
|
||||
- ✅ API endpoints (`/api/v1/agents`, `/api/v1/agents/{id}`) return ZERO secrets
|
||||
- ✅ Gateway bridge controller (`/api/bridge/*`) uses only agent IDs from sanitized config
|
||||
- ✅ No direct `openclaw.json` reads in any C# code path
|
||||
- ✅ Agent identity catalog (`AgentIdentityCatalog`) is a hardcoded fallback, not a primary source
|
||||
|
||||
### Verification
|
||||
|
||||
```bash
|
||||
# Check sanitized file has no secrets
|
||||
curl -s http://nexus-api-1:8080/api/v1/agents \
|
||||
-H "X-Api-Key: <key>" | grep -i "password\|secret\|token\|apikey"
|
||||
# Expected: no output
|
||||
|
||||
# Verify only "agents" key exists in sanitized file
|
||||
python3 -c "
|
||||
import json
|
||||
with open('agents-sanitized.json') as f:
|
||||
data = json.load(f)
|
||||
print(list(data.keys())) # Should print ['agents']
|
||||
"
|
||||
```
|
||||
- `docs/OPENCLAW_GATEWAY_CONNECTION.md`
|
||||
- `docs/AGENT_FIRST_MISSION_CONTROL.md`
|
||||
- `docs/audits/2026-07-30/openclaw-attach-adopt/IMPLEMENTATION_AND_ACCEPTANCE.md`
|
||||
|
||||
@@ -0,0 +1,101 @@
|
||||
# Authenticated dashboard design migration audit
|
||||
|
||||
## Outcome
|
||||
|
||||
The dashboard V2 language now covers all 16 other authenticated routes through
|
||||
a shared token source, presentation layer, and aligned legacy shell. Dashboard
|
||||
and Login remain visually unchanged. No product behavior, backend contract,
|
||||
route registration, store/service/composable logic, or permission rule was
|
||||
modified.
|
||||
|
||||
## Implemented layers
|
||||
|
||||
1. Expanded `nexus-tokens.css` into the V2 source for surfaces, text, accents,
|
||||
status colors, focus, typography, page geometry, and legacy aliases.
|
||||
2. Added `nexus-components.css` for route frames, headers, glass panels,
|
||||
controls, badges, modals, and state surfaces.
|
||||
3. Aligned `App.vue`, `AppSidebar`, and `AppHeader` with the dashboard's galaxy,
|
||||
248px sidebar, 62px topbar, glass, and responsive navigation.
|
||||
4. Applied standard, workspace, or reading-width contracts to every migrated
|
||||
route family.
|
||||
5. Replaced presentation emoji/glyph icons with existing Lucide icons and added
|
||||
accessible names, semantic interactive elements, keyboard equivalence, and
|
||||
visible focus.
|
||||
6. Unified both authenticated navigation shells around the four dashboard
|
||||
categories and added a persistent Settings destination to the dashboard
|
||||
footer. Shared-shell and dashboard destinations now use RouterLinks, while
|
||||
detail routes retain the active state of their parent section.
|
||||
|
||||
## Evidence matrix
|
||||
|
||||
| Evidence | Coverage | Result |
|
||||
| --- | --- | --- |
|
||||
| Fresh dashboard reference | `/dashboard`, `1440 × 900` | Passed |
|
||||
| Full desktop route matrix | all 18 registered routes, `1440 × 900` | Passed |
|
||||
| Full migrated mobile matrix | 16 migrated routes, `375 × 812` | Passed |
|
||||
| Representative responsive matrix | 5 route families at `768`, `1024`, `1920px` | Passed |
|
||||
| Automated geometry | document width and route-root geometry | Passed |
|
||||
| Same-viewport visual comparison | dashboard reference beside migrated Agents | Passed |
|
||||
| Core interactions | filters, forms, modal, detail changes, board, chat, notifications | Passed |
|
||||
| Keyboard/accessibility | names, semantics, focus, equivalent activation | Passed |
|
||||
| Frontend gates | typecheck, tests, build | Passed |
|
||||
|
||||
Evidence is under `screenshots/`. The final reference is
|
||||
`screenshots/00-dashboard-reference-1440.png`; route captures are under
|
||||
`screenshots/design-migration-routes/`; and the combined visual comparison is
|
||||
`screenshots/design-qa-comparison-dashboard-vs-agents-1280.png`.
|
||||
|
||||
## Measured contracts
|
||||
|
||||
- Sidebar: `248px` desktop.
|
||||
- Topbar: `62px`.
|
||||
- Page title: Space Grotesk `24px / 30px`, weight `700`.
|
||||
- Desktop/mobile inset: `20px / 14px`.
|
||||
- Maximum route widths: standard `1180px`, workspace `1440px`, reading/form
|
||||
`880px`.
|
||||
- No document-level horizontal overflow at the required breakpoints.
|
||||
- Task Board columns retain their intentional internal horizontal scroller.
|
||||
|
||||
## Findings resolved during QA
|
||||
|
||||
- The inherited 768px shell breakpoint initially hid the sidebar without
|
||||
exposing the mobile navigation button. The shell now switches coherently at
|
||||
`900px`.
|
||||
- Scoped Settings width rules initially overrode the shared reading-width
|
||||
modifier. Higher-specificity shared contracts now enforce `880px` for every
|
||||
reading/form root.
|
||||
- Undefined or ambiguous legacy color aliases and hard-coded route colors were
|
||||
replaced by V2 semantic tokens.
|
||||
- Presentation emoji/glyph icons and unnamed icon controls were replaced with
|
||||
Lucide icons and explicit accessible names.
|
||||
- The shared sidebar initially exposed one flat list and the dashboard omitted
|
||||
Settings. Both shells now expose the same category framework and persistent
|
||||
Settings access without changing routes, handlers, stores, or permissions.
|
||||
- A RouterLink migration initially shadowed each dashboard item's target with
|
||||
the current route. The prop/current-route names are now distinct, and browser
|
||||
checks confirmed the real registered destinations.
|
||||
|
||||
## Residuals
|
||||
|
||||
There are no P0-P2 design defects. A deliberate Task Board route leave aborts
|
||||
the fixture-backed live stream and logs the existing polling-fallback warning.
|
||||
This is outside the presentation scope and does not affect the rendered result
|
||||
or interaction path.
|
||||
|
||||
## Verification
|
||||
|
||||
```text
|
||||
pnpm typecheck -> passed
|
||||
pnpm test -> passed (1 file, 2 tests)
|
||||
pnpm build -> passed (1,882 modules)
|
||||
git diff --check -> passed; line-ending notices only
|
||||
```
|
||||
|
||||
Navigation follow-up evidence:
|
||||
|
||||
```text
|
||||
navigation-groups-after-dashboard.png
|
||||
navigation-groups-after-settings.png
|
||||
navigation-groups-after-settings-375.png
|
||||
navigation-groups-comparison-dashboard-vs-settings-1440.png
|
||||
```
|
||||
@@ -0,0 +1,148 @@
|
||||
# Nexus – Seitenaudit
|
||||
|
||||
**Datum:** 2026-07-26
|
||||
**Commit:** `3bc7622977f4a6c2f2e98ab4aa856a2e45c3cf49`
|
||||
**Auditumfang:** Alle 18 in `frontend/src/router.ts` registrierten Seiten plus
|
||||
ungültige Navigationsziele und sechs Viewport-Größen.
|
||||
|
||||
## Methodik und Evidenzgrenze
|
||||
|
||||
Die Anwendung wurde lokal gebaut und im Browser mit repräsentativen,
|
||||
deterministischen API-Fixtures betrieben. Dadurch konnten Authentifizierung,
|
||||
Routen, Inhalte, Lade-/Leerzustände, Interaktionen und Responsive-Verhalten
|
||||
reproduzierbar geprüft werden.
|
||||
|
||||
Die Fixtures ersetzen keinen Live-Systemtest:
|
||||
|
||||
- keine reale PostgreSQL- oder OpenClaw-Verbindung,
|
||||
- kein produktiver Nginx-/Traefik-Pfad,
|
||||
- SSE absichtlich nicht als Live-Vertrag bewertet,
|
||||
- fixturebedingte Datums- oder Reconnect-Anzeigen gelten nicht als
|
||||
Produktdefekte.
|
||||
|
||||
Jeder Screenshot stammt aus diesem Auditlauf und liegt unter
|
||||
[`screenshots/`](screenshots/).
|
||||
|
||||
## Leitbefunde
|
||||
|
||||
1. **Dashboard ist zwischen 375 und 1024 px nicht nutzbar.** Agent-Cards,
|
||||
Header und Iris-Panel überlappen oder werden abgeschnitten.
|
||||
2. **Bei 768 px greift der mobile Sidebar-Breakpoint noch nicht.** Die feste
|
||||
248-px-Sidebar lässt dem Board nur einen schmalen Restbereich.
|
||||
3. **Zwei UI-Shells erzeugen einen Produktbruch.** Dashboard und restliche
|
||||
Seiten unterscheiden sich in Navigation, Sprache, Dichte, Tokens und
|
||||
Verhalten.
|
||||
4. **Vier Dashboard-Navigationsziele sind nicht registriert.** Der
|
||||
Wildcard-Redirect kaschiert das Problem und zeigt wieder `/dashboard`.
|
||||
5. **Daten nach Login werden nicht zuverlässig initialisiert.** Projects,
|
||||
Models und Activity bleiben bis zum manuellen Refresh leer.
|
||||
6. **Task Board verliert auf kleinen Displays den Gesamtüberblick.** Es zeigt
|
||||
praktisch nur die erste Spalte und erzeugt große leere Höhen.
|
||||
7. **Kontrast und Schriftgrößen sind zu schwach.** Das betrifft besonders
|
||||
Labels, Metadaten, Buttons und sekundäre Texte.
|
||||
|
||||
## Visuelle Kernevidenz
|
||||
|
||||
### Dashboard, Desktop 1440 px
|
||||
|
||||
|
||||
|
||||
### Dashboard, Mobile 375 px
|
||||
|
||||
|
||||
|
||||
### Dashboard, Tablet 768 px
|
||||
|
||||
|
||||
|
||||
### Task Board, Mobile 375 px
|
||||
|
||||
|
||||
|
||||
## Audit pro registrierter Seite
|
||||
|
||||
| Route | Status | Wesentliche Befunde | Evidenz |
|
||||
|---|---|---|---|
|
||||
| `/login` | P1 | Visuell fokussiert, aber sehr dunkel. Bei 320×568 werden oberer Brand-Bereich und untere Inhalte nicht gemeinsam sichtbar; der Flow benötigt Scrollen. | [Desktop](screenshots/01-login-desktop.png), [320 px](screenshots/22-login-mobile-320.png) |
|
||||
| `/dashboard` | P0 | Eigenständige V2-Shell; dichte, überlappende Agent-Topologie; Suche und „Ask Iris“ ohne vollständige Aktion; feste Dashboard-Aktivmarkierung. Zwischen 375 und 1024 px schwer bis vollständig unbrauchbar. | [1440](screenshots/02-dashboard-desktop.png), [375](screenshots/19-dashboard-mobile-375.png), [768](screenshots/23-dashboard-tablet-768.png), [1024](screenshots/24-dashboard-1024.png), [1920](screenshots/25-dashboard-wide-1920.png) |
|
||||
| `/memory` | P2 | Kohärente List-/Detailansicht, aber sehr kleine und kontrastarme Metadaten. Der große leere Detailbereich gibt beim Einstieg wenig Orientierung. | [Desktop](screenshots/03-memory-desktop.png) |
|
||||
| `/docs` | P2 | Such- und Kategorienstruktur sind verständlich. Initial bleibt viel leerer Raum; kein automatisch ausgewähltes Dokument und zu schwache Sekundärtexte. | [Desktop](screenshots/04-docs-desktop.png) |
|
||||
| `/agents/:id` | P1 | Informationsarchitektur ist brauchbar. „Zurück zum Team“ navigiert jedoch zu nicht registriertem `/team` und landet über Wildcard auf dem Dashboard. | [Detail](screenshots/05-agent-detail-desktop.png), [Fehlredirect](screenshots/05b-agent-back-redirect-desktop.png) |
|
||||
| `/security` | P0 | Übersicht ist visuell nachvollziehbar, vermittelt aber mehr Sicherheit als die tatsächliche Controller-Autorisierung bietet. Deaktivierte 2FA und kritische Zugriffslücken sind nicht als Release-Blocker erkennbar. | [Desktop](screenshots/06-security-desktop.png) |
|
||||
| `/incidents` | P2 | Solide List-/Detailstruktur. Kleine Typografie, schwache Statusdifferenzierung und ein großer initial leerer Detailbereich bremsen den Scan. | [Desktop](screenshots/07-incidents-desktop.png) |
|
||||
| `/calendar` | P2 | Termine und Zeitbezug sind gut strukturiert. Refresh und Metadaten sind visuell zu zurückhaltend. | [Desktop](screenshots/08-calendar-desktop.png) |
|
||||
| `/projects` | P1 | Nach normalem Login zunächst leer. Erst manueller Refresh lädt Daten. Geladener ModuleView wirkt weitgehend ungestaltet und nicht wie Teil derselben Anwendung. | [Vor Refresh](screenshots/09-projects-desktop.png), [nach Refresh](screenshots/09b-projects-after-refresh-desktop.png) |
|
||||
| `/projects/:id` | P2 | Klare Stammdaten und Task-Zuordnung. Sehr große Leerflächen; destruktive Archivaktion erhält relativ viel visuelles Gewicht. | [Desktop](screenshots/10-project-detail-desktop.png) |
|
||||
| `/tasks` | P1 | Funktionsreicher Board-Flow, aber fünf Spalten überlaufen bereits auf Desktop. Auf 375 px ist nur eine Spalte plus Restkante sichtbar; keine gute mobile Statusnavigation. | [Desktop](screenshots/11-tasks-desktop.png), [375 px](screenshots/20-task-board-mobile-375.png) |
|
||||
| `/tasks/:id` | P1 | Detail- und Subtask-Struktur sind brauchbar. Existierende Priorität `Critical` erscheint leer, weil die Select-Option fehlt. | [Desktop](screenshots/12-task-detail-desktop.png) |
|
||||
| `/agents` | P2 | Stärkste Legacy-Übersichtsseite: konsistentes Grid und verständliche Rollen. Ganze `article`-Cards sind jedoch clickbar statt semantische Links/Buttons zu verwenden. | [Desktop](screenshots/13-agents-desktop.png) |
|
||||
| `/models` | P1 | Initial leer wegen fehlender Store-Hydration. Nach Refresh inhaltlich vorhanden, aber visuell als roher ModuleView ohne klare Hierarchie. | [Vor Refresh](screenshots/14-models-desktop.png), [nach Refresh](screenshots/14b-models-after-refresh-desktop.png) |
|
||||
| `/activity` | P1 | Dasselbe Hydration-Problem. Geladene Activity ist funktional lesbar, wirkt aber wie eine unvollständige Zwischenansicht. | [Vor Refresh](screenshots/15-activity-desktop.png), [nach Refresh](screenshots/15b-activity-after-refresh-desktop.png) |
|
||||
| `/chat` | P1 | Kernfunktion ist erkennbar, Oberfläche wirkt jedoch unfertig: schwache Hierarchie, rohe Form-Controls und keine belastbare mobile Conversation-Struktur. | [Desktop](screenshots/16-chat-desktop.png) |
|
||||
| `/notifications` | P2 | Filter und Gruppierung sind vorhanden. Kontrast ist schwach; Emoji-Icons brechen die sonstige Icon-Sprache und besitzen uneinheitliche Semantik. | [Desktop](screenshots/17-notifications-desktop.png) |
|
||||
| `/settings` | P2 | Am besten gelöste responsive Legacy-Seite. Formfelder bleiben bei 375 px nutzbar. Globale Topbar-Icons und kleine Labels bleiben Accessibility-Risiken. | [Desktop](screenshots/18-settings-desktop.png), [375 px](screenshots/21-settings-mobile-375.png) |
|
||||
|
||||
## Nicht registrierte oder defekte Ziele
|
||||
|
||||
| Quelle | Ziel | Tatsächliches Verhalten |
|
||||
|---|---|---|
|
||||
| Dashboard-Sidebar | `/orchestration` | Wildcard -> `/dashboard` |
|
||||
| Dashboard-Sidebar | `/research` | Wildcard -> `/dashboard` |
|
||||
| Dashboard-Sidebar | `/hosts` | Wildcard -> `/dashboard` |
|
||||
| Dashboard-Sidebar | `/costs` | Wildcard -> `/dashboard` |
|
||||
| Agent Detail | `/team` | Wildcard -> `/dashboard` |
|
||||
|
||||
`TeamView.vue` existiert, ist aber nicht im Router registriert. Der
|
||||
Wildcard-Redirect macht diese Integrationsfehler für Nutzer schwer
|
||||
diagnostizierbar.
|
||||
|
||||
## Responsive-Matrix
|
||||
|
||||
| Viewport | Ergebnis |
|
||||
|---|---|
|
||||
| 320 px | Login scrollbar und vertikal gequetscht; kein kompakter First-Viewport-Flow |
|
||||
| 375 px | Dashboard P0-defekt; Task Board nur eingeschränkt navigierbar; Settings brauchbar |
|
||||
| 768 px | Schlechtester Dashboard-Zwischenzustand durch Off-by-one-Breakpoint und feste Sidebar |
|
||||
| 1024 px | Dashboard weiterhin überlappend und abgeschnitten |
|
||||
| 1440 px | Grundsätzlich bedienbar, aber Dashboard-Header/Cards kollidieren und Task Board läuft horizontal über |
|
||||
| 1920 px | Dashboard erstmals stabiler, erzeugt jedoch übermäßig viel ungenutzten Raum |
|
||||
|
||||
## Accessibility-Spot-Check
|
||||
|
||||
Keine vollständige WCAG-Prüfung. Sichtbar und im DOM nachvollziehbar:
|
||||
|
||||
- zahlreiche Icon-Buttons ohne Accessible Name,
|
||||
- clickbare `article`-Elemente statt Links oder Buttons,
|
||||
- sehr kleine Textgrößen bis in den einstelligen Pixelbereich,
|
||||
- schwache Kontraste für Text, Controls und Statusinformationen,
|
||||
- horizontale Informationsarchitektur ohne gleichwertige mobile Alternative,
|
||||
- Platzhalter-Controls, deren sichtbare Affordance keine Aktion auslöst.
|
||||
|
||||
## Priorisierte Korrekturen
|
||||
|
||||
### P0
|
||||
|
||||
1. Dashboard zwischen 375 und 1024 px neu layouten; 768-px-Grenze explizit
|
||||
testen.
|
||||
2. Navigation nur aus registrierten Routen erzeugen oder fehlende Seiten
|
||||
bewusst implementieren.
|
||||
3. Security-Seite und Release-Status an die tatsächlichen
|
||||
Zugriffskontrollbefunde koppeln.
|
||||
|
||||
### P1
|
||||
|
||||
1. Eine gemeinsame Shell, Tokenbasis und Navigation für alle Seiten festlegen.
|
||||
2. Operations Store direkt nach erfolgreichem Login hydratisieren.
|
||||
3. Task Board mit mobiler Statusauswahl oder segmentierter Liste statt
|
||||
abgeschnittener Fünf-Spalten-Fläche ausstatten.
|
||||
4. `Critical` im gesamten Priority-Vertrag unterstützen.
|
||||
5. Suche, Ask-Iris, Logout und Back-Navigation entweder funktionsfähig machen
|
||||
oder ihre Affordance entfernen.
|
||||
|
||||
### P2
|
||||
|
||||
1. Standardgrößen und Kontrast anheben.
|
||||
2. Empty-/Loading-/Error-Zustände mit klarer nächster Aktion gestalten.
|
||||
3. Interaktive Cards und Icon-Buttons semantisch und keyboard-tauglich machen.
|
||||
4. Projects, Models, Activity und Chat aus dem generischen ModuleView in
|
||||
kohärente Produktseiten überführen.
|
||||
@@ -0,0 +1,117 @@
|
||||
# Structural proof preflight
|
||||
|
||||
- Product, route, or flow: Nexus authenticated legacy shell and the first migrated grid route, `/agents`
|
||||
- Selected direction or inspected source: `/dashboard`, captured in `screenshots/02-dashboard-desktop.png`
|
||||
- First bounded slice: shared V2 tokens, legacy sidebar/topbar/content frame, and the Agents overview
|
||||
- Explicit exclusions: dashboard and login visuals; route targets; stores, services, API contracts, backend behavior, and domain state transitions
|
||||
- Owner: Codex
|
||||
- Status: passed
|
||||
|
||||
## Entry contract
|
||||
|
||||
- Entry mode: task-first
|
||||
- Minimum context required before the first real action: current route title, gateway state, agent count, and any loading/error warning
|
||||
- Why each preceding block is necessary: the shell orients the user; the route header identifies the operational scope; gateway feedback determines whether agent data is trustworthy
|
||||
- First real action or task-entry control: open an agent profile
|
||||
- Success destination: the existing `/agents/:id` route
|
||||
- Blocked-destination reason and recovery: when no agents are returned, the existing empty state names gateway reachability and configuration as the recovery path
|
||||
|
||||
| Viewport or container | Initial `scrollY` | Identifying context rectangle | Action rectangle | Required reserve | Destination and sticky offset | Settled result |
|
||||
| --- | ---: | --- | --- | ---: | --- | --- |
|
||||
| Narrowest supported / `375px` | 0 | `x=14`, `y=76`, `w=332`; identity and gateway status wrap inside the page frame | first agent card `x=14`, `y=186`, `w=332`; keyboard activation verified | 14px page inset | `/agents/iris`; 62px topbar remains visible | passed; no page or content x-overflow |
|
||||
| Representative wide / `1280px` rendered browser ceiling | 0 | `x=268`, `y=82`, `w=977`; title uses Space Grotesk 24/30, 700 | first agent card `x=268`, `y=161`, `w=316` | 20px page inset | `/agents/iris`; 62px topbar remains visible | passed; 248px sidebar and 62px topbar measured |
|
||||
|
||||
## Section grammar
|
||||
|
||||
| Order | Section | Primary role | User question | Evidence or input | Layout grammar | Density and disclosure | Narrow transformation | State responsibility |
|
||||
| ---: | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| 1 | Legacy shell | orient | Where am I and what can I open? | registered navigation and existing counts | fixed sidebar plus topbar | compact operational chrome | sidebar becomes an overlay | active route, connection status, mobile navigation |
|
||||
| 2 | Route header | orient | Which agent surface and gateway state am I seeing? | agent count and gateway response | title cluster plus status badge | concise | stack and wrap | loading, gateway warning, error |
|
||||
| 3 | Agent grid | act | Which agent should I inspect? | existing agent data | responsive card grid | operational summary per agent | 3 to 2 to 1 columns | runtime state and profile navigation |
|
||||
| 4 | Empty/error message | recover | Why is no agent available and what can I check? | existing error and empty copy | single glass state panel | readable | full-width | diagnostic and next valid check |
|
||||
|
||||
- Accidental preamble removed or justified: no decorative preamble is added before the route identity.
|
||||
- Repeated wrappers or layout grammars that need a product reason: cards are reserved for comparable agents and operational panels.
|
||||
- Evidence kept with its claim: gateway state remains in the route header; runtime state remains inside its agent card.
|
||||
- Actions kept with their object and consequence: profile navigation remains on the corresponding agent card.
|
||||
- Recovery kept in destination context: loading, warning, error, and empty feedback stays inside the Agents page.
|
||||
|
||||
## Signature-gesture distribution
|
||||
|
||||
- Gesture: blue-to-violet gradient with controlled glow
|
||||
- One dominant use: active navigation and primary action
|
||||
- Supporting echo 1: brand mark
|
||||
- Supporting echo 2: a meaningful active or blocked status
|
||||
- Prohibited sections or states: ordinary data cards, neutral inputs, metadata, empty states, long-form copy, and destructive confirmation surfaces
|
||||
- Plain operational, error, and recovery grammar: glass surface, semantic border/status color, no decorative glow
|
||||
|
||||
## Content and type pressure
|
||||
|
||||
| Pressure input | Exact fixture or source | Narrow result | Wide result | Fix or accepted rationale | Status |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| Longest heading | existing route titles such as `Notifications` and `Project Detail` | retained at 24/30 and allowed to wrap | retained at 24/30 | wrap rather than shrink below the title contract | passed for the slice |
|
||||
| Longest control label | `Iris, Chief of Staff: View Profile` accessible name | keyboard reachable without changing visual copy | card action remains local to its object | preserve copy; allow action rows to wrap | passed |
|
||||
| Largest value or identifier | `claude-sonnet-4-5` | contained in the card metadata track | contained in the three-column grid | mono text keeps the existing ellipsis policy | passed |
|
||||
| Longest error, limitation, and recovery copy | authored error plus the existing gateway/configuration recovery copy | both wrap inside 332px | state surface remains inside the page frame | full-width glass state panels with natural wrapping | passed |
|
||||
| Required localization | current German and English UI strings | German copy wraps naturally; English labels remain intact | no content rewrite | do not rewrite product copy in this visual migration | passed |
|
||||
| `200%` zoom | represented structurally by the single-column narrow transformation and adjacent breakpoint matrix | no x-overflow | n/a | page remains vertically scrollable; controls wrap | accepted; final responsive matrix passed |
|
||||
| Narrow parent container | 375px required viewport | `scrollWidth=clientWidth=375`; content overflow delta `0` | n/a | `min-width: 0`, safe wrapping, and no page-level x overflow | passed |
|
||||
|
||||
- Important instructions, limitations, provenance, status, safety, consequences, and recovery are at least `14px`: required for final proof.
|
||||
- Any `12px` use is truly secondary and nonessential, with contrast and line-height evidence: reserved for compact interface labels; metadata uses JetBrains Mono at 11px minimum.
|
||||
- Min-content and unbreakable-content policy: content columns use `minmax(0, 1fr)` and `min-width: 0`; identifiers wrap or use an existing internal scroller only on horizontal workspaces.
|
||||
- Risky breakpoints and adjacent widths: 375, 767/768, 1023/1024, 1440, and 1920px.
|
||||
|
||||
## State-and-copy truth table
|
||||
|
||||
| State | Entry cause | Visible facts | Allowed actions | Forbidden stale copy or values | Recovery or next action | Focus target | URL, history, and storage effect |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| Initial/loading | route mounts and requests data | route title and loading message | navigation remains available | stale success state must not be presented as current | wait or navigate elsewhere | route heading | unchanged |
|
||||
| Success | API returns agents and gateway data | count, gateway state, cards, runtime metadata | open an agent, navigate, refresh | loading/error copy | select an agent profile | first actionable card | existing router history only |
|
||||
| Failure | API or gateway request fails | existing diagnostic message | navigate or refresh | stale cards presented as newly loaded | retry through the existing refresh/re-entry path | error message then next control | unchanged |
|
||||
| Recovery/empty | response contains no agents | existing empty-state reason and checks | navigate or re-enter after configuration changes | invented agents or changed recovery copy | check gateway reachability/configuration | empty-state heading | unchanged |
|
||||
|
||||
- Additional orthogonal states required: connected, thinking, blocked, ready, stale, error, unsupported, mobile navigation open/closed, and keyboard focus.
|
||||
- Atomic stale-content removal rule: visual CSS must not change existing state guards or data replacement behavior.
|
||||
- Exact reset or recovery snapshot: current store and component behavior remains the source of truth.
|
||||
|
||||
## Action vocabulary ledger
|
||||
|
||||
| User intent | Idle control | Pending or progress | Success or result | Failure and next action | Recovery, undo, or reversal |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| Refresh operational data | Refresh | existing loading/spinner treatment | updated current state | existing error message | invoke Refresh again |
|
||||
| Inspect an agent | View Profile / agent card | route transition | agent detail route | existing route/error behavior | return through existing navigation |
|
||||
|
||||
- Same user-recognized verb and domain noun retained through the journey: yes; no product copy or action is renamed by the visual migration.
|
||||
- Labels, statuses, toasts, confirmations, errors, recovery, and assistive announcements agree: existing strings remain authoritative.
|
||||
- Empty and failure states name the next valid action: existing page copy is preserved and presented accessibly.
|
||||
|
||||
## Proof architecture
|
||||
|
||||
- Stable semantic selectors, state attributes, and dedicated value nodes: route root classes, shell landmarks, existing data/state classes, and `data-route` on the legacy content frame
|
||||
- Assertions intentionally independent of translated copy, neighboring text, wrappers, and visual position: geometry and overflow checks target landmarks and route roots
|
||||
- Explicit settle conditions for scroll, fonts, media, transitions, async state, and geometry: document fonts loaded, fixture/API requests settled, no pending transitions, and two animation frames after route mount
|
||||
- Independent oracle or source of truth: router registration plus the independently authored audit fixture; production stores and API contracts are not modified
|
||||
- Required positive and negative assertions: every registered route renders; no page-level horizontal overflow; dashboard/login source files remain visually untouched; navigation/events/handlers remain registered
|
||||
- Source, build, harness, fixture, oracle, and capture bindings: repository HEAD and working tree, frontend build, local fixture, route matrix, and dated screenshots under this audit folder
|
||||
- Capture claim ledger location: `design-qa.md` and `docs/audits/2026-07-26/DESIGN_MIGRATION_AUDIT.md`
|
||||
- Failure classification: product / harness / evidence / environment
|
||||
|
||||
## Structural slice gate
|
||||
|
||||
| Gate | Narrow evidence | Wide evidence | Independent rendered review | Status |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Entry mode and minimum context remain true | title, count, gateway state, and first agent/action are visible | same hierarchy inside the standard page frame | accepted from rendered captures | passed |
|
||||
| First action is reachable and completely framed | first card is fully framed and opens by Enter | first row is visible above the fold | `/agents/iris` navigation verified | passed |
|
||||
| Section roles and layout grammars remain distinct | shell, identity, grid/state surface remain separate | same roles with three-column grid | accepted | passed |
|
||||
| Signature-gesture budget is respected | gradient is limited to active navigation, brand/primary action, and card identity accents | ordinary panels remain plain glass | accepted | passed |
|
||||
| Long content, localization, and min-content pressure pass | long descriptions, model IDs, tags, and recovery copy wrap without x-overflow | three-column content remains contained | accepted for bounded slice | passed |
|
||||
| Core path passes success, failure, and recovery | success grid, empty recovery, and API error were rendered | success grid rendered | fixture states captured independently | passed |
|
||||
| Focus, state copy, controls, and recovery agree | focused agent card measured with 2px blue outline and 2px offset | keyboard Enter opened the existing destination | accepted | passed |
|
||||
| Proof selectors, settle conditions, negatives, oracle, and capture binding pass | `data-route`, route root, landmark geometry, authored fixture, and dated captures recorded | same | typecheck passed; dashboard/login source files untouched | passed |
|
||||
|
||||
- Automated result: candidate
|
||||
- Independent rendered-review result: accepted
|
||||
- Defects and classification: the initial comparison host was capped at 1280px; exact 1440px route checks and 1920px family checks were completed separately and passed.
|
||||
- Contract corrections: moved the gateway chip below the identity cluster on narrow screens; kept all recovery copy in glass state panels; added keyboard-equivalent link semantics to agent cards.
|
||||
- Expansion decision: proceed
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 96 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 35 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 78 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 46 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 55 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 78 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 63 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 46 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 53 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 71 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 63 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 61 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 42 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 48 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 44 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 25 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 39 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 70 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 100 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 108 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 19 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 86 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 37 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 110 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 128 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 139 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 38 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 87 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 76 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 59 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 70 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 32 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 62 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 54 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 70 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 33 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 47 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 15 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 62 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 66 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 76 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 29 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 40 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 56 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 67 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 24 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 93 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 70 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 28 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 95 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 66 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 82 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 93 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 47 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 110 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 42 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 18 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.1 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 68 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 20 KiB |
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user