From ae1c3dc7e6ad0f26b8e153383cf396d63b21c68b Mon Sep 17 00:00:00 2001 From: Scott Hanselman Date: Mon, 6 Jul 2026 21:41:34 -0700 Subject: [PATCH] Update repository documentation plan Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- AGENTS.md | 3 +- DEVELOPMENT.md | 56 ++++++++++++++++++++-------- README.md | 19 ++-------- docs/A2UI_NATIVE_WINUI.md | 18 +++++---- docs/ACCESSIBILITY.md | 28 ++++++++++++++ docs/CONNECTION_PROTOCOL_RESEARCH.md | 2 +- docs/DATA_FLOW_ARCHITECTURE.md | 2 +- docs/MCP_MODE.md | 30 ++++++++++++++- docs/MISSION_CONTROL.md | 11 +++++- docs/ONBOARDING_WIZARD.md | 2 +- docs/RELEASING.md | 7 ++-- docs/SETUP.md | 2 +- docs/SETUP_ENGINE_REDESIGN.md | 17 ++++++--- docs/TEST_COVERAGE.md | 36 ++++++++++-------- docs/VERSIONING.md | 2 + 15 files changed, 166 insertions(+), 69 deletions(-) create mode 100644 docs/ACCESSIBILITY.md diff --git a/AGENTS.md b/AGENTS.md index 3a58046e8..cc42d2f9d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,7 +13,7 @@ Required steps: 3. Run tray tests: - `dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore` -This is the required local closeout subset for agents. CI also builds and runs additional connection, setup, CLI, UI, integration, and E2E suites; see `docs/TEST_COVERAGE.md` for the broader inventory. +This is the required local closeout subset for agents. CI also builds and runs additional connection, setup, CLI, UI, accessibility, integration, and E2E suites; see `docs/TEST_COVERAGE.md` for the broader test inventory and `.github/workflows/ci.yml` for the workflow source of truth. If a command fails: @@ -77,6 +77,7 @@ Start with these docs before changing connection, pairing, node, MCP, or tray UX - `docs/MCP_MODE.md` - local MCP server mode and the `EnableNodeMode` / `EnableMcpServer` matrix. - `docs/WINDOWS_NODE_TESTING.md` - Windows node capabilities, manual smokes, and gateway-dependent behavior. - `docs/ONBOARDING_WIZARD.md` - first-run setup flow, setup-code/bootstrap pairing, and test isolation. +- `docs/SETUP_ENGINE_REDESIGN.md` - setup pipeline, rollback/logging, Windows node context injection, and setup CLI contract. - `docs/WSL_EXE_ARGV_PITFALL.md` - wsl.exe argv variable-expansion pitfall; required reading before adding any multi-line WSL script through `RunInWslAsync`. ## Architecture Guardrails for Large Refactors diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 56efb46b8..627f0bb81 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -56,10 +56,12 @@ openclaw-windows-hub/ │ │ │ ├── OpenClaw.SetupEngine/ # Local WSL gateway setup and setup-code support │ │ +│ ├── OpenClaw.SetupEngine.UI/ # WinUI setup wizard pages hosted by the tray app +│ │ │ ├── OpenClawTray.FunctionalUI/ # Small in-repo declarative WinUI helper │ │ └── FunctionalUI.cs # Components, hooks, elements, host control │ │ -│ ├── OpenClaw.Tray.WinUI/ # WinUI 3 system tray application (primary) +│ └── OpenClaw.Tray.WinUI/ # WinUI 3 system tray application (primary) │ │ ├── App.xaml.cs # Main application, tray icon, gateway connection │ │ ├── Services/ # Settings, logging, hotkeys, deep links │ │ ├── Windows/ # UI windows (Settings, WebChat, Status, etc.) @@ -71,8 +73,11 @@ openclaw-windows-hub/ │ ├── OpenClaw.Connection.Tests/ # Gateway registry and connection manager tests │ ├── OpenClaw.Tray.Tests/ # Tests for tray helpers (menu, settings, deep links) │ ├── OpenClaw.WinNode.Cli.Tests/ # winnode CLI contract tests -│ ├── OpenClaw.SetupEngine.Tests/ # Setup engine tests -│ └── OpenClaw.Tray.UITests/ # Native WinUI/A2UI UI tests +│ ├── OpenClaw.SetupEngine.Tests/ # Setup engine tests +│ ├── OpenClaw.Tray.UITests/ # Native WinUI/A2UI UI tests +│ ├── OpenClawTray.FunctionalUI.Tests/ # FunctionalUI smoke tests +│ ├── OpenClaw.Tray.IntegrationTests/ # Real-process tray/MCP integration tests +│ └── OpenClaw.E2ETests/ # Gateway-mediated setup/connect E2E suites │ ├── .github/workflows/ │ └── ci.yml # GitHub Actions CI/CD workflow @@ -85,8 +90,9 @@ openclaw-windows-hub/ ### Project Dependencies ``` -OpenClaw.Tray.WinUI ──depends on──▶ OpenClaw.Shared + OpenClaw.Connection + OpenClaw.Chat +OpenClaw.Tray.WinUI ──depends on──▶ OpenClaw.Shared + OpenClaw.Connection + OpenClaw.Chat + OpenClaw.SetupEngine.UI OpenClaw.WinNode.Cli ──depends on──▶ OpenClaw.Shared +OpenClaw.SetupEngine.UI ──wraps──▶ OpenClaw.SetupEngine OpenClaw.SetupEngine ──supports──▶ local WSL gateway setup OpenClaw.*.Tests ──test──▶ corresponding shared, connection, tray, setup, and CLI surfaces ``` @@ -110,11 +116,10 @@ OpenClaw.*.Tests ──test──▶ corresponding shared, connection, tray, s From the repository root: ```bash -dotnet restore -dotnet build +./build.ps1 ``` -This builds all projects (shared library, tray app, setup engine, and CLI tools). +This restores prerequisites as needed and builds the shared library, tray app, setup engine, and CLI tools with the required Windows runtime identifiers. ### Build Individual Projects @@ -125,7 +130,7 @@ dotnet build src/OpenClaw.Shared **Tray App (WinUI):** ```bash -dotnet build src/OpenClaw.Tray.WinUI +dotnet build src/OpenClaw.Tray.WinUI -r win-x64 ``` ### Platform and Architecture Notes @@ -152,7 +157,7 @@ dotnet build The WinUI Tray app is Windows-only but can be built on Linux using: ```bash -dotnet build -p:EnableWindowsTargeting=true +dotnet build src/OpenClaw.Tray.WinUI -r win-x64 -p:EnableWindowsTargeting=true ``` ### Running in Debug Mode @@ -166,13 +171,13 @@ dotnet build -p:EnableWindowsTargeting=true #### Command Line ```bash -dotnet run --project src/OpenClaw.Tray.WinUI +dotnet run --project src/OpenClaw.Tray.WinUI -r win-x64 ``` For verbose output: ```bash -dotnet run --project src/OpenClaw.Tray.WinUI -c Debug +dotnet run --project src/OpenClaw.Tray.WinUI -c Debug -r win-x64 ``` ### Publishing (Self-Contained) @@ -202,6 +207,26 @@ Use the local helper to build unsigned installer EXEs without waiting for CI: `-Fast` uses ZIP/no-solid compression for quick local iteration. CI release builds keep the default LZMA solid compression and Azure signing. +#### Dev identity and side-by-side installs + +Release identity is the default for every configuration. Use `-DevBuild` on `build.ps1` or `-Dev` on `run-app-local.ps1` when you explicitly want the side-by-side dev identity: + +```powershell +.\build.ps1 -Project WinUI -DevBuild +.\run-app-local.ps1 -Dev -Isolated +``` + +`-DevBuild` passes `-p:DevBuild=true` to the WinUI project and produces the dev app identity marker that CI verifies in the **Verify DevBuild identity marker** step. `installer.iss` also accepts `/DDevBuild=1` for side-by-side dev installers; `.\scripts\build-inno-local.ps1 -Dev` wires that flag for local installer iteration. + +#### Onboarding and setup workflow helpers + +The first-run Windows gateway onboarding wizard lives in `OpenClaw.SetupEngine.UI` and is hosted by `OpenClaw.Tray.WinUI`; see [docs/ONBOARDING_WIZARD.md](docs/ONBOARDING_WIZARD.md) for the page flow. The setup pipeline itself is documented in [docs/SETUP_ENGINE_REDESIGN.md](docs/SETUP_ENGINE_REDESIGN.md), including the Windows node context step that injects agent instructions into the WSL workspace. + +Useful local scripts: + +- `.\scripts\dev-reset-rebuild-launch.ps1` resets tray data, rebuilds, and optionally launches the app; add `-WipeWslDistro` for a full local WSL gateway reset. +- `.\scripts\validate-mxc-e2e.ps1` runs the formal WSL Gateway -> Windows node -> `system.run` MXC proof path for MXC-sensitive changes. + ## Architecture Overview ### Native chat surface (FunctionalUI + OpenClaw.Chat) @@ -461,7 +486,7 @@ prompts. ### Running Unit Tests -Two test projects cover the shared library and tray helpers: +The repository has multiple unit, UI, integration, and E2E test projects. Use [docs/TEST_COVERAGE.md](docs/TEST_COVERAGE.md) as the inventory of record. ```bash # Run local-dev tests. E2E is intentionally excluded from the solution and @@ -476,9 +501,10 @@ dotnet test --filter "FullyQualifiedName~AgentActivityTests" ``` **Test Coverage:** -- ✅ **1182 tests** in `OpenClaw.Shared.Tests` — models, gateway client, exec approvals, capabilities, URL helpers, notification categorization, shell quoting, MCP, device identity, and WinNode client coverage -- ✅ **388 tests** in `OpenClaw.Tray.Tests` — settings round-trip, deep link parsing, onboarding state, setup code decoder, gateway health/chat helpers, security validation, wizard step parsing, gateway discovery, localization validation -- ✅ All tests are pure unit tests (no network, no file system, no external dependencies) +- `OpenClaw.Shared.Tests` covers models, gateway client behavior, capabilities, URL helpers, notification categorization, shell quoting, MCP, device identity, and WinNode client contracts. +- `OpenClaw.Tray.Tests` covers settings isolation, deep link parsing, onboarding state, setup code decoding, gateway health/chat helpers, security validation, wizard step parsing, gateway discovery, localization, and tray UI helpers. +- Additional projects cover connection management, setup engine behavior, `winnode`, FunctionalUI, native UI/A2UI, integration, and gateway-mediated E2E flows. +- See [docs/TEST_COVERAGE.md](docs/TEST_COVERAGE.md) for current method counts, runtime totals, and which lanes require network, WSL, real-process, or desktop prerequisites. See [tests/OpenClaw.Shared.Tests/README.md](tests/OpenClaw.Shared.Tests/README.md) for detailed test documentation. diff --git a/README.md b/README.md index d9ba566ee..3424a7162 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,8 @@ This monorepo contains the Windows hub, shared client libraries, and CLI utiliti | **OpenClaw.Cli** | CLI validator for WebSocket connect/send/probe using tray settings | | **OpenClaw.WinNode.Cli** | `winnode` CLI for invoking local Windows node/MCP capabilities | | **OpenClaw.SetupEngine** | Local gateway setup, WSL installation, and setup-code support | +| **OpenClaw.SetupEngine.UI** | WinUI setup wizard pages hosted by the tray app | +| **OpenClawTray.FunctionalUI** | In-repo declarative WinUI helper used by native chat and newer UI surfaces | ## 🚀 Quick Start @@ -401,21 +403,8 @@ Shared library containing: ## Development ### Project Structure -``` -openclaw-windows-node/ -├── src/ -│ ├── OpenClaw.Shared/ # Shared gateway library -│ └── OpenClaw.Tray.WinUI/ # System tray app (WinUI 3) -├── tests/ -│ ├── OpenClaw.Shared.Tests/ # Shared library tests -│ └── OpenClaw.Tray.Tests/ # Tray app helper tests -├── docs/ -│ └── images/ # Screenshots -├── openclaw-windows-node.slnx # Solution file -├── README.md -├── LICENSE -└── .gitignore -``` + +See [DEVELOPMENT.md](DEVELOPMENT.md#project-structure) for the complete and current `src/` and `tests/` project inventory. ### Configuration diff --git a/docs/A2UI_NATIVE_WINUI.md b/docs/A2UI_NATIVE_WINUI.md index 4ed6f23cc..c37ba9eeb 100644 --- a/docs/A2UI_NATIVE_WINUI.md +++ b/docs/A2UI_NATIVE_WINUI.md @@ -1,22 +1,24 @@ # Native WinUI A2UI Canvas — Design Spec -> **Status:** Draft / proposal -> **Audience:** Contributors implementing a native A2UI renderer for the Windows node +> **Status:** Implemented; historical design rationale +> **Audience:** Contributors maintaining the native A2UI renderer for the Windows node > **Target version:** A2UI v0.8 (parity with current openclaw clients), with a v0.9 migration path +The native WinUI renderer is implemented under `src\OpenClaw.Tray.WinUI\A2UI\`. This file preserves the original design rationale; the current source of truth for protocol and component details lives in `docs\a2ui\` (`README.md`, `protocol.md`, `components.md`, and grading notes). Phase 4 / A2UI v0.9 migration has not started. + ## 1. Motivation -Today the Windows node renders A2UI by hosting a WebView2 control (`CanvasWindow`) that navigates to an HTTP page served by the openclaw gateway at `/__openclaw__/a2ui/`. That page bundles `@a2ui/lit` and openclaw's bridge JS. Pushed messages travel `agent → gateway → node (canvas.a2ui.push) → WebView2 → window.__a2ui.receive(msg)`. +Before the native renderer landed, the Windows node rendered A2UI by hosting a WebView2 control (`CanvasWindow`) that navigated to an HTTP page served by the openclaw gateway at `/__openclaw__/a2ui/`. That page bundled `@a2ui/lit` and openclaw's bridge JS. Pushed messages traveled `agent → gateway → node (canvas.a2ui.push) → WebView2 → window.__a2ui.receive(msg)`. -That works, but it has costs: +That worked, but it had costs: -- **Hard gateway dependency.** A node running in MCP-only mode (no gateway connection) silently drops A2UI pushes — `OnCanvasA2UIPush` bails when `_a2uiHostUrl` is null. The renderer code physically lives at the gateway. +- **Hard gateway dependency.** A node running in MCP-only mode (no gateway connection) could silently drop A2UI pushes because the WebView2 renderer code lived at the gateway. - **WebView2 surface area.** Drag/drop, IME, accessibility, focus, DPI, and keyboard shortcuts inherit WebView2 quirks instead of XAML's native behavior. The canvas always feels like an embedded browser. - **Bootstrapping latency.** Each cold start has to ensure WebView2 is ready, navigate, and wait for `window.__a2ui` to register before any message can be delivered (`EnsureA2UIHostAsync` + `ensureA2uiReady` polling). - **Theming drift.** WinUI windows around the canvas use Mica/Fluent; the canvas uses Lit components styled with CSS. Achieving consistent visuals requires duplicate theme work. - **Hardening.** Surface area for arbitrary script execution remains larger than necessary for what is fundamentally a declarative UI tree. -A native WinUI renderer renders A2UI surfaces directly into XAML — no WebView, no HTTP host, no JS bridge. The node becomes self-contained: it can render A2UI whether it's connected to a gateway, an MCP client, or both. +The implemented native WinUI renderer renders A2UI surfaces directly into XAML — no WebView, no HTTP host, no JS bridge. The node is self-contained: it can render A2UI whether it's connected to a gateway, an MCP client, or both. ## 2. Goals & non-goals @@ -267,12 +269,14 @@ Mirror what `CanvasCapability` already logs: ## 13. Phasing +This table is historical. Phases 0-3 are now implemented by the native renderer path; no `--canvas=web` coexistence flag shipped. Phase 4 / v0.9 migration has not started. + | Phase | Scope | Exit criteria | |---|---|---| | **0 — Spike** | `Text`, `Column`, `Button` only; one surface; no data model | Single button click round-trips to agent | | **1 — Catalog parity** | All v0.8 standard catalog types; data model + bindings; modal/tabs | Full conformance fixtures pass | | **2 — Polish** | Theming, transitions, focus management, accessibility (Narrator), keyboard nav | A11y audit clean; UX review against Lit version | -| **3 — Coexistence** | Native window default; WebView2 path retained behind `--canvas=web` flag for parity testing | No regressions in WebView2 path | +| **3 — Native default** | Native window default for A2UI rendering | Native path covers the v0.8 surface without the WebView2 host | | **4 — v0.9 migration** | Bidirectional messages, modular schemas, prompt-first | Tracks Google A2UI v0.9 release | ## 14. Open questions diff --git a/docs/ACCESSIBILITY.md b/docs/ACCESSIBILITY.md new file mode 100644 index 000000000..a994c4959 --- /dev/null +++ b/docs/ACCESSIBILITY.md @@ -0,0 +1,28 @@ +# Accessibility validation + +OpenClaw Companion treats accessibility as a CI quality gate for the WinUI app. The Build and Test workflow runs real-process Axe.Windows scans against the tray UI test project after the normal native UI tests. + +## What CI enforces + +The `.github\workflows\ci.yml` **Run Accessibility Tests (Axe.Windows)** step runs: + +```powershell +dotnet test tests\OpenClaw.Tray.UITests --no-build -c Debug -r win-x64 --filter Category=Accessibility +``` + +Those tests launch the app in a real Windows desktop process and scan pages for WCAG violations through Axe.Windows. Failures are summarized in the GitHub Actions step summary and written to `Accessibility.trx`. + +## Running locally + +From the repository root: + +```powershell +dotnet build tests\OpenClaw.Tray.UITests -c Debug -r win-x64 +dotnet test tests\OpenClaw.Tray.UITests -c Debug -r win-x64 --no-build --filter Category=Accessibility +``` + +Run this lane for UI changes that add or modify pages, dialogs, controls, focus behavior, labels, contrast-sensitive visuals, or keyboard navigation. + +## Relationship to other validation + +Accessibility scans do not replace the required agent closeout validation in `AGENTS.md`. They are an additional focused lane for WinUI accessibility work and a formal CI gate documented in `docs\TEST_COVERAGE.md`. diff --git a/docs/CONNECTION_PROTOCOL_RESEARCH.md b/docs/CONNECTION_PROTOCOL_RESEARCH.md index d072f90fd..e35151058 100644 --- a/docs/CONNECTION_PROTOCOL_RESEARCH.md +++ b/docs/CONNECTION_PROTOCOL_RESEARCH.md @@ -47,7 +47,7 @@ Public upstream gateway sources reviewed: - `https://github.com/openclaw/openclaw/blob/main/src/gateway/server-methods/nodes.ts` - `https://github.com/openclaw/openclaw/blob/main/packages/gateway-protocol/src/schema/frames.ts` -The setup engine currently pins gateway LKG `2026.6.1` in +The setup engine currently pins gateway LKG `2026.6.11` in `src/OpenClaw.SetupEngine/GatewayLkgVersion.cs`. Before implementing behavior that depends on newer upstream `main`, compare the installed LKG against the reviewed upstream docs/code. diff --git a/docs/DATA_FLOW_ARCHITECTURE.md b/docs/DATA_FLOW_ARCHITECTURE.md index 42cedf07e..d33643a70 100644 --- a/docs/DATA_FLOW_ARCHITECTURE.md +++ b/docs/DATA_FLOW_ARCHITECTURE.md @@ -47,7 +47,7 @@ src/OpenClaw.Tray.WinUI/Services/AppState.cs ### GatewayService (`Services/GatewayService.cs`) -Owns all 27 operator gateway client event subscriptions. Moved from App.xaml.cs to separate concerns. +Owns the operator gateway client event subscriptions, including data events and connection lifecycle events. Moved from App.xaml.cs to separate concerns. ``` src/OpenClaw.Tray.WinUI/Services/GatewayService.cs diff --git a/docs/MCP_MODE.md b/docs/MCP_MODE.md index a93ea0037..0065dd2d3 100644 --- a/docs/MCP_MODE.md +++ b/docs/MCP_MODE.md @@ -4,7 +4,7 @@ ## Summary -The Windows tray app now ships a **local Model Context Protocol (MCP) server** alongside its existing OpenClaw gateway client. The same node capabilities the agent reaches over the OpenClaw gateway WebSocket — `system.run`, `screen.snapshot`, `canvas.*`, `camera.list`, `camera.snap`, `camera.clip`, `location.get`, `tts.speak`, `system.notify`, `system.execApprovals.*` — are advertised, on the same machine, as MCP tools over `http://127.0.0.1:8765/`. +The Windows tray app now ships a **local Model Context Protocol (MCP) server** alongside its existing OpenClaw gateway client. The same node capabilities the agent reaches over the OpenClaw gateway WebSocket — `system.*`, `screen.*`, `canvas.*`, `camera.*`, `location.get`, `tts.*`, `stt.*`, `device.*`, and `browser.proxy` — are advertised, on the same machine, as MCP tools over `http://127.0.0.1:8765/`. Local-only `app.*` and `app.connection.*` tools are also exposed to MCP clients for tray automation and connection/pairing workflows; those are not registered with the remote gateway node transport. This means any local MCP client (Claude Desktop, Claude Code, Cursor, an MCP-aware CLI, a custom dev script) can reach into the running tray and drive Windows-native capabilities directly, without an OpenClaw gateway in the loop. The tray app can run in **MCP-only mode** with no gateway connection at all. @@ -153,6 +153,34 @@ The exact same node tools the OpenClaw gateway uses are now invocable by any loc In all cases the user gets a Windows-native agent experience without OpenClaw infrastructure. They can be entirely offline w.r.t. an OpenClaw gateway and still hand the LLM a working set of "do something on my Windows box" tools. +### Current command surface + +The canonical command descriptions live in `OpenClaw.Shared\Mcp\McpToolBridge.CommandDescriptions`; `OpenClaw.WinNode.Cli.Tests\SkillMdDriftTests` keeps `src\OpenClaw.WinNode.Cli\skill.md` in sync with that documented capability surface. The live `tools/list` output may also include newly registered capabilities with fallback descriptions before prose is updated. + +Gateway/node command groups currently include: + +- `system.notify`, `system.run`, `system.run.prepare`, `system.which`, `system.execApprovals.get`, `system.execApprovals.set` +- `canvas.present`, `canvas.hide`, `canvas.navigate`, `canvas.eval`, `canvas.snapshot`, `canvas.a2ui.push`, `canvas.a2ui.reset`, `canvas.a2ui.dump`, `canvas.caps`, `canvas.a2ui.pushJSONL` +- `screen.snapshot`, `screen.record` +- `camera.list`, `camera.snap`, `camera.clip` +- `stt.transcribe`, `stt.listen`, `stt.status` +- `tts.speak`, `tts.status` +- `location.get` +- `device.info`, `device.status` +- `browser.proxy` + +Local MCP-only app control commands currently include: + +- `app.navigate`, `app.status`, `app.sessions`, `app.agents`, `app.nodes`, `app.config.get`, `app.settings.get`, `app.settings.set`, `app.menu`, `app.search`, `app.dashboard.url` +- Chat automation: `app.chat.snapshot`, `app.chat.send`, `app.chat.reset` +- Connection automation: `app.connection.applySetupCode`, `app.connection.connectSharedToken`, `app.connection.pendingApprovals`, `app.connection.approveDevicePairing`, `app.connection.rejectDevicePairing`, `app.connection.approveNodePairing`, `app.connection.rejectNodePairing`, `app.connection.reconnect`, `app.connection.reconnectNode` + +Example chat automation smoke: + +```powershell +winnode --command app.chat.send --params '{"message":"hello from local MCP"}' +``` + ### Dev acceleration when building new features This is the strongest argument for making MCP a first-class citizen, not an afterthought. diff --git a/docs/MISSION_CONTROL.md b/docs/MISSION_CONTROL.md index 3c1394ed8..d3629853d 100644 --- a/docs/MISSION_CONTROL.md +++ b/docs/MISSION_CONTROL.md @@ -22,7 +22,7 @@ The main product decision is deliberate: **do not make a native Windows gateway Windows now has a strong foundation: -- Node Mode with canvas, camera, screen snapshot/record, location, device info/status, system commands, notifications, and exec approval policy. +- Node Mode with canvas, camera, screen snapshot/record, location, device info/status, system commands, notifications, exec approval policy, and local MCP `app.chat.*` automation commands. - Command Center status detail window with channels, sessions, usage, local/operator node inventory, allowlist diagnostics, pairing warnings, and activity stream. - SSH tunnel settings and service. - Activity Stream and support-bundle copy path that avoid storing invoke payloads. @@ -465,6 +465,15 @@ Deliverables: - Hover HUD / richer tray tooltip: **implemented with topology, channel, node, warning, and activity summary** - Update status: **implemented in Command Center support/debug section and copied support context, including current version, latest prompted version when known, and last check outcome** +Recent native chat behavior implemented during this phase: + +- Queued-message UI tracks local send state (`Queued`, `Sending`, `Failed`) until the gateway confirms or rejects the turn. +- Timeline virtualization keeps long chat histories responsive while preserving stable render identity for visible entries. +- Completed sessions are hidden by default in the native chat session list, with active/in-progress sessions surfaced first. +- TTS notification speech preserves full assistant text while UI preview truncation remains visual-only. +- Slash-command suggestions use the gateway command catalog grouped into Mac-compatible command buckets. +- Local MCP chat automation exposes `app.chat.snapshot`, `app.chat.send`, and `app.chat.reset` for current-thread inspection, send, and reset flows. + Risk: medium; mostly UI and gateway method plumbing. ### Phase 8: Optional local Windows gateway convenience diff --git a/docs/ONBOARDING_WIZARD.md b/docs/ONBOARDING_WIZARD.md index 2eb44c4f8..26d6ba6d6 100644 --- a/docs/ONBOARDING_WIZARD.md +++ b/docs/ONBOARDING_WIZARD.md @@ -16,7 +16,7 @@ The setup flow walks users through: 6. **OpenClaw onboard** — Gateway-driven provider/model/key configuration 7. **All set** — Feature summary, startup preference, and completion -The setup flow no longer configures remote/manual gateways inline. The Welcome page's **Connect to an existing gateway** option closes setup and opens the tray app's Connections tab. +The setup flow no longer configures remote/manual gateways inline. The Welcome page's **Connect to an existing gateway** option routes through `AdvancedSetupPage`, closes setup, and opens the tray app's Connections tab. ## Screen Details diff --git a/docs/RELEASING.md b/docs/RELEASING.md index b24bc8a62..87f3b429f 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -161,12 +161,11 @@ For alpha tags, the **Build and Test** workflow should run: - `repo-hygiene` - `test` -- `e2etests` -- `build (win-x64)` -- `build (win-arm64)` +- `e2etests` shards: `setup-connect`, `revocation-recovery`, and `network-recovery` +- `build` matrix entries shown by GitHub as `build (win-x64)` and `build (win-arm64)` - `release` -MSIX jobs may appear as skipped while MSIX is paused. +The `setup-connect` E2E shard contains the MXC proof tests for the gateway -> Windows node -> `system.run` path and validates that the expected proof test names appear in the TRX output. GitHub-hosted runners may report those MXC proofs as skipped when the host is not MXC-capable; use `.\scripts\validate-mxc-e2e.ps1` for required local/self-hosted MXC merge validation. The `build-msix` job is disabled with `if: false` while MSIX is paused for alpha releases, so it should not appear in the required run list. The release job should: diff --git a/docs/SETUP.md b/docs/SETUP.md index 3d9217d0b..5ed6d17ad 100644 --- a/docs/SETUP.md +++ b/docs/SETUP.md @@ -9,7 +9,7 @@ Before installing, make sure you have: - **Windows 10 (20H2 or later)** or **Windows 11** - **WebView2 Runtime** — pre-installed on Windows 11 and most up-to-date Windows 10 systems. If missing, download from [Microsoft Edge WebView2](https://developer.microsoft.com/microsoft-edge/webview2/). -You do **not** need a pre-existing local OpenClaw gateway before installing. On first launch, OpenClaw Companion can install a dedicated local WSL gateway for you, or you can use **Advanced setup** to connect to an existing local, remote, or manually configured gateway. +You do **not** need a pre-existing local OpenClaw gateway before installing. On first launch, OpenClaw Companion can install a dedicated local WSL gateway for you, or you can use **Advanced setup** to connect to an existing local, remote, or manually configured gateway. See [Onboarding Wizard](ONBOARDING_WIZARD.md) for the install-new-WSL and connect-existing handoff flow. New to the OpenClaw roles? Read [Operator and node concepts](OPERATOR_NODE_CONCEPTS.md) for a short glossary of gateway, local WSL gateway, operator, node, pairing, reapproval, and allowlisted node capabilities before starting setup. diff --git a/docs/SETUP_ENGINE_REDESIGN.md b/docs/SETUP_ENGINE_REDESIGN.md index aa55fa6ba..0fcc7111a 100644 --- a/docs/SETUP_ENGINE_REDESIGN.md +++ b/docs/SETUP_ENGINE_REDESIGN.md @@ -4,12 +4,14 @@ The Setup Engine is a **config-driven system** for provisioning an OpenClaw WSL gateway from scratch. It consists of two setup projects plus the tray host: -1. **`OpenClaw.SetupEngine`** — Headless pipeline library. Runs 18 steps sequentially with full JSONL logging, transaction journal, and rollback support. +1. **`OpenClaw.SetupEngine`** — Headless pipeline library. Runs 19 steps sequentially with full JSONL logging, transaction journal, and rollback support. 2. **`OpenClaw.SetupEngine.UI`** — WinUI3 setup window/pages that wrap the same pipeline with a fluent wizard UI. 3. **`OpenClaw.Tray.WinUI`** — The only shipped WinUI executable. It hosts `SetupWindow` directly and self-restarts after successful setup. The bundled `default-config.json` ships with the tray executable and provides secure defaults (loopback bind, WSL isolation, systemd enabled). Defaults can be overridden via config file or environment variables. +> **Status note (2026-07-06):** Current default setup includes `WindowsNodeBootstrapContextStep`, which injects Windows-node context into the WSL workspace `AGENTS.md` after onboarding. + --- ## Architecture @@ -18,7 +20,7 @@ The bundled `default-config.json` ships with the tray executable and provides se ┌─────────────────────────────────────────────────────────────┐ │ OpenClaw.SetupEngine (net10.0 library) │ │ │ -│ SetupPipeline ──→ 18 SetupStep classes ──→ StepResult │ +│ SetupPipeline ──→ 19 SetupStep classes ──→ StepResult │ │ │ │ │ │ SetupContext CommandRunner (WSL + Process) │ │ SetupConfig TransactionJournal (JSONL) │ @@ -164,7 +166,7 @@ src/OpenClaw.SetupEngine.UI/ --- -## Pipeline Steps (18 total) +## Pipeline Steps (19 total) Executed sequentially. Each step is a small class (30–120 lines) in `SetupSteps.cs`. @@ -187,7 +189,8 @@ Executed sequentially. Each step is a small class (30–120 lines) in `SetupStep | 15 | `PairNodeStep` | WebSocket node connection + capability registration | | 16 | `VerifyEndToEndStep` | End-to-end health check (operator → node round trip) | | 17 | `RunGatewayWizardStep` | Run/configure the gateway wizard unless skipped | -| 18 | `StartKeepaliveStep` | Background WSL keepalive to prevent VM shutdown | +| 18 | `WindowsNodeBootstrapContextStep` | Inject Windows-node context into the WSL workspace `AGENTS.md` | +| 19 | `StartKeepaliveStep` | Background WSL keepalive to prevent VM shutdown | ### Step Base Class @@ -253,7 +256,7 @@ Structured JSONL logger. Records sanitized entries for: - State transitions - Errors with stack traces -Log path defaults to `%APPDATA%\OpenClawTray\Logs\Setup\setup-.log` +Log path defaults to `%APPDATA%\OpenClawTray\Logs\Setup\setup-engine-.jsonl` for setup and `uninstall-engine-.jsonl` for uninstall. --- @@ -314,7 +317,9 @@ OpenClaw.SetupEngine.Program.Main(["--no-rollback-on-failure"]) OpenClaw.SetupEngine.Program.Main(["--log-path", "./trace.log"]) ``` -Exit codes: 0 = success, 1 = failure +Common flags include `--config`, `--headless`, `--dry-run`, `--rollback-on-failure`, `--no-rollback-on-failure`, `--log-path`, `--gateway-port`, and uninstall safety flags such as `--uninstall` plus `--confirm-destructive`. + +Exit codes: 0 = success, 1 = pipeline failure, 2 = bad arguments or setup lock/safety failure, 3 = cancelled ### UI (hosted by tray) diff --git a/docs/TEST_COVERAGE.md b/docs/TEST_COVERAGE.md index 53e3aaaa4..84b0c0cb0 100644 --- a/docs/TEST_COVERAGE.md +++ b/docs/TEST_COVERAGE.md @@ -1,6 +1,6 @@ # Test Coverage Summary -**Last audited**: 2026-07-01
+**Last audited**: 2026-07-06
**Framework**: xUnit / .NET 10.0
**Required validation status**: passing (`.\build.ps1`, Shared tests, Tray tests) @@ -11,28 +11,27 @@ These are the suites every agent must run after code changes, as documented in | Suite | Latest runtime result | |---|---:| -| `OpenClaw.Shared.Tests` | 2,720 total: 2,689 passed, 31 skipped | -| `OpenClaw.Tray.Tests` | 1,452 total: 1,452 passed, 0 skipped | +| `OpenClaw.Shared.Tests` | 2,734 total: 2,703 passed, 31 skipped | +| `OpenClaw.Tray.Tests` | 1,584 total: 1,584 passed, 0 skipped | -Runtime totals come from `dotnet test` on 2026-07-01. They are higher than +Runtime totals come from `dotnet test` on 2026-07-06. They are higher than method counts because some `[Theory]` tests expand into multiple cases. ## Test project inventory | Project | Primary scope | Test methods | |---|---|---:| -| `OpenClaw.Connection.Tests` | Gateway registry, credential resolution, connection manager/state machine, setup codes, pairing, diagnostics | 307 | -| `OpenClaw.Shared.Tests` | Shared models, gateway client, capabilities, MCP, exec approval, A2UI security, URL handling, notification categorization | 1,932 | -| `OpenClaw.Tray.Tests` | Tray state/UI helpers, settings isolation, onboarding, connection page behavior, localization, local gateway setup/uninstall | 1,131 | -| `OpenClaw.Tray.UITests` | Native WinUI/A2UI control and rendering coverage | 61 | -| `OpenClaw.WinNode.Cli.Tests` | Windows node CLI argument parsing, command behavior, JSON output, uninstall flow | 83 | -| `OpenClaw.SetupEngine.Tests` | Setup engine, WSL gateway installation, setup-code, and local setup policy coverage | 244 | +| `OpenClaw.Connection.Tests` | Gateway registry, credential resolution, connection manager/state machine, setup codes, pairing, diagnostics | 325 | +| `OpenClaw.Shared.Tests` | Shared models, gateway client, capabilities, MCP, exec approval, A2UI security, URL handling, notification categorization | 1,977 | +| `OpenClaw.Tray.Tests` | Tray state/UI helpers, settings isolation, onboarding, connection page behavior, localization, local gateway setup/uninstall | 1,240 | +| `OpenClaw.Tray.UITests` | Native WinUI/A2UI control, rendering, and accessibility scan coverage | 64 | +| `OpenClaw.WinNode.Cli.Tests` | Windows node CLI argument parsing, command behavior, JSON output, uninstall flow | 89 | +| `OpenClaw.SetupEngine.Tests` | Setup engine, WSL gateway installation, setup-code, and local setup policy coverage | 284 | | `OpenClawTray.FunctionalUI.Tests` | Functional UI smoke coverage | 10 | -| `OpenClaw.E2ETests` | Gateway-mediated setup/connect, revocation recovery, and network recovery suites | 0 | -| `OpenClaw.Tray.IntegrationTests` | Integration-test project scaffold; no `[Fact]`/`[Theory]` methods currently | 0 | +| `OpenClaw.E2ETests` | Gateway-mediated setup/connect, revocation recovery, and network recovery suites | 21 | +| `OpenClaw.Tray.IntegrationTests` | Real-process tray/MCP integration tests gated by `OPENCLAW_RUN_INTEGRATION=1` | 18 | -The method inventory is a source scan of `[Fact]` and `[Theory]` attributes. Use -`dotnet test` for authoritative runtime totals. +The method inventory is a source scan of `[Fact]`, `[Theory]`, and repo custom xUnit attributes such as `[E2EFact]`, `[MxcE2EFact]`, and `[IntegrationFact]`. Use `dotnet test` for authoritative runtime totals. ## Coverage highlights @@ -60,7 +59,9 @@ The method inventory is a source scan of `[Fact]` and `[Theory]` attributes. Use - **OpenClaw.WinNode.Cli.Tests** covers the standalone Windows node CLI contract. - **OpenClaw.SetupEngine.Tests** covers gateway setup and local WSL installation policy. - **OpenClawTray.FunctionalUI.Tests** covers newer UI surfaces outside the main tray test project. -- **OpenClaw.E2ETests** is exercised by CI with trait filters even though the project currently has no direct `[Fact]`/`[Theory]` method inventory. +- **OpenClaw.E2ETests** uses custom `[E2EFact]` / `[MxcE2EFact]` attributes that inherit xUnit `FactAttribute`; CI exercises them with shard filters. +- **OpenClaw.Tray.IntegrationTests** uses custom `[IntegrationFact]` attributes and runs only when `OPENCLAW_RUN_INTEGRATION=1`. +- **PackagingTests** is a PowerShell-script lane under `tests\PackagingTests\`, not a dotnet test project. ## Formal validation paths @@ -71,9 +72,11 @@ required closeout lane for code changes. |---|---|---| | Required closeout | `.\build.ps1`, Shared tests, Tray tests | Every code change and every agent closeout | | GitHub-hosted PR/main CI | `.github\workflows\ci.yml` | Every pull request and push to `main`; runs normal E2E shards but skips MXC proofs on hosted runners | +| Accessibility scan | `dotnet test .\tests\OpenClaw.Tray.UITests\OpenClaw.Tray.UITests.csproj -r win-x64 --filter Category=Accessibility` | UI changes and CI quality gate; runs real-process Axe.Windows scans; see `docs\ACCESSIBILITY.md` | | Local E2E | `OPENCLAW_RUN_E2E=1` with `OpenClaw.E2ETests` | Gateway setup/connect, recovery, or pairing changes that need real WSL Gateway coverage | | Local MXC E2E | `.\scripts\validate-mxc-e2e.ps1` | MXC sandboxing, `system.run`, exec approvals, Windows node command execution, gateway setup/connect changes that affect MXC | | Product WSL setup validation | `.\scripts\validate-wsl-gateway.ps1` | Tray onboarding/setup-engine changes that must prove the product WSL install path | +| Packaging script checks | `powershell -File .\tests\PackagingTests\Test-InnoUninstallOrdering.ps1` | Installer script changes that affect uninstall or cleanup ordering | ## Running tests @@ -96,6 +99,9 @@ dotnet test .\tests\OpenClaw.E2ETests\OpenClaw.E2ETests.csproj -r win-x64 # itself and fails when MXC proofs skip unless -AllowSkip is explicitly supplied. .\scripts\validate-mxc-e2e.ps1 +# Accessibility scan, matching the CI quality gate. +dotnet test .\tests\OpenClaw.Tray.UITests\OpenClaw.Tray.UITests.csproj -r win-x64 --filter Category=Accessibility + # Single project dotnet test .\tests\OpenClaw.Connection.Tests\OpenClaw.Connection.Tests.csproj diff --git a/docs/VERSIONING.md b/docs/VERSIONING.md index 931261a18..3314672d1 100644 --- a/docs/VERSIONING.md +++ b/docs/VERSIONING.md @@ -15,6 +15,8 @@ imports GitVersion through `src\Directory.Build.props`, so normal `dotnet build` `.\build.ps1`, `.\run-app-local.ps1`, and CI builds all derive assembly metadata from the same tag history. +The repository-local tool manifest (`.config\dotnet-tools.json`) and MSBuild package reference (`src\Directory.Build.props`) are the authoritative local tool/package pins and currently target GitVersion 6.8.1. The CI workflow's `gittools/actions/gitversion/setup` step currently pins `6.4.x` for workflow output computation; if workflow files are being changed, prefer aligning that setup action to `6.8.x`. Until then, CI's tag/SemVer verification remains the release-blocking guard against version drift. + ## Tagged and untagged builds Tagged releases must resolve to the exact tag SemVer: