diff --git a/docs/concepts/backends.md b/docs/concepts/backends.md index 7c2f848..aacd543 100644 --- a/docs/concepts/backends.md +++ b/docs/concepts/backends.md @@ -2,14 +2,15 @@ A compiled workflow does not care what is underneath it. The runtime sits behind a small four-method `Backend` protocol (screenshot in; click, type, key, scroll -out), so the same bundle, the same resolution ladder, and the same identity gate -run against a browser, a native Windows desktop, or a pixel-only remote session. +out), so the same bundle, resolution ladder, identity gate, effect checks, and +reporting run against browser, Windows, macOS, Linux, RDP, and Citrix/VDI. Backends are **adapters, not rewrites**. !!! tip "Selecting a backend on the CLI" `record`, `replay`, `run`, and `resume` take - [`--backend {web,windows,rdp}`](../reference/cli.md#backend) (with - `--agent-url` for Windows and `--rdp-host` for RDP). The default is `web`. + [`--backend {web,windows,macos,linux,rdp,citrix}`](../reference/cli.md#backend). + Each native backend has an exact target selector; governed Citrix `run` + also requires a readiness marker. The default is `web`. See [Choosing a backend](../reference/cli.md#backend). ## Vision-first, not vision-only @@ -83,6 +84,40 @@ selection, and stale-target rejection. The older `/execute_windows` compatibility route remains a migration surface and is disabled by default; it is not the production RPC contract. +### Desktop: native macOS + +The native macOS backend captures and drives one exact application window. It +uses the owner plus an optional title substring to bind the target, refuses +ambiguous or non-frontmost windows before input, and fails loud when Screen +Recording or Accessibility permission is unavailable. + +!!! info "macOS qualification evidence" + On one macOS 15.7.3 arm64 host, counted candidate `b1b61a5` completed 3/3 + exact-byte TextEdit trials and refused a two-window ambiguity without + changing either file, with 0 silent incorrect successes and 0 over-halts. + The immutable original report remains failed because cleanup warnings were + classified as a batch failure; a separate SHA-256-bound adjudication + verified actual cleanup and accepts only the action-effect and + ambiguity-refusal evidence. Review [Flow PR #135](https://github.com/OpenAdaptAI/openadapt-flow/pull/135) + and the [exact adjudication](https://github.com/OpenAdaptAI/openadapt-flow/blob/ca1b522cad215875f7471782283f8f8bb8e6c998/benchmark/macos_native/textedit_counted_3plus1_b1b61a5_20260717.adjudication.json). + +### Desktop: native Linux (AT-SPI) + +`LinuxBackend` binds one exact AT-SPI application and top-level window, resolves +structural controls, and revalidates the target fingerprint immediately before +actuation. `--linux-allow-physical-input` is an explicit X11-only fallback when +native AT-SPI actuation is unavailable; it is never selected silently. + +!!! info "Linux qualification evidence" + Required current-main job + [`linux-atspi-x11`](https://github.com/OpenAdaptAI/openadapt-flow/actions/runs/30059807758/job/89378981573) + at exact commit `3de5fc67` confirmed 3/3 independently checked exact-file + effects, 3/3 ambiguity refusals, and 3/3 stale-target refusals on a fresh + GTK3 process per trial. It recorded 0 silent incorrect successes, + 0 over-halts, 0 operator interventions, and 0 model calls. The scope is the + in-tree GTK3 fixture on isolated Ubuntu 24.04 X11/AT-SPI, not Wayland or + arbitrary third-party applications. + ### Remote: RDP (pixel-only) The `FreeRDPBackend` drives a legacy application over **RDP**, read pixel-only: @@ -111,37 +146,39 @@ there. [Flow PR #142](https://github.com/OpenAdaptAI/openadapt-flow/pull/142) and the [immutable sanitized report](https://github.com/OpenAdaptAI/openadapt-flow/blob/6610d24cebba27918b8ea507b2f05a094057ac85/benchmark/rdp/results_82a658a_20260718.sanitized.json). + A separate full governed lifecycle uses the swappable transport contract + over a real FreeRDP3 client/server round trip. It recorded, compiled, and + replayed a synthetic note write with 3/3 healthy effects and 3/3 + drift safe-halts, zero model calls, silent incorrect successes, false + completions, drift writes, or healthy over-halts. That result is scoped to + a synthetic Linux Tk task and simulated drift on the real RDP session; it + is not the Aardwolf transport or a Windows-app qualification. Review + [Flow PR #177](https://github.com/OpenAdaptAI/openadapt-flow/pull/177) and + the [accepted FreeRDP lifecycle report](https://github.com/OpenAdaptAI/openadapt-flow/blob/affedc5f1f0de533a0744deaa8e30a203c91c6b3/benchmark/rdp_ladder/results.json). + ### Remote-display / Citrix / VDI (pixel-only) -Citrix and other virtual-desktop surfaces are first-class substrates. They are -driven pixel-first through the same remote-display adapter that captures a named -application window and injects input at screen coordinates, the exact mechanism -the vision-first runtime was built for. The same bundle, resolution ladder, -identity gate, and effect verification apply here as everywhere else. - -Each Citrix/VDI deployment is qualified in its real ICA/HDX environment, where -the client's compression and latency, DPI mapping, credentials and lock -screens, and synthetic-input acceptance are exercised against the actual -application: the same "qualify the workflow in its real environment" step every -substrate goes through. - -### Native macOS - -A native exact-window candidate in [Flow PR #135](https://github.com/OpenAdaptAI/openadapt-flow/pull/135) -captures only a uniquely selected application window, refuses ambiguous or -non-frontmost targets, and fails before input when Screen Recording or -Accessibility access is missing. On one macOS 15.7.3 arm64 host, counted -candidate `b1b61a5` completed 3/3 exact-byte TextEdit trials and refused a -two-window ambiguity without changing either file, with 0 silent incorrect -successes and 0 over-halts. - -The [immutable original report](https://github.com/OpenAdaptAI/openadapt-flow/blob/ca1b522cad215875f7471782283f8f8bb8e6c998/benchmark/macos_native/textedit_counted_3plus1_b1b61a5_20260717.json) -still says `status: failed`: its graceful-close cleanup warnings were classified -as a batch failure. A separate [SHA-256-bound adjudication](https://github.com/OpenAdaptAI/openadapt-flow/blob/ca1b522cad215875f7471782283f8f8bb8e6c998/benchmark/macos_native/textedit_counted_3plus1_b1b61a5_20260717.adjudication.json) -verified all exact harness PIDs and the temporary root were absent, preserved -the original result, and accepted only the action-effect and ambiguity-refusal -evidence. This is one-host TextEdit evidence, not clean-machine, design-partner, -production, broad-app, AX structural-resolution, or general macOS acceptance. +`CitrixWorkspaceBackend` is the released, dedicated `--backend citrix` path. It +selects the exact Citrix Workspace/Viewer owner for the host OS, optionally +binds an exact window title, refuses ambiguous targets, requires a visible +readiness marker for governed `run`, and carries the closed target into durable +resume. It is pixel-only by construction, so the same visual resolution, +identity, effect, policy, and halt contracts run without pretending a DOM or +accessibility tree exists. + +!!! info "Citrix qualification evidence" + The accepted no-DOM qualification completed 3/3 healthy effects and 3/3 + severe-drift safe-halts, with 0 model calls, silent incorrect successes, + false completions, healthy over-halts, or drift writes. Review + [Flow PR #183](https://github.com/OpenAdaptAI/openadapt-flow/pull/183) and + the [immutable report](https://github.com/OpenAdaptAI/openadapt-flow/blob/f6faac5b900b78cbda5980de0e983a9f987285ac/benchmark/citrix_workspace/results.json). + + The accepted artifact explicitly records `code_readiness_accepted: true` + and `ica_hdx_accepted: false`. It qualifies the shipped Workspace-window + backend contract over a no-DOM canvas stand-in, not a counted real ICA/HDX + batch. The exact client, codec, latency, DPI, lock/readiness, input, + identity, and effect matrix is qualified separately for consequential + ICA/HDX use. ## Status at a glance @@ -150,8 +187,9 @@ production, broad-app, AX structural-resolution, or general macOS acceptance. | Playwright (web) | Browser DOM | Yes (DOM) | Structured text (DOM) | **First-class**: structured DOM identity | | `WindowsBackend` | Native Windows | Via UIA | UI Automation `Name`/`Value` | **First-class**: UIA structured identity | | Native macOS | Native macOS | Exact window candidate; AX candidate metadata | Window identity and pixel/OCR floor | **First-class**: window identity and AX metadata | +| `LinuxBackend` | Native Linux | Yes (AT-SPI) | Exact app/window plus AT-SPI role/name/fingerprint | **First-class**: AT-SPI structured identity | | `FreeRDPBackend` | Pixel-only network RDP | No | Pixel / OCR floor | **First-class**: pixel/OCR identity floor | -| Citrix / VDI | ICA/HDX remote application | Deployment-dependent | Pixel / OCR floor unless the client exposes more | **First-class**: pixel/OCR identity floor via the client | +| `CitrixWorkspaceBackend` | Citrix Workspace / VDI window | No | Exact Workspace owner/title/readiness plus pixel/OCR floor | **First-class**: governed pixel identity floor | Every backend runs the same bundle, resolution ladder, identity gate, and effect verification. What varies per substrate is how high up the diff --git a/docs/concepts/demonstration-compiler.md b/docs/concepts/demonstration-compiler.md index ff9cbbe..e6c46fd 100644 --- a/docs/concepts/demonstration-compiler.md +++ b/docs/concepts/demonstration-compiler.md @@ -54,10 +54,11 @@ openadapt flow replay bundle --url https://your.app # replay, local, $0 ``` On the web substrate shown here, `record` opens a headed browser on your own app -and captures what you do; the same loop records a native Windows desktop or a -pixel-only Citrix/RDP session by choosing a [backend](backends.md) instead of a -`--url`. `compile` turns the recording into a bundle. `replay` runs the bundle -deterministically on the same substrate and writes an illustrated report. +and captures what you do. The same loop records native Windows, macOS, or Linux +applications and pixel-only RDP or Citrix sessions by choosing a +[backend](backends.md) instead of a `--url`. `compile` turns the recording into +a bundle. `replay` runs the bundle deterministically on the same substrate and +writes an illustrated report. ## Vision-first behind a small backend @@ -66,9 +67,9 @@ pixel surface (PNG in, clicks and keys out) behind a small `Backend` protocol, which is why the whole loop runs in CI with no OS permissions. Where a backend exposes more than pixels (a browser DOM, a native accessibility tree, an API), OpenAdapt uses that higher-fidelity signal via -[the capability ladder](capability-ladder.md). The web (Playwright), desktop -(Windows/UIA), native macOS, RDP, and Citrix/VDI [backends](backends.md) are all -adapters to the same protocol, not rewrites. +[the capability ladder](capability-ladder.md). The web (Playwright), Windows +UIA, native macOS, native Linux AT-SPI, RDP, and Citrix/VDI +[backends](backends.md) are all adapters to the same protocol, not rewrites. ## An API compiler for the API-less long tail diff --git a/docs/concepts/deployment-matrix.md b/docs/concepts/deployment-matrix.md index c34b5a5..6fc0597 100644 --- a/docs/concepts/deployment-matrix.md +++ b/docs/concepts/deployment-matrix.md @@ -6,25 +6,24 @@ schema. What differs across lanes is data handling, not substrate capability. ## Deployment architecture -| Deployment / substrate | Browser | Windows UIA | Native macOS | RDP | Citrix / VDI | -|---|---|---|---|---|---| -| **OpenAdapt Hosted** | Managed execution, schedules, reports, usage, and billing | Not a public hosted offer; runs in the customer boundary | Not a public hosted offer; runs in the customer boundary | Not a public hosted offer; runs in the customer boundary | Not a public hosted offer; runs in the customer boundary | -| **Customer cloud / BYOC** | Customer runner and storage with managed governance | Customer runner and storage | Customer runner and storage | Customer runner and storage | Customer runner and storage | -| **Self-hosted / on-prem** | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | +| Deployment / substrate | Browser | Windows UIA | Native macOS | Native Linux | RDP | Citrix / VDI | +|---|---|---|---|---|---|---| +| **OpenAdapt Hosted** | Managed execution, schedules, reports, usage, and billing | Customer-controlled runtime connected to Cloud | Customer-controlled runtime connected to Cloud | Customer-controlled runtime connected to Cloud | Customer-controlled runtime connected to Cloud | Customer-controlled runtime connected to Cloud | +| **Customer cloud / BYOC** | Customer runner and storage with managed governance | Customer runner and storage | Customer runner and storage | Customer runner and storage | Customer runner and storage | Customer runner and storage | +| **Self-hosted / on-prem** | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | Every substrate is a first-class target of the shared compiler, runner, and safety gates. Where each lane is available today differs, and the matrix states that plainly rather than implying uniform hosted availability. The public $500/month self-serve subscription runs the browser substrate in OpenAdapt's -cloud. Windows, native macOS, RDP, and Citrix/VDI run in the customer boundary: -self-hosted or on-prem today, and control-plane-managed in the customer's own -cloud (BYOC) as that Experimental lane opens. An in-our-cloud desktop runner +cloud. Windows, native macOS, native Linux, RDP, and Citrix/VDI run in a local, +self-hosted, or customer-controlled boundary and can connect to Cloud for +governed operation. An in-our-cloud desktop runner exists only as an internal, licensing-gated lane, and multi-tenant hosting of the desktop substrate in OpenAdapt's cloud is deferred; neither is part of any public -offer. Between the customer-boundary lanes the difference is a per-workflow -qualified commercial order rather than a capability gap, and none of these -substrates is an entitlement of the browser subscription. The matrix describes -the product architecture; the +managed-runner offer. None of these native or remote substrates is silently +moved into the shared managed-browser boundary or included as a managed-runner +entitlement. The matrix describes the product architecture; the [qualification appendix](../get-started/what-works-today.md) and commercial terms define the accepted workload and entitlement. @@ -155,20 +154,28 @@ qualified in its real environment. The published qualification evidence to date: SHA-256-bound adjudication verified actual cleanup and accepts the action effect and ambiguity refusal. Review [Flow PR #135](https://github.com/OpenAdaptAI/openadapt-flow/pull/135) and the [exact adjudication](https://github.com/OpenAdaptAI/openadapt-flow/blob/ca1b522cad215875f7471782283f8f8bb8e6c998/benchmark/macos_native/textedit_counted_3plus1_b1b61a5_20260717.adjudication.json). -- **RDP:** Candidate `82a658a` - passed 3/3 unique-file trials on one Parallels Windows 11 VM over network RDP; - exact guest-tools readback confirmed every effect. Trial latencies were - 51.845s, 10.467s, and 7.477s, with 0 failures, 0 silent incorrect successes, - 0 over-halts, and 0 model calls. Exact snapshot cleanup passed. Review - [Flow PR #142](https://github.com/OpenAdaptAI/openadapt-flow/pull/142) - and the [immutable sanitized report](https://github.com/OpenAdaptAI/openadapt-flow/blob/6610d24cebba27918b8ea507b2f05a094057ac85/benchmark/rdp/results_82a658a_20260718.sanitized.json). -- **Citrix / VDI (Exploratory):** Driven pixel-first through the same - remote-display adapter and the same identity gate and effect verification as - every other substrate. No real ICA/HDX environment has been qualified yet. Each - Citrix/VDI workflow must be qualified in its real ICA/HDX environment before - consequential use: the client, latency, compression, DPI, lock-screen, and - synthetic-input behavior are exercised against the actual application, the same - real-environment qualification step every substrate goes through. +- **Linux native:** Required current-main `linux-atspi-x11` at exact Flow commit + `3de5fc67` confirmed 3/3 exact-file effects, 3/3 ambiguity refusals, and + 3/3 stale-target refusals on the in-tree GTK3/X11 fixture, with 0 silent + incorrect successes, 0 over-halts, 0 operator interventions, and 0 model + calls. Review the [exact required CI job](https://github.com/OpenAdaptAI/openadapt-flow/actions/runs/30059807758/job/89378981573). +- **RDP:** Candidate `82a658a` passed 3/3 unique-file trials on one Parallels + Windows 11 VM over Aardwolf network RDP with exact guest-tools readback. A + separate full governed lifecycle over a real FreeRDP3 round trip passed 3/3 + healthy effects and 3/3 drift safe-halts with zero model calls, silent + incorrect successes, false completions, drift writes, or healthy over-halts. + Review [Flow PR #142](https://github.com/OpenAdaptAI/openadapt-flow/pull/142), + [Flow PR #177](https://github.com/OpenAdaptAI/openadapt-flow/pull/177), the + [Aardwolf report](https://github.com/OpenAdaptAI/openadapt-flow/blob/6610d24cebba27918b8ea507b2f05a094057ac85/benchmark/rdp/results_82a658a_20260718.sanitized.json), + and the [FreeRDP report](https://github.com/OpenAdaptAI/openadapt-flow/blob/affedc5f1f0de533a0744deaa8e30a203c91c6b3/benchmark/rdp_ladder/results.json). +- **Citrix / VDI:** The released dedicated `--backend citrix` binds the exact + Workspace window, gates readiness, and preserves the target through durable + resume. Its accepted no-DOM artifact records 3/3 healthy effects and 3/3 + drift safe-halts with zero model calls, silent writes, false completions, or + healthy over-halts. It also explicitly records `ica_hdx_accepted: false`: + this is bounded evidence for the shipped backend contract over a no-DOM + stand-in, not a counted real ICA/HDX batch. Review [Flow PR #183](https://github.com/OpenAdaptAI/openadapt-flow/pull/183) + and the [immutable report](https://github.com/OpenAdaptAI/openadapt-flow/blob/f6faac5b900b78cbda5980de0e983a9f987285ac/benchmark/citrix_workspace/results.json). Review [Qualification evidence](../get-started/what-works-today.md) and the engine's [published limits](https://github.com/OpenAdaptAI/openadapt-flow/blob/main/docs/LIMITS.md) diff --git a/docs/concepts/index.md b/docs/concepts/index.md index 348d199..c63402a 100644 --- a/docs/concepts/index.md +++ b/docs/concepts/index.md @@ -13,8 +13,8 @@ jump to what you need. - [__The substrate model__](substrate-model.md) - Routing across web, native Windows, native macOS, and pixel-only Citrix/RDP; - one runner contract, every substrate first-class. + Routing across browser, native Windows, native macOS, native Linux, RDP, + and Citrix/VDI; one runner contract, every substrate first-class. - [__The deployment matrix__](deployment-matrix.md) @@ -73,10 +73,11 @@ jump to what you need. - [__Backends: where it runs__](backends.md) - Browser (Playwright), native Windows (UIA), native macOS, RDP, and - Citrix/VDI are all first-class substrates behind one backend protocol. The - same bundle, resolution ladder, identity gate, and effect verification run on - each; every workflow is qualified in its real environment. + Browser (Playwright), native Windows (UIA), native macOS, native Linux + (AT-SPI), RDP, and Citrix/VDI are all first-class substrates behind one + backend protocol. The same bundle, resolution ladder, identity gate, and + effect verification run on each; every workflow is qualified in its real + environment. - [__The on-prem VLM appliance__](vlm-appliance.md) diff --git a/docs/concepts/substrate-model.md b/docs/concepts/substrate-model.md index 288f87a..3083fff 100644 --- a/docs/concepts/substrate-model.md +++ b/docs/concepts/substrate-model.md @@ -16,8 +16,8 @@ the resolution ladder, the [identity gate](identity-gate.md), Two orthogonal questions about any run, kept separate: -- **Substrate**: *what surface is being driven?* Web (browser) or - Windows-desktop / Citrix-RDP. +- **Substrate**: *what surface is being driven?* Browser, Windows UIA, native + macOS, native Linux, RDP, or Citrix/VDI. - **Deployment**: *where does the run execute and who owns the data?* See [the deployment matrix](deployment-matrix.md). @@ -31,9 +31,11 @@ pixels or resolved field values. flowchart TD J[Job: signed bundle + target + params] --> R{{Substrate-agnostic runner}} R -->|target_kind = web| W[Browser sandbox
Playwright backend] - R -->|target_kind = desktop| D[Windows session
WindowsBackend / FreeRDP] + R -->|target_kind = desktop| D[Native desktop
Windows / macOS / Linux] + R -->|target_kind = remote| V[Remote display
RDP / Citrix] W --> L[Resolution ladder · identity gate · effect verification] D --> L + V --> L L --> C[[Signed report + minimized callback]] ``` @@ -45,14 +47,14 @@ compares **structured text** where `0` and `O` are distinct characters. The whole record → compile → replay loop runs in CI with no OS permissions. See [Backends](backends.md#web-playwright). -## The Windows-desktop / Citrix substrate: the wedge +## Native desktop and remote applications: the wedge The differentiated work has no web UI and no usable API: a native Windows EMR, a WinForms line-of-business app, a clinical tool published through Citrix. This is where a computer-use agent is otherwise the only option and where a wrong write is expensive. -Two backends cover it behind the same protocol: +The released backends cover it behind the same protocol: - **`WindowsBackend`** drives a native Windows desktop through an in-session agent. Its shipped typed RPC exposes bounded screenshot, input, and UIA @@ -61,10 +63,18 @@ Two backends cover it behind the same protocol: native controls expose `Name` / `Value` text **even without a stable `AutomationId`**, so structured identity is viable on desktop, not just the browser. +- The **native macOS backend** binds one exact application window and uses + Accessibility metadata plus retained visual evidence. +- **`LinuxBackend`** binds one exact AT-SPI application and top-level window, + uses structural actuation where available, and refuses ambiguous or stale + native targets. - **`FreeRDPBackend`** drives a legacy app over RDP as **pure pixels**: no accessibility tree, no DOM, no structured layer. This is the floor the vision-first runtime was built for, the lowest-fidelity surface a Citrix/VDI deployment may expose. +- **`CitrixWorkspaceBackend`** is the dedicated `--backend citrix` preset over + the exact-window remote-display backend. It binds the Workspace owner/title + and gates readiness before governed input. !!! info "Citrix / RDP is pixel-first: the identity gate adapts to it" On a pure-pixel substrate the ladder runs on its visual floor and the @@ -80,13 +90,13 @@ Two backends cover it behind the same protocol: ## Where the desktop substrate runs today -Today the desktop and Citrix substrates run **inside the customer boundary**: -self-hosted or on-prem on a machine the customer controls (see -[Deploy on-prem](../guides/deploy-on-prem.md)), and, as that lane opens, -control-plane-managed in the customer's own cloud (BYOC). The public managed -subscription runs the browser substrate only. The desktop mechanism, backends, -and safety gates are the same wherever they run; what differs is who owns the -machine and the data. +Desktop, RDP, and Citrix substrates run **inside the customer boundary**: +locally, self-hosted/on-prem on a machine the customer controls (see +[Deploy on-prem](../guides/deploy-on-prem.md)), or in a configured +customer-controlled cloud runtime. The public managed runner executes approved +browser workflows. Customer-controlled runtimes can connect to the same Cloud +control plane for reports and governed operation without moving sensitive live +observations into the shared managed-browser boundary. OpenAdapt also runs the desktop substrate in its own infrastructure as an **internal, licensing-gated lane** rather than a public offer. There the Windows @@ -118,17 +128,21 @@ offer. over-halts. The original batch remains failed due to cleanup-warning classification; a hash-bound adjudication verified actual cleanup and accepts those effects/refusal. -- RDP is qualified for candidate `82a658a` on one Parallels Windows 11 - VM at 1280x800 with Aardwolf 0.2.14: 3/3 Windows Run-dialog unique-file - trials, exact independent guest-tools readback, latencies of 51.845s, 10.467s, - and 7.477s, 0 failures, 0 silent incorrect successes, 0 over-halts, and 0 model - calls. - Exact snapshot cleanup passed. Review the - [immutable sanitized report](https://github.com/OpenAdaptAI/openadapt-flow/blob/6610d24cebba27918b8ea507b2f05a094057ac85/benchmark/rdp/results_82a658a_20260718.sanitized.json). -- Citrix/VDI is driven pixel-first through the same identity gate and effect - verification as every substrate. No real ICA/HDX environment has been qualified - yet (status: Exploratory); each workflow must be qualified in its real ICA/HDX - environment before consequential use. +- Linux AT-SPI is a required current-main CI lane. Exact Flow commit + `3de5fc67` confirmed 3/3 exact-file effects, 3/3 ambiguity refusals, and + 3/3 stale-target refusals on the in-tree GTK3/X11 fixture, with zero silent + incorrect successes, over-halts, operator interventions, or model calls. +- RDP has complementary accepted evidence: 3/3 Aardwolf-over-Windows + transport/input effects, plus a full real-FreeRDP record → compile → governed + replay lifecycle with 3/3 healthy effects and 3/3 drift safe-halts. The + [FreeRDP artifact](https://github.com/OpenAdaptAI/openadapt-flow/blob/affedc5f1f0de533a0744deaa8e30a203c91c6b3/benchmark/rdp_ladder/results.json) + covers a synthetic Linux task on a real protocol round trip; it does not + inherit the separate Windows/Aardwolf scope. +- Citrix/VDI ships as dedicated `--backend citrix` with exact Workspace-window + binding, readiness gating, and durable resume. Its accepted no-DOM contract + evidence records 3/3 healthy effects and 3/3 drift safe-halts. The artifact + explicitly records `ica_hdx_accepted: false`: a counted real ICA/HDX batch is + a separate evidence/qualification boundary, not a missing backend. - The public hosted subscription currently entitles approved browser workflows. Desktop and virtual-desktop deployments are scoped and qualified separately. diff --git a/docs/desktop/install.md b/docs/desktop/install.md index df838f6..c1217bf 100644 --- a/docs/desktop/install.md +++ b/docs/desktop/install.md @@ -16,7 +16,9 @@ you explicitly push it to a [cloud workspace](connect-to-cloud.md). Get the installer from [openadapt.ai/download](https://openadapt.ai/download). The page detects your OS -and architecture and offers the right build. +and architecture and offers the right build. Public Beta release +`desktop-v0.9.0` ships the complete Windows, macOS, and Linux installer set with +`SHA256SUMS` and per-platform provenance metadata. | OS | Installer | |---|---| @@ -24,6 +26,11 @@ and architecture and offers the right build. | macOS (Apple Silicon / Intel) | `.dmg` | | Linux | `.AppImage` or `.deb` | +The desktop app and `openadapt flow` use the same released engine. Browser +workflows can use the managed OpenAdapt Cloud runner; native desktop, RDP, and +Citrix workflows execute locally or in a self-hosted/customer-controlled runtime +and can connect to Cloud for governed reports and updates. + ## 2. Get past the first-launch OS warning The current builds are **not code-signed yet**, so your OS shows a one-time diff --git a/docs/ecosystem/index.md b/docs/ecosystem/index.md index 09c9458..1df3410 100644 --- a/docs/ecosystem/index.md +++ b/docs/ecosystem/index.md @@ -30,9 +30,9 @@ module inside it: | Repository | Lifecycle | Public role | |---|---|---| | [OpenAdapt](https://github.com/OpenAdaptAI/OpenAdapt) | **Supported** | Installer/meta-package and unified `openadapt flow` dispatcher. | -| [openadapt-flow](https://github.com/OpenAdaptAI/openadapt-flow) | **Supported** | Canonical compiler and governed runtime. Drives web, native Windows, native macOS, RDP, and Citrix/VDI as first-class substrates behind one backend protocol. | +| [openadapt-flow](https://github.com/OpenAdaptAI/openadapt-flow) | **Supported** | Canonical compiler and governed runtime. Drives web, native Windows, native macOS, native Linux, RDP, and Citrix/VDI as first-class substrates behind one backend protocol. | | [openadapt-cloud](https://github.com/OpenAdaptAI/openadapt-cloud) | **Supported** | Live control plane for the public managed-browser subscription: organizations, exact-hash admission, runner orchestration, reports, billing, and usage. | -| [openadapt-desktop](https://github.com/OpenAdaptAI/openadapt-desktop) | **Supported** | The `desktop-v0.5.1` release provides six install/uninstall-smoke-tested installers for Windows, macOS, and Linux, plus exact checksums, platform metadata, and build attestations. | +| [openadapt-desktop](https://github.com/OpenAdaptAI/openadapt-desktop) | **Supported** | Public Beta `desktop-v0.9.0` provides Windows MSI/NSIS, macOS arm64/x64 DMG, and Linux AppImage/DEB installers. Every installer path was installed, launched, and uninstalled in the native release workflow; the release includes exact checksums, platform metadata, and build attestations. | | [openadapt-agent](https://github.com/OpenAdaptAI/openadapt-agent) | **Supported** | Active v2 bridge that exposes governed Flow bundles to MCP clients and Agent Skills. The pre-v2 model-driven execution wrapper is the deprecated line; the repository itself is active. | | [openadapt-capture](https://github.com/OpenAdaptAI/openadapt-capture) | **Supported** | Optional native mouse, keyboard, and screen recorder behind Flow's Windows and RDP recording path. Browser recording remains inside Flow's Playwright listener. | | [openadapt-privacy](https://github.com/OpenAdaptAI/openadapt-privacy) | **Supported** | Optional PII/PHI scrubbing used on configured persist, log, and upload paths. | diff --git a/docs/get-started/first-workflow.md b/docs/get-started/first-workflow.md index 71ddde2..365aab5 100644 --- a/docs/get-started/first-workflow.md +++ b/docs/get-started/first-workflow.md @@ -3,8 +3,9 @@ This walks through compiling a workflow on **your own** web app: record what you do, compile it, replay it, and read the report. It takes about five minutes and makes zero model calls. Web is the quickest substrate to start on; the same -record, compile, replay loop drives a native Windows desktop or a pixel-only -Citrix/RDP session by choosing a [backend](../reference/cli.md#backend). +record, compile, replay loop drives native Windows, macOS, or Linux applications +and RDP or Citrix sessions by choosing a +[backend](../reference/cli.md#backend). ## Prerequisites diff --git a/docs/get-started/what-works-today.md b/docs/get-started/what-works-today.md index 317dc68..7ef465f 100644 --- a/docs/get-started/what-works-today.md +++ b/docs/get-started/what-works-today.md @@ -21,25 +21,19 @@ execution, usage, portal, and cancellation as continuing production evidence. ## How to read this appendix -Most surfaces below are **Supported**: a first-class product surface you can build -on, backed by the evidence in the "What is actually demonstrated" column. A few -carry a narrower status the Status column names explicitly: **Supported / scoped -deployment** (qualified and ordered as a scoped deployment), **Experimental** or -**Internal only** (built but not a public offer), and **Exploratory** (the -mechanism exists but no real environment has been qualified yet). The -"Important boundary" column states, honestly and per surface, exactly what each -result does and does not cover. Read it before trusting a surface with -consequential work. Public delivery of a given surface may still carry a separate -production-qualification or commercial gate. +Every substrate below is implemented in the released compiler and governed +runtime. The Status column describes product availability; the "What is actually +demonstrated" and "Important boundary" columns separately record the exact +bounded evidence. Availability never turns one fixture or qualification batch +into a broad application-support claim. Before consequential use, qualify the +exact workflow, application, environment, identity contract, effect oracle, and +deployment boundary. -Buyer-facing availability is reported distinctly from evidence, and reconciles -to the machine-readable [status manifest](https://openadapt.ai/status.json) that -the website, launcher, and packages also read. **Early access** means the -substrate works and is validated on specific named tasks but is not yet broadly -exercised: it is a first-class execution target ordered as a scoped deployment -and qualified per workflow in its real environment, the same real-environment -qualification step every substrate, including the browser, goes through before -it carries consequential work. +The machine-readable [status manifest](https://openadapt.ai/status.json) +publishes the same release, availability, evidence, and deployment dimensions. +The public managed runner executes approved browser workflows. Native desktop, +RDP, and Citrix/VDI workflows execute locally or in a self-hosted or +customer-controlled runtime connected to the same governance model. ## Integrated product matrix @@ -54,11 +48,12 @@ it carries consequential work. | System-of-record effect verification | **Supported** | REST, FHIR, and document-hash verifiers run in the live replay path and halt on refuted or indeterminate declared effects. | The compiler does not infer effects. A deployment must author effects and configure the matching verifier; otherwise screen checks remain the oracle. | | `teach` halt-to-correction loop | **Supported** | The deterministic reference inducer covers the optional-dialog correction class behind regression and canary gates. | Arbitrary UI corrections are not generally learned. Unsafe or underdetermined revisions are refused. | | Workflow-program IR, branches, loops, and multi-trace induction | **Supported** | Implemented against synthetic fixtures, including refusal for underdetermined programs. | No real recording exercises the full Phase-2 program path yet. | -| Windows UIA backend | **Early access** | The counted `20260717-candidate-56759c8-v2` in-tree WinForms matrix completed 3/3 trials; an independent SQLite oracle confirmed 3/3 effects; stale-target and ambiguous-target controls each refused 3/3; there were 0 silent incorrect successes, 0 over-halts, and 0 model calls. [Review the immutable report at the merged Flow commit](https://github.com/OpenAdaptAI/openadapt-flow/blob/defafbae758a75c8e149d9693f2cffe1f2264b8c/benchmark/windows_uia/results.json) and [Flow PR #132](https://github.com/OpenAdaptAI/openadapt-flow/pull/132). | The report also preserves earlier rejected diagnostic runs; their failures are not counted acceptance trials. Each Windows workflow is qualified in its real environment; the published evidence covers the named workflow and Windows 11 ARM VM snapshot. | -| Native macOS backend | **Early access** | On one macOS 15.7.3 arm64 host, candidate `b1b61a5` completed 3/3 exact-byte TextEdit trials and refused a two-window ambiguity without changing either file; there were 0 silent incorrect successes and 0 over-halts. [Review the hash-bound adjudication at immutable evidence commit `ca1b522`](https://github.com/OpenAdaptAI/openadapt-flow/blob/ca1b522cad215875f7471782283f8f8bb8e6c998/benchmark/macos_native/textedit_counted_3plus1_b1b61a5_20260717.adjudication.json) and [Flow PR #135](https://github.com/OpenAdaptAI/openadapt-flow/pull/135). | The counted candidate is `b1b61a5`; `ca1b522` preserves its reports and adjudication but is not the current PR head. The immutable original report remains `status: failed` because graceful-close cleanup warnings were classified as batch failure. The separate adjudication preserves that result, verifies the exact harness PIDs and temporary root were absent, and accepts the action-effect and ambiguity-refusal evidence. Each macOS workflow is qualified in its real environment. | -| RDP backend | **Early access** | On one Parallels Windows 11 VM at 1280x800 with Aardwolf 0.2.14, candidate `82a658a` completed 3/3 trials that created a unique file through the Windows Run dialog over network RDP. Independent guest-tools readback confirmed the exact file contents. Trial latencies were 51.845s, 10.467s, and 7.477s; there were 0 failures, 0 silent incorrect successes, 0 over-halts, and 0 model calls. [Review the immutable sanitized report at evidence commit `6610d24`](https://github.com/OpenAdaptAI/openadapt-flow/blob/6610d24cebba27918b8ea507b2f05a094057ac85/benchmark/rdp/results_82a658a_20260718.sanitized.json) and [Flow PR #142](https://github.com/OpenAdaptAI/openadapt-flow/pull/142). | Cleanup deleted only the batch-owned snapshot, restored the exact eight-snapshot inventory, left the VM suspended, and returned the current pointer without resume to the unchanged original base. Each RDP workflow is qualified in its real environment; the published evidence covers the named task, VM snapshot, transport, and oracle. Earlier rejected batches remain evidence and are not counted as acceptance trials. | -| Citrix / VDI backend | **Exploratory** | The pixel-first mechanism (the same remote-display adapter, identity gate, and effect verification as every substrate) is implemented, but no real Citrix ICA/HDX environment has been qualified yet. | Each Citrix/VDI workflow must be qualified in its real ICA/HDX environment, where the client, latency, compression, DPI, lock-screen, input, identity, and effect behavior are exercised against the actual application, before it carries consequential work. | -| Desktop authoring GUI and tray | **Supported** | The published 0.1.1 prerelease provides install/uninstall-qualified native packages across the six targeted platform/architecture variants. | The current prerelease qualifies packaging and removal; the complete record -> compile -> replay -> teach cockpit remains an integration track. | +| Windows UIA backend | **Supported** | The counted `20260717-candidate-56759c8-v2` in-tree WinForms matrix completed 3/3 trials; an independent SQLite oracle confirmed 3/3 effects; stale-target and ambiguous-target controls each refused 3/3; there were 0 silent incorrect successes, 0 over-halts, and 0 model calls. [Review the immutable report at the merged Flow commit](https://github.com/OpenAdaptAI/openadapt-flow/blob/defafbae758a75c8e149d9693f2cffe1f2264b8c/benchmark/windows_uia/results.json) and [Flow PR #132](https://github.com/OpenAdaptAI/openadapt-flow/pull/132). | The report also preserves earlier rejected diagnostic runs; their failures are not counted acceptance trials. Each Windows workflow is qualified in its real environment; the published evidence covers the named workflow and Windows 11 ARM VM snapshot. | +| Native macOS backend | **Supported** | On one macOS 15.7.3 arm64 host, candidate `b1b61a5` completed 3/3 exact-byte TextEdit trials and refused a two-window ambiguity without changing either file; there were 0 silent incorrect successes and 0 over-halts. [Review the hash-bound adjudication at immutable evidence commit `ca1b522`](https://github.com/OpenAdaptAI/openadapt-flow/blob/ca1b522cad215875f7471782283f8f8bb8e6c998/benchmark/macos_native/textedit_counted_3plus1_b1b61a5_20260717.adjudication.json) and [Flow PR #135](https://github.com/OpenAdaptAI/openadapt-flow/pull/135). | The counted candidate is `b1b61a5`; `ca1b522` preserves its reports and adjudication but is not the current PR head. The immutable original report remains `status: failed` because graceful-close cleanup warnings were classified as batch failure. The separate adjudication preserves that result, verifies the exact harness PIDs and temporary root were absent, and accepts the action-effect and ambiguity-refusal evidence. Each macOS workflow is qualified in its real environment. | +| Native Linux backend | **Supported** | Required current-main job [`linux-atspi-x11`](https://github.com/OpenAdaptAI/openadapt-flow/actions/runs/30059807758/job/89378981573) at exact Flow commit `3de5fc67acf3024a621f812c5a6ed9be07fac335` ran one fresh GTK3 process per trial on Ubuntu 24.04 X11/AT-SPI. It confirmed 3/3 exact-file effects, 3/3 ambiguous-target refusals, and 3/3 stale-target refusals, with 0 silent incorrect successes, 0 over-halts, 0 operator interventions, and 0 model calls. | Native receipts prove AT-SPI delivery only; independent exact file bytes or confirmed absence prove effects. This is bounded to the in-tree GTK3 fixture and CI Xvfb image; it does not establish Wayland or arbitrary third-party application support. | +| RDP backend | **Supported** | Two bounded results exercise complementary RDP paths. Aardwolf 0.2.14 over a Parallels Windows 11 VM completed 3/3 Windows Run-dialog file effects with independent guest-tools readback. The accepted full governed lifecycle at mechanism commit `6031fde` recorded, compiled, and replayed a synthetic note workflow through real FreeRDP3-transported pixels/input: 3/3 healthy effects and 3/3 drift safe-halts, with zero model calls, silent incorrect successes, false completions, drift writes, or healthy over-halts. Review the [Aardwolf/Windows report](https://github.com/OpenAdaptAI/openadapt-flow/blob/6610d24cebba27918b8ea507b2f05a094057ac85/benchmark/rdp/results_82a658a_20260718.sanitized.json), the [FreeRDP lifecycle report](https://github.com/OpenAdaptAI/openadapt-flow/blob/affedc5f1f0de533a0744deaa8e30a203c91c6b3/benchmark/rdp_ladder/results.json), [Flow PR #142](https://github.com/OpenAdaptAI/openadapt-flow/pull/142), and [Flow PR #177](https://github.com/OpenAdaptAI/openadapt-flow/pull/177). | The Windows batch qualifies its exact task, snapshot, transport, and oracle. The FreeRDP batch qualifies a synthetic Linux Tk task over a real RDP round trip; it is not Aardwolf, a Windows-app qualification, Citrix ICA/HDX, or WAN-captured drift. | +| Citrix / VDI backend | **Supported** | The dedicated `--backend citrix` path selects the exact Citrix Workspace/Viewer owner, optionally binds an exact title, requires a readiness marker for governed `run`, carries the closed target into durable resume, and uses the shared pixel identity, effect, policy, and halt contracts. The accepted no-DOM qualification completed 3/3 healthy effects and 3/3 severe-drift safe-halts with 0 model calls, silent incorrect successes, false completions, healthy over-halts, or drift writes. Review the [immutable report](https://github.com/OpenAdaptAI/openadapt-flow/blob/f6faac5b900b78cbda5980de0e983a9f987285ac/benchmark/citrix_workspace/results.json) and [Flow PR #183](https://github.com/OpenAdaptAI/openadapt-flow/pull/183). | The accepted artifact explicitly records `code_readiness_accepted: true` and `ica_hdx_accepted: false`. It qualifies the shipped Citrix Workspace-window backend contract over a no-DOM canvas stand-in, not a counted real ICA/HDX batch. The exact ICA/HDX client, codec, latency, DPI, lock/readiness, input, identity, and effect matrix is a separate per-deployment qualification boundary. | +| Desktop authoring GUI and tray | **Supported / Beta** | Public `desktop-v0.9.0` provides Windows MSI/NSIS, macOS arm64/x64 DMG, and Linux AppImage/DEB installers. All six installer paths were installed, launched, and uninstalled in the native release workflow; the published set includes checksums and per-platform provenance metadata. | Builds are not yet fully code-signed/notarized, so verify `SHA256SUMS` and provenance before overriding the OS publisher warning. The app and CLI drive the same released compiler/runtime. | | Hosted CLI connectivity | **Supported / public offer** | `login`, exact-hash artifact preparation/upload, one-time runtime validation, bound replacement activation, and `report-break` connect the local engine to the live control plane. | Upload requires destination policy and an approved sanitized derivative; checkout never bypasses an egress refusal. | | Artifact sanitation and local review | **Supported / launch gate** | The sanitized-derivative pipeline inventories, transforms, rescans, manifests, hashes, and supports local review/approval. | The raw original remains sensitive; unknown or unresolved content is refused; runtime observations can reintroduce PHI/PII. | | Cross-engine hosted validation | **Supported / launch gate** | `validate-hosted` binds an approved recording and bundle, compiler provenance, strict lint, policy certification, derived risk class, and successful replay report to a one-time Cloud challenge. | It is operator self-attestation signed with the ingest token, not an independently observed certification. Exact deployment policy, risk-class, and deployed compiler-version allowlists still apply. | diff --git a/docs/guides/hosted.md b/docs/guides/hosted.md index e3fb282..db46e7a 100644 --- a/docs/guides/hosted.md +++ b/docs/guides/hosted.md @@ -39,12 +39,13 @@ switching, and sign-out. | Self-hosted browser execution | **Beta** | No hosted account required. | | Windows UIA | **Supported / scoped deployment** | The exact in-tree WinForms matrix passed 3/3 with an independent SQLite oracle and 3/3 stale/ambiguity refusals. Windows subscriptions and deployments are ordered separately from the public browser offer and qualified per workflow. | | Native macOS | **Supported / scoped deployment** | One macOS 15.7.3 arm64 host produced 3/3 exact-byte TextEdit effects plus a two-window ambiguity refusal. Native macOS subscriptions and deployments are ordered separately from the public browser offer and qualified per workflow. | -| RDP | **Supported / scoped deployment** | One Parallels Windows 11 VM produced 3/3 exact guest-file effects through network RDP, with 0 silent incorrect successes, 0 over-halts, and 0 model calls. RDP subscriptions and deployments are ordered separately from the public browser offer and qualified per workflow. | -| Citrix / VDI | **Supported / scoped deployment** | Driven pixel-first through the same identity gate and effect verification as every substrate; ordered separately from the public browser offer and qualified in its real ICA/HDX environment per workflow. | +| Native Linux | **Supported / scoped deployment** | The required Ubuntu 24.04 X11/AT-SPI current-main lane completed 3/3 exact-file effects and refused 3/3 ambiguous plus 3/3 stale targets, with zero silent incorrect successes, over-halts, interventions, or model calls. Native Linux deployments run locally or in a customer-controlled boundary and are qualified per workflow. | +| RDP | **Supported / scoped deployment** | Complementary accepted evidence covers 3/3 Aardwolf-over-Windows guest-file effects with independent guest-tools readback and a separate full record -> compile -> governed replay/refusal lifecycle over a real FreeRDP round trip. These are two bounded evidence records, not one combined Windows application claim. RDP subscriptions and deployments are ordered separately from the public browser offer and qualified per workflow. | +| Citrix / VDI | **Supported / scoped deployment** | The dedicated Citrix Workspace-window backend binds an exact owner/title, requires current-frame readiness for governed execution, and uses the shared pixel identity, effect, policy, halt, and durable-resume contracts. Its retained no-DOM stand-in completed 3/3 healthy effects and 3/3 severe-drift safe-halts with zero silent incorrect successes, false completions, healthy over-halts, drift writes, or model calls. The artifact records `code_readiness_accepted: true` and `ica_hdx_accepted: false`; a counted real ICA/HDX client/codec/latency/DPI matrix remains an exact-deployment evidence boundary, not part of the public managed-browser subscription. | | Regulated runtime data | **Customer-controlled boundary** | Use a scoped BYOC/on-prem deployment when live screens necessarily contain PHI/PII. | The public subscription covers approved browser workflows. Windows, native -macOS, RDP, Citrix, regulated customer-controlled execution, professional +macOS, native Linux, RDP, Citrix, regulated customer-controlled execution, professional services, support commitments, and assurance terms are scoped separately. See [qualification evidence](../get-started/what-works-today.md) for the exact accepted substrate results; configured commercial terms define entitlement and diff --git a/docs/guides/record-your-app.md b/docs/guides/record-your-app.md index 4b34f99..2b7f57f 100644 --- a/docs/guides/record-your-app.md +++ b/docs/guides/record-your-app.md @@ -2,10 +2,9 @@ The bundled demo shows the loop end to end, but the point is your app. This guide records a real workflow, compiles it, and replays it. It uses the **web -substrate** throughout; a native Windows desktop or a pixel-only Citrix/RDP -session follows the same steps with a different -[backend](../reference/cli.md#backend) (`--backend windows` / `--backend rdp` and -its target flag) in place of `--url`. +substrate** throughout; Windows, macOS, Linux, RDP, and Citrix follow the same +steps with a different [backend](../reference/cli.md#backend) and its exact +target flags in place of `--url`. ## Record diff --git a/docs/guides/security-review.md b/docs/guides/security-review.md index e0b104a..ae399aa 100644 --- a/docs/guides/security-review.md +++ b/docs/guides/security-review.md @@ -113,17 +113,29 @@ pre-payment trials verified tenant-bound Checkout and refusal before entitlement The first genuine paid subscription extends the evidence through signed-webhook activation, managed execution, usage, portal, and cancellation. -Windows UIA, native macOS, RDP, and Citrix/VDI are first-class substrates, +Windows UIA, native macOS, native Linux, RDP, and Citrix/VDI are first-class substrates, ordered as scoped deployments and qualified per workflow in their real environment. The published qualification evidence to date: Windows UIA passed one 3/3 in-tree WinForms matrix with an independent SQLite oracle; native macOS passed one-host TextEdit action-effect and ambiguity-refusal evidence (its preserved original batch remains failed on a cleanup-warning classification, and -a hash-bound adjudication verified the actual cleanup); RDP passed 3/3 -one-snapshot network-input trials with independent guest-file readback; and -Citrix/VDI is driven pixel-first through the same identity gate and effect -verification, qualified in its real ICA/HDX environment per workflow. The public -browser subscription is ordered separately from these scoped deployments. See +a hash-bound adjudication verified the actual cleanup); native Linux's required +Ubuntu 24.04 X11/AT-SPI lane completed 3/3 exact-file effects and refused 3/3 +ambiguous plus 3/3 stale targets; and RDP has two complementary bounded records: +3/3 Aardwolf-over-Windows guest-file effects with independent guest-tools +readback, plus a separate full record -> compile -> governed replay/refusal +lifecycle over a real FreeRDP round trip. + +Citrix/VDI uses the dedicated Citrix Workspace-window backend: it binds an exact +owner/title, requires current-frame readiness before governed input, and carries +the closed target through durable resume. Its accepted no-DOM stand-in completed +3/3 healthy effects and 3/3 severe-drift safe-halts with zero silent incorrect +successes, false completions, healthy over-halts, drift writes, or model calls. +The retained artifact explicitly records `code_readiness_accepted: true` and +`ica_hdx_accepted: false`; it proves the shipped window/backend contract, not a +counted real ICA/HDX client/codec/latency/DPI batch. That exact environment is a +per-deployment evidence boundary. The public browser subscription is ordered +separately from these customer-controlled deployments. See [Qualification evidence](../get-started/what-works-today.md) for the exact reports. See [Hosted browser diff --git a/docs/index.md b/docs/index.md index f495bf6..aaf4e59 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,12 +7,12 @@ hide: # Show it a repeated workflow. OpenAdapt compiles it into governed, deterministic replay.

-OpenAdapt is a demonstration compiler for repeated GUI work in the browser, -native desktop, Citrix, and other virtual desktops. Demonstrate a task once. -OpenAdapt compiles it into a deterministic, locally executable program that -replays with no model calls on a healthy run. When interfaces drift, it -re-resolves targets deterministically or uses an explicitly configured model -tier, records the repair, and halts instead of guessing when verification +OpenAdapt is a demonstration compiler for repeated GUI work across browser, +Windows, macOS, Linux, RDP, Citrix, and other virtual desktops. Demonstrate a +task once. OpenAdapt compiles it into a deterministic, locally executable +program that replays with no model calls on a healthy run. When interfaces +drift, it re-resolves targets deterministically or uses an explicitly configured +model tier, records the repair, and halts instead of guessing when verification fails.

@@ -36,11 +36,11 @@ a thousand times. OpenAdapt compiles the demonstration instead, so the model is consulted only to repair the script, not to drive it. One compiled workflow and one governance model run across browser, Windows, -native macOS, RDP, Citrix, and other VDI surfaces. Each substrate supplies the -strongest observations and actions available; the compiler, identity checks, -effect verification, policy, repair, and audit trail stay consistent. Teams -qualify each workflow against its real application and success oracle before -production use. +native macOS, native Linux, RDP, Citrix, and other VDI surfaces. Each substrate +supplies the strongest observations and actions available; the compiler, +identity checks, effect verification, policy, repair, and audit trail stay +consistent. Teams qualify each workflow against its real application and +success oracle before production use. --- @@ -123,22 +123,23 @@ deployment boundaries. A [substrate-agnostic runner](concepts/substrate-model.md routes each job to the right driver while governance stays above that boundary. Two orthogonal axes, one contract: -| Deployment ↓ / Substrate → | **Web (browser)** | **Windows UIA** | **Native macOS** | **RDP** | **Citrix** | -|---|---|---|---|---|---| -| **OpenAdapt Cloud** | Managed runner, schedules, reports, usage, and billing | Not multi-tenant hosted; runs in the customer boundary | Not multi-tenant hosted; runs in the customer boundary | Not multi-tenant hosted; runs in the customer boundary | Design-partner; runs in the customer boundary | -| **Customer cloud / BYOC** | Customer runner and storage with managed governance | Customer runner and storage | Customer runner and storage | Customer runner and storage | Customer runner and storage | -| **Self-hosted / on-prem** | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | +| Deployment ↓ / Substrate → | **Web (browser)** | **Windows UIA** | **Native macOS** | **Native Linux** | **RDP** | **Citrix / VDI** | +|---|---|---|---|---|---|---| +| **OpenAdapt Cloud** | Managed runner, schedules, reports, usage, and billing | Customer-controlled runtime connected to Cloud | Customer-controlled runtime connected to Cloud | Customer-controlled runtime connected to Cloud | Customer-controlled runtime connected to Cloud | Customer-controlled runtime connected to Cloud | +| **Customer cloud / BYOC** | Customer runner and storage with managed governance | Customer runner and storage | Customer runner and storage | Customer runner and storage | Customer runner and storage | Customer runner and storage | +| **Self-hosted / on-prem** | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | Local runner and audit trail | You choose where execution and data live. For regulated data the [`run`](concepts/regulated-execution.md) verb is **fail-closed by default**: it gates certification, identity and effect coverage, approval fallback, encryption, and manifest integrity before execution. -The public subscription covers approved browser workflows. Desktop and -virtual-desktop lanes run in the customer boundary (self-hosted or on-prem today, -control-plane-managed BYOC as that Experimental lane opens), not in OpenAdapt's -multi-tenant cloud, and they require a separate order and workflow-specific -qualification; they are not entitlements of the browser subscription. The +The public subscription covers approved browser workflows on the managed +runner. Windows, macOS, Linux, RDP, and Citrix/VDI execute in a local, +self-hosted, or customer-controlled boundary and can connect to the same Cloud +control plane for governed operation. They are not silently moved into +OpenAdapt's shared managed-browser boundary or included as managed-runner +entitlements. The [hosted guide](guides/hosted.md), [qualification evidence](get-started/what-works-today.md), and commercial terms define the accepted scope. Artifacts cross boundaries only as approved sanitized diff --git a/docs/llms.txt b/docs/llms.txt index 25a9017..cb9c1ca 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -27,7 +27,7 @@ - [The halt-learn loop](https://docs.openadapt.ai/concepts/halt-learn-loop/): Turning halts into demonstrated corrections via teach - [Durable runtime](https://docs.openadapt.ai/concepts/durable-runtime/): Turning a halt into a pause an operator can approve and resume - [Policy and certify](https://docs.openadapt.ai/concepts/policy-and-certify/): Safety policies and the certification gate -- [Backends, where it runs](https://docs.openadapt.ai/concepts/backends/): Web, native Windows, native macOS, RDP, and Citrix/VDI as first-class substrates behind one backend protocol +- [Backends, where it runs](https://docs.openadapt.ai/concepts/backends/): Browser, native Windows, native macOS, native Linux, RDP, and Citrix/VDI as first-class substrates behind one backend protocol - [The on-prem VLM appliance](https://docs.openadapt.ai/concepts/vlm-appliance/): Optional, off-by-default grounding that keeps model calls inside a customer-controlled boundary ## Guides diff --git a/docs/reference/cli.md b/docs/reference/cli.md index d5fef0b..563f74c 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -13,7 +13,7 @@ is a subcommand of `openadapt flow`. | Verb | What it does | Exit code | |---|---|---| -| [`record`](#record) | Record your own app on any [substrate](#backend) (browser via `--url`, native Windows or Citrix/RDP via `--backend`) | 0 | +| [`record`](#record) | Record your own app on any [substrate](#backend) (browser via `--url`; Windows, macOS, Linux, RDP, or Citrix via `--backend`) | 0 | | [`demo-record`](#demo-record) | Serve the sample app and record the canonical demo | 0 | | [`compile`](#compile) | Compile a recording into a workflow bundle | 0 | | [`induce`](#induce) | Induce a parameterized program from **multiple** recordings | 0 if certified, 2 if underdetermined | @@ -47,31 +47,48 @@ is a subcommand of `openadapt flow`. ## Choosing a backend {#backend} `record`, `replay`, `run`, and `resume` all accept a **backend selector** that -chooses what the workflow drives: a browser, a native Windows desktop, or a -pixel-only remote session. It overrides the `backend` section of a +chooses what the workflow drives: a browser, native Windows/macOS/Linux +desktop, RDP session, or Citrix Workspace window. It overrides the `backend` section of a [`--config`](deployment-config.md). With no flag the default is `web`, which reproduces the historical browser behavior. See [Backends, where it runs](../concepts/backends.md) for the substrate model. | Flag | Description | |---|---| -| `--backend {web,windows,rdp}` | `web` (default; Playwright/Chromium), `windows` (native Windows via the WAA HTTP agent, needs `--agent-url`), or `rdp` (pixel-only remote desktop / Citrix, needs `--rdp-host`, or a configured `rdp_window` for a local Citrix/Parallels window) | +| `--backend {web,windows,macos,linux,rdp,citrix}` | Select the released adapter: browser, Windows UIA, exact native macOS window, exact Linux AT-SPI window, RDP transport/window, or the dedicated Citrix Workspace-window preset. | | `--agent-url URL` | Base URL of the in-guest Windows (WAA) agent for `--backend windows` (e.g. `http://localhost:5001`). Overrides `backend.agent_url` | -| `--rdp-host HOST` | RDP host/IP for `--backend rdp` (network RDP via FreeRDP). Overrides `backend.rdp_host`. For a **local** Citrix/Parallels window instead of a network host, set `backend.rdp_window` in `--config` | +| `--macos-app APP` | Exact owner application for `--backend macos` (for example `TextEdit`). | +| `--macos-window-title TITLE` | Window-title substring for `--backend macos`; ambiguous matches are refused. | +| `--linux-app APP` | Exact AT-SPI application name for `--backend linux` (for example `gedit`). | +| `--linux-window-title TITLE` | Exact top-level window title for `--backend linux`; zero or multiple matches are refused. | +| `--linux-allow-physical-input` | Explicitly allow window-bound X11 pointer/keyboard fallback when native AT-SPI actuation is unavailable. | +| `--rdp-host HOST` | RDP host/IP for `--backend rdp` (network RDP). For a local client window use `--rdp-window` instead. | +| `--rdp-window OWNER` | Exact local remote-display window owner/process for `rdp` or `citrix` (`Citrix Viewer` on macOS; `wfica32` on Windows by default for Citrix). | +| `--rdp-window-title TITLE` | Exact local RDP/Citrix client-window title used to disambiguate multiple owner matches. | +| `--rdp-readiness-text TEXT` | Stable text that must be visible before input. Required for governed Citrix `run`. | ```bash # Drive a native Windows app through the in-session agent openadapt flow replay bundle --backend windows --agent-url http://localhost:5001 -# Drive a pixel-only Citrix / RDP session +# Drive one exact native Linux application window through AT-SPI +openadapt flow replay bundle --backend linux \ + --linux-app gedit --linux-window-title 'Patient notes' + +# Drive network RDP openadapt flow run bundle --backend rdp --rdp-host 10.0.0.5 --config deployment.yaml + +# Drive a bound Citrix Workspace window and refuse a locked/not-ready frame +openadapt flow run bundle --backend citrix \ + --rdp-window-title 'Ward A' --rdp-readiness-text 'Appointments' \ + --config deployment.yaml ``` !!! note "Selecting a backend" - `web` (browser), `windows`, and `rdp` (also the transport for Citrix/VDI) are - all first-class substrates behind one backend protocol, running the same - bundle, resolution ladder, identity gate, and effect verification. Every - workflow is qualified in its real environment. See the + `web`, `windows`, `macos`, `linux`, `rdp`, and `citrix` are released + adapters behind one backend protocol, running the same bundle, resolution + ladder, identity gate, and effect verification. Every workflow is qualified + in its real environment. See the [backend support table](../concepts/backends.md#status-at-a-glance) and [Qualification evidence](../get-started/what-works-today.md). @@ -79,9 +96,9 @@ openadapt flow run bundle --backend rdp --rdp-host 10.0.0.5 --config deployment. Record what you do on your own app. The [backend selector](#backend) chooses the substrate: `--backend web` (the default) opens a headed browser on the app at -`--url`; `--backend windows` records a native Windows desktop through its -in-session agent, and `--backend rdp` records a pixel-only Citrix/RDP session. -The example below records the web substrate. +`--url`; the native and remote selectors record Windows, macOS, Linux, RDP, or +Citrix through their exact target flags. The example below records the web +substrate. ```bash openadapt flow record --url https://your.app --out rec @@ -186,9 +203,9 @@ all **fail loudly** and write no bundle. Once authored, drive the loop with Replay a bundle against the substrate chosen by the [backend selector](#backend). On the default `web` backend, `--url` names the target app and, with no `--url`, -replay serves the bundled sample app. For a native Windows desktop or a -pixel-only Citrix/RDP session, use `--backend windows`/`--backend rdp` with its -target flag instead of `--url`. The example below replays the web substrate. +replay serves the bundled sample app. For Windows, macOS, Linux, RDP, or Citrix, +select its backend and exact target flags instead of `--url`. The example below +replays the web substrate. ```bash openadapt flow replay bundle --url https://your.app --param note="Follow-up" diff --git a/docs/reference/deployment-config.md b/docs/reference/deployment-config.md index 93eabc3..ee15eca 100644 --- a/docs/reference/deployment-config.md +++ b/docs/reference/deployment-config.md @@ -23,6 +23,7 @@ name: mockmed-triage-demo # audit / logs only # -- backend: where/how to drive the target application's GUI --------------- backend: + kind: web # web | windows | macos | linux | rdp | citrix url: http://localhost:8080 # GUI under automation; omit to use the # command's default (replay serves MockMed) headed: false # true => a visible browser (demo/debugging) @@ -85,13 +86,56 @@ each other substrate targets through its own field in place of `url`. | Field | Default | Meaning | |---|---|---| -| `kind` | `web` | Substrate to drive: `web` (Playwright/Chromium), `windows` (native Windows via the in-session agent), `macos` (a native macOS app window), `linux` (an exact AT-SPI app window), or `rdp` (pixel-only remote desktop / Citrix). | +| `kind` | `web` | Substrate to drive: `web` (Playwright/Chromium), `windows` (native Windows via the in-session agent), `macos` (a native macOS app window), `linux` (an exact AT-SPI app window), `rdp` (network RDP or a bound local remote-display window), or `citrix` (the dedicated Citrix Workspace/Viewer window backend). | | `url` | `null` | **`web` only.** The GUI URL under automation. `null` lets the command choose its default (`replay`/`run` serve the bundled MockMed demo). | | `headed` | `false` | **`web` only.** Run the browser visible (demo / debugging). | | `agent_url` | `null` | **`windows`.** Base URL of the in-guest agent (e.g. `http://localhost:5001`). Required for `kind: windows`. `agent_token` / `agent_tls_pin` authenticate and pin it. | | `macos_app` | `null` | **`macos`.** Owner application name or substring. Required for `kind: macos`; `macos_window_title` disambiguates a multi-window app. | | `linux_app` | `null` | **`linux`.** Exact AT-SPI application name. Required for `kind: linux`, along with `linux_window_title`. | -| `rdp_host` | `null` | **`rdp`.** Host/IP for a network RDP session. Required for `kind: rdp` unless `rdp_window` names a local Citrix / remote-display client window to drive instead. | +| `linux_window_title` | `null` | **`linux`.** Exact AT-SPI top-level window title. Required for `kind: linux`; zero or multiple matches are refused. | +| `linux_allow_physical_input` | `false` | **`linux`.** Explicitly permits window-bound X11 input when native AT-SPI actuation is unavailable. | +| `rdp_host` | `null` | **`rdp` network mode.** Host/IP for a network RDP session. Required for network `kind: rdp`; never use it with `kind: citrix`. | +| `rdp_username` / `rdp_password` / `rdp_domain` | `null` | **`rdp` network mode.** Credentials passed to the RDP transport. Keep secrets out of committed YAML and inject them at the deployment boundary. | +| `rdp_port` | `3389` | **`rdp` network mode.** Remote Desktop port. | +| `rdp_window` | `null` | **`rdp` local-window or `citrix`.** Exact local client owner/process. Citrix defaults to the host OS's Workspace/Viewer owner, but a deployment can pin it explicitly. | +| `rdp_window_title` | `null` | **`rdp` local-window or `citrix`.** Exact client-window title used to bind one session. Zero or multiple matches are refused. Pin this in a governed deployment when more than one session can exist. | +| `rdp_max_frame_age_s` | `10.0` | **`rdp` or `citrix`.** Maximum age of the captured frame that established a coordinate/input lease. A stale frame halts before input. Choose and qualify a deliberate positive value for the deployment. | +| `rdp_readiness_text` | `null` | **`rdp` or `citrix`.** Stable text that must be visible on the current frame before input. Governed Citrix `run` and `resume` require a nonblank value and refuse before actuation when it is absent. | +| `rdp_readiness_min_ratio` | `0.85` | **`rdp` or `citrix`.** OCR similarity threshold for the readiness marker, from `0.0` to `1.0`. | + +### Citrix Workspace configuration + +Citrix is a dedicated backend, not an alias for generic RDP. Set +`kind: citrix` so Flow constructs `CitrixWorkspaceBackend`, binds the local +Workspace/Viewer window, and carries that closed target through governed run, +halt, and durable resume. + +```yaml +backend: + kind: citrix + rdp_window: wfica32 # Windows; host default is used if omitted + rdp_window_title: Claims - Citrix Workspace # exact session binding + rdp_max_frame_age_s: 3.0 # refuse stale coordinate leases + rdp_readiness_text: Claims queue # required by governed run/resume + rdp_readiness_min_ratio: 0.90 +``` + +On macOS, the default Citrix owner is `Citrix Viewer`; on Windows it is +`wfica32`. An explicit owner is optional when the platform default is correct. +For a governed deployment, use an exact title whenever multiple Workspace +sessions can exist, set the required readiness marker to stable application +chrome (not record-specific data), and qualify the frame-age and OCR thresholds +against the actual session. `kind: citrix` rejects `rdp_host`; use `kind: rdp` +for a network RDP transport. + +!!! important "Governed Citrix deployment profile" + Treat `rdp_window_title`, `rdp_max_frame_age_s`, and + `rdp_readiness_text` as required deployment safety inputs: the exact title + binds the intended session, the positive frame-age limit refuses stale + coordinates, and the stable readiness marker rejects lock, login, + disconnect, or wrong-application screens. Flow enforces a nonblank + readiness marker for governed Citrix `run` and `resume`; deployment review + must also pin and qualify the title and frame-age value before writes. ### `actuation` @@ -146,8 +190,11 @@ flag tweaks one run: openadapt flow run bundle --config deployment.yaml --durable ``` -The overrides: `--backend` / `--url` / `--headed` / `--agent-url` / `--rdp-host` -(backend), `--effects-kind` / +The overrides: `--backend` / `--url` / `--headed` / `--agent-url` / +`--macos-app` / `--macos-window-title` / `--linux-app` / +`--linux-window-title` / `--linux-allow-physical-input` / `--rdp-host` / +`--rdp-window` / `--rdp-window-title` / `--rdp-readiness-text` (backend), +`--effects-kind` / `--effects-base-url` / `--effects-root` (effects), `--api-actuator` / `--api-base-url` (actuation), `--durable` and `--allow-model-grounding` (runtime). See the [CLI reference](cli.md#run) and the diff --git a/docs/reference/documentation-governance.md b/docs/reference/documentation-governance.md index bf22f61..4efc428 100644 --- a/docs/reference/documentation-governance.md +++ b/docs/reference/documentation-governance.md @@ -32,9 +32,9 @@ Public docs must: unified command surface. 2. Link each capability claim to its evidence (benchmarks, PRs, limits) so readers can see exactly what a surface does and does not yet cover. -3. Present every execution substrate (web, native Windows, native macOS, RDP, - and Citrix/VDI) as first-class, and keep the hosted, customer-cloud, and - self-hosted deployment lanes distinct. +3. Present every execution substrate (web, native Windows, native macOS, native + Linux, RDP, and Citrix/VDI) as first-class, and keep the hosted, + customer-cloud, and self-hosted deployment lanes distinct. 4. Put product journeys before package topology. 5. Link claims to the engine's benchmarks and limits rather than silently expanding them. diff --git a/tests/test_substrate_evidence_copy.py b/tests/test_substrate_evidence_copy.py index 58b5148..1ba006f 100644 --- a/tests/test_substrate_evidence_copy.py +++ b/tests/test_substrate_evidence_copy.py @@ -1,15 +1,9 @@ -"""Keep buyer-facing substrate availability tied to exact, bounded evidence. - -Target-state policy: every execution substrate is presented as a first-class -mechanism, not ranked below the browser. Substrates with a validated real -environment are **Early access** (Windows UIA, native macOS, -RDP); Citrix/VDI is **Exploratory** until a real ICA/HDX environment is qualified, -matching the canonical status.json ladder. This guard does not police the -availability label beyond that; it pins the substrate-evidence section to the -current honest wording and verifies that each qualified substrate still ships its -exact, bounded evidence (run counts, oracle, immutable commit, Flow PR) and an -honest per-surface boundary. The public browser offer must stay distinct from -these scoped deployments. +"""Keep released substrate availability tied to exact, bounded evidence. + +Every backend is presented as implemented in the governed product. The tests +also preserve the two independent honesty dimensions: task/environment evidence +does not become a broad app-support claim, and the managed browser runner does +not silently absorb customer-controlled desktop or remote execution. """ from pathlib import Path @@ -23,48 +17,60 @@ def _read(relative_path: str) -> str: return (DOCS / relative_path).read_text() -def test_scoped_windows_macos_and_rdp_evidence_is_exact_and_bounded(): +def test_native_desktop_evidence_is_exact_and_bounded(): what_works = _read("get-started/what-works-today.md") - assert "Windows UIA backend | **Early access**" in what_works - assert "`20260717-candidate-56759c8-v2` in-tree WinForms matrix completed 3/3 trials" in what_works + assert "Windows UIA backend | **Supported**" in what_works + assert ( + "`20260717-candidate-56759c8-v2` in-tree WinForms matrix completed " + "3/3 trials" in what_works + ) assert "independent SQLite oracle confirmed 3/3 effects" in what_works assert "stale-target and ambiguous-target controls each refused 3/3" in what_works assert "0 silent incorrect successes, 0 over-halts, and 0 model calls" in what_works - assert "Each Windows workflow is qualified in its real environment" in what_works assert "preserves earlier rejected diagnostic runs" in what_works assert "defafbae758a75c8e149d9693f2cffe1f2264b8c" in what_works - assert "https://github.com/OpenAdaptAI/openadapt-flow/pull/132" in what_works - assert "Native macOS backend | **Early access**" in what_works - assert "one macOS 15.7.3 arm64 host" in what_works + assert "Native macOS backend | **Supported**" in what_works assert "candidate `b1b61a5` completed 3/3 exact-byte TextEdit trials" in what_works assert "refused a two-window ambiguity without changing either file" in what_works assert "immutable original report remains `status: failed`" in what_works - assert "immutable evidence commit `ca1b522`" in what_works - assert "`ca1b522` preserves its reports and adjudication but is not the current PR head" in what_works assert "verifies the exact harness PIDs and temporary root were absent" in what_works - assert "Each macOS workflow is qualified in its real environment" in what_works assert "ca1b522cad215875f7471782283f8f8bb8e6c998" in what_works - assert "https://github.com/OpenAdaptAI/openadapt-flow/pull/135" in what_works - - assert "RDP backend | **Early access**" in what_works - assert "one Parallels Windows 11 VM at 1280x800 with Aardwolf 0.2.14" in what_works - assert "candidate `82a658a` completed 3/3 trials" in what_works - assert "unique file through the Windows Run dialog over network RDP" in what_works - assert "Independent guest-tools readback confirmed the exact file contents" in what_works - assert "51.845s, 10.467s, and 7.477s" in what_works - assert "0 failures, 0 silent incorrect successes, 0 over-halts, and 0 model calls" in what_works - assert "restored the exact eight-snapshot inventory" in what_works - assert "returned the current pointer without resume to the unchanged original base" in what_works - assert "Each RDP workflow is qualified in its real environment" in what_works - assert "not counted as acceptance trials" in what_works - assert "results_82a658a_20260718.sanitized.json" in what_works - assert "6610d24cebba27918b8ea507b2f05a094057ac85" in what_works - assert "https://github.com/OpenAdaptAI/openadapt-flow/pull/142" in what_works - - -def test_public_offer_and_scoped_substrate_evidence_remain_distinct(): + + assert "Native Linux backend | **Supported**" in what_works + assert "3/3 exact-file effects" in what_works + assert "3/3 ambiguous-target refusals" in what_works + assert "3/3 stale-target refusals" in what_works + assert "3de5fc67acf3024a621f812c5a6ed9be07fac335" in what_works + assert "30059807758/job/89378981573" in what_works + assert "does not establish Wayland or arbitrary third-party application support" in what_works + + +def test_remote_evidence_covers_rdp_lifecycle_and_citrix_contract(): + what_works = _read("get-started/what-works-today.md") + + assert "RDP backend | **Supported**" in what_works + assert "Aardwolf 0.2.14 over a Parallels Windows 11 VM" in what_works + assert "3/3 Windows Run-dialog file effects" in what_works + assert "full governed lifecycle at mechanism commit `6031fde`" in what_works + assert "3/3 healthy effects and 3/3 drift safe-halts" in what_works + assert "affedc5f1f0de533a0744deaa8e30a203c91c6b3" in what_works + assert "https://github.com/OpenAdaptAI/openadapt-flow/pull/177" in what_works + assert "not Aardwolf, a Windows-app qualification, Citrix ICA/HDX" in what_works + + assert "Citrix / VDI backend | **Supported**" in what_works + assert "dedicated `--backend citrix` path" in what_works + assert "requires a readiness marker for governed `run`" in what_works + assert "carries the closed target into durable resume" in what_works + assert "3/3 healthy effects and 3/3 severe-drift safe-halts" in what_works + assert "`code_readiness_accepted: true` and `ica_hdx_accepted: false`" in what_works + assert "not a counted real ICA/HDX batch" in what_works + assert "f6faac5b900b78cbda5980de0e983a9f987285ac" in what_works + assert "https://github.com/OpenAdaptAI/openadapt-flow/pull/183" in what_works + + +def test_public_managed_runner_and_customer_runtime_boundaries_remain_distinct(): pages = [ _read("get-started/what-works-today.md"), _read("concepts/deployment-matrix.md"), @@ -77,18 +83,68 @@ def test_public_offer_and_scoped_substrate_evidence_remain_distinct(): ] combined = "\n".join(pages) - assert "acceptance remains in progress" not in combined - assert "RDP backend | **Early access**" in combined - # Citrix / VDI is a first-class substrate mechanism but has no validated real - # environment yet, so its honest label is Exploratory, matching the canonical - # status.json ladder. The ICA/HDX honesty is preserved: each Citrix/VDI - # workflow must be qualified in its own real ICA/HDX environment before - # consequential use rather than inheriting RDP's evidence. - assert "Citrix / VDI backend | **Exploratory**" in combined - assert "in its real ICA/HDX environment" in combined - # The public browser subscription stays distinct from the scoped substrate - # deployments. + for stale_label in ["Early access", "Exploratory", "Design-partner"]: + assert stale_label not in combined + assert "The public subscription covers approved browser workflows" in combined - assert "scoped separately from the public browser offer" in combined - assert "ordered separately from these scoped deployments" in combined - assert "hosted launch candidate" not in combined + assert "Customer-controlled runtime connected to Cloud" in combined + assert "shared managed-browser boundary" in combined + assert "not a counted real ICA/HDX batch" in combined + + +def test_desktop_beta_release_is_current_and_cross_platform(): + what_works = _read("get-started/what-works-today.md") + install = _read("desktop/install.md") + + for source in [what_works, install]: + assert "desktop-v0.9.0" in source + assert "Windows" in source + assert "macOS" in source + assert "Linux" in source + assert "SHA256SUMS" in what_works + assert "installed, launched, and uninstalled" in what_works + + +def test_deployment_config_selects_dedicated_citrix_backend_and_safety_contract(): + deployment = _read("reference/deployment-config.md") + + assert "`citrix` (the dedicated Citrix Workspace/Viewer window backend)" in deployment + assert "Citrix is a dedicated backend, not an alias for generic RDP" in deployment + assert "kind: citrix" in deployment + assert "Flow constructs `CitrixWorkspaceBackend`" in deployment + assert "rdp_window_title: Claims - Citrix Workspace" in deployment + assert "rdp_max_frame_age_s: 3.0" in deployment + assert "rdp_readiness_text: Claims queue" in deployment + assert "rdp_readiness_min_ratio: 0.90" in deployment + assert "`kind: citrix` rejects `rdp_host`" in deployment + assert "Governed Citrix `run` and `resume` require a nonblank value" in deployment + assert "Treat `rdp_window_title`, `rdp_max_frame_age_s`, and" in deployment + assert "`rdp_readiness_text` as required deployment safety inputs" in deployment + + +def test_source_of_truth_pages_cover_all_released_substrates_and_current_desktop(): + hosted = _read("guides/hosted.md") + security = _read("guides/security-review.md") + ecosystem = _read("ecosystem/index.md") + governance = _read("reference/documentation-governance.md") + + for source in [hosted, security]: + assert "native Linux" in source or "Native Linux" in source + assert "Aardwolf-over-Windows" in source + assert "real FreeRDP round trip" in source + assert "3/3 healthy effects and 3/3 severe-drift safe-halts" in source + assert "`code_readiness_accepted: true`" in source + assert "`ica_hdx_accepted: false`" in source + + assert "native Linux" in ecosystem + assert "desktop-v0.9.0" in ecosystem + assert "desktop-v0.5.1" not in ecosystem + for substrate in [ + "web", + "native Windows", + "native macOS", + "native\n Linux", + "RDP", + "Citrix/VDI", + ]: + assert substrate in governance