nexus-windows-codex 0.0.0-stage → 3.0.0

package/README.md

@@ -1,3 +1,438 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# NexusWindows for Codex
+
+<!-- mcp-name: io.github.pironjulien/nexus-windows-codex -->
+
+[![Release](https://img.shields.io/github/v/release/pironjulien/NexusWindows-Codex)](https://github.com/pironjulien/NexusWindows-Codex/releases)
+[![Tests](https://github.com/pironjulien/NexusWindows-Codex/actions/workflows/tests.yml/badge.svg)](https://github.com/pironjulien/NexusWindows-Codex/actions/workflows/tests.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/pironjulien/NexusWindows-Codex/badge)](https://scorecard.dev/viewer/?uri=github.com/pironjulien/NexusWindows-Codex)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/pironjulien/NexusWindows-Codex/blob/main/LICENSE)
+[![npm](https://img.shields.io/npm/v/nexus-windows-codex)](https://www.npmjs.com/package/nexus-windows-codex)
+[![Node 22+](https://img.shields.io/badge/node-22%2B-5FA04E?logo=nodedotjs&logoColor=white)](https://github.com/pironjulien/NexusWindows-Codex/blob/main/package.json)
+[![.NET 8](https://img.shields.io/badge/.NET-8-512BD4?logo=dotnet&logoColor=white)](https://github.com/pironjulien/NexusWindows-Codex/tree/main/native)
+[![Windows 10/11](https://img.shields.io/badge/Windows-10%20%7C%2011-0078D4)](#installation)
+
+[![NexusWindows: Windows computer use for AI agents, in the background. Works with Claude, Codex and Antigravity.](https://raw.githubusercontent.com/pironjulien/NexusWindows-Codex/main/docs/assets/banner.webp)](https://julienpiron.fr/nexuswindows/)
+
+**Windows computer use for Codex, in the background.** An MCP server (`nexus-windows-codex`, one `npx` command) that
+lets OpenAI Codex see and operate Windows desktop applications while the user keeps their mouse, keyboard and
+foreground window. Codex's own Computer Use came to macOS first; on Windows, OpenAI's documentation says to keep the
+target app visible on the active desktop while it runs ([Codex docs](https://developers.openai.com/codex/app/computer-use)).
+NexusWindows for Codex has its own local .NET helper for everything: window inventory, UI Automation tree, PrintWindow
+capture of covered windows, Win32 messages and UI Automation patterns without focus, and its own real mouse and
+keyboard as the last resort, under a shared foreground token. Every action is judged from the application's real
+state, and a batch needs an explicit postcondition per step. It also ships as a Codex skill that layers the same session over Codex's Computer Use API (`@oai/sky`).
+
+Version 3.0.0 · Windows 10/11 · Node 22+ · .NET 8 · MIT licence
+
+Part of the Nexus family: [NexusWindows](https://julienpiron.fr/nexuswindows/)
+([Claude](https://github.com/pironjulien/NexusWindows-Claude) ·
+[Codex](https://github.com/pironjulien/NexusWindows-Codex) ·
+[Antigravity](https://github.com/pironjulien/NexusWindows-Antigravity)),
+[NexusBrowser](https://julienpiron.fr/nexusbrowser/) ([repo](https://github.com/pironjulien/NexusBrowser)),
+[NexusAndroid](https://julienpiron.fr/nexusandroid/) ([repo](https://github.com/pironjulien/NexusAndroid)).
+Project page: [julienpiron.fr/nexuswindows](https://julienpiron.fr/nexuswindows/).
+
+## Why
+
+Codex's built-in Computer Use acts with the physical mouse and keyboard: it brings the target window to the front and
+the user has to stop working while it acts. Many Windows applications can be driven without that. NexusWindows for
+Codex tries the background techniques first, judges the result from the application's real state, and only uses its
+helper's real mouse and keyboard as a fallback, after a pause in the user's own typing and under a token shared with
+the other agents on the PC.
+
+It is an MCP server (Node, no npm dependency) with a self-contained .NET helper: no listening network port, no token
+and no private Electron API. The optional Codex skill runs the same session in Codex's Node REPL instead, over Codex's
+Computer Use API.
+
+## NexusWindows family
+
+Three MCP servers, one per agent, built separately because each model needs its tools shaped for it, with the same
+promise: the user keeps their mouse, keyboard and foreground window, and every action is read back.
+
+| | Claude | Codex | Antigravity |
+|---|---|---|---|
+| Install | `uvx --python 3.14 nexus-windows` | `npx -y nexus-windows-codex` | `uvx --python 3.14 nexus-windows-antigravity` |
+| Package | [PyPI](https://pypi.org/project/nexus-windows/) | [npm](https://www.npmjs.com/package/nexus-windows-codex) | [PyPI](https://pypi.org/project/nexus-windows-antigravity/) |
+| Tools | `windows` `look` `act` `launch` `window`, plus `notifications` and `logs` | `windows` `look` `act` `launch` `window` | `windows` `look` `act` `launch` `window` |
+| Repository | [NexusWindows-Claude](https://github.com/pironjulien/NexusWindows-Claude) | [NexusWindows-Codex](https://github.com/pironjulien/NexusWindows-Codex) | [NexusWindows-Antigravity](https://github.com/pironjulien/NexusWindows-Antigravity) |
+
+Every step reports ✓ verified, = already done, ~ unknown (never replayed) or ✗ failed or refused. The three share the
+guardrail policy, the foreground token, the emergency stop (Ctrl+Alt+Shift+Esc), a common journal format and a common
+bench.
+
+## Installation
+
+Requirements: Windows 10 or 11 and Node 22+. The npm package carries a self-contained helper: no .NET install.
+
+From [npm](https://www.npmjs.com/package/nexus-windows-codex), in Codex's `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.nexus-windows]
+command = "cmd"
+args = ["/c", "npx", "-y", "nexus-windows-codex"]
+```
+
+On Windows, `npx` is a `.cmd` script, hence `cmd /c`. The same command works in any MCP client
+(`"command": "cmd", "args": ["/c", "npx", "-y", "nexus-windows-codex"]`).
+
+### Codex skill (alternative, from a clone)
+
+The skill runs the same session inside Codex's Node REPL and can fall back on Codex's Computer Use API. It needs the
+Codex desktop app with its Computer Use plugin and the .NET 8 SDK:
+
+```powershell
+git clone https://github.com/pironjulien/NexusWindows-Codex.git
+cd NexusWindows-Codex
+pwsh -NoProfile -File install.ps1             # build the helper, install the skill into %USERPROFILE%\.codex\skills\nexus-windows
+pwsh -NoProfile -File install.ps1 -CheckOnly  # verify the installation matches the sources
+```
+
+`install.ps1` keeps versioned helper builds under `%LOCALAPPDATA%\NexusCodex\ComputerUse` (or `-StateRoot`), writes a
+source-linked `entry.mjs` next to the skill (so keep the clone where it is), checks the four .NET runtime files by
+hash, and serialises concurrent installations. `CODEX_HOME` or `-CodexHome` changes the Codex folder. Re-run it after
+updating the clone. Note: the build path must stay under the Windows 260-character limit. The MCP server also finds
+this helper when it runs from a clone.
+
+The skill is picked up by new Codex sessions. A REPL that already imported an older version must be reset, because
+the JavaScript module cache does not reload.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `windows(filter)` | Application windows (id, app, title, pid), like the taskbar; password managers never listed |
+| `look(window, mode)` | One window by id or a unique part of its title or app: UI Automation tree, plus a capture that works on covered windows with `mode="image"` or `"both"`; selects the window for `act` |
+| `act(steps)` | One step, or up to 32 each with its own `expect`, on the window of the last `look`; stops at the first step not verified |
+| `launch(app)` | Start an application (name, path, Store app id), a folder, a document or a Settings page (`ms-settings:`) and give the foreground back |
+| `window(action, window)` | `action="close"`: one close message, read back; a "save?" prompt is reported, never answered |
+
+Step kinds: `click` (selector, or point and native capture id; `button`, `count`), `setValue`, `typeText`, `key`,
+`select`, `menu`, `secondary`, `scroll`, `drag`. Each step reports ✓ verified, = already done, ~ unknown (look again,
+never replayed) or ✗ failed or refused.
+
+## Usage
+
+As an MCP server: `windows`, then `look` at one window, then `act` with selectors from that look and an `expect`
+that proves the effect. An observation serves one `act` and expires after 60 s.
+
+As a skill, the agent follows [SKILL.md](https://github.com/pironjulien/NexusWindows-Codex/blob/main/skill/nexus-windows/SKILL.md) and the [API reference](https://github.com/pironjulien/NexusWindows-Codex/blob/main/skill/nexus-windows/references/api.md).
+In Codex's Node REPL:
+
+```js
+if (!globalThis.sky) { const { sky } = await import('@oai/sky'); globalThis.sky = sky; }
+const home = nodeRepl.homeDir ?? (await import('node:os')).homedir();
+globalThis.nexusWindows = await import('file:///' + home.replaceAll('\\', '/') + '/.codex/skills/nexus-windows/entry.mjs');
+globalThis.win = nexusWindows.createWindowsSession(sky);
+nodeRepl.write(await win.windows());          // pick exactly one window from this list
+await win.bind({ id: chosenWindowId, app: chosenAppId });
+globalThis.obs = await win.observe();
+globalThis.result = await win.act(obs, {
+  kind: 'click', selector: { automationId: 'okButton', role: 'button' },
+  expect: { selector: { automationId: 'status' }, field: 'name', equals: 'Saved' }
+});
+```
+
+Read `result.status`, `result.technique` and `result.foregroundTaken`, then continue from `result.observation`.
+Call `await win.close()` at the end.
+
+Local files:
+
+| Location | Content |
+|---|---|
+| `%USERPROFILE%\.codex\skills\nexus-windows` | installed skill and `entry.mjs` |
+| `%LOCALAPPDATA%\NexusCodex\ComputerUse\native\<fingerprint>` | versioned helper builds |
+| `%LOCALAPPDATA%\NexusCodex\ComputerUse\recipes` | verified recipes (static UI labels only) |
+| `%LOCALAPPDATA%\NexusCodex\ComputerUse\reports` | explicit measurements, no window content or typed text |
+| `%LOCALAPPDATA%\NexusCodex\ComputerUse\captures` | native captures, 10 minutes and 32 files at most |
+
+## What it does
+
+### Background first, physical input last
+
+Each semantic `click`, `setValue`, `typeText`, `secondary`, `select` and `menu` goes first to the helper:
+
+| UI family | Background technique | Never used |
+|---|---|---|
+| Win32 | `BN_CLICKED` to the parent (`BM_SETCHECK` for check boxes and radio groups), `EM_SETSEL` + `EM_REPLACESEL`, combo box list opened and closed by `CB_SHOWDROPDOWN` (read back by `CB_GETDROPPEDSTATE`), option chosen by `CB_SETCURSEL` + `CBN_SELCHANGE` + `CBN_SELENDOK` (an open list is closed first: that close is a cancel which restores the previous choice), `LB_SETCURSEL` + `LBN_SELCHANGE`, `TCM_SETCURFOCUS`, menu `WM_COMMAND`; UIA Toggle | UIA Invoke (the Win32 proxy calls `SetForegroundWindow`), UIA Select on a list (silent) |
+| WinForms | UIA Invoke/Toggle; messages for Edit, ComboBox (same as Win32, open list included) and ListBox | `BN_CLICKED` on a check box, UIA Select on a list |
+| WPF, UWP/WinUI, Chromium/Electron | COM UI Automation with `AutoSetFocus = FALSE`: Invoke, Toggle, Value, ExpandCollapse (state read back), SelectionItem; a combo box is closed again after any choice | |
+
+A measured detail drives the design: once the managed `System.Windows.Automation` client has been used in a process,
+a COM Invoke or Toggle from that same process activates the target window despite `AutoSetFocus = FALSE` (WPF and
+WinForms on .NET 8). UI Automation patterns are therefore sent from a child process (`--com-worker`) that never loads
+the managed client. Since 1.4.0 the managed client is not loaded anywhere: the tree is read with the COM UI
+Automation client in **one round trip** (`CacheRequest`, `Subtree` scope, control view; about 50 ms for the bench
+forms instead of 150 to 300 ms). For an action, only the target and its ancestors are read again, and any difference
+from the observation is refused.
+
+The options of a Win32/WinForms combo box are read by messages (`CB_GETCOUNT`, `CB_GETLBTEXT`, `CB_GETCURSEL`), open
+or not, as `list`/`listitem` nodes under it; `expanded` comes from `CB_GETDROPPEDSTATE`. Measured: the UIA subtree of
+an open WinForms combo box answers "Malformed Cacheresponse" after about 7 s and then stops answering, so it is never
+walked.
+
+Each technique reads its effect back: `applied`, `none` (nothing changed) or `sent` (no read-back possible).
+Physical fallback happens only when no technique applies, or when the `expect` is not met **and** nothing observable
+changed. A partial effect is never repeated physically; `fallback:false` forbids the physical path. Every result says
+which technique acted (`background:messages`, `background:uia`, `foreground:uia`, `physical:sky`, `sky:semantic`),
+whether the foreground was taken, and every attempt.
+
+### Explicit postconditions
+
+`expect` distinguishes `verified`, `unmet`, `already-satisfied` and unknown results. An observation is consumed once;
+a stale observation, another window, a missing or ambiguous control, or a changed control identity aborts the action
+before any input. A truncated UIA value cannot satisfy an exact equality, and an empty tree never proves that a
+control disappeared. Native password fields are refused.
+
+A postcondition already true **before** the action skips it (`already-satisfied`, nothing sent) only when it is a
+precise state (`equals`) that the action changes: `value`, `checked`, `selected`, `expanded` or `focused` on the
+target, or a result on another element. A postcondition that only restates the target ("the button exists") is
+refused, and a non-precise one already true (`exists`, `includes`, the target's label) is refused before any input:
+it could not tell the effect from the previous state. A combo box choice is proven by the combo box `value`, never by
+its option element.
+
+### Clean capture with PrintWindow
+
+`observe({mode:'image', capture:'native'})` captures the bound window with `PrintWindow(PW_RENDERFULLCONTENT)`
+without bringing it forward, even when covered: per-monitor DPI aware, cropped to the DWM frame, DPI-unaware windows
+drawn at their logical size and scaled. In the Codex skill, a blank, minimized or failed capture falls back to Sky's
+screenshot; the MCP server has no such fallback and reports the failure. Native images are local PNG files (32 files
+at most, removed after 10 minutes at the next capture, at server start and at a clean stop): evidence for the model,
+and the coordinate frame of a point action that names the image (`screenshotId`).
+
+### Verified batches (`actBatch`)
+
+`actBatch(obs, steps)` runs up to 32 actions in one call. Every step needs an `expect`; all steps are validated before
+any input; each step acts on the observation refreshed by the previous one; the batch stops at the first step that is
+not `verified` or `already-satisfied`.
+
+### Multiple windows
+
+The session follows dialogs and popups without a new `bind`: windows owned by the followed windows, windows that
+disable the window in front (modal), and windows of the same process that appear during an action. When a dialog
+closes, the session returns to its nearest open owner. Each observation reports `windowStack` and `windowChange`.
+Transient popups (caption-less `WS_POPUP` windows with `WS_EX_NOACTIVATE`: an open drop-down list, a tooltip, a WPF
+popup; or a Win32 `ComboLBox`) are never followed: they are read through the window's own tree and listed in
+`obs.popups`.
+
+### Guardrails: one shared policy
+
+Since 1.5.0 the guardrails come from the policy shared by the three NexusWindows editions (Codex, Claude,
+Antigravity), `garde-fous.json`, with a `codex` entry. A copy is embedded at the root of this repository; inside the
+author's private workspace the live shared file is read instead (a test checks both are byte-identical).
+`NEXUS_GARDE_FOUS` can point to another file; an imposed path is never silently replaced. A missing or invalid policy
+refuses every action (fail closed), and the .NET helper refuses every window request without a readable policy.
+
+**Hard block** (refused before any read or input): the secure desktop (UAC, lock screen, sign-in), Windows credential
+prompts, password managers (KeePass, Bitwarden, 1Password, Dashlane, NordPass, RoboForm, LastPass, by process
+prefix), and Codex's own application (Codex, ChatGPT), because Codex Computer Use asks for app access inside its
+main window. Consoles and terminals, File Explorer and administration tools are no longer refused (they were until
+1.4.1): the layer is meant for a user who already lets Codex run commands. Password fields stay refused everywhere,
+and their value is never read.
+
+**Confirmation** (`confirm:true` on the action, set only on the user's explicit order or after their yes): paying,
+calling, sending, publishing, deleting permanently, formatting, uninstalling, resetting, cancelling a subscription,
+making a repository public, plus a generic verb (Validate, OK, Start) in a window whose title is about payment or
+formatting. The check is on what the gesture triggers, not on its form, before any input and whatever technique
+follows: a click by selector or by screenshot coordinates (single or double; a text or icon inside a button counts as
+the button), Enter, Ctrl+Enter, Space, Alt+letter (access key or underlined letter), typed text containing a line
+break, a menu command, a secondary action other than expand, collapse, toggle, select or scroll. The refusal
+(`error.confirmationRequired`) sends nothing; a batch stops at that step. A learned recipe never carries
+`confirm`. Direct calls to Sky bypass this layer: always go through the session.
+
+### The user's presence (Raw Input)
+
+A long-lived `--stop-guard` process registers Raw Input (`RIDEV_INPUTSINK`, message-only window, no hook). It reports
+only the instant of each physical keyboard or mouse input, never its content. Injected input, including Sky's own
+`SendInput`, has no source device and is ignored. Before any physical input the session waits for 1.618 s without
+user input (at most 8 s, otherwise the action is deferred and nothing is sent), then types in chunks of at most
+48 graphemes and stops (`interrupted`, never resent) if the user takes the keyboard or mouse back. Without Raw
+Input it falls back to `GetLastInputInfo`, excluding its own injections.
+
+### Application memory
+
+A verified semantic click or secondary action can be saved as a recipe with its expected effect, a fingerprint of
+the executable's metadata and one of the control structure. Any change forces a new inspection. No control number or
+pixel is ever replayed, and typed content is never stored.
+
+### Agent at work
+
+While an action runs (`act`, `actBatch`, `activate`; never an observation), a small logo spins on itself in the
+bottom-right corner of the bound window's screen, like a game loading screen, with a breathing blue halo. It goes away
+1.6 s after the last action. The emergency-stop guard, already alive for the whole REPL, draws it on the commands
+`busy <hwnd>` and `idle` (`native/BusyIndicator.cs`): a layered window that is always on top, borderless,
+click-through, never activated, absent from the taskbar and excluded from screen captures. Rendering is analytic
+(halo, shadow, coin) from `native/logo.png` decoded by GDI+, with no added dependency. `NEXUS_WINDOWS_INDICATOR=0`
+turns it off.
+
+## Working alongside other agents
+
+This layer runs next to two other desktop agents on the same PC (a Claude MCP server,
+[NexusWindows for Claude](https://github.com/pironjulien/NexusWindows-Claude), and an Antigravity layer).
+They coordinate through two file-based protocols that any agent can implement:
+
+**Foreground token** (`%USERPROFILE%\.nexus\foreground.lock`): held only while really using the mouse or the
+foreground (Sky physical input, activation, the foreground UIA fallback), never for reads or background techniques.
+Holding it means an exclusive `LockFileEx` on 1 byte at offset 2^32 (in C#: `FileStream` with
+`FileShare.ReadWrite | FileShare.Delete`, then `Lock(1L << 32, 1)`). Windows releases it when the handle closes,
+including when the process dies. The holder writes `{"owner", "pid", "since", "purpose"}` for diagnostics only. A
+waiter waits at most 8 s, then reports a deferred action and sends nothing.
+
+**Emergency stop** (Ctrl+Alt+Shift+Esc, files in `%USERPROFILE%\.nexus\`): one process per PC holds
+`RegisterHotKey(MOD_NOREPEAT)` (others retry every 3 s) and beats in `stop.owner` every 3 s; a press rewrites `stop`
+with `{"by", "pid", "at", "hold_s": 120, "nonce"}`. Here the `--stop-guard` helper takes the hotkey when nobody else
+holds it, for as long as the Codex REPL lives. The JavaScript session watches `stop` every 0.2 s and before each
+action, and the helper checks it again before each UIA action and token acquisition. A new version younger than 120 s
+blocks every desktop action for the remaining time; observations stay allowed. The stop is latched in memory on a
+monotonic clock: deleting the file or changing the clock does not lift it.
+
+## Architecture
+
+```mermaid
+flowchart LR
+    Codex["Codex"] --> MCP["MCP server bin and lib mcp.mjs"]
+    MCP --> Provider["lib native-provider.mjs"]
+    Provider --> Session["lib session.mjs"]
+    Codex --> Skill["skill entry.mjs in the Node REPL"]
+    Skill --> Session
+    Session -. skill only .-> Sky["Codex Computer Use API"]
+    Session --> Native["lib native.mjs"]
+    Native --> Helper["NexusCodex.UIA server"]
+    Helper --> Messages["Win32 messages"]
+    Helper --> ComWorker["COM only worker for UIA patterns"]
+    Helper --> Capture["PrintWindow capture"]
+    Session --> Guard["stop guard with Raw Input"]
+    Guard --> Shared["shared files in USERPROFILE nexus"]
+    Helper --> Shared
+```
+
+```
+bin/nexus-windows-codex.mjs   the MCP server command (stdio)
+lib/
+  mcp.mjs        MCP protocol and tools (no npm dependency)
+  native-provider.mjs  window inventory by the helper, every window driven by the helper alone
+  session.mjs    WindowsSession: bind, observe, act, actBatch, recipes, window following
+  native.mjs     client for the .NET helper (one reused process, correlated requests, timeouts)
+  tree.mjs       accessibility tree normalisation and digests
+  memory.mjs     recipes and metrics (atomic, locked writes)
+  presence.mjs   user presence from the stop guard
+  stop.mjs       emergency stop watcher and guard process
+native/          .NET 8 helper: Program.cs (modes --server, --com-worker, --stop-guard, --foreground-token),
+                 Background.cs, ComUia.cs, ComWorker.cs, Capture.cs, Presence.cs, EmergencyStop.cs,
+                 ForegroundToken.cs, Win32.cs
+skill/nexus-windows/   SKILL.md and references (API, per-application notes)
+tests/           node:test suites; tests/live: real validation fixture (WinForms, Win32, WPF)
+install.ps1      builds the helper and installs the skill
+test.ps1         offline check; -Full adds the real validation
+```
+
+## Measurements
+
+From [VALIDATION.md](VALIDATION.md) (October 15, 2026, real validation on the repository's own fixture; the file is in
+French). Windows shown without activation at the bottom of the z-order, the Win32 one covered by the WinForms one.
+Each action: postcondition verified, event counted by the application, foreground unchanged, cursor still.
+
+| Action | Technique | Duration (input and read-backs) |
+|---|---|---|
+| Win32 button, check box, typing, append at caret, combo box, list, menu | messages | 105 to 159 ms |
+| WinForms typing, combo box, list | messages | 292 to 338 ms |
+| WinForms check box, button, dialog opened then closed (followed automatically) | COM UIA Toggle / Invoke | 205 to 441 ms |
+| WPF button, check box, value | COM UIA Invoke / Toggle / Value | 193 to 241 ms |
+| Batch of 3 steps, stopped at step 2 (step 3 never sent) | messages | 658 ms |
+| Capture of the covered Win32 window | PrintWindow, not blank | 19 ms |
+
+Offline suite: 108 JavaScript tests, 103 passed and 5 real-environment tests skipped outside `-Full`
+(`test.ps1`, October 16, 2026). Durations are dominated by full UIA tree read-backs. The physical fallback that takes
+the foreground was skipped in that run because the user was active; it is not counted as passed.
+
+### Cross-agent bench (October 16, 2026)
+
+The same task was run by the three Windows desktop agents used on this PC (this layer, the Claude server and the
+Antigravity layer) on WinForms and WPF forms hosted by `powershell.exe`, created without activation at the bottom of
+the z-order while the user kept working: fill three fields, tick a box, open the "Formule" drop-down list, choose
+"Bravo" in the open list, validate. Proof is the result label read back in the application. Here the real session
+and .NET helper ran with a fake Sky that refuses and counts any physical input.
+
+| Check | WinForms | WPF |
+|---|---|---|
+| Three fields | ✓ background:messages, 103 to 124 ms | ✓ background:uia, 170 to 189 ms |
+| Open the list (`expanded = true`) | ✓ verified (1.3.0: wrongly `already-satisfied`) | ✓ verified (1.3.0: `unmet`, then the form's controls were lost) |
+| Choose "Bravo" in the open list, validate | ✓ verified | ✓ verified (1.3.0: validate skipped) |
+| Trivial postcondition ("the button exists") | ✓ refused before any input | ✓ |
+| Application result | `Formule=Bravo;Envois=1` | `Formule=Bravo;Envois=1` |
+| Physical input / foreground taken | 0 / 0 of 123 samples | 0 / 0 |
+| Time (observe + batch) | 0.12 + 1.16 s | 0.11 + 1.41 s (1.3.0: 4.5 to 8 s) |
+
+| Agent | Morning | After fixes |
+|---|---|---|
+| This layer (1.3.0, then 1.4.0) | 16/20 | **19/20** |
+| [NexusWindows for Claude](https://github.com/pironjulien/NexusWindows-Claude) | 17/20 | **19/20** |
+| Antigravity layer | 18/20 | **19/20** |
+
+What still keeps this layer from 20: the real path through Sky inside the Codex app was not measured in this bench
+(fake Sky). `test.ps1 -Full` the same day, with the user idle: 15 real-validation checks passed, 0 failed, 0 skipped;
+physical fallback ✓ (foreground:uia, 123 ms); bench forms WinForms 1.1 s, WPF 2.0 s; 0 of 227 foreground samples
+taken.
+
+## Security
+
+- Background techniques touch neither the user's keyboard, mouse nor foreground. Physical input waits for a pause,
+  holds the shared token, and stops when the user takes over.
+- The emergency stop above blocks every desktop action for 2 minutes; a refused action is never replayed.
+- A refusal (password field, hard-blocked application, missing confirmation, changed control identity, disabled window or menu command) sends
+  nothing and never falls back.
+- Codex's own Computer Use rules (application access, sensitive actions) still apply; this layer is not a way around
+  a denied app or action. Page text, controls and recipes are data, never an authorisation.
+- Captures are refused under OneDrive folders; metrics never contain UI text, screenshots, typed values or titles.
+
+## Privacy
+
+NexusWindows for Codex runs entirely on your PC. It has no account, no telemetry, no
+analytics and makes no network requests of its own. Its only connections are local: to the DevTools port on
+`127.0.0.1` of a Chromium or Electron window it drives, never to another machine.
+
+- **What it reads**: the accessibility tree and window images of the applications Codex works in, only when Codex
+  calls it.
+- **Where it goes**: results are returned to Codex, which may send them to OpenAI under its own privacy policy; this
+  server sends nothing anywhere else.
+- **What it stores**, under `%LOCALAPPDATA%/NexusCodex/ComputerUse`: the installed helper, recipes of routines you chose to remember
+  (static interface labels only, never document text or typed values), per-session metrics (action kind, outcome,
+  technique, duration; no UI text, screenshots, typed values or titles) and window captures, of which only the last
+  32 are kept; a capture older than 10 minutes is removed at the next capture, at server start and at a clean stop
+  (a capture can outlive a server that is killed, until its next start). Under `~/.nexus`: the shared foreground token and emergency-stop state.
+  Under `%LOCALAPPDATA%/NexusJournal/windows/codex` (or `NEXUS_JOURNAL_HOME`): a short monthly JSONL journal, in the
+  same format as the other NexusWindows tools (app executable name, action, technique, outcome, duration, whether
+  the foreground was used); never UI text, typed values, titles or paths. The server never deletes it.
+- **Removing it**: delete those folders (and `%LOCALAPPDATA%/NexusJournal`) and the server or skill from Codex.
+
+Questions or concerns: open an issue on this repository.
+
+## Limits
+
+- Support does not mean every Windows application is certified. Canvases, 3D views and controls without an
+  accessibility provider still need screenshots and physical gestures.
+- Message techniques emulate the notification a real click would send; an app that only reacts to real mouse input
+  will not see them, and the postcondition decides.
+- Raw clicks, wheels, keyboard shortcuts and rich editors without an Edit control still need physical input. Tk has
+  no UI Automation and ignores posted input.
+- An effect with no trace in the accessibility tree cannot be told from "no effect": give a postcondition that
+  observes it, or `fallback:false`.
+- `launch` attributes a window to the launch by its process, and says how (`proof`): `process`, the process the
+  shell returned; or `application`, for an application named by its executable or Store id (whose launcher may hand
+  over to another process), a process of that application born after the request. With `application`, another
+  instance of the same application started by something else at the same moment could be taken for it. Files and
+  folders need an absolute path; their windows come back as candidates unless the shell returned the process that
+  shows them.
+- In the skill, Sky's physical input cannot be tested outside the Codex REPL; its orchestration (pause, token,
+  chunks, interruption) is covered by the offline tests only. The MCP server never uses Sky.
+- The skill, comments and some messages are written for one user (they name the user) and partly in French.
+
+## Development
+
+```powershell
+pwsh -NoProfile -File test.ps1         # node tests + helper build in a temp folder; never touches %USERPROFILE%\.nexus
+pwsh -NoProfile -File test.ps1 -Full   # also real token/stop tests and the background validation on the fixture
+```
+
+## Licence
+
+MIT, see [LICENSE](https://github.com/pironjulien/NexusWindows-Codex/blob/main/LICENSE). Copyright (c) 2026 Julien Piron.

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security policy
+
+NexusWindows for Codex drives real Windows applications, so safety issues matter more than usual: a way to make the
+agent pay, send, publish, delete permanently or confirm without `confirm: true`, to read or drive a password manager,
+a credential prompt or the secure desktop, to type into a password field, to take the user's mouse, keyboard or
+foreground outside the shared token and the user's pause, or to act during the emergency stop.
+
+Please report such issues privately through
+[GitHub private vulnerability reporting](https://github.com/pironjulien/NexusWindows-Codex/security/advisories/new),
+not in a public issue. Include the tool call, the application involved and what happened. You will get an answer
+within a few days.
+
+Only the latest release is supported.

package/bin/nexus-windows-codex.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Commande `nexus-windows-codex` : serveur MCP autonome (stdio) de NexusWindows for Codex, sans Sky.
+// Helper natif cherché dans l'ordre : NEXUS_WINDOWS_CODEX_HELPER, celui du paquet npm (native/bin, construit par la
+// CI), puis celui de install.ps1 (installation.json de l'état local).
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { NativeUIA } from '../lib/native.mjs';
+import { nativeProvider } from '../lib/native-provider.mjs';
+import { WindowsSession } from '../lib/session.mjs';
+import { emergencyStop } from '../lib/stop.mjs';
+import { WindowsTools, serve } from '../lib/mcp.mjs';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const stateRoot = path.join(process.env.LOCALAPPDATA ?? path.join(process.env.USERPROFILE ?? '.', 'AppData', 'Local'), 'NexusCodex', 'ComputerUse');
+
+function helperPath() {
+  // Chemin imposé : lui seul (absent = aucun helper), jamais un autre trouvé à sa place.
+  const forced = process.env.NEXUS_WINDOWS_CODEX_HELPER;
+  if (forced) return existsSync(forced) ? forced : null;
+  const candidates = [path.join(root, 'native', 'bin', 'NexusCodex.UIA.exe')];
+  try { candidates.push(JSON.parse(readFileSync(path.join(stateRoot, 'installation.json'), 'utf8')).NativeExecutable); } catch { /* pas d'install.ps1 */ }
+  return candidates.find(file => file && existsSync(file)) ?? null;
+}
+
+const version = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8')).version;
+// Hors Windows ou sans helper, le serveur démarre et liste ses outils (annuaires MCP qui le lancent dans un conteneur
+// Linux) ; chaque appel répond la cause, rien n'est tenté.
+const unavailable = reason => ({ async call() { throw new Error(reason); } });
+const helper = process.platform === 'win32' ? helperPath() : null;
+if (process.platform !== 'win32') {
+  await serve({ tools: unavailable('NexusWindows for Codex drives the Windows desktop: Windows 10 or 11 is required.'), version });
+} else if (!helper) {
+  await serve({ tools: unavailable('Native helper not found: install the npm package, run install.ps1, or set NEXUS_WINDOWS_CODEX_HELPER.'), version });
+} else {
+  const stop = emergencyStop();
+  stop.startGuard(helper);
+  const native = new NativeUIA(helper, { emergencyStop: stop });
+  const session = new WindowsSession(nativeProvider(native), { stateRoot, native, emergencyStop: stop, maxAgeMs: 60000 });
+  await session.pruneCaptures(); // captures d'une session précédente : purgées dès le démarrage
+  await serve({ tools: new WindowsTools(session), version });
+  await session.close().catch(() => {});
+  native.close();
+}
+process.exit(0);