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)