nexus-windows-antigravity 3.0.0__tar.gz

nexus_windows_antigravity-3.0.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.log
+.venv/
+
+# Windows / OS
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+.DS_Store
+
+# Backups
+*.bak
+*.tmp
+
+# Development caches (normally stored outside OneDrive by test.ps1)
+.pytest_cache/
+.ruff_cache/

nexus_windows_antigravity-3.0.0/CHANGELOG.md

@@ -0,0 +1,215 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+This is the public changelog of NexusWindows for Antigravity: it lists the changes that matter to someone using the
+MCP server. Versions up to 2.5.0 were published here under the name "Antigravity Computer Use"; see the git history.
+
+## [Unreleased]
+
+## [3.0.0] - 2026-10-23 — One-command install, common tool names
+
+The three NexusWindows tools (Claude, Codex, Antigravity) move to 3.0.0 together: one-command install from a package
+registry, the same five tool names (`windows`, `look`, `act`, `launch`, `window`), the same step outcomes
+(✓ verified, = already done, ~ unknown, ✗ failed or refused), and from now on one version number for the family.
+
+### Added
+- PyPI package `nexus-windows-antigravity`: `uvx --python 3.14 nexus-windows-antigravity` in Antigravity's
+  `mcp_config.json`, no clone needed; published by Trusted Publishing, then to the official MCP registry.
+- The server announces its title and version at initialization.
+
+### Changed
+- Listed tools renamed `windows`, `look`, `act`, `launch` (`app`) and `window` (`action="close"`), like the other two
+  tools; the former names (`computer_look`, `computer_act`, `computer_open_path`, `computer_close_window`...) stay
+  callable, unlisted.
+- Python 3.11 or later (Pillow 13 requires it); Pillow 13.0.0.
+
+### Fixed
+- `computer.log` no longer records the expected or observed text of a failed batch, nor typed text quoted by a step
+  error: only their length (the reply to the agent keeps them). Screenshots are pruned after each write (at most 50,
+  previously 51) and at server start.
+
+## [2.11.0] - 2026-10-23 — Background input recipes, common journal, stop on unknown outcome
+
+### Added
+- Common journal shared by the three NexusWindows tools (Claude, Codex, Antigravity): every action call (opening,
+  closing, scrolling, dragging, refusals, stops, confirmations) writes one line per batch step to
+  `%LOCALAPPDATA%\NexusJournal\windows\antigravity\` (or `NEXUS_JOURNAL_HOME`), `~` when the effect was not read
+  back. It never contains screen text.
+- Coordinate clicks and the mouse wheel in the background in Win32 and WinForms: messages posted to the deepest child
+  under the point (foreground, cursor and clipboard untouched). Sent once, never replayed with the real mouse.
+  Coordinate clicks are also posted in covered Chromium/Electron windows.
+- Ctrl/Shift shortcuts in the background in Win32 and WinForms: keys posted with a simulated keyboard state on the
+  target's thread only, restored once the target has processed them (Ctrl+S never becomes S); Alt is refused.
+- Right-click and double-click in Win32 and WinForms posted at the element's centre: a WinForms context menu opens
+  without touching the foreground, and its command is then picked by label.
+- Single-line fields in Chromium/Electron set in the background through UI Automation Value (input events fired);
+  never for multi-line fields or rich editors, which UI Automation cannot tell apart.
+- Chromium/Electron without real activation: `<select>` picked by typing its label, appending to rich editors and
+  multi-line fields, keys and Ctrl shortcuts. Focus is taken and proved just before sending; never with a
+  validating Enter or a line break.
+- Covered Chromium/Electron windows publish their accessibility changes before each read: fields and the options of
+  an open list are no longer missing.
+- Mouse wheel in the background in Chrome, Edge and Electron through the window's own DevTools port. Nothing is sent
+  unless the port belongs to the window's exact process, the page is proved to be the one shown in that window and
+  exactly one render surface matches its viewport; one input event only, an unacknowledged one is an unknown outcome,
+  never replayed. New dependency: `websocket-client`.
+- Mouse wheel at a point in WPF, UWP and WinUI (which ignore posted wheel messages) by semantic scrolling
+  (ScrollPattern) of the smallest scrollable container under the point; ambiguity refuses, a real end (0/100 %) sends
+  nothing, and the position read back decides whether it is verified.
+
+### Fixed
+- `computer_act` stops a batch as soon as a step stays unverified, before sending the next action: a
+  validation can no longer follow a click whose effect is unknown. No automatic replay; the result is
+  `unverified`, `success: None`, and says the rest was not sent. A true `expect`, an already-satisfied state or a
+  verified wait still lets the batch go on.
+- A step whose control was already in the wanted state no longer keeps the `already` mark when its final
+  postcondition is unreadable or false: it reports `~` or `✗` and the batch stops.
+- Partial send (one message posted, then a refusal) is an unknown outcome: never a physical fallback or a second
+  technique on top of it.
+- WinForms push buttons: `BN_CLICKED` is posted first (a synchronous UI Automation Invoke blocked on a modal dialog
+  and the fallback opened it twice); after an unverified `BN_CLICKED`, no second technique.
+- List items outside Win32/WinForms are selected by UI Automation Select only (Invoke then Select selected twice in
+  Electron); a Chromium item still read as unselected afterwards is an unknown outcome, never a physical click on top.
+- Posted double-clicks and right-clicks are verified only by structural evidence (title, application windows, size);
+  a selection made by the first click no longer passes for a verified double-click. Window size is proved by its
+  rectangle, never by comparing two screenshots.
+- Posted clicks in windows that are not DPI-aware (or system-DPI-aware) are converted to logical pixels: at 125 %, a
+  double-click on a WinForms list landed one row too low.
+- A posted double-click on a covered WinForms control is refused before sending; the real mouse takes over only when
+  `foreground=true` is allowed.
+- Physical wheel is proved by the scroll position read back from the targeted container, never by the window title
+  or the tree; without a readable container the outcome is unverified.
+- DevTools wheel recognises tabbed Edge titles ("page - Profile 1 – Microsoft Edge").
+- `computer_open_path` resolves a bare program name (`notepad.exe`, `mspaint`) like Start > Run (PATH including Store
+  aliases, then App Paths) instead of answering "path not found".
+- Text targets: an editable ComboBox and its same-named child Edit (the "File name:" box of Open/Save dialogs) are no
+  longer ambiguous; the text goes to the Edit.
+- `computer_close_window` reports a closed window as verified (`✓`) when it is destroyed, or was visible and is now
+  hidden; the wait is 2 s for UWP apps. A lost COM reply stays `~`, and `WM_CLOSE` is never replayed.
+- The foreground is given back by the window that holds it, never taken from a window the user has just chosen.
+- Emergency stop: the remaining time is now capped at the 120 s hold (floating-point rounding could report
+  120.00000000000003 s).
+
+### Changed
+- "Agent at work" indicator: the breathing halo is gone; only the logo spins, with its drop shadow.
+- Checked on the common bench of the three NexusWindows tools (Claude, Codex, Antigravity): canvas click, wheel and
+  Ctrl+K in Win32/WinForms now pass, and double actions are gone.
+- Development tools and CI actions updated: ruff 0.17.1, pyright 1.1.414, `actions/checkout` v7.0.1,
+  `astral-sh/setup-uv` v10.3.0 (pinned by hash).
+
+## [2.10.0] - 2026-10-20 — "Agent at work" indicator
+
+### Added
+- While an action runs (`computer_act`, opening, closing, focusing and the action aliases; never the reads), a logo
+  spins on itself in the bottom-right corner of the driven window's screen with a breathing blue halo, and goes away
+  1.6 s after the last action. Always on top, borderless, click-through, never activated, absent from the taskbar,
+  excluded from screen captures. `NEXUS_WINDOWS_INDICATOR=0` turns it off.
+
+## [2.9.0] - 2026-10-20 — Exact-action consent, visual fallback, hardened supply chain
+
+### Added
+
+- **Consent bound to the exact action** for outward gestures (paying, sending, publishing, transferring, calling):
+  besides `confirm: true`, a single-use `accord` token (10 minutes) returned by the first refusal, which describes
+  the exact action. It binds the tool, the gesture, the target, the actual contents of the window's editable fields
+  (read again at execution, passwords excluded) and the window; any change voids it. Also covers validation keys
+  (Enter, Ctrl+Enter, Space, Alt shortcuts), coordinate clicks and `type_text(submit=True)`. Local destructive
+  actions (permanent deletion, formatting, uninstalling, resetting) keep `confirm: true` alone.
+- **Visual fallback**: `target` accepts coordinates (`"@150,200"`, `"150, 200"`, `"coords:150,200"`) and Gemini
+  boxes (`"[ymin, xmin, ymax, xmax]"`, `"box_2d:[...]"`); a step whose label is missing from the UI Automation
+  tree falls back to its coordinates; `computer_look` says when a window exposes no UI Automation element.
+- Blind paste guard: a batch may not chain a paste (Ctrl+V) and a validation; the pasted text is read back first.
+- OpenSSF Scorecard workflow and badge; Dependabot for GitHub Actions and uv (7-day cooldown); GitHub Actions
+  pinned by commit SHA without persisted credentials (zizmor clean).
+- Every MCP tool has a readable `title` in its annotations, next to its four hints.
+- The server starts and lists its tools outside Windows (as MCP directories such as Glama check it, in a Linux
+  container); there, each tool call answers that Windows is required. Windows-only dependencies (`comtypes`,
+  `uiautomation`) are installed on Windows only.
+- GitHub Actions: `test.ps1` on Windows and the startup test on Linux, with a Tests badge; `glama.json`.
+- README: Privacy section.
+- README: demo (animated WebP, GIF fallback) recorded with this server's own `computer_act` on neutral test
+  windows: one batch of five steps in a window behind another, the user's window untouched.
+
+### Changed
+
+- Repository renamed to `pironjulien/NexusWindows-Antigravity`; GitHub redirects the old address.
+- Shared guard-rail policy updated (nexus-shared 6d82bbb): erasing, resetting or formatting the whole device now
+  needs confirmation too; "erase everything" counts only on a reset screen.
+- Shared guard-rail policy updated (same file as the Claude, Codex and Android editions): calling ("appeler",
+  "call") now needs `confirm: true` too.
+- `SECURITY.md`: private vulnerability reporting.
+
+## [2.8.2] - 2026-10-18
+
+### Changed
+- The guard-rail lists (protected surfaces, password managers, confirmation patterns, payment and formatting
+  contexts, action and non-action roles) are read from a policy file shared with NexusWindows for Claude
+  (`client/garde-fous.json`, read by `client/garde_fous.py`) instead of being hard-coded. Behaviour unchanged,
+  checked value by value against 2.8.1. If the policy cannot be read, the server refuses to start.
+- Repository renamed to `antigravity-windows-computer-use` and README rewritten as NexusWindows for Antigravity.
+
+## [2.8.1] - 2026-10-18
+
+### Added
+- Password managers (KeePass, KeePassXC, Bitwarden, 1Password, Dashlane, NordPass, RoboForm, LastPass, matched by
+  process prefix) are hard-blocked: never looked at, read through UI Automation, captured or driven. A full-screen
+  capture is refused while one of them is shown.
+- Making a repository public needs confirmation ("Make public", "Change to public", "Rendre public"...).
+- An explicit order from the user counts as confirmation (`confirm: true` directly); only the agent's own initiative
+  asks first.
+
+## [2.8.0] - 2026-10-18
+
+### Fixed
+- Enter, Space and `submit` no longer get around confirmation: a key is judged on what it would trigger (default
+  button of the window, focused button, send button next to the field; Ctrl+Enter: any action button of the window;
+  Alt+letter: the button or menu of that access key). Shift+Enter and Alt+Enter stay free.
+- A coordinate click outside any UI Automation control is checked against the short text read under the point
+  before the real mouse is used.
+
+### Added
+- More irreversible actions under confirmation: uninstall, format a drive, reset, factory reset, cancel a
+  subscription, delete or close an account, erase data.
+- Generic verbs judged by the window title: validate/confirm/OK in a payment or money-transfer window, start/OK in a
+  format dialog.
+- MCP tool annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`).
+
+### Changed
+- MCP SDK 1.30 → 2.3.0; `comtypes` declared as a dependency.
+- The UI Automation read also returns the access key and the keyboard focus, in the same round trip.
+
+## [2.7.0] - 2026-10-17
+
+### Changed
+- Autonomy first: banking and finance applications, password fields (filled, masked value never read back),
+  Chrome/Edge (with a note that a browser bridge is more reliable for the web) and any existing path in
+  `computer_open_path` are allowed. The sign-in screen, lock screen and UAC prompt stay refused.
+- Confirmation limited to actions that reach a third party or cost money (pay, buy, order, transfer money, send,
+  publish, delete permanently, empty the trash), in one list (`CONFIRM_PATTERNS`).
+- `NEXUS_AGY_CONFIRM=off` in the MCP server environment turns confirmation off (default: on).
+- Windows activation protocols (`ms-settings:`, `shell:`) open through `computer_open_path`; web addresses are
+  refused with a pointer to a browser tool.
+
+## Earlier changes since 2.5.0 (2026-10-14 to 2026-10-17)
+
+### Added
+- Five listed MCP tools (`computer_list_windows`, `computer_look`, `computer_act`, `computer_open_path`,
+  `computer_close_window`); the older tool names stay callable as unlisted aliases.
+- Designed for Gemini: one-line `next` in every reply, compact look (one line per element), WebP image of the window
+  when an effect was not read back, refusal of a batch resent unchanged without a new look.
+- Background techniques per UI family: direct Win32 messages, UI Automation read in one cross-process round trip,
+  posted keys in Win32, WinForms and WPF; real input only as a fallback with `foreground=True`.
+- Read-back after every action (`verified`), postconditions (`expect`), `check`, `uncheck`, `select` and `menu`
+  steps.
+- The user's physical input detected through Raw Input: pause before real input, stop if the user takes over.
+- Shared foreground token and emergency stop (Ctrl+Alt+Shift+Esc) with the other desktop agents of the PC.
+- Guards in the code: named window required, ambiguous labels refused with the candidates, foreground read back
+  before every `SendInput`, clipboard saved and restored.
+
+### Removed
+- The Chrome browser bridge, moved to its own project, NexusBrowser
+  ([chrome-computer-use](https://github.com/pironjulien/chrome-computer-use)).
+- The floating companion window and the former multi-adapter layout of 2.5.0.

nexus_windows_antigravity-3.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julien Piron (https://julienpiron.fr)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nexus_windows_antigravity-3.0.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.5
+Name: nexus-windows-antigravity
+Version: 3.0.0
+Summary: NexusWindows for Antigravity: Windows computer use in the background for Google Antigravity (MCP server).
+Project-URL: Homepage, https://julienpiron.fr/nexuswindows/antigravity/
+Project-URL: Repository, https://github.com/pironjulien/NexusWindows-Antigravity
+Project-URL: Changelog, https://github.com/pironjulien/NexusWindows-Antigravity/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/pironjulien/NexusWindows-Antigravity/issues
+Author: Julien Piron
+License-Expression: MIT
+License-File: LICENSE
+Keywords: antigravity,computer-use,gemini,mcp,model-context-protocol,ui-automation,windows
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Desktop Environment
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: comtypes<2,>=1.4.17; sys_platform == 'win32'
+Requires-Dist: mcp<3,>=2.3.0
+Requires-Dist: mss<11,>=9.0
+Requires-Dist: pillow<14,>=13.0.0
+Requires-Dist: uiautomation<3,>=2.0; sys_platform == 'win32'
+Requires-Dist: websocket-client<2,>=1.8
+Description-Content-Type: text/markdown
+
+# NexusWindows for Antigravity
+
+<!-- mcp-name: io.github.pironjulien/nexus-windows-antigravity -->
+
+[![Release](https://img.shields.io/github/v/release/pironjulien/NexusWindows-Antigravity)](https://github.com/pironjulien/NexusWindows-Antigravity/releases)
+[![Tests](https://github.com/pironjulien/NexusWindows-Antigravity/actions/workflows/tests.yml/badge.svg)](https://github.com/pironjulien/NexusWindows-Antigravity/actions/workflows/tests.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/pironjulien/NexusWindows-Antigravity/badge)](https://scorecard.dev/viewer/?uri=github.com/pironjulien/NexusWindows-Antigravity)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/pironjulien/NexusWindows-Antigravity/blob/main/LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/nexus-windows-antigravity)](https://pypi.org/project/nexus-windows-antigravity/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue?logo=python&logoColor=white)](https://github.com/pironjulien/NexusWindows-Antigravity/blob/main/pyproject.toml)
+[![MCP](https://img.shields.io/badge/MCP-server-7ee2a8)](https://modelcontextprotocol.io)
+[![Windows 10/11](https://img.shields.io/badge/Windows-10%20%7C%2011-0078D4)](#install)
+
+[![NexusWindows: Windows computer use for AI agents, in the background. Works with Claude, Codex and Antigravity.](https://raw.githubusercontent.com/pironjulien/NexusWindows-Antigravity/main/docs/assets/banner.webp)](https://julienpiron.fr/nexuswindows/)
+
+![NexusWindows for Antigravity: an AI agent fills and submits a form through act in a window that stays behind another one, five steps read back](https://raw.githubusercontent.com/pironjulien/NexusWindows-Antigravity/main/docs/assets/demo.webp)
+
+**Windows computer use for Antigravity, in the background.** An MCP server (`nexus-computer`) that lets Google
+Antigravity (Gemini) see and operate Windows desktop applications while the user keeps their mouse, keyboard and
+foreground window. Built for a fast model: one look, then one batch of steps with label targets, and every reply
+says what to do next.
+
+Version 3.0.0 · Windows 10/11 · Python 3.11+ · 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
+
+Screenshot-and-click computer use moves the real cursor and brings windows to the front, so the person at the PC has
+to stop working while the agent acts. Most Windows applications can be driven without that: native controls accept
+window messages and modern frameworks expose UI Automation. This server acts in the background first, reads the
+effect back, and only falls back to the real mouse or keyboard when the step allows it (`foreground=True`).
+
+## 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, [uv](https://docs.astral.sh/uv/) (`winget install astral-sh.uv`).
+
+From [PyPI](https://pypi.org/project/nexus-windows-antigravity/), no clone needed: declare the server in
+Antigravity's `mcp_config.json` (`%USERPROFILE%\.gemini\config\mcp_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "nexus-computer": {
+      "command": "uvx",
+      "args": ["--python", "3.14", "nexus-windows-antigravity"],
+      "env": { "PYTHONUTF8": "1" }
+    }
+  }
+}
+```
+
+The agent guide that teaches Antigravity the five tools is
+[`SKILL.md`](https://github.com/pironjulien/NexusWindows-Antigravity/blob/main/plugins/nexus-computer/skills/nexus-computer/SKILL.md): copy the
+`plugins/nexus-computer` folder into Antigravity's plugins to install it with the server.
+
+From a clone (development), with PowerShell 7:
+
+```powershell
+git clone https://github.com/pironjulien/NexusWindows-Antigravity.git
+cd NexusWindows-Antigravity
+pwsh -NoProfile -File install.ps1
+```
+
+The Python environment, logs and screenshots then live in `%USERPROFILE%\.nexusagy` (outside the clone), and the
+server is declared with `"command": "pwsh"`, `"args": ["-NoProfile", "-File",
+"C:/path/to/NexusWindows-Antigravity/scripts/start-computer-mcp.ps1"]`.
+
+## Tools
+
+Five listed MCP tools, named like the other NexusWindows tools (Claude, Codex); the older names (`look`,
+`computer_act`, `computer_click`...) stay callable as unlisted aliases.
+
+| Tool | Purpose |
+| --- | --- |
+| `windows` | Application windows (`by_app=true`: grouped by application) |
+| `look` | One line per element `[N] role « name » = « value » states @x,y`, plus an image, without bringing the window forward |
+| `act` | Several steps in one call (click, type, check, uncheck, select, menu, keys...), each read back: ✓ = ~ ✗ |
+| `launch` | Open an application, document, folder, script or shortcut; the opening is read back |
+| `window` | `action="close"`: close a window (UI Automation, then `WM_CLOSE`) |
+
+Tool descriptions and replies are in French; tool and parameter names are in English.
+
+## What it does
+
+- **Designed for Gemini**: golden rule *look, then act in one batch with label targets*; every action reply carries
+  a one-line `next` (✓ done · = already done, do not redo · ~ effect not seen, look at the attached image · ✗ failure,
+  cause and what to try) and, when the effect was not read back, a compact WebP image (≤ 1280 px) of the window. A
+  batch identical to one sent in the last 10 s on the same window without a `look` in between is
+  **refused** (`repeat=true` forces it).
+- **Background first, even with `foreground=True`**: a `box_2d` or (x, y) target is mapped to the element under the
+  point in the window's own UI Automation tree (covered windows included) and handled like a label target; a click on
+  a text field *retains* it, so `type` without target, `ctrl+a`, `ctrl+v` and erase keys become background writes
+  read back; plain keys are posted (`WM_KEYDOWN`/`WM_KEYUP`) in Win32, WinForms and WPF. Real mouse and keyboard only
+  as a fallback with `foreground=True`; otherwise an explicit refusal (`needs_foreground`) and nothing is sent.
+- **Per UI family**: Win32 → direct messages (`BN_CLICKED`, `BM_SETCHECK`, `EM_REPLACESEL`, `CB_SETCURSEL` /
+  `LB_SETCURSEL` with their notifications, menu `WM_COMMAND`); WinForms → UI Automation then messages; WPF, UWP,
+  Chromium → UI Automation only. Never UI Automation Invoke on a Win32 button (its proxy activates the window) nor
+  Select on a Win32 list (silent).
+- **One cross-process read**: the window-scoped UI Automation tree is read in one round trip
+  (`IUIAutomationCacheRequest` + `BuildCache`, `AutoSetFocus = False`). A truncated or failed read is reported
+  (`uia.status`, `warning`), never a silent empty list.
+- **Read-back after every action**: `verified` true/false/None from a real read (field value, check state,
+  selection, focused element, window title, image); `success` is never true on "command sent" alone. Steps accept a
+  postcondition `expect` (already true: step skipped with `already: true`; false after: step failed).
+  A batch stops at the first failed or unverified step, before sending the next action, with no automatic replay.
+  A verified postcondition establishes the effect and allows the batch to continue; an unknown effect requires
+  observation before preparing the remaining steps.
+- **The user's physical input via Raw Input** (injected input ignored): wait for a pause before any real mouse or
+  keyboard action, and stop at the next checkpoint if the user touches keyboard or mouse (`interrupted_by_user`).
+- **Guards in the code, not only in the instructions**: the window is always named (never the foreground one by
+  default, ambiguous titles refused with the candidates); an ambiguous label is refused with the candidates; the
+  target window is read back in the foreground right before every `SendInput`; password managers (KeePass,
+  KeePassXC, Bitwarden, 1Password, Dashlane, NordPass, RoboForm, LastPass) are never looked at, captured or driven;
+  the sign-in screen, lock screen and UAC prompt are refused. An action labelled pay, buy, order, transfer money,
+  send, publish, delete permanently, uninstall, format, reset, cancel a subscription, erase data or make a repository
+  public needs `confirm: true` on the step, and so does any key, `submit` or coordinate click that would trigger one.
+  `NEXUS_AGY_CONFIRM=off` in the MCP server environment turns confirmation off entirely (default: on).
+- **Clipboard**: saved in all its formats and restored; the text put there is excluded from Win+V history and cloud
+  clipboard. Used only as a last resort for typing (multi-line or more than 300 characters).
+- **Agent at work**: while an action runs (`act`, opening, closing, focusing and the action aliases; never
+  the reads), a small logo spins on itself in the bottom-right corner of the driven window's screen, like a game
+  loading screen, with a breathing blue halo, and goes away 1.6 s after the last action. Always on top, borderless,
+  click-through, never activated, absent from the taskbar and excluded from screen captures (`busy_indicator.py`).
+  `NEXUS_WINDOWS_INDICATOR=0` turns it off.
+- **Shared with the other desktop agents of the PC**: foreground token (`%USERPROFILE%\.nexus\foreground.lock`) and
+  emergency stop (Ctrl+Alt+Shift+Esc, `%USERPROFILE%\.nexus\stop`), the same file protocols as
+  [NexusWindows for Claude](https://github.com/pironjulien/NexusWindows-Claude#working-alongside-other-agents).
+
+## Architecture
+
+| Path | Role |
+| --- | --- |
+| `client/mcp_server.py` | MCP server `nexus-computer` (stdio), started by `scripts/start-computer-mcp.ps1` |
+| `client/computer_client.py` | Windows engine: windows, UI Automation, Win32 messages, capture, actions and read-back |
+| `client/uia_fast.py`, `client/win32_controls.py` | One-round-trip UI Automation reads, native control messages |
+| `client/physical_input.py`, `client/agent_guard.py`, `client/emergency_stop.py` | The user's presence (Raw Input), batch guard, shared emergency stop |
+| `client/foreground_lock.py`, `client/garde_fous.py`, `client/garde-fous.json` | Shared foreground token and guard-rail policy, common to the author's desktop agents (also used by NexusWindows for Claude). Vendored in the public copy; in the author's setup they live in a sibling `shared` folder |
+| `plugins/nexus-computer/` | Antigravity plugin and the agent guide (`SKILL.md`) |
+| `tests/` | Unit tests (pytest) and the real desktop validation |
+
+## Privacy
+
+NexusWindows for Antigravity runs entirely on your PC. It has no account, no telemetry, no analytics and makes no
+network requests of its own.
+
+- **What it reads**: window titles, the accessibility tree and window images of the applications the agent works
+  in, only when a tool is called. Password managers are neither read nor driven.
+- **Where it goes**: tool results are returned to Antigravity, which may send them to Google under its own privacy
+  policy; this server sends nothing anywhere else.
+- **What it stores**, under `~/.nexusagy/`: the Python environment (clone install only; `uvx` keeps its own in the
+  uv cache), an action log `computer.log` (action, method,
+  window, duration, outcome and short details such as a target label, coordinates, key names, a menu path or the
+  number of characters typed, never the typed or expected text; rotated at 5 MB, three backups) and screenshots (at
+  most 50 after each capture; those older than 24 hours are purged at the next capture and at server start, so a
+  stopped server can leave its last screenshots until it starts again). Under `~/.nexus/`: the shared foreground token and emergency-stop state.
+  Under `%LOCALAPPDATA%\NexusJournal\windows\antigravity\` (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, and the first words of an error, cut before any quote, colon or bracket); never
+  typed text, screen text, labels, titles or paths. The server never deletes it.
+- **Removing it**: remove the server from Antigravity's MCP settings, then delete `~/.nexusagy/` (and
+  `%LOCALAPPDATA%\NexusJournal`).
+
+Questions or concerns: open an issue on this repository.
+
+## Limits
+
+- Windows only. Tool descriptions, replies and code comments are in French.
+- In the background, keyboard input is refused in UWP/WinUI, Firefox and Tk, and Ctrl/Alt shortcuts in WPF;
+  Chromium/Electron receives keys, shortcuts and typing through a simulated activation, checked by read-back (`~` if
+  nothing changes). For web pages, [NexusBrowser](https://github.com/pironjulien/NexusBrowser) is more reliable.
+- An effect with nothing readable stays `~` (not verified).
+
+## Development
+
+```powershell
+pwsh -NoProfile -File test.ps1         # offline: ruff, Pyright, pytest
+pwsh -NoProfile -File test.ps1 -Full   # plus the real desktop validation on its own Win32, WinForms and WPF windows
+```
+
+The real validation shows its test windows without activation and closes them at the end; real mouse and keyboard
+checks run only when the PC has been idle for 120 s, otherwise they are reported as skipped.
+
+## Licence
+
+MIT, see [LICENSE](https://github.com/pironjulien/NexusWindows-Antigravity/blob/main/LICENSE). Copyright (c) 2026 Julien Piron.