feat: ship agent-first mission control v0.2.57

2026-07-31 22:39:47 +02:00
parent 3bc7622977
commit f5552218bc
535 changed files with 95242 additions and 8791 deletions
@@ -0,0 +1,180 @@
+# OpenClaw Core Integration — Implementation Evidence
+
+**Stand:** 2026-07-28
+**Scope:** Nexus frontend, authenticated API facade, OpenClaw Gateway transport,
+core-route wiring and operated browser QA.
+
+## Ergebnis
+
+Nexus now has one browser-safe OpenClaw control-plane path:
+
+```text
+Browser
+  -> authenticated Nexus API
+  -> IOpenClawControlService
+  -> IGatewayConnector
+  -> OpenClaw Gateway protocol v4
+  -> provider and tools selected by OpenClaw
+```
+
+The browser never receives an OpenClaw token, password or OpenAI credential.
+OpenClaw remains authoritative for runtime agents, sessions, tasks, approvals,
+cron jobs, models and runtime events. Nexus remains authoritative for users,
+projects, product tasks, notifications and the control-plane UX.
+
+This checkpoint is a functional vertical slice, not yet proof that the deployed
+OpenClaw instance and OpenAI provider are production-ready. The repository has
+contract coverage and a clearly labelled browser-QA simulation; a real
+credentialed OpenClaw/OpenAI smoke test remains required.
+
+## Protocol-v4 connector
+
+`GatewayConnector` and `OpenClawGatewayProtocol` now provide:
+
+- `connect.challenge` detection followed by a protocol-v4 `connect` request and
+  validated `hello-ok`;
+- request/response correlation with backend-only request IDs;
+- advertised method, event and granted-scope discovery;
+- configurable handshake/RPC timeouts and receive-frame size limits;
+- bounded recent-event buffering;
+- reconnect backoff with jitter and explicit
+  `initializing/reconnecting/disconnected/failed/connected` states;
+- optional exact Gateway-version pinning through
+  `OPENCLAW_REQUIRED_VERSION`;
+- fail-closed method availability checks before RPC invocation;
+- safe error projection without returning credentials or raw transport state to
+  the browser.
+
+The current trusted backend flow intentionally omits device identity only for
+the OpenClaw-supported direct-loopback/shared-secret topology. A remote or
+container-to-host Gateway topology needs a paired device identity and signed
+challenge response before it can be claimed production-ready.
+
+## Typed Nexus facade
+
+All endpoints below require Nexus authentication. Mutations additionally
+require the `owner` role and use the existing agent rate-limit policy.
+
+| Method | Endpoint | OpenClaw operation |
+|---|---|---|
+| `GET` | `/api/v1/openclaw/connection` | Connection and recovery state |
+| `GET` | `/api/v1/openclaw/capabilities` | Advertised method/scope matrix |
+| `GET` | `/api/v1/openclaw/overview` | Aggregated control-plane read model |
+| `GET` | `/api/v1/openclaw/tasks` | `tasks.list` |
+| `POST` | `/api/v1/openclaw/tasks/{id}/cancel` | `tasks.cancel` |
+| `GET` | `/api/v1/openclaw/sessions` | `sessions.list` |
+| `POST` | `/api/v1/openclaw/sessions/abort` | `sessions.abort` |
+| `POST` | `/api/v1/openclaw/sessions/model` | `sessions.patch` |
+| `GET` | `/api/v1/openclaw/cron` | `cron.list` |
+| `POST` | `/api/v1/openclaw/cron/{id}/run` | `cron.run` with force mode |
+| `GET` | `/api/v1/openclaw/approvals` | approval snapshot/events |
+| `POST` | `/api/v1/openclaw/approvals/{id}/resolve` | approval resolution |
+| `GET` | `/api/v1/openclaw/activity` | normalized recent Gateway events |
+| `GET` | `/api/v1/openclaw/models` | `models.list` |
+| `GET` | `/api/v1/openclaw/agents` | `agents.list` |
+
+Each read returns its own state, message, recovery action and observation time.
+Missing scopes and missing Gateway methods are distinct from disconnection.
+Mutations return an explicit `ok/state/message/data/recovery/completedAt`
+envelope instead of silently succeeding.
+
+## Frontend integration
+
+The authenticated shell polls only the Nexus facade and exposes one shared
+OpenClaw status/recovery contract. The implemented operator paths are:
+
+- Run Control: tasks, sessions, approvals, cron, events, inspector and
+  confirmation dialogs;
+- Dashboard: authoritative agent/session projection, focus tasks, runtime
+  status, model patching and Iris chat through Nexus;
+- Agents and Agent Detail: live OpenClaw agents and session state merged with
+  Nexus-safe metadata;
+- Models: provider-safe live catalog with availability and recovery reasons;
+- Activity: OpenClaw runtime events combined with Nexus control-plane events;
+- Calendar: live cron list and owner-confirmed `cron.run`;
+- Notifications: live approval summary plus working notification actions;
+- Security and Settings: connection, version, scope and trust-boundary
+  diagnostics without secret values;
+- Projects, Tasks, Memory, Docs and Incidents: explicit OpenClaw context and
+  recovery links while preserving Nexus ownership of their domain state.
+
+Iris chat is hidden by default, opens as a modal and keeps the dashboard space
+for live orchestration. Sending uses `POST /api/v1/chat`; the conversation ID is
+stable per browser. The former `/chat` route is intentionally absent.
+
+## Additional reliability fixes
+
+- Initial authentication now shares an in-flight refresh between overlapping
+  router guards. Direct authenticated route loads no longer race into
+  `/login`.
+- Authenticated post-login hydration refreshes operations/sidebar state.
+- Task Board and live-SSE consumers validate snapshot shape before assignment
+  and fall back to polling instead of blanking the route.
+- Iris history uses stable timestamps in the QA fixture, preventing false
+  duplicate-poll evidence.
+
+## Verification
+
+### Automated
+
+| Check | Result |
+|---|---|
+| `pnpm test` | 3 files, 5 tests passed |
+| `pnpm build` | Typecheck and Vite production build passed; 1886 modules |
+| `.tools/dotnet/dotnet.exe test backend-tests/Nexus.Api.Tests.csproj --configuration Release` | 201/201 passed |
+| Gateway protocol/normalization tests | challenge, hello, errors, capabilities, tasks, cron, approvals and session-model patch covered |
+| Frontend state tests | concurrent auth initialization, disconnected recovery and API failure covered |
+
+### Operated browser paths
+
+- all 17 authenticated routes loaded at 375, 768, 1024, 1440 and 1920 px;
+- no document-level horizontal overflow or visible alert remained;
+- Run Control node selection, cancel confirmation, approval resolution and cron
+  execution worked;
+- Activity and Models search/detail dialogs worked and closed with `Escape`;
+- Task Board opened a real task detail;
+- dashboard Iris chat loaded once, sent, received, closed and restored focus;
+- the Iris agent session model changed through the typed facade;
+- a notification marked read and routed to its target; mark-all-read cleared the
+  unread count;
+- the final browser console contained no warning or error entries.
+
+The browser data came from `scripts/qa/openclaw-ui-mock.mjs`. Every response is
+labelled with `X-Nexus-QA-Fixture`, and the UI visibly reports
+`QA SIMULATION`; it is not live OpenClaw evidence.
+
+## Visual evidence
+
+- [Dashboard reference vs current](dashboard-reference-vs-current.png)
+- [Run Control mockup vs functional build](run-control-mock-vs-current.png)
+- [All core pages contact sheet](core-pages-contact-sheet.png)
+- [Run Control responsive contact sheet](run-control-responsive-contact-sheet.png)
+- [Route evaluation](ROUTE_EVALUATION.md)
+- [Design QA](design-qa.md)
+
+## Remaining production boundary
+
+The next release-blocking proof is:
+
+1. pair a backend device identity for the actual remote/container topology, or
+   run Nexus in the documented direct-loopback topology;
+2. pin the deployed Gateway version;
+3. configure OpenAI exclusively inside OpenClaw;
+4. run one credentialed flow
+   `Nexus -> OpenClaw session -> OpenAI -> OpenClaw result -> Nexus`;
+5. record provider/model evidence, an unauthorized negative case, reconnect
+   recovery and an audited owner mutation.
+
+Until this proof exists, Nexus is a tested control-plane implementation but not
+yet a verified replacement for every OpenClaw operational workflow.
+
+## Primary sources
+
+- [OpenClaw Gateway protocol](https://docs.openclaw.ai/gateway/protocol)
+- [Building an OpenClaw Gateway client](https://docs.openclaw.ai/gateway/clients)
+- [OpenClaw operator scopes](https://docs.openclaw.ai/gateway/operator-scopes)
+- [OpenClaw models](https://docs.openclaw.ai/models)
+- [OpenClaw background tasks](https://docs.openclaw.ai/automation/tasks)
+- [OpenClaw cron operations](https://docs.openclaw.ai/cli/cron)
+- [OpenClaw tools invoke HTTP API](https://docs.openclaw.ai/gateway/tools-invoke-http-api)
+- [OpenClaw Gateway troubleshooting](https://docs.openclaw.ai/gateway/troubleshooting)
@@ -0,0 +1,93 @@
+# Nexus Core Route Evaluation
+
+**Stand:** 2026-07-28
+**Bewertungsziel:** Wie nah ist jede Seite an einer agent-first Mission Control,
+die tägliche OpenClaw-Bedienung ersetzt?
+
+## Zusammenfassung
+
+The core route set is now coherent and functionally connected, but Nexus is not
+yet complete OpenClaw parity.
+
+| Dimension | Reife | Bewertung |
+|---|---:|---|
+| Browser -> Nexus -> OpenClaw trust boundary | 9/10 | Correct architectural boundary; no provider secrets in the browser |
+| Gateway protocol foundation | 7/10 | Protocol v4, states, scopes and reconnect exist; remote device pairing and live interop proof remain |
+| Runtime visibility | 8/10 | Tasks, sessions, agents, approvals, cron, models and events are visible |
+| Safe runtime mutations | 5/10 | Cancel, abort, model patch, approval and run-now work; lifecycle coverage is incomplete |
+| Agent-first operator workflow | 6/10 | Iris, Run Control and contextual recovery work; start/resume/retry/artifacts are incomplete |
+| Full daily OpenClaw replacement | 4/10 | Tools, config, nodes, channels, complete scheduler and recovery are still missing |
+| Production proof | 3/10 | Contract/browser QA is green; credentialed OpenClaw/OpenAI E2E is not yet recorded |
+
+**Overall:** solid functional control-plane foundation, not yet a production
+claim of “OpenClaw is no longer needed for normal operation.”
+
+## Route-by-route evaluation
+
+| Route | Current functional state | OpenClaw integration | Highest-value next improvement |
+|---|---|---|---|
+| `/login` | Owner login, rotating refresh path and return-to-route work; overlapping refresh race fixed | Indirect: protects every facade route | Add passkeys/2FA, device/session management and explicit recovery |
+| `/dashboard` | Live orchestration dominates the workspace; Iris chat is an on-demand modal; model change works | Agents, sessions, tasks, activity, Gateway health and chat are real Nexus-facade data | Add streaming chat, stop/retry, live usage/cost and run-start intent |
+| `/runs` | Functional work graph, inspector, tasks, sessions, approvals, cron and recent activity | Strongest integrated surface; cancel, abort, approve/deny and run-now are wired | Add start/resume/retry/branch, durable run deep links, tool trace and artifact output |
+| `/agents` | Runtime inventory with status, model and workspace-safe metadata | Live `agents.list` plus session state | Add create/import, enable/disable, restart, capability/tool policy and drift |
+| `/agents/:id` | Agent identity, activity and config workspace render; dashboard model selection patches a session | Live agents, sessions, activity and `sessions.patch` | Add session explorer, lifecycle controls, tools, budget, effective permissions and evals |
+| `/projects` | Functional Nexus portfolio and create flow | Shared connection/recovery context; project remains correctly Nexus-owned | Correlate active OpenClaw runs, agents, approvals, usage and artifacts per project |
+| `/projects/:id` | Project detail, progress and task list work | Same explicit runtime boundary | Add “delegate to Iris”, run start, project automation, budget and artifact timeline |
+| `/tasks` | Parent/child task board works and opens real details; horizontal board scrolling is intentional | Shared OpenClaw status and Run Control handoff | Persist task <-> session/run correlation and add retry/resume/cancel at the task |
+| `/tasks/:id` | Detail, children, activity and task mutations work | Runtime boundary is visible, but the Nexus task remains the domain record | Add linked session/run, approvals, tool calls, artifacts and replay |
+| `/memory` | Search, list, selected-file and empty states work | Connection/recovery is explicit; data remains Nexus/workspace-owned | Add OpenClaw ingestion status, scope, provenance, freshness, retention and retrieval evals |
+| `/docs` | Category/search/list/reader and empty states work | Same safe boundary as Memory | Add upload/import, versioning, citations, sync status and approval |
+| `/models` | Live catalog, provider filter, availability reasons and detail dialog work | Direct typed `models.list`; no hardcoded UI catalog | Add OpenAI auth-profile status, primary/alias/fallback policy, limits, budgets and test run |
+| `/activity` | Search, type/source filters and event details work | OpenClaw runtime events and Nexus events share one surface | Add durable correlation ID, actor/diff, pagination, export, retention and trace links |
+| `/calendar` | Live schedule list, next/last run and owner-confirmed run-now work | `cron.list` and admin-scoped `cron.run` | Add create/edit/enable/pause/delete, timezone editor, run history, retry and delivery |
+| `/security` | Real Nexus JWT settings and OpenClaw trust/pairing boundary are visible | Connection, version and trust posture are no longer invented | Add effective scope/policy audit, 2FA/passkeys, sessions/devices, secret rotation and remediation |
+| `/incidents` | Incident list/detail selection and Run Control recovery link work | Runtime status is visible; incident content remains Nexus-owned | Add create/ack/assign/escalate/resolve, event correlation, remediation and postmortem |
+| `/notifications` | Unread state, target routing, mark-read and mark-all work; OpenClaw approvals are summarized | Live approval queue is visible | Add inline decision, snooze, quiet hours, preference routing and incident actions |
+| `/settings` | Profile/password/users plus read-only Gateway diagnostics work | Endpoint, version, protocol, scopes and recovery are visible without secrets | Add paired-device setup, validated config forms, provider policy and controlled reload/rollback |
+
+The old `/chat` page is intentionally removed. Iris is a contextual modal on
+the dashboard and a global entry links to that real destination.
+
+## Capability gaps that still force OpenClaw or break-glass access
+
+### P0
+
+- paired device identity for remote/container Gateway access;
+- one real OpenAI-over-OpenClaw E2E proof with negative auth and reconnect;
+- start, resume, retry and durable deep link for a run/session;
+- durable Nexus task/project <-> OpenClaw run/session correlation;
+- audit/correlation/idempotency for every privileged mutation.
+
+### P1
+
+- agent lifecycle and effective tool permissions;
+- model/auth-profile/fallback/budget policy editing;
+- complete cron CRUD and history;
+- tool/approval trace and artifacts;
+- incident lifecycle and recovery actions;
+- knowledge ingestion, provenance and retrieval evaluation.
+
+### P2
+
+- channels, connectors and node inventory/pairing;
+- config schema forms, diff, backup, reload and rollback;
+- provider usage/cost/latency dashboards;
+- eval datasets, regression gates, export and retention.
+
+## Recommendation
+
+Do not broaden the navigation again yet. The highest-value next slice is one
+real, durable run:
+
+```text
+Iris intent
+  -> create/start OpenClaw run
+  -> correlate Nexus project/task
+  -> observe session and tool events
+  -> owner approval
+  -> artifact/result
+  -> stop/retry/reload recovery
+```
+
+That single path will close more of the “return to OpenClaw” gap than adding
+more read-only pages.
@@ -0,0 +1,107 @@
+# Nexus OpenClaw Core Integration — Design QA
+
+**Stand:** 2026-07-28
+**Reference:** existing Nexus Dashboard design language and approved Run Control
+mockup.
+
+## Visual contract
+
+- Existing Galaxy background, glass panels, blue-violet accents, Manrope,
+  Space Grotesk and JetBrains Mono remain the only design language.
+- Sidebar categories, 248 px desktop rail and 62 px topbar stay consistent.
+- Glows are limited to active navigation, primary actions and meaningful live
+  state.
+- Standard pages remain bounded while Run Control and Task Board keep the wider
+  operational workspace.
+- Iris chat stays hidden until requested, leaving maximum space for live
+  orchestration.
+
+## Same-input comparisons
+
+The required side-by-side comparisons were generated from current-run
+screenshots:
+
+- [Dashboard reference vs current](dashboard-reference-vs-current.png)
+- [Run Control mockup vs functional build](run-control-mock-vs-current.png)
+
+The current Dashboard preserves the reference visual system while removing the
+persistent chat column and secondary dashboard clutter. Run Control is denser
+than the approved mockup because it includes real capability, approval and
+recovery state; the hierarchy, spacing rhythm, color use and panel treatment
+remain consistent.
+
+## Core-page review
+
+[Core pages contact sheet](core-pages-contact-sheet.png)
+
+Observed result:
+
+- all page families use the same sidebar, topbar, background, headings, panels,
+  inputs, buttons, status chips and focus treatment;
+- no route reintroduced the former flat gray legacy shell;
+- empty views on Memory, Docs and Incidents are deliberate content states, not
+  failed layouts;
+- Settings correctly uses a narrower form/diagnostic measure;
+- Task Board keeps an internal horizontal work-surface scroller without causing
+  document-level overflow;
+- no P0, P1 or P2 visual inconsistency remained after the final pass.
+
+## Responsive and geometry QA
+
+[Run Control responsive contact sheet](run-control-responsive-contact-sheet.png)
+
+Every authenticated route was loaded at:
+
+| Viewport | Routes | Document overflow | Visible alerts |
+|---:|---:|---:|---:|
+| 375 x 812 | 17 | 0 | 0 |
+| 768 x 900 | 17 | 0 | 0 |
+| 1024 x 900 | 17 | 0 | 0 |
+| 1440 x 900 | 17 | 0 | 0 |
+| 1920 x 1080 | 17 | 0 | 0 |
+
+The mobile/sidebar drawer, responsive columns and wide orchestration workspace
+all remained usable. The project does not ship a separate mobile product; these
+checks only guarantee that the authenticated web UI does not break at the
+required narrow viewport.
+
+## Interaction and accessibility QA
+
+Verified in the in-app browser:
+
+- categorized desktop and narrow-viewport navigation;
+- direct authenticated deep links after reload;
+- Run Control node selection and inspector update;
+- cancel, approval and cron confirmation dialogs;
+- `Escape` closes detail/confirmation dialogs;
+- Activity and Models search/filter/detail paths;
+- Task Board card to Task Detail navigation;
+- Iris modal open/send/response/close and focus restoration;
+- agent session-model change;
+- notification target routing, mark-read and mark-all-read;
+- explicit labels for buttons, links, dialogs and status regions;
+- final browser console: no warnings or errors.
+
+## State QA
+
+- Loading: Run Control and shared OpenClaw polling show explicit loading state.
+- Empty: every collection keeps its section and explains the absence of data.
+- Error/disconnected: the shared notice reports message, recovery and a working
+  Run Control link; the store never substitutes simulated production data.
+- Unsupported/forbidden: capability state distinguishes missing Gateway methods
+  from missing operator scopes.
+
+The QA fixture is intentionally visible as `QA SIMULATION`; screenshots are
+design/interaction evidence only, not proof of a live OpenClaw deployment.
+
+## Remaining visual debt
+
+No P0–P2 design issue blocks this checkpoint. P3 polish remains:
+
+- finish language consistency between German owner workflows and English
+  runtime vocabulary;
+- add a compact correlation/trace breadcrumb once durable run deep links exist;
+- replace temporary loading copy with skeletons only if measured latency makes
+  it useful;
+- add screenshots for real degraded/version-mismatch states after live Gateway
+  pairing.