nexus-windows-codex 0.0.0-stage → 3.0.0

package/lib/stop.mjs

@@ -0,0 +1,184 @@
+// Arrêt d'urgence commun aux agents de Julien (protocole commun emergency-stop.md).
+// Une NOUVELLE version de `stop` (date + contenu) datée de moins de HOLD_S secondes fige toute action de bureau pour
+// le temps restant. L'arrêt est tenu en mémoire sur une horloge monotone : ni la suppression du fichier ni un saut de
+// l'horloge murale ne le lèvent, seul le temps le fait ; un nouvel appui le réarme, jamais il ne le lève.
+import { spawn } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { Presence } from './presence.mjs';
+
+export const HOLD_S = 120;
+export const HEARTBEAT_S = 3;
+export const OWNER_STALE_S = 3 * HEARTBEAT_S;
+export const HOTKEY_LABEL = 'Ctrl+Alt+Maj+Échap';
+const WATCH_MS = 200;
+const VERSION = (() => {
+  try { return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version ?? 'unknown'; }
+  catch { return 'unknown'; }
+})();
+
+// Dossier commun local au poste. NEXUS_SHARED_HOME ne sert qu'aux tests : ils ne doivent jamais écrire le vrai
+// `~\.nexus\stop`, qui figerait les autres agents.
+export function sharedDirectory(env = typeof process === 'undefined' ? {} : process.env) {
+  return env.NEXUS_SHARED_HOME || path.join(os.homedir(), '.nexus');
+}
+
+export class EmergencyStopError extends Error {
+  constructor(remainingS) {
+    super(stopMessage(remainingS));
+    this.name = 'EmergencyStopError';
+    this.emergencyStop = true;
+    this.deferred = true; // Aucune entrée envoyée ; ne jamais rejouer automatiquement.
+    this.remainingS = remainingS;
+  }
+}
+
+export function stopMessage(remainingS) {
+  return `Arrêt d'urgence demandé par Julien (${HOTKEY_LABEL}) : plus aucune action pendant encore ${Math.ceil(remainingS)} s ; ne pas contourner. ` +
+    'Attendre ses instructions dans la conversation ; une action refusée ainsi ne doit jamais être rejouée.';
+}
+
+export class EmergencyStop {
+  #directory; #monotonic; #wall; #latchedUntil = 0; #seen = null; #timer = null; #guard = null; #guardState = 'absent'; #busyCount = 0;
+  #guardStartedAt = -Infinity; #guardExecutable = null; #guardPrefix = []; #presence;
+  constructor({ directory = sharedDirectory(), monotonic = () => performance.now(), wall = () => Date.now(), watch = true } = {}) {
+    this.#directory = directory; this.#monotonic = monotonic; this.#wall = wall;
+    // Présence de Julien : alimentée par le même garde (Raw Input), indisponible tant qu'il ne l'a pas annoncée.
+    this.#presence = new Presence({ monotonic });
+    this.check();
+    if (watch) {
+      // Surveillance au repos : un « rm » entre deux actions ne doit pas lever l'arrêt.
+      this.#timer = setInterval(() => { try { this.check(); } catch { /* le verrou déjà posé tient */ } }, WATCH_MS);
+      this.#timer.unref();
+    }
+  }
+  get directory() { return this.#directory; }
+  get presence() { return this.#presence; }
+  get stopFile() { return path.join(this.#directory, 'stop'); }
+  get ownerFile() { return path.join(this.#directory, 'stop.owner'); }
+  #latch(seconds) {
+    this.#latchedUntil = Math.max(this.#latchedUntil, this.#monotonic() + seconds * 1000);
+  }
+  // Lit le fichier ; chaque nouvelle version pose le verrou une seule fois, pour ce qu'il lui reste d'après sa date,
+  // borné à [0, HOLD_S] (une date « du futur » ne prolonge pas l'arrêt au-delà de HOLD_S).
+  check() {
+    let version, mtimeMs;
+    try {
+      const info = statSync(this.stopFile, { bigint: true });
+      mtimeMs = Number(info.mtimeNs / 1000000n);
+      version = info.mtimeNs.toString() + ':' + readFileSync(this.stopFile).toString('base64');
+    } catch { return this.remainingS(false); } // absent ou illisible : seul le verrou compte
+    if (version !== this.#seen) {
+      this.#seen = version;
+      const left = Math.min(Math.max(HOLD_S - (this.#wall() - mtimeMs) / 1000, 0), HOLD_S);
+      if (left > 0) this.#latch(left);
+    }
+    return this.remainingS(false);
+  }
+  remainingS(read = true) {
+    if (read) return this.check();
+    return Math.max(this.#latchedUntil - this.#monotonic(), 0) / 1000;
+  }
+  // Point de contrôle avant chaque action de bureau. Les observations n'y passent pas. Il relance aussi le garde s'il
+  // est mort (crash, fermeture) : sans lui, ni raccourci ni présence de Julien.
+  assertClear() {
+    this.#ensureGuard();
+    const left = this.check();
+    if (left > 0) throw new EmergencyStopError(left);
+  }
+  // Appui reçu par le détenteur du raccourci (processus de garde) : verrou immédiat, même si l'écriture du fichier
+  // a échoué de son côté.
+  pressed() { this.#latch(HOLD_S); }
+
+  // Processus de garde .NET : détient Ctrl+Alt+Maj+Échap (RegisterHotKey) tant que ce processus Node vit, bat dans
+  // stop.owner et écrit stop à l'appui. Il s'arrête à la fermeture de son entrée standard (mort du REPL).
+  // `prefix` : arguments placés avant `--stop-guard` (tests : script Node qui imite le garde).
+  startGuard(executable, prefix = []) {
+    this.#guardExecutable = executable; this.#guardPrefix = [...prefix];
+    this.#ensureGuard();
+  }
+  // Un garde est prévu (session réelle) : sans présence connue, aucune entrée physique ne part.
+  get guardExpected() { return Boolean(this.#guardExecutable); }
+  get guardState() { return this.#guardState; }
+  #ensureGuard() {
+    if (!this.#guardExecutable || this.#guard) return;
+    if (this.#monotonic() - this.#guardStartedAt < HEARTBEAT_S * 1000) return; // relance bornée
+    this.#guardStartedAt = this.#monotonic();
+    let child;
+    try {
+      child = spawn(this.#guardExecutable, [...this.#guardPrefix, '--stop-guard', VERSION], { windowsHide: true, stdio: ['pipe', 'pipe', 'ignore'] });
+    } catch { this.#guardState = 'failed'; return; }
+    this.#guard = child; this.#guardState = 'starting';
+    child.on('error', () => { if (this.#guard === child) { this.#guard = null; this.#guardState = 'failed'; } });
+    // Garde arrêté : sa présence n'est plus connue (une inactivité supposée serait fausse).
+    child.on('close', () => { if (this.#guard === child) { this.#guard = null; this.#guardState = 'exited'; this.#presence.setSource('none'); } });
+    child.stdin.on('error', () => {});
+    child.stdout.setEncoding('utf8');
+    let buffer = '';
+    child.stdout.on('data', chunk => {
+      buffer += chunk;
+      if (buffer.length > 65536) buffer = '';
+      let end;
+      while ((end = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, end); buffer = buffer.slice(end + 1);
+        let event;
+        try { event = JSON.parse(line); } catch { continue; }
+        if (event.event === 'stop') this.pressed();
+        else if (event.event === 'hotkey') this.#guardState = event.state;
+        else if (event.event === 'presence') this.#presence.setSource(event.source);
+        else if (event.event === 'input') this.#presence.input({ injectedPossible: event.injectedPossible === true });
+      }
+    });
+    // Le REPL ne doit pas rester ouvert pour son garde ; la fin du REPL ferme le tube et arrête le garde.
+    child.unref(); child.stdin.unref?.(); child.stdout.unref?.();
+  }
+  // Logo « agent au travail » (BusyIndicator.cs, dessiné par le garde) : allumé pendant chaque action de bureau des
+  // sessions de ce REPL, retiré par le garde 1,618 s après la dernière. Sans garde (tests, garde absent) : rien.
+  busy(hwnd) {
+    this.#ensureGuard();
+    this.#busyCount++;
+    this.#send(`busy ${Number.isSafeInteger(hwnd) && hwnd > 0 ? hwnd : 0}`);
+  }
+  idle() {
+    if (this.#busyCount > 0 && --this.#busyCount === 0) this.#send('idle');
+  }
+  #send(line) {
+    try { this.#guard?.stdin.write(`${line}\n`); } catch {} // garde parti : l'indicateur se tait, l'action continue
+  }
+  closeGuard() {
+    const child = this.#guard; this.#guard = null; this.#guardExecutable = null;
+    this.#guardState = 'absent';
+    this.#presence.setSource('none');
+    child?.stdin.end();
+  }
+  #owner() {
+    try {
+      const data = JSON.parse(readFileSync(this.ownerFile, 'utf8'));
+      return data && typeof data === 'object' && (this.#wall() / 1000 - Number(data.ts)) <= OWNER_STALE_S ? data : null;
+    } catch { return null; }
+  }
+  // État pour le modèle : arrêt restant et disponibilité du raccourci (détenu ici, par un autre agent vivant, ou non).
+  status() {
+    this.#ensureGuard();
+    const remainingS = this.check();
+    const owner = this.#owner();
+    let hotkey;
+    if (this.#guardState === 'owned') hotkey = 'détenu par ce garde NexusCodex';
+    else if (owner) hotkey = `détenu par ${owner.owner ?? 'un agent'} pid ${owner.pid}`;
+    else if (this.#guardState === 'disabled') hotkey = 'désactivé (dossier de test NEXUS_SHARED_HOME)';
+    else hotkey = `NON GARANTI (garde ${this.#guardState}, aucun détenteur vivant) : prévenir Julien`;
+    return { remainingS, stopped: remainingS > 0, hotkey, guard: this.#guardState, directory: this.#directory, presence: this.#presence.status() };
+  }
+  close() {
+    clearInterval(this.#timer); this.#timer = null;
+    this.closeGuard();
+  }
+}
+
+let shared = null;
+// Instance commune au processus (toutes les sessions d'un même REPL partagent l'arrêt et le garde).
+export function emergencyStop() {
+  shared ??= new EmergencyStop();
+  return shared;
+}

package/lib/tree.mjs

@@ -0,0 +1,152 @@
+import { createHash } from 'node:crypto';
+
+const roles = {
+  button: ['button', 'bouton'], edit: ['edit', 'modifier', 'zone de texte', 'édition'],
+  text: ['text', 'texte'], window: ['window', 'fenêtre'],
+  pane: ['pane', 'volet', 'région'], group: ['group', 'groupe'],
+  document: ['document'], link: ['link', 'lien'], tab: ['tab item', 'onglet'],
+  list: ['list', 'liste'], listitem: ['list item', 'élément de liste'], dataitem: ['data item', 'élément de données'],
+  menuitem: ['menu item', 'élément de menu'], menu: ['menu', 'barre de menus'],
+  combobox: ['combo box', 'zone de liste déroulante', 'zone de liste modifiable'],
+  checkbox: ['check box', 'case à cocher'], radio: ['radio button', 'case d’option', "case d'option"],
+  tree: ['tree', 'arborescence'], treeitem: ['tree item', "élément d’arborescence", "élément d'arborescence"],
+  image: ['image', 'élément graphique'], heading: ['heading', 'titre'],
+  scrollbar: ['scroll bar', 'barre de défilement'], slider: ['slider', 'curseur'],
+};
+const aliases = Object.entries(roles).flatMap(([role, names]) => names.map(name => [name, role]))
+  .sort((a, b) => b[0].length - a[0].length);
+const stateFlags = new Set(['disabled', 'selected', 'unselected', 'selectable', 'checked', 'unchecked',
+  'expanded', 'collapsed', 'focused', 'offscreen', 'read only', 'read-only', 'readonly',
+  'settable', 'string', 'float', 'integer', 'boolean']);
+export const digest = value => createHash('sha256').update(value).digest('hex');
+
+export function parseTree(tree = '') {
+  const elements = [], stack = [];
+  for (const line of tree.split(/\r?\n/)) {
+    const match = /^(\s*)(\d+)\s+(.+)$/.exec(line);
+    if (!match) continue;
+    const [, indent, index, body] = match;
+    const depth = indent.replaceAll('\t', '    ').length;
+    const metadata = [...body.matchAll(/(?:^|\s)(Value|Description|Help|ID|Secondary Actions):\s*/g)];
+    const main = body.slice(0, metadata[0]?.index ?? body.length).trim();
+    const fields = {};
+    for (let i = 0; i < metadata.length; i++) {
+      fields[metadata[i][1]] = body.slice(metadata[i].index + metadata[i][0].length,
+        metadata[i + 1]?.index ?? body.length).trim();
+    }
+    const alias = aliases.find(([name]) => main.toLowerCase() === name || main.toLowerCase().startsWith(name + ' '));
+    const role = alias?.[1] ?? 'unknown';
+    let name = alias ? main.slice(alias[0].length).trim() : main;
+    const flags = [];
+    // Sky emits a leading state group, often with several comma-separated flags.
+    // Parentheses inside the actual control name must remain literal.
+    while (alias) {
+      const group = /^\(([^)]+)\)(?:\s+|$)/.exec(name);
+      if (!group) break;
+      const tokens = group[1].split(',').map(flag => flag.trim().toLowerCase());
+      if (!tokens.every(flag => stateFlags.has(flag))) break;
+      flags.push(...tokens);
+      name = name.slice(group[0].length).trim();
+    }
+    while (stack.length && stack.at(-1).depth >= depth) stack.pop();
+    const element = {
+      index: Number(index), depth, role, name, automationId: fields.ID ?? '',
+      value: fields.Value ?? null, description: fields.Description ?? null,
+      disabled: flags.includes('disabled'),
+      selected: flags.includes('selected') ? true : flags.includes('unselected') ? false : null,
+      checked: flags.includes('checked') ? true : flags.includes('unchecked') ? false : null,
+      expanded: flags.includes('expanded') ? true : flags.includes('collapsed') ? false : null, flags,
+      actions: fields['Secondary Actions']?.split(/,\s*/) ?? [],
+      ancestors: stack.map(e => e.index), line: line.trim(),
+    };
+    if (elements.some(e => e.index === element.index)) throw new Error('Duplicate accessibility index; observation cannot be targeted');
+    elements.push(element); stack.push(element);
+  }
+  return elements;
+}
+
+export function validateSelector(selector, nested = false) {
+  if (!selector || typeof selector !== 'object' || Array.isArray(selector)) throw new Error('A semantic selector is required');
+  // Ancêtre seulement : `window`, HWND natif d'une fenêtre de l'ascendance (menu contextuel attesté par le clic droit qui
+  // l'a ouvert) ; la commande est alors cherchée dans CE menu, jamais dans un autre (relecture de Codex du 22/10 07:59).
+  const allowed = ['role', 'name', 'automationId', 'ancestor', ...(nested ? ['window'] : [])];
+  if (Object.keys(selector).some(k => !allowed.includes(k))) throw new Error('Unknown selector field');
+  if (selector.window !== undefined && !(Number.isSafeInteger(selector.window) && selector.window > 0)) throw new Error('Invalid selector field');
+  if (!['role', 'name', 'automationId'].some(k => typeof selector[k] === 'string' && selector[k].length) && selector.window === undefined) {
+    throw new Error('Empty selector');
+  }
+  for (const k of ['role', 'name', 'automationId']) {
+    if (selector[k] !== undefined && (typeof selector[k] !== 'string' || !selector[k].length)) throw new Error('Invalid selector field');
+  }
+  if (selector.ancestor !== undefined) {
+    if (nested) throw new Error('Nested ancestor selectors are unsupported');
+    validateSelector(selector.ancestor, true);
+  }
+}
+
+// Résolution UNIQUE d'un sélecteur, la même pour la cible, le jugement préalable et la postcondition (relecture de Codex
+// du 22/10 : une cible résolue autrement que sa postcondition inversait une case déjà cochée). Sélecteur par nom sans
+// rôle : un libellé (texte statique) homonyme d'un seul contrôle ne le rend pas ambigu (banc commun du 21/10 :
+// « Éditeur » désignait le libellé ET l'éditeur riche) ; deux contrôles restent ambigus. Même règle côté natif.
+export function findElements(elements, selector) {
+  validateSelector(selector);
+  const matches = (e, s) => ['role', 'name', 'automationId'].every(k => s[k] === undefined || e[k] === s[k]) &&
+    (s.window === undefined || e.nativeWindow === s.window);
+  const found = elements.filter(e => matches(e, selector) && (!selector.ancestor || e.ancestors.some(index => {
+    const parent = elements.find(p => p.index === index);
+    return parent && matches(parent, selector.ancestor);
+  })));
+  if (found.length > 1 && selector.role === undefined) {
+    const controls = found.filter(e => e.role !== 'text');
+    if (controls.length === 1) return controls;
+  }
+  return found;
+}
+
+export function uniqueElement(elements, selector) {
+  const found = findElements(elements, selector);
+  if (found.length !== 1) throw new Error(`Selector must match exactly one current element; found ${found.length}`);
+  if (found[0].disabled) throw new Error('Target is disabled');
+  if (found[0].password) throw new Error('Password controls require the dedicated supported workflow');
+  return found[0];
+}
+
+export function structureHash(elements) {
+  // Values, document text and window titles are intentionally excluded.
+  const named = new Set(['button', 'tab', 'menuitem', 'checkbox', 'radio', 'combobox']);
+  return digest(JSON.stringify(elements.map(e => [e.depth, e.role, e.automationId, named.has(e.role) ? e.name : ''])));
+}
+
+// Empreinte de l'état observable (valeurs et états compris) : sert seulement à prouver qu'une action d'arrière-plan
+// n'a eu AUCUN effet relu avant un repli physique. Jamais persistée.
+export function stateDigest(elements) {
+  return digest(JSON.stringify(elements.map(e => [e.depth, e.role, e.automationId, e.name, e.value ?? null, e.valueTruncated ?? false,
+    e.checked ?? null, e.selected ?? null, e.expanded ?? null, e.disabled ?? false, e.focused ?? null, e.actions ?? []])));
+}
+
+export function validateExpectation(expect) {
+  if (!expect || typeof expect !== 'object') throw new Error('An explicit postcondition is required');
+  validateSelector(expect.selector);
+  if (Object.keys(expect).some(k => !['selector', 'exists', 'field', 'equals', 'includes'].includes(k))) throw new Error('Unknown postcondition field');
+  if (expect.exists !== undefined && typeof expect.exists !== 'boolean') throw new Error('exists must be boolean');
+  if (expect.field !== undefined && !['name', 'value', 'selected', 'checked', 'expanded', 'disabled', 'description', 'focused'].includes(expect.field)) throw new Error('Unsupported postcondition field');
+  if (expect.equals !== undefined && !['string', 'boolean'].includes(typeof expect.equals)) throw new Error('Invalid equality');
+  if (expect.includes !== undefined && (typeof expect.includes !== 'string' || !expect.includes.length)) throw new Error('Invalid text condition');
+  if (expect.equals !== undefined && expect.includes !== undefined) throw new Error('Choose equals or includes');
+  if (expect.exists === false && (expect.equals !== undefined || expect.includes !== undefined)) throw new Error('Absence cannot have a value condition');
+  if (expect.exists === undefined && expect.equals === undefined && expect.includes === undefined) throw new Error('Empty postcondition');
+}
+
+export function checkExpectation(elements, expect) {
+  validateExpectation(expect);
+  // No accessible controls means no semantic evidence, not proof of absence.
+  if (!elements.length) return false;
+  const found = findElements(elements, expect.selector);
+  if (expect.exists === false) return found.length === 0;
+  if (found.length !== 1) return false;
+  const value = found[0][expect.field ?? 'name'];
+  if (expect.field === 'value' && expect.equals !== undefined && found[0].valueTruncated) return false;
+  if (expect.equals !== undefined) return value === expect.equals;
+  if (expect.includes !== undefined) return typeof value === 'string' && value.includes(expect.includes);
+  return true;
+}

package/native/bin/NexusCodex.UIA.exe

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/native/bin/NexusCodex.UIA.exe
+size: 35227674 bytes
+sha256: 8a4819f3ea83e5102d40fbde8a11907dc2eb2b1e861d58b267fc8356a694d38a

package/package.json

@@ -1,6 +1,44 @@
-{
-  "name": "nexus-windows-codex",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "nexus-windows-codex",
+  "version": "3.0.0",
+  "description": "NexusWindows for Codex: Windows computer use in the background for OpenAI Codex (MCP server and Codex skill).",
+  "type": "module",
+  "license": "MIT",
+  "author": "Julien Piron",
+  "mcpName": "io.github.pironjulien/nexus-windows-codex",
+  "homepage": "https://julienpiron.fr/nexuswindows/codex/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pironjulien/NexusWindows-Codex.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pironjulien/NexusWindows-Codex/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "codex",
+    "windows",
+    "computer-use",
+    "ui-automation"
+  ],
+  "bin": {
+    "nexus-windows-codex": "bin/nexus-windows-codex.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "native/bin/",
+    "garde-fous.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  }
+}