@vascend/talos 0.1.0

package/dist/vendor/computer-use/computer-scripts.js

@@ -0,0 +1,1230 @@
+'use strict';
+
+// Layer NATIVO di Computer Use: gli script PowerShell e i loro runner. Vive
+// separato dalle definizioni dei tool perche' qui non c'e' nessuna politica,
+// solo l'accesso a user32 e a UI Automation. Gli script sono fissi e ricevono
+// soltanto numeri validati o un payload su stdin: nessun input dell'utente
+// viene mai interpolato come codice.
+
+const { spawn } = require('child_process');
+const fs = require('fs/promises');
+const os = require('os');
+const path = require('path');
+
+const MAX_TEXT = 12000;
+// Oltre questa soglia la digitazione carattere per carattere non arriva in
+// tempo: il ritmo umano su 2000 caratteri supererebbe il timeout. Sopra la
+// soglia si incolla dagli appunti (e li si ripristina).
+const PASTE_THRESHOLD = 400;
+
+const VK = Object.freeze({
+  BACKSPACE: 0x08, TAB: 0x09, CLEAR: 0x0C, ENTER: 0x0D, RETURN: 0x0D,
+  SHIFT: 0x10, CTRL: 0x11, CONTROL: 0x11, ALT: 0x12, MENU: 0x12,
+  PAUSE: 0x13, CAPSLOCK: 0x14, ESC: 0x1B, ESCAPE: 0x1B, SPACE: 0x20,
+  PAGEUP: 0x21, PGUP: 0x21, PAGEDOWN: 0x22, PGDN: 0x22,
+  END: 0x23, HOME: 0x24, LEFT: 0x25, UP: 0x26, RIGHT: 0x27, DOWN: 0x28,
+  PRINTSCREEN: 0x2C, INSERT: 0x2D, DELETE: 0x2E, DEL: 0x2E,
+  META: 0x5B, WIN: 0x5B, WINDOWS: 0x5B, SUPER: 0x5B, LWIN: 0x5B, RWIN: 0x5C, APPS: 0x5D,
+  NUMPAD0: 0x60, NUMPAD1: 0x61, NUMPAD2: 0x62, NUMPAD3: 0x63, NUMPAD4: 0x64,
+  NUMPAD5: 0x65, NUMPAD6: 0x66, NUMPAD7: 0x67, NUMPAD8: 0x68, NUMPAD9: 0x69,
+  MULTIPLY: 0x6A, ADD: 0x6B, SUBTRACT: 0x6D, DECIMAL: 0x6E, DIVIDE: 0x6F,
+  F1: 0x70, F2: 0x71, F3: 0x72, F4: 0x73, F5: 0x74, F6: 0x75,
+  F7: 0x76, F8: 0x77, F9: 0x78, F10: 0x79, F11: 0x7A, F12: 0x7B,
+  NUMLOCK: 0x90, SCROLLLOCK: 0x91,
+  // Tasti multimediali: agiscono sull'app in primo piano o sul player attivo
+  // senza bisogno di collegare una finestra.
+  MUTE: 0xAD, VOLUMEDOWN: 0xAE, VOLUMEUP: 0xAF,
+  MEDIANEXT: 0xB0, MEDIAPREV: 0xB1, MEDIASTOP: 0xB2, MEDIAPLAY: 0xB3,
+  SEMICOLON: 0xBA, EQUAL: 0xBB, COMMA: 0xBC, MINUS: 0xBD, PERIOD: 0xBE,
+  SLASH: 0xBF, BACKTICK: 0xC0, LBRACKET: 0xDB, BACKSLASH: 0xDC,
+  RBRACKET: 0xDD, QUOTE: 0xDE,
+});
+
+// I tasti estesi vanno inviati con KEYEVENTF_EXTENDEDKEY: senza il flag alcune
+// applicazioni (Electron e i controlli WPF in particolare) ignorano frecce,
+// PagUp/PagGiu, Canc e i tasti multimediali.
+const EXTENDED_VK = new Set([
+  0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28, 0x2C, 0x2D, 0x2E,
+  0x5B, 0x5C, 0x5D, 0x90, 0xAD, 0xAE, 0xAF, 0xB0, 0xB1, 0xB2, 0xB3, 0x6F,
+]);
+
+const ALIAS = Object.freeze({ PLUS: 'ADD', SPACEBAR: 'SPACE', ESCAPE_KEY: 'ESC', CMD: 'WIN' });
+
+// Una scorciatoia sola: ['CTRL','L'] -> [0x11, 0x4c].
+function keyCodes(value) {
+  const raw = Array.isArray(value) ? value : String(value || '').split(/[+\s]+/);
+  const out = [];
+  for (const item of raw.slice(0, 8)) {
+    const key = String(item || '').trim().toUpperCase().replace(/[\s_-]+/g, '');
+    if (!key) continue;
+    let code = VK[ALIAS[key] || key];
+    if (code == null && /^[A-Z0-9]$/.test(key)) code = key.charCodeAt(0);
+    if (code == null) return [];
+    if (!out.includes(code)) out.push(code);
+  }
+  return out;
+}
+
+// Sequenza di scorciatoie: ['CTRL+A', 'DELETE'] oppure [['CTRL','A'], 'DELETE'].
+// Serve a chiudere in una sola chiamata cio' che altrimenti diventa una catena
+// di tool call identiche ("seleziona tutto", "cancella", "conferma").
+function keyChords(value) {
+  const list = Array.isArray(value) ? value : [value];
+  const flatChord = list.every((item) => typeof item === 'string' && !/[+\s]/.test(String(item).trim()))
+    && list.length > 1 && keyCodes(list).length === list.length;
+  const chords = flatChord ? [list] : list;
+  const out = [];
+  for (const chord of chords.slice(0, 12)) {
+    const codes = keyCodes(chord);
+    if (!codes.length) return [];
+    out.push(codes);
+  }
+  return out;
+}
+
+function keyFlags(code, up) {
+  return (EXTENDED_VK.has(code) ? 0x0001 : 0) | (up ? 0x0002 : 0);
+}
+
+function chordScript(codes) {
+  const press = codes.map((code) => `[VascendComputerInput]::keybd_event(${code},0,${keyFlags(code, false)},[UIntPtr]::Zero)`);
+  const release = codes.slice().reverse().map((code) => `[VascendComputerInput]::keybd_event(${code},0,${keyFlags(code, true)},[UIntPtr]::Zero)`);
+  return press.concat(release).join('\n');
+}
+
+const USER32_HEAD = String.raw`
+Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+public static class VascendComputerInput {
+  [DllImport("user32.dll")] public static extern bool SetCursorPos(int X, int Y);
+  [DllImport("user32.dll")] public static extern void mouse_event(uint flags, uint dx, uint dy, int data, UIntPtr extra);
+  [DllImport("user32.dll")] public static extern void keybd_event(byte vk, byte scan, uint flags, UIntPtr extra);
+  [DllImport("user32.dll")] static extern IntPtr GetForegroundWindow();
+  [DllImport("user32.dll")] static extern uint GetWindowThreadProcessId(IntPtr h, out uint pid);
+  [DllImport("kernel32.dll")] static extern uint GetCurrentThreadId();
+  [DllImport("user32.dll")] static extern bool AttachThreadInput(uint from, uint to, bool attach);
+  [DllImport("user32.dll")] static extern bool IsIconic(IntPtr h);
+  [DllImport("user32.dll")] static extern bool ShowWindowAsync(IntPtr h, int command);
+  [DllImport("user32.dll")] static extern bool BringWindowToTop(IntPtr h);
+  [DllImport("user32.dll")] static extern bool SetForegroundWindow(IntPtr h);
+  [DllImport("user32.dll")] static extern IntPtr SetActiveWindow(IntPtr h);
+  [DllImport("user32.dll")] static extern IntPtr GetAncestor(IntPtr h, uint flags);
+  [DllImport("user32.dll")] static extern bool SetWindowPos(IntPtr h, IntPtr after, int x, int y, int cx, int cy, uint flags);
+  static bool IsForeground(IntPtr h) {
+    if (h == IntPtr.Zero) return false;
+    return GetAncestor(GetForegroundWindow(), 2) == GetAncestor(h, 2);
+  }
+  public static bool ActivateWindow(IntPtr h) {
+    if (h == IntPtr.Zero) return true;
+    if (IsIconic(h)) ShowWindowAsync(h, 9);
+    else ShowWindowAsync(h, 5);
+    for (int attempt = 0; attempt < 4; attempt++) {
+      IntPtr foreground = GetForegroundWindow(); uint ignored;
+      uint foregroundThread = foreground == IntPtr.Zero ? 0 : GetWindowThreadProcessId(foreground, out ignored);
+      uint targetThread = GetWindowThreadProcessId(h, out ignored);
+      uint currentThread = GetCurrentThreadId();
+      bool attachedForeground = foregroundThread != 0 && foregroundThread != currentThread
+        && AttachThreadInput(currentThread, foregroundThread, true);
+      bool attachedTarget = targetThread != 0 && targetThread != currentThread
+        && targetThread != foregroundThread && AttachThreadInput(currentThread, targetThread, true);
+      try {
+        SetWindowPos(h, IntPtr.Zero, 0, 0, 0, 0, 0x0001 | 0x0002 | 0x0040);
+        BringWindowToTop(h); SetActiveWindow(h); SetForegroundWindow(h);
+      } finally {
+        if (attachedTarget) AttachThreadInput(currentThread, targetThread, false);
+        if (attachedForeground) AttachThreadInput(currentThread, foregroundThread, false);
+      }
+      System.Threading.Thread.Sleep(35 + attempt * 20);
+      if (IsForeground(h)) return true;
+    }
+    return IsForeground(h);
+  }
+}
+'@
+`;
+
+// Digitazione Unicode reale (SendInput con scan code): funziona anche dove
+// SetValue di UI Automation non genera eventi, per esempio nelle superfici web
+// dentro Electron.
+const UNICODE_TYPER = String.raw`
+Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+public static class VascendUnicodeInput {
+  [StructLayout(LayoutKind.Sequential)] public struct INPUT { public uint type; public InputUnion U; }
+  [StructLayout(LayoutKind.Explicit)] public struct InputUnion {
+    [FieldOffset(0)] public KEYBDINPUT ki; [FieldOffset(0)] public MOUSEINPUT mi; [FieldOffset(0)] public HARDWAREINPUT hi;
+  }
+  [StructLayout(LayoutKind.Sequential)] public struct KEYBDINPUT {
+    public ushort wVk; public ushort wScan; public uint dwFlags; public uint time; public UIntPtr dwExtraInfo;
+  }
+  [StructLayout(LayoutKind.Sequential)] public struct MOUSEINPUT {
+    public int dx; public int dy; public uint mouseData; public uint dwFlags; public uint time; public UIntPtr dwExtraInfo;
+  }
+  [StructLayout(LayoutKind.Sequential)] public struct HARDWAREINPUT {
+    public uint uMsg; public ushort wParamL; public ushort wParamH;
+  }
+  [DllImport("user32.dll", SetLastError=true)] static extern uint SendInput(uint count, INPUT[] inputs, int size);
+  static INPUT Key(char ch, uint flags) {
+    INPUT input = new INPUT(); input.type = 1; input.U.ki.wScan = ch; input.U.ki.dwFlags = flags; return input;
+  }
+  static readonly Random Random = new Random();
+  public static void TypeText(string value) {
+    int length = value == null ? 0 : value.Length;
+    foreach (char ch in value ?? "") {
+      INPUT[] pair = new INPUT[] { Key(ch, 0x0004), Key(ch, 0x0004 | 0x0002) };
+      SendInput(2, pair, Marshal.SizeOf(typeof(INPUT)));
+      // Ritmo umano senza rendere interminabili i testi lunghi: piccole
+      // variazioni per carattere e una pausa naturale sulla punteggiatura.
+      int delay = length > 400 ? Random.Next(1, 4) : length > 120 ? Random.Next(3, 9) : Random.Next(8, 22);
+      if (ch == '.' || ch == ',' || ch == ';' || ch == ':' || ch == '!' || ch == '?') delay += Random.Next(10, 30);
+      else if (ch == ' ' || ch == '\n') delay += Random.Next(2, 8);
+      System.Threading.Thread.Sleep(delay);
+    }
+  }
+}
+'@
+`;
+
+const TYPE_SCRIPT = UNICODE_TYPER + String.raw`
+$text = [Console]::In.ReadToEnd()
+[VascendUnicodeInput]::TypeText($text)
+`;
+
+// Incolla dagli appunti e li riporta come erano: un testo lungo arriva in un
+// colpo solo invece di superare il timeout carattere per carattere.
+const PASTE_BODY = String.raw`
+function Invoke-VascendPaste([string] $value) {
+  $previous = $null
+  try { $previous = Get-Clipboard -Raw -ErrorAction SilentlyContinue } catch {}
+  try { Set-Clipboard -Value $value } catch { return $false }
+  Start-Sleep -Milliseconds 45
+  [VascendComputerInput]::keybd_event(0x11,0,0,[UIntPtr]::Zero)
+  [VascendComputerInput]::keybd_event(0x56,0,0,[UIntPtr]::Zero)
+  [VascendComputerInput]::keybd_event(0x56,0,2,[UIntPtr]::Zero)
+  [VascendComputerInput]::keybd_event(0x11,0,2,[UIntPtr]::Zero)
+  Start-Sleep -Milliseconds 140
+  try { if ($null -ne $previous -and $previous -ne '') { Set-Clipboard -Value $previous } else { Set-Clipboard -Value ' ' } } catch {}
+  return $true
+}
+`;
+
+const PASTE_SCRIPT = USER32_HEAD + PASTE_BODY + String.raw`
+$text = [Console]::In.ReadToEnd()
+if (-not (Invoke-VascendPaste $text)) { [Console]::Error.Write('Appunti non disponibili: il testo non e stato incollato.'); exit 4 }
+`;
+
+function focusGuard(windowId) {
+  const id = /^\d+$/.test(String(windowId || '')) ? String(windowId) : '';
+  return id ? `\nif (-not [VascendComputerInput]::ActivateWindow([IntPtr]([Int64]${id}))) { [Console]::Error.Write('Non riesco a riportare la finestra collegata in primo piano. Nessun input e stato inviato.'); exit 3 }\n` : '\n';
+}
+
+const DESKTOP_INFO_SCRIPT = String.raw`
+Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+using System.Text;
+public static class VascendDesktopInfo {
+  [StructLayout(LayoutKind.Sequential)] public struct RECT { public int Left, Top, Right, Bottom; }
+  [StructLayout(LayoutKind.Sequential)] public struct POINT { public int X, Y; }
+  [DllImport("user32.dll")] static extern IntPtr GetForegroundWindow();
+  [DllImport("user32.dll", CharSet=CharSet.Unicode)] static extern int GetWindowText(IntPtr h, StringBuilder s, int n);
+  [DllImport("user32.dll")] static extern bool GetWindowRect(IntPtr h, out RECT r);
+  [DllImport("user32.dll")] static extern bool GetCursorPos(out POINT p);
+  static string Esc(string value) {
+    var text = new StringBuilder();
+    foreach (char ch in value ?? "") {
+      if (ch == '\\') text.Append("\\\\");
+      else if (ch == '"') text.Append("\\\"");
+      else if (ch < 32 || ch == 127) text.Append(' ');
+      else text.Append(ch);
+    }
+    return text.ToString();
+  }
+  public static string Json() {
+    IntPtr h = GetForegroundWindow(); var title = new StringBuilder(1024); GetWindowText(h, title, title.Capacity);
+    RECT r; GetWindowRect(h, out r); POINT p; GetCursorPos(out p);
+    string safe = Esc(title.ToString());
+    return "{\"activeWindow\":\"" + safe + "\",\"windowBounds\":{\"x\":" + r.Left + ",\"y\":" + r.Top + ",\"width\":" + (r.Right-r.Left) + ",\"height\":" + (r.Bottom-r.Top) + "},\"cursor\":{\"x\":" + p.X + ",\"y\":" + p.Y + "}}";
+  }
+}
+'@
+[Console]::Out.Write([VascendDesktopInfo]::Json())
+`;
+
+// Elenca le finestre top-level della sessione, incluse quelle minimizzate o
+// temporaneamente nascoste nel tray. Filtrare con IsWindowVisible faceva
+// sparire proprio Claude Desktop quando era in background: il processo veniva
+// trovato, ma non esisteva alcun target collegabile. Non leggiamo memoria,
+// command line o contenuti privati dei processi.
+const WINDOWS_SCRIPT = String.raw`
+Add-Type @'
+using System;
+using System.Collections.Generic;
+using System.Runtime.InteropServices;
+using System.Text;
+public static class VascendTopLevelWindows {
+  public delegate bool EnumWindowsProc(IntPtr h, IntPtr p);
+  [StructLayout(LayoutKind.Sequential)] public struct RECT { public int Left, Top, Right, Bottom; }
+  [DllImport("user32.dll")] static extern bool EnumWindows(EnumWindowsProc cb, IntPtr p);
+  [DllImport("user32.dll")] static extern bool IsWindowVisible(IntPtr h);
+  [DllImport("user32.dll")] static extern bool IsIconic(IntPtr h);
+  [DllImport("user32.dll", CharSet=CharSet.Unicode)] static extern int GetWindowText(IntPtr h, StringBuilder s, int n);
+  [DllImport("user32.dll")] static extern bool GetWindowRect(IntPtr h, out RECT r);
+  [DllImport("user32.dll")] static extern uint GetWindowThreadProcessId(IntPtr h, out uint pid);
+  // Un titolo di finestra puo contenere caratteri di controllo (Spotify usa BEL
+  // fra brano e artista): non escaparli produceva un JSON illeggibile e la
+  // lista finestre tornava VUOTA per colpa di una sola app.
+  static string Esc(string value) {
+    var text = new StringBuilder();
+    foreach (char ch in value ?? "") {
+      if (ch == '\\') text.Append("\\\\");
+      else if (ch == '"') text.Append("\\\"");
+      else if (ch < 32 || ch == 127) text.Append(' ');
+      else text.Append(ch);
+    }
+    return text.ToString();
+  }
+  public static string Json() {
+    var rows = new List<string>();
+    EnumWindows((h, p) => {
+      var title = new StringBuilder(1024); GetWindowText(h, title, title.Capacity);
+      if (title.Length == 0) return true;
+      RECT r; if (!GetWindowRect(h, out r) || r.Right-r.Left < 20 || r.Bottom-r.Top < 20) return true;
+      uint pid; GetWindowThreadProcessId(h, out pid);
+      string process = "";
+      try { process = System.Diagnostics.Process.GetProcessById((int)pid).ProcessName; } catch {}
+      Func<string,string> esc = Esc;
+      rows.Add("{\"windowId\":\"" + h.ToInt64().ToString() + "\",\"processId\":" + pid
+        + ",\"process\":\"" + esc(process) + "\",\"title\":\"" + esc(title.ToString())
+        + "\",\"visible\":" + (IsWindowVisible(h) ? "true" : "false")
+        + ",\"minimized\":" + (IsIconic(h) ? "true" : "false")
+        + ",\"bounds\":{\"x\":" + r.Left + ",\"y\":" + r.Top + ",\"width\":" + (r.Right-r.Left)
+        + ",\"height\":" + (r.Bottom-r.Top) + "}}" );
+      return rows.Count < 240;
+    }, IntPtr.Zero);
+    return "[" + string.Join(",", rows) + "]";
+  }
+}
+'@
+[Console]::Out.Write([VascendTopLevelWindows]::Json())
+`;
+
+// EnumWindows descrive soltanto le superfici top-level. Per scegliere
+// un'applicazione in modo affidabile serve anche l'elenco dei processi della
+// sessione utente corrente: Electron, Claude Desktop incluso, puo mantenere il
+// processo vivo mentre la sua finestra e minimizzata o temporaneamente nel
+// tray. Non leggiamo command line o memoria. Il percorso dell'eseguibile viene
+// usato soltanto dall'host locale per ricavare l'icona Windows e non viene mai
+// consegnato al modello o al renderer.
+const PROCESSES_SCRIPT = String.raw`
+Add-Type @'
+using System;
+using System.Runtime.InteropServices;
+public static class VascendProcessWindowState {
+  [StructLayout(LayoutKind.Sequential)] public struct RECT { public int Left, Top, Right, Bottom; }
+  [DllImport("user32.dll")] static extern bool GetWindowRect(IntPtr h, out RECT r);
+  [DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr h);
+  [DllImport("user32.dll")] public static extern bool IsIconic(IntPtr h);
+  public static int[] Bounds(IntPtr h) {
+    RECT r; if (h == IntPtr.Zero || !GetWindowRect(h, out r)) return new int[0];
+    return new [] { r.Left, r.Top, r.Right-r.Left, r.Bottom-r.Top };
+  }
+}
+'@
+$session = [System.Diagnostics.Process]::GetCurrentProcess().SessionId
+$items = New-Object System.Collections.Generic.List[object]
+foreach ($process in [System.Diagnostics.Process]::GetProcesses()) {
+  try {
+    if ($process.SessionId -ne $session) { continue }
+    $title = [string]$process.MainWindowTitle
+    $handle = [Int64]$process.MainWindowHandle
+    $executablePath = ''
+    try { $executablePath = [string]$process.MainModule.FileName } catch {}
+    $rect = [VascendProcessWindowState]::Bounds([IntPtr]$handle)
+    $bounds = $null
+    if ($rect.Length -eq 4 -and $rect[2] -gt 0 -and $rect[3] -gt 0) {
+      $bounds = [ordered]@{ x = $rect[0]; y = $rect[1]; width = $rect[2]; height = $rect[3] }
+    }
+    $items.Add([ordered]@{
+      processId = [int]$process.Id
+      process = [string]$process.ProcessName
+      executablePath = $executablePath
+      title = ([regex]::Replace($title, '[\p{Cc}\p{Cf}]', ' ')).Substring(0, [Math]::Min(300, $title.Length))
+      windowId = $(if ($handle -gt 0) { [string]$handle } else { '' })
+      hasWindow = [bool]($handle -gt 0 -or -not [string]::IsNullOrWhiteSpace($title))
+      visible = [bool]($handle -gt 0 -and [VascendProcessWindowState]::IsWindowVisible([IntPtr]$handle))
+      minimized = [bool]($handle -gt 0 -and [VascendProcessWindowState]::IsIconic([IntPtr]$handle))
+      bounds = $bounds
+      responding = [bool]$process.Responding
+    })
+  } catch {}
+}
+$sorted = @($items | Sort-Object @{Expression='hasWindow';Descending=$true}, @{Expression='process';Descending=$false}, @{Expression='processId';Descending=$false})
+[Console]::Out.Write((ConvertTo-Json -InputObject $sorted -Depth 3 -Compress))
+`;
+
+// Frammento condiviso: cammina il tree UIA di una finestra e produce righe
+// semantiche. Lo usano sia la lettura (computer_inspect) sia la risoluzione di
+// un target prima di agire.
+const UIA_WALK_BODY = String.raw`
+Add-Type -AssemblyName UIAutomationClient
+Add-Type -AssemblyName UIAutomationTypes
+# Le applicazioni di terze parti mettono caratteri di CONTROLLO dentro i nomi
+# accessibili: Spotify usa BEL (U+0007) come separatore in "Brano BEL Artista".
+# ConvertTo-Json di PowerShell 5.1 non li escapa, il JSON diventa illeggibile e
+# l'intera lettura si perdeva restituendo "nessun controllo". Gli emoji (coppie
+# di surrogati) devono invece sopravvivere: si toglie solo Cc/Cf.
+function Get-VascendText([string] $value, [int] $max) {
+  if ([string]::IsNullOrEmpty($value)) { return '' }
+  $clean = [regex]::Replace($value, '[\p{Cc}\p{Cf}]', ' ')
+  if ($clean.Length -gt $max) { $clean = $clean.Substring(0, $max) }
+  return $clean.Trim()
+}
+function Get-VascendRoot([string] $handle) {
+  $root = $null
+  if ($handle -match '^\d+$') {
+    try { $root = [System.Windows.Automation.AutomationElement]::FromHandle([IntPtr]([Int64]$handle)) } catch {}
+  }
+  if ($null -eq $root) {
+    $focused = [System.Windows.Automation.AutomationElement]::FocusedElement
+    if ($null -ne $focused) {
+      $walker = [System.Windows.Automation.TreeWalker]::ControlViewWalker
+      $cursor = $focused
+      for ($i = 0; $i -lt 24 -and $null -ne $cursor; $i++) {
+        if ($cursor.Current.ControlType.ProgrammaticName -eq 'ControlType.Window') { $root = $cursor; break }
+        $cursor = $walker.GetParent($cursor)
+      }
+    }
+  }
+  if ($null -eq $root) { $root = [System.Windows.Automation.AutomationElement]::RootElement }
+  return $root
+}
+function Get-VascendNodes($root, [int] $max) {
+  $queue = New-Object 'System.Collections.Generic.Queue[System.Windows.Automation.AutomationElement]'
+  $walker = [System.Windows.Automation.TreeWalker]::RawViewWalker
+  $walkChildren = $false
+  try {
+    $nodes = $root.FindAll([System.Windows.Automation.TreeScope]::Descendants, [System.Windows.Automation.Condition]::TrueCondition)
+    foreach ($candidate in $nodes) { $queue.Enqueue($candidate) }
+  } catch {
+    $walkChildren = $true
+    try {
+      $child = $walker.GetFirstChild($root)
+      while ($null -ne $child) { $queue.Enqueue($child); $child = $walker.GetNextSibling($child) }
+    } catch {}
+  }
+  $found = New-Object System.Collections.Generic.List[object]
+  while ($queue.Count -gt 0) {
+    $node = $queue.Dequeue()
+    if ($found.Count -ge $max) { break }
+    $found.Add($node)
+    if ($walkChildren) {
+      try {
+        $child = $walker.GetFirstChild($node)
+        while ($null -ne $child) { $queue.Enqueue($child); $child = $walker.GetNextSibling($child) }
+      } catch {}
+    }
+  }
+  return $found
+}
+# Enumerazione RISTRETTA: il filtro per ruolo lo applica il provider, non noi.
+# Chiedere TrueCondition significa farsi consegnare anche seicento Pane/Group/
+# Text per poi buttarli — ed e' meta' del costo di una scansione. Si usa quando
+# il chiamante vuole solo i controlli agibili; per la lettura del testo o per
+# l'ispezione completa resta il cammino su tutto l'albero.
+function Get-VascendInteractive($root, [int] $max) {
+  $names = @('Button','Edit','CheckBox','RadioButton','ComboBox','ListItem','MenuItem','TabItem',
+    'TreeItem','Hyperlink','Slider','Spinner','SplitButton','DataItem','Document','List','Tree','Tab','Menu')
+  $conditions = New-Object System.Collections.Generic.List[System.Windows.Automation.Condition]
+  foreach ($name in $names) {
+    try {
+      $type = [System.Windows.Automation.ControlType]::$name
+      if ($null -ne $type) {
+        $conditions.Add((New-Object System.Windows.Automation.PropertyCondition(
+          [System.Windows.Automation.AutomationElement]::ControlTypeProperty, $type)))
+      }
+    } catch {}
+  }
+  if ($conditions.Count -lt 2) { return Get-VascendNodes $root $max }
+  try {
+    $condition = New-Object System.Windows.Automation.OrCondition($conditions.ToArray())
+    $found = $root.FindAll([System.Windows.Automation.TreeScope]::Descendants, $condition)
+    $out = New-Object System.Collections.Generic.List[object]
+    foreach ($node in $found) {
+      if ($out.Count -ge $max) { break }
+      $out.Add($node)
+    }
+    return $out
+  } catch { return Get-VascendNodes $root $max }
+}
+function Get-VascendRow($node, [bool] $allowOffscreen) {
+  $c = $node.Current
+  $r = $c.BoundingRectangle
+  # Un controllo fuori vista non e' leggibile, ma DEVE restare risolvibile:
+  # ScrollIntoView esiste proprio per riportarlo sullo schermo prima di agire.
+  if (-not $allowOffscreen -and ($c.IsOffscreen -or $r.Width -lt 2 -or $r.Height -lt 2)) { return $null }
+  $name = [string]$c.Name
+  $automationId = [string]$c.AutomationId
+  $type = ([string]$c.ControlType.ProgrammaticName).Replace('ControlType.','')
+  # Regola volutamente permissiva: nelle app Electron molti controlli reali si
+  # presentano come Custom o Group con un nome. Il filtro per intento (query,
+  # types, interactive_only) vive nel layer di osservazione, non qui.
+  $interactive = $type -in @('Edit','Button','CheckBox','RadioButton','ComboBox','ListItem','MenuItem','TabItem','TreeItem','Hyperlink','Slider','Document','Spinner','SplitButton')
+  if ([string]::IsNullOrWhiteSpace($name) -and [string]::IsNullOrWhiteSpace($automationId) -and -not $interactive) { return $null }
+  $isPassword = [bool]$c.IsPassword
+  $value = ''
+  $toggle = ''
+  $selected = $null
+  $expanded = ''
+  # Ogni TryGetCurrentPattern e' una chiamata COM cross-process: cinque per nodo,
+  # su duecento nodi, erano i tre secondi della scansione. Le etichette di testo
+  # non hanno pattern da interrogare: si sondano solo i controlli che possono
+  # averne (ruolo interattivo, oppure un automationId, come le superfici web).
+  $probe = $interactive -or $automationId -ne ''
+  if ($isPassword) { $value = '[PASSWORD REDACTED]' }
+  elseif ($probe) {
+    try { $pattern = $null; if ($node.TryGetCurrentPattern([System.Windows.Automation.ValuePattern]::Pattern, [ref]$pattern)) { $value = [string]$pattern.Current.Value } } catch {}
+    if ([string]::IsNullOrEmpty($value)) {
+      try { $pattern = $null; if ($node.TryGetCurrentPattern([System.Windows.Automation.RangeValuePattern]::Pattern, [ref]$pattern)) { $value = [string]$pattern.Current.Value } } catch {}
+    }
+  }
+  $actions = New-Object System.Collections.Generic.List[string]
+  if ($probe) {
+    try { $pattern = $null; if ($node.TryGetCurrentPattern([System.Windows.Automation.TogglePattern]::Pattern, [ref]$pattern)) { $toggle = [string]$pattern.Current.ToggleState } } catch {}
+    try { $pattern = $null; if ($node.TryGetCurrentPattern([System.Windows.Automation.SelectionItemPattern]::Pattern, [ref]$pattern)) { $selected = [bool]$pattern.Current.IsSelected } } catch {}
+    try { $pattern = $null; if ($node.TryGetCurrentPattern([System.Windows.Automation.ExpandCollapsePattern]::Pattern, [ref]$pattern)) { $expanded = [string]$pattern.Current.ExpandCollapseState } } catch {}
+    try { $pattern = $null; if ($node.TryGetCurrentPattern([System.Windows.Automation.InvokePattern]::Pattern, [ref]$pattern)) { $actions.Add('invoke') } } catch {}
+  }
+  if ($toggle -ne '') { $actions.Add('toggle') }
+  if ($null -ne $selected) { $actions.Add('select') }
+  if ($expanded -ne '') { $actions.Add('expand') }
+  if (-not $isPassword) {
+    try { $pattern = $null; if ($node.TryGetCurrentPattern([System.Windows.Automation.ValuePattern]::Pattern, [ref]$pattern)) { if (-not $pattern.Current.IsReadOnly) { $actions.Add('setValue') } } } catch {}
+  }
+  return [ordered]@{
+    name = Get-VascendText $name 180; automationId = Get-VascendText $automationId 120;
+    type = $type; className = Get-VascendText ([string]$c.ClassName) 100;
+    processId = [int]$c.ProcessId; enabled = [bool]$c.IsEnabled; focusable = [bool]$c.IsKeyboardFocusable;
+    isPassword = $isPassword; value = Get-VascendText $value 500; toggle = $toggle; selected = $selected; expanded = $expanded;
+    actions = @($actions.ToArray() | Select-Object -Unique)
+    bounds = [ordered]@{ x=[int]$r.X; y=[int]$r.Y; width=[int]$r.Width; height=[int]$r.Height }
+  }
+}
+`;
+
+// Lo script riceve soltanto un windowId numerico via stdin e interroga il tree
+// UIA della finestra. Questo fornisce controlli semantici (Button, Edit, Tab...)
+// molto piu affidabili di un click stimato da un'immagine.
+const UI_ELEMENTS_SCRIPT = UIA_WALK_BODY + String.raw`
+$raw = [Console]::In.ReadToEnd().Trim()
+# '+interactive': il chiamante vuole solo i controlli agibili, quindi il filtro
+# per ruolo lo fa il provider. Senza il suffisso si cammina tutto l'albero.
+$narrow = $raw.EndsWith('+interactive')
+if ($narrow) { $raw = $raw.Substring(0, $raw.Length - 12) }
+$root = Get-VascendRoot $raw
+$items = New-Object System.Collections.Generic.List[object]
+$nodes = if ($narrow) { Get-VascendInteractive $root 900 } else { Get-VascendNodes $root 900 }
+foreach ($node in $nodes) {
+  if ($items.Count -ge 320) { break }
+  try { $row = Get-VascendRow $node $false; if ($null -ne $row) { $items.Add($row) } } catch {}
+}
+$array = [object[]]$items.ToArray()
+[Console]::Out.Write((ConvertTo-Json -InputObject $array -Depth 5 -Compress))
+`;
+
+// Agisce su un controllo tramite i pattern nativi di UI Automation: Invoke,
+// Toggle, Select, ExpandCollapse, SetValue, SetFocus. E' molto piu affidabile di
+// un click a coordinate (funziona anche se il controllo va portato in vista, non
+// sposta il puntatore dell'utente e non sbaglia bersaglio se la finestra si e
+// mossa). Il controllo viene RIRISOLTO qui, nel tree vivo: se non esiste piu,
+// nessun input viene inviato.
+// Corpo dell azione: risoluzione del target piu il ramo per ogni azione. I
+// frammenti C# NON si caricano tutti sempre — ogni Add-Type e una compilazione
+// a runtime (circa 250 ms a testa) e il typer serve solo a chi digita.
+const UIA_ACTION_BODY = String.raw`
+$payload = [Console]::In.ReadToEnd() | ConvertFrom-Json
+$handle = [string]$payload.windowId
+$selector = $payload.selector
+$action = [string]$payload.action
+# locate e' una LETTURA: non ruba il focus a quello che l'utente sta facendo.
+# Tutte le altre azioni consegnano input, quindi la finestra va davvero davanti.
+if ($handle -match '^\d+$' -and $action -ne 'locate') {
+  if (-not [VascendComputerInput]::ActivateWindow([IntPtr]([Int64]$handle))) {
+    [Console]::Out.Write('{"ok":false,"code":"FOREGROUND_LOST","error":"Non riesco a riportare la finestra collegata in primo piano."}')
+    exit 0
+  }
+}
+$root = Get-VascendRoot $handle
+$best = $null
+$bestRow = $null
+$bestScore = -1
+$wantId = [string]$selector.automationId
+$wantName = [string]$selector.name
+$wantType = [string]$selector.type
+$wantClass = [string]$selector.className
+$wantX = [double]$selector.centerX
+$wantY = [double]$selector.centerY
+
+# VIA RAPIDA. Camminare tutto l'albero per trovare UN elemento costava sei
+# secondi per azione: 1572 nodi, e per ognuno cinque interrogazioni COM
+# cross-process sui pattern. FindFirst con una PropertyCondition e' una query
+# indicizzata dentro il provider: stesso risultato, un ordine di grandezza in
+# meno. Il cammino completo resta come ripiego, per quando l'identita' non basta
+# (nessun automationId, nessun nome: solo la posizione).
+function Find-VascendFast($root, [string] $id, [string] $name) {
+  $conditions = New-Object System.Collections.Generic.List[System.Windows.Automation.Condition]
+  if ($id -ne '') {
+    $conditions.Add((New-Object System.Windows.Automation.PropertyCondition(
+      [System.Windows.Automation.AutomationElement]::AutomationIdProperty, $id)))
+  }
+  if ($name -ne '') {
+    $conditions.Add((New-Object System.Windows.Automation.PropertyCondition(
+      [System.Windows.Automation.AutomationElement]::NameProperty, $name)))
+  }
+  if ($conditions.Count -eq 0) { return $null }
+  try {
+    $condition = if ($conditions.Count -eq 1) { $conditions[0] } else {
+      New-Object System.Windows.Automation.AndCondition($conditions.ToArray())
+    }
+    return $root.FindFirst([System.Windows.Automation.TreeScope]::Descendants, $condition)
+  } catch { return $null }
+}
+
+$fast = Find-VascendFast $root $wantId $wantName
+if ($null -ne $fast) {
+  try {
+    $row = Get-VascendRow $fast $true
+    if ($null -ne $row) {
+      # Stessa soglia del cammino lento: identita' piu' tipo/classe.
+      $score = 0
+      if ($wantId -ne '' -and $row.automationId -eq $wantId) { $score += 8 }
+      if ($wantName -ne '' -and $row.name -eq $wantName) { $score += 5 }
+      if ($wantType -ne '' -and $row.type -eq $wantType) { $score += 3 }
+      if ($wantClass -ne '' -and $row.className -eq $wantClass) { $score += 2 }
+      if ($score -ge 5) { $best = $fast; $bestRow = $row; $bestScore = $score }
+    }
+  } catch {}
+}
+
+if ($null -eq $best) {
+foreach ($node in Get-VascendNodes $root 900) {
+  try {
+    $row = Get-VascendRow $node $true
+    if ($null -eq $row) { continue }
+    if ($wantId -ne '' -and $row.automationId -ne $wantId) { continue }
+    if ($wantId -eq '' -and $wantName -ne '' -and $row.name -ne $wantName) { continue }
+    $score = 0
+    if ($wantId -ne '' -and $row.automationId -eq $wantId) { $score += 8 }
+    if ($wantName -ne '' -and $row.name -eq $wantName) { $score += 5 }
+    if ($wantType -ne '' -and $row.type -eq $wantType) { $score += 3 }
+    if ($wantClass -ne '' -and $row.className -eq $wantClass) { $score += 2 }
+    if ($wantId -eq '' -and $wantName -eq '') {
+      $dx = [Math]::Abs(($row.bounds.x + $row.bounds.width / 2) - $wantX)
+      $dy = [Math]::Abs(($row.bounds.y + $row.bounds.height / 2) - $wantY)
+      if ($dx + $dy -le 48) { $score += 4 }
+    }
+    if ($score -gt $bestScore) { $bestScore = $score; $best = $node; $bestRow = $row }
+  } catch {}
+}
+}
+if ($null -eq $best -or $bestScore -lt 5) {
+  [Console]::Out.Write('{"ok":false,"code":"TARGET_GONE","error":"Il controllo non esiste piu nel tree corrente."}')
+  exit 0
+}
+try { $pattern = $null; if ($best.TryGetCurrentPattern([System.Windows.Automation.ScrollItemPattern]::Pattern, [ref]$pattern)) { $pattern.ScrollIntoView() } } catch {}
+Start-Sleep -Milliseconds 25
+try { $bestRow = Get-VascendRow $best $true } catch {}
+$result = [ordered]@{ ok = $false; method = ''; code = ''; error = ''; fallback = '' }
+if ($null -ne $bestRow) {
+  $result.name = $bestRow.name; $result.type = $bestRow.type; $result.enabled = $bestRow.enabled
+  $result.isPassword = $bestRow.isPassword; $result.bounds = $bestRow.bounds; $result.value = $bestRow.value
+}
+function Set-VascendFocus($node) {
+  try { $node.SetFocus(); Start-Sleep -Milliseconds 60; return $true } catch { return $false }
+}
+if ($null -ne $bestRow -and -not $bestRow.enabled -and $action -ne 'locate') {
+  $result.code = 'DISABLED'; $result.error = 'Il controllo esiste ma e disabilitato.'
+} elseif ($action -eq 'locate') {
+  $result.ok = $true; $result.method = 'Locate'
+} elseif ($action -eq 'invoke') {
+  $done = $false
+  try { $pattern = $null; if ($best.TryGetCurrentPattern([System.Windows.Automation.InvokePattern]::Pattern, [ref]$pattern)) { $pattern.Invoke(); $result.method = 'Invoke'; $done = $true } } catch { $result.error = [string]$_.Exception.Message }
+  if (-not $done) {
+    try { $pattern = $null; if ($best.TryGetCurrentPattern([System.Windows.Automation.TogglePattern]::Pattern, [ref]$pattern)) { $pattern.Toggle(); $result.method = 'Toggle'; $done = $true } } catch {}
+  }
+  if (-not $done) {
+    try { $pattern = $null; if ($best.TryGetCurrentPattern([System.Windows.Automation.SelectionItemPattern]::Pattern, [ref]$pattern)) { $pattern.Select(); $result.method = 'Select'; $done = $true } } catch {}
+  }
+  if (-not $done) {
+    try {
+      $pattern = $null
+      if ($best.TryGetCurrentPattern([System.Windows.Automation.ExpandCollapsePattern]::Pattern, [ref]$pattern)) {
+        if ([string]$pattern.Current.ExpandCollapseState -eq 'Expanded') { $pattern.Collapse(); $result.method = 'Collapse' }
+        else { $pattern.Expand(); $result.method = 'Expand' }
+        $done = $true
+      }
+    } catch {}
+  }
+  $result.ok = $done
+  if (-not $done) { $result.code = 'NO_PATTERN'; $result.fallback = 'click'; $result.error = 'Il controllo non espone un pattern nativo.' }
+} elseif ($action -eq 'toggle' -or $action -eq 'select' -or $action -eq 'expand' -or $action -eq 'collapse') {
+  try {
+    $pattern = $null
+    if ($action -eq 'toggle' -and $best.TryGetCurrentPattern([System.Windows.Automation.TogglePattern]::Pattern, [ref]$pattern)) { $pattern.Toggle(); $result.ok = $true; $result.method = 'Toggle' }
+    elseif ($action -eq 'select' -and $best.TryGetCurrentPattern([System.Windows.Automation.SelectionItemPattern]::Pattern, [ref]$pattern)) { $pattern.Select(); $result.ok = $true; $result.method = 'Select' }
+    elseif ($best.TryGetCurrentPattern([System.Windows.Automation.ExpandCollapsePattern]::Pattern, [ref]$pattern)) {
+      if ($action -eq 'expand') { $pattern.Expand(); $result.method = 'Expand' } else { $pattern.Collapse(); $result.method = 'Collapse' }
+      $result.ok = $true
+    }
+  } catch { $result.error = [string]$_.Exception.Message }
+  if (-not $result.ok -and $result.error -eq '') { $result.code = 'NO_PATTERN'; $result.fallback = 'click'; $result.error = 'Pattern non disponibile su questo controllo.' }
+} elseif ($action -eq 'focus') {
+  $result.ok = Set-VascendFocus $best
+  if ($result.ok) { $result.method = 'SetFocus' } else { $result.code = 'NO_FOCUS'; $result.fallback = 'click'; $result.error = 'Il controllo non accetta il focus da UI Automation.' }
+} elseif ($action -eq 'setValue' -or $action -eq 'type' -or $action -eq 'paste') {
+  if ($null -ne $bestRow -and $bestRow.isPassword) {
+    $result.code = 'PASSWORD'; $result.error = 'Computer Use non scrive in campi password.'
+  } else {
+    $focused = Set-VascendFocus $best
+    if (-not $focused) { $result.code = 'NO_FOCUS'; $result.fallback = 'click'; $result.error = 'Il controllo non accetta il focus da UI Automation.' }
+    else {
+      $text = [string]$payload.value
+      if ($payload.clear -eq $true) {
+        [VascendComputerInput]::keybd_event(0x11,0,0,[UIntPtr]::Zero)
+        [VascendComputerInput]::keybd_event(0x41,0,0,[UIntPtr]::Zero)
+        [VascendComputerInput]::keybd_event(0x41,0,2,[UIntPtr]::Zero)
+        [VascendComputerInput]::keybd_event(0x11,0,2,[UIntPtr]::Zero)
+        Start-Sleep -Milliseconds 40
+      }
+      if ($action -eq 'setValue') {
+        try {
+          $pattern = $null
+          if ($best.TryGetCurrentPattern([System.Windows.Automation.ValuePattern]::Pattern, [ref]$pattern) -and -not $pattern.Current.IsReadOnly) {
+            $pattern.SetValue($text); $result.ok = $true; $result.method = 'SetValue'
+          } else { $result.code = 'NO_PATTERN'; $result.fallback = 'type'; $result.error = 'Il campo non espone ValuePattern scrivibile.' }
+        } catch { $result.code = 'NO_PATTERN'; $result.fallback = 'type'; $result.error = [string]$_.Exception.Message }
+      } elseif ($action -eq 'paste') {
+        if (Invoke-VascendPaste $text) { $result.ok = $true; $result.method = 'Paste' }
+        else { $result.code = 'NO_CLIPBOARD'; $result.fallback = 'type'; $result.error = 'Appunti non disponibili.' }
+      } else {
+        [VascendUnicodeInput]::TypeText($text)
+        $result.ok = $true; $result.method = 'Type'
+      }
+      if ($result.ok -and $payload.submit -eq $true) {
+        Start-Sleep -Milliseconds 90
+        [VascendComputerInput]::keybd_event(13,0,0,[UIntPtr]::Zero)
+        [VascendComputerInput]::keybd_event(13,0,2,[UIntPtr]::Zero)
+      }
+    }
+  }
+} else {
+  $result.code = 'UNSUPPORTED'; $result.error = 'Azione UI Automation sconosciuta.'
+}
+[Console]::Out.Write((ConvertTo-Json -InputObject $result -Depth 4 -Compress))
+`;
+
+// Script per una singola azione: solo i frammenti che servono davvero. Sotto la
+// soglia degli 8000 caratteri evita anche il giro dal file temporaneo.
+function uiaActionScript(action) {
+  const needsTyper = action === 'type';
+  const needsPaste = action === 'paste';
+  return UIA_WALK_BODY + USER32_HEAD
+    + (needsTyper ? UNICODE_TYPER : '')
+    + (needsPaste ? PASTE_BODY : '')
+    + UIA_ACTION_BODY;
+}
+
+// Variante completa: la usano i test statici e gli adapter che vogliono un solo
+// programma per tutte le azioni.
+const UIA_ACTION_SCRIPT = UIA_WALK_BODY + USER32_HEAD + UNICODE_TYPER + PASTE_BODY + UIA_ACTION_BODY;
+
+// Avvia una applicazione. Il percorso arriva via stdin come DATO (mai come
+// codice) e viene passato a Start-Process come argomento. Nessuna riga di
+// comando viene composta per interpolazione.
+const LAUNCH_SCRIPT = String.raw`
+$payload = [Console]::In.ReadToEnd() | ConvertFrom-Json
+$target = [string]$payload.target
+if ([string]::IsNullOrWhiteSpace($target)) { [Console]::Out.Write('{"ok":false,"error":"Percorso applicazione mancante."}'); exit 0 }
+$processId = 0
+try {
+  if ($target.StartsWith('shell:', [System.StringComparison]::OrdinalIgnoreCase)) {
+    # Le applicazioni del Microsoft Store non hanno un eseguibile da avviare:
+    # si aprono dalla loro voce in AppsFolder, tramite la shell di Windows.
+    Start-Process -FilePath 'explorer.exe' -ArgumentList $target -ErrorAction Stop
+  } else {
+    $started = Start-Process -FilePath $target -PassThru -ErrorAction Stop
+    if ($null -ne $started) { $processId = [int]$started.Id }
+  }
+} catch {
+  [Console]::Out.Write((ConvertTo-Json -InputObject ([ordered]@{ ok = $false; error = [string]$_.Exception.Message }) -Compress))
+  exit 0
+}
+[Console]::Out.Write((ConvertTo-Json -InputObject ([ordered]@{ ok = $true; processId = $processId }) -Compress))
+`;
+
+// Navigazione semantica di Esplora file. Il percorso arriva via stdin e il
+// risultato e' positivo soltanto quando Shell.Application espone esattamente
+// quella cartella: inviare Ctrl+L/Invio non basta a dichiarare il successo.
+const OPEN_FOLDER_SCRIPT = String.raw`
+$payload = [Console]::In.ReadToEnd() | ConvertFrom-Json
+$requested = [System.IO.Path]::GetFullPath([string]$payload.path)
+$expected = $requested.TrimEnd([char[]]'\')
+if (-not (Test-Path -LiteralPath $requested -PathType Container)) {
+  [Console]::Out.Write((ConvertTo-Json -InputObject ([ordered]@{ ok = $false; code = 'NOT_FOUND'; error = 'La cartella non esiste.' }) -Compress))
+  exit 0
+}
+$shell = New-Object -ComObject Shell.Application
+$requestedWindow = [string]$payload.windowId
+$navigated = $false
+if (-not [string]::IsNullOrWhiteSpace($requestedWindow)) {
+  foreach ($window in @($shell.Windows())) {
+    try {
+      if ([string][long]$window.HWND -eq $requestedWindow) {
+        $window.Navigate($requested)
+        $navigated = $true
+        break
+      }
+    } catch {}
+  }
+}
+if (-not $navigated) {
+  try { Start-Process -FilePath 'explorer.exe' -ArgumentList @($requested) -ErrorAction Stop } catch {
+    [Console]::Out.Write((ConvertTo-Json -InputObject ([ordered]@{ ok = $false; code = 'OPEN_FAILED'; error = [string]$_.Exception.Message }) -Compress))
+    exit 0
+  }
+}
+$lastPath = ''
+for ($attempt = 0; $attempt -lt 40; $attempt++) {
+  Start-Sleep -Milliseconds 150
+  foreach ($window in @($shell.Windows())) {
+    try {
+      $current = [System.IO.Path]::GetFullPath([string]$window.Document.Folder.Self.Path).TrimEnd([char[]]'\')
+      $lastPath = $current
+      if ($current.Equals($expected, [System.StringComparison]::OrdinalIgnoreCase)) {
+        [Console]::Out.Write((ConvertTo-Json -InputObject ([ordered]@{
+          ok = $true
+          verified = $true
+          path = $current
+          windowId = [string][long]$window.HWND
+          title = [string]$window.LocationName
+        }) -Compress))
+        exit 0
+      }
+    } catch {}
+  }
+}
+[Console]::Out.Write((ConvertTo-Json -InputObject ([ordered]@{
+  ok = $false
+  code = 'PATH_NOT_CONFIRMED'
+  error = 'Esplora file non ha confermato la cartella richiesta.'
+  currentPath = $lastPath
+}) -Compress))
+`;
+
+// Windows limita la riga di comando a 32767 caratteri e -EncodedCommand paga
+// UTF-16 piu base64: gli script UI Automation, che portano con se' il walk del
+// tree, la sforano (visto come spawn ENAMETOOLONG). Oltre la soglia il
+// programma passa da un file temporaneo in una cartella dedicata; lo stdin
+// resta il canale del PAYLOAD, quindi nessun input dell'utente diventa codice.
+const MAX_ENCODED_SCRIPT = 8000;
+
+async function writeTempScript(text) {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'vascend-computer-'));
+  const file = path.join(dir, 'step.ps1');
+  // Il BOM evita che PowerShell 5.1 legga il file come ANSI e rovini gli accenti.
+  await fs.writeFile(file, '' + text, 'utf8');
+  return { file, cleanup: () => fs.rm(dir, { recursive: true, force: true }).catch(() => {}) };
+}
+
+function spawnPowerShell(args, options = {}, cleanup = null) {
+  return new Promise((resolve) => {
+    const child = spawn('powershell.exe', args, {
+      windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (typeof cleanup === 'function') cleanup();
+      resolve(result);
+    };
+    const timer = setTimeout(() => {
+      try { child.kill(); } catch (_) { /* gia chiuso */ }
+      finish({ ok: false, error: 'Computer Use: timeout del controllo Windows.' });
+    }, Math.max(1000, Number(options.timeoutMs) || 15000));
+    const maxOutput = Math.max(24000, Math.min(256000, Number(options.maxOutput) || 24000));
+    child.stdout.on('data', (chunk) => { stdout += String(chunk); if (stdout.length > maxOutput) stdout = stdout.slice(0, maxOutput); });
+    child.stderr.on('data', (chunk) => { stderr += String(chunk); if (stderr.length > 2000) stderr = stderr.slice(0, 2000); });
+    child.on('error', (error) => finish({ ok: false, error: String(error && error.message || error) }));
+    child.on('close', (code) => finish(Number(code) === 0
+      ? { ok: true, output: stdout.trim() }
+      : { ok: false, error: stderr.trim() || 'PowerShell terminato con codice ' + code }));
+    if (options.input != null) child.stdin.write(String(options.input));
+    child.stdin.end();
+  });
+}
+
+// PowerShell scrive su stdout con la code page OEM della console: il bullet
+// "•" dei titoli Chromium (Spotify usa "Brano • Artista") diventava il byte
+// 0x07, cioe' BEL, e il JSON arrivava a Node con un carattere di controllo
+// dentro una stringa -> JSON.parse falliva -> la lettura dei controlli
+// sembrava VUOTA. Le stesse code page rovinavano accenti e trattini lunghi nei
+// titoli delle finestre. Si dichiara UTF-8 prima di ogni script.
+const OUTPUT_ENCODING_PREFIX = '[Console]::OutputEncoding = [System.Text.Encoding]::UTF8\n';
+
+async function runPowerShell(script, options = {}) {
+  const text = OUTPUT_ENCODING_PREFIX + String(script || '');
+  const base = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass'];
+  if (text.length > MAX_ENCODED_SCRIPT) {
+    let temp = null;
+    try { temp = await writeTempScript(text); } catch (error) {
+      return { ok: false, error: 'Computer Use: non riesco a preparare il controllo Windows. ' + String(error && error.message || error) };
+    }
+    return spawnPowerShell([...base, '-File', temp.file], options, temp.cleanup);
+  }
+  // -EncodedCommand separa il programma dallo stdin: computer_type puo cosi'
+  // consegnare testo arbitrario a Console.In senza trasformarlo in script.
+  const encoded = Buffer.from(text, 'utf16le').toString('base64');
+  return spawnPowerShell([...base, '-EncodedCommand', encoded], options);
+}
+
+// Ultima rete di sicurezza lato JS: se un'app emette comunque caratteri che
+// PowerShell non ha escapato (o un emoji troncato a meta'), si ripara il testo
+// invece di perdere l'intera lettura.
+function repairJsonText(text) {
+  return String(text || '')
+    .replace(/[\u0000-\u001f]/g, ' ')
+    .replace(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])/g, '')
+    .replace(/(^|[^\uD800-\uDBFF])([\uDC00-\uDFFF])/g, '$1');
+}
+
+// Un JSON illeggibile NON e' un risultato vuoto. Confonderli rendeva ciechi:
+// una lettura fallita diceva "nessun controllo" e il modello concludeva che
+// l'applicazione non fosse pilotabile.
+function readJsonOutput(result) {
+  if (!result || result.ok !== true) {
+    return { ok: false, code: 'NATIVE_ERROR', error: String(result && result.error || 'Controllo Windows non riuscito.') };
+  }
+  const text = String(result.output || '').trim();
+  if (!text) return { ok: true, value: null, empty: true };
+  try { return { ok: true, value: JSON.parse(text) }; } catch (_) { /* si tenta la riparazione */ }
+  try { return { ok: true, value: JSON.parse(repairJsonText(text)), repaired: true }; } catch (error) {
+    return {
+      ok: false,
+      code: 'UNREADABLE',
+      error: 'La risposta del controllo Windows non e interpretabile: ' + String(error && error.message || '').slice(0, 140),
+    };
+  }
+}
+
+function parseJsonOutput(result, fallback) {
+  const read = readJsonOutput(result);
+  if (!read.ok || read.value == null) return fallback;
+  if (Array.isArray(fallback)) return Array.isArray(read.value) ? read.value : [read.value];
+  return typeof read.value === 'object' ? read.value : fallback;
+}
+
+function integer(value, min, max, fallback = 0) {
+  const number = Math.trunc(Number(value));
+  return Number.isFinite(number) ? Math.max(min, Math.min(max, number)) : fallback;
+}
+
+function typingTimeout(text) {
+  return Math.min(60000, Math.max(20000, 12000 + String(text || '').length * 55));
+}
+
+async function defaultDesktopInfo() {
+  return parseJsonOutput(await runPowerShell(DESKTOP_INFO_SCRIPT, { timeoutMs: 5000 }), {});
+}
+
+async function defaultWindows() {
+  return parseJsonOutput(await runPowerShell(WINDOWS_SCRIPT, { timeoutMs: 7000, maxOutput: 128000 }), []);
+}
+
+async function defaultProcesses() {
+  // Una workstation di sviluppo puo avere facilmente centinaia di processi.
+  // Il JSON non deve venire troncato prima che computer_processes applichi la
+  // query richiesta dall'agente (es. "spotify").
+  return parseJsonOutput(await runPowerShell(PROCESSES_SCRIPT, { timeoutMs: 7000, maxOutput: 256000 }), []);
+}
+
+// Ritorna un ESITO, non solo righe: chi legge deve poter distinguere "finestra
+// senza controlli" da "lettura non riuscita". Confonderli e' esattamente cio'
+// che rendeva Computer Use cieco su Spotify.
+async function defaultUiElements(target = {}) {
+  const windowId = /^\d+$/.test(String(target.windowId || '')) ? String(target.windowId) : '';
+  const narrow = target.interactiveOnly === true ? '+interactive' : '';
+  const read = readJsonOutput(await runPowerShell(UI_ELEMENTS_SCRIPT, {
+    input: windowId + narrow,
+    timeoutMs: 20000,
+    maxOutput: 400000,
+  }));
+  if (!read.ok) return { ok: false, code: read.code, error: read.error, rows: [] };
+  const rows = Array.isArray(read.value) ? read.value : (read.value ? [read.value] : []);
+  return { ok: true, rows, ...(read.repaired ? { repaired: true } : {}) };
+}
+
+// Azione semantica su un controllo: il target viene ririsolto nel tree vivo
+// dentro lo stesso processo che agisce, quindi non esiste una finestra temporale
+// in cui la UI cambia tra risoluzione e input.
+async function defaultUiAction(request = {}) {
+  const payload = {
+    windowId: /^\d+$/.test(String(request.windowId || '')) ? String(request.windowId) : '',
+    action: String(request.action || 'locate'),
+    selector: {
+      automationId: String(request.selector && request.selector.automationId || ''),
+      name: String(request.selector && request.selector.name || ''),
+      type: String(request.selector && request.selector.type || ''),
+      className: String(request.selector && request.selector.className || ''),
+      centerX: Number(request.selector && request.selector.centerX) || 0,
+      centerY: Number(request.selector && request.selector.centerY) || 0,
+    },
+    value: String(request.value || '').slice(0, MAX_TEXT),
+    clear: request.clear === true,
+    submit: request.submit === true,
+  };
+  const result = await runPowerShell(uiaActionScript(payload.action), {
+    input: JSON.stringify(payload),
+    timeoutMs: payload.action === 'type' ? typingTimeout(payload.value) : 20000,
+    maxOutput: 32000,
+  });
+  if (!result.ok) return { ok: false, code: 'NATIVE_ERROR', error: String(result.error || 'Azione UI Automation non riuscita.') };
+  return parseJsonOutput(result, { ok: false, code: 'NATIVE_ERROR', error: 'Risposta UI Automation illeggibile.' });
+}
+
+async function defaultLaunch(request = {}) {
+  const target = String(request.target || '').slice(0, 1024);
+  if (!target) return { ok: false, error: 'Percorso applicazione mancante.' };
+  const result = await runPowerShell(LAUNCH_SCRIPT, {
+    input: JSON.stringify({ target }),
+    timeoutMs: 15000,
+    maxOutput: 8000,
+  });
+  if (!result.ok) return { ok: false, error: String(result.error || 'Avvio non riuscito.') };
+  return parseJsonOutput(result, { ok: false, error: 'Risposta di avvio illeggibile.' });
+}
+
+async function defaultOpenPath(request = {}) {
+  const requested = String(request.path || '').trim();
+  if (!requested || requested.includes('\0') || !path.win32.isAbsolute(requested)) {
+    return { ok: false, code: 'BAD_PATH', error: 'Serve un percorso assoluto di una cartella.' };
+  }
+  const folderPath = path.win32.normalize(requested);
+  try {
+    const stat = await fs.stat(folderPath);
+    if (!stat.isDirectory()) return { ok: false, code: 'NOT_DIRECTORY', error: 'Il percorso non e una cartella.' };
+  } catch (_) {
+    return { ok: false, code: 'NOT_FOUND', error: 'La cartella non esiste.' };
+  }
+  const result = await runPowerShell(OPEN_FOLDER_SCRIPT, {
+    input: JSON.stringify({
+      path: folderPath,
+      windowId: /^\d+$/.test(String(request.windowId || '')) ? String(request.windowId) : '',
+    }),
+    timeoutMs: 12000,
+    maxOutput: 16000,
+  });
+  if (!result.ok) return { ok: false, code: 'NATIVE_ERROR', error: String(result.error || 'Navigazione non riuscita.') };
+  return parseJsonOutput(result, { ok: false, code: 'NATIVE_ERROR', error: 'Risposta di navigazione illeggibile.' });
+}
+
+async function defaultAction(action, input) {
+  if (action === 'click') {
+    const x = integer(input.x, -32768, 32767);
+    const y = integer(input.y, -32768, 32767);
+    const button = String(input.button || 'left').toLowerCase();
+    const count = integer(input.clicks, 1, 3, 1);
+    const down = button === 'right' ? 0x0008 : button === 'middle' ? 0x0020 : 0x0002;
+    const up = button === 'right' ? 0x0010 : button === 'middle' ? 0x0040 : 0x0004;
+    const script = USER32_HEAD + focusGuard(input.windowId) + `[VascendComputerInput]::SetCursorPos(${x}, ${y}) | Out-Null\n`
+      + Array.from({ length: count }, () => `[VascendComputerInput]::mouse_event(${down},0,0,0,[UIntPtr]::Zero)\n[VascendComputerInput]::mouse_event(${up},0,0,0,[UIntPtr]::Zero)\nStart-Sleep -Milliseconds 45`).join('\n');
+    return runPowerShell(script);
+  }
+  if (action === 'hover') {
+    const x = integer(input.x, -32768, 32767);
+    const y = integer(input.y, -32768, 32767);
+    return runPowerShell(USER32_HEAD + focusGuard(input.windowId)
+      + `[VascendComputerInput]::SetCursorPos(${x}, ${y}) | Out-Null\nStart-Sleep -Milliseconds 220`);
+  }
+  if (action === 'drag') {
+    const x = integer(input.x, -32768, 32767);
+    const y = integer(input.y, -32768, 32767);
+    const toX = integer(input.toX, -32768, 32767);
+    const toY = integer(input.toY, -32768, 32767);
+    // Il trascinamento viene interpolato: molti controlli ignorano un salto
+    // secco dal punto di partenza a quello d'arrivo perche' non vedono mai il
+    // movimento del mouse.
+    const steps = 14;
+    const path = Array.from({ length: steps }, (_, index) => {
+      const progress = (index + 1) / steps;
+      return `[VascendComputerInput]::SetCursorPos(${Math.round(x + (toX - x) * progress)}, ${Math.round(y + (toY - y) * progress)}) | Out-Null\nStart-Sleep -Milliseconds 18`;
+    }).join('\n');
+    const script = USER32_HEAD + focusGuard(input.windowId)
+      + `[VascendComputerInput]::SetCursorPos(${x}, ${y}) | Out-Null\nStart-Sleep -Milliseconds 60\n`
+      + '[VascendComputerInput]::mouse_event(2,0,0,0,[UIntPtr]::Zero)\nStart-Sleep -Milliseconds 90\n'
+      + path + '\nStart-Sleep -Milliseconds 90\n'
+      + '[VascendComputerInput]::mouse_event(4,0,0,0,[UIntPtr]::Zero)';
+    return runPowerShell(script, { timeoutMs: 20000 });
+  }
+  if (action === 'type') {
+    const text = String(input.text || '').slice(0, MAX_TEXT);
+    if (!text) return { ok: false, error: 'Testo mancante.' };
+    const submit = input.submit === true
+      ? '\n[VascendComputerInput]::keybd_event(13,0,0,[UIntPtr]::Zero)\n[VascendComputerInput]::keybd_event(13,0,2,[UIntPtr]::Zero)\n' : '';
+    // Un testo lungo non puo passare per la digitazione a ritmo umano: si
+    // incolla dagli appunti (poi ripristinati) e resta dentro il timeout.
+    if (text.length > PASTE_THRESHOLD || input.paste === true) {
+      return runPowerShell(USER32_HEAD + focusGuard(input.windowId) + PASTE_BODY
+        + '$text = [Console]::In.ReadToEnd()\n'
+        + 'if (-not (Invoke-VascendPaste $text)) { [Console]::Error.Write(\'Appunti non disponibili: il testo non e stato incollato.\'); exit 4 }\n'
+        + submit, { input: text, timeoutMs: 25000 });
+    }
+    return runPowerShell(USER32_HEAD + focusGuard(input.windowId) + TYPE_SCRIPT + submit, {
+      input: text,
+      timeoutMs: typingTimeout(text),
+    });
+  }
+  if (action === 'key') {
+    const chords = keyChords(input.keys || input.key);
+    if (!chords.length) return { ok: false, error: 'Scorciatoia non valida.' };
+    const repeat = integer(input.repeat, 1, 40, 1);
+    const body = Array.from({ length: repeat }, () => chords.map((codes) => chordScript(codes)).join('\nStart-Sleep -Milliseconds 45\n'))
+      .join('\nStart-Sleep -Milliseconds 45\n');
+    return runPowerShell(USER32_HEAD + focusGuard(input.windowId) + body, {
+      timeoutMs: Math.min(60000, 15000 + chords.length * repeat * 200),
+    });
+  }
+  if (action === 'scroll') {
+    const x = integer(input.x, -32768, 32767);
+    const y = integer(input.y, -32768, 32767);
+    const amount = integer(input.amount, -12000, 12000, -600);
+    // 0x0800 = WHEEL verticale, 0x01000 = WHEEL orizzontale.
+    const wheel = String(input.axis || '').toLowerCase() === 'horizontal' ? 0x01000 : 0x0800;
+    const script = USER32_HEAD + focusGuard(input.windowId) + `[VascendComputerInput]::SetCursorPos(${x}, ${y}) | Out-Null\n[VascendComputerInput]::mouse_event(${wheel},0,0,${amount},[UIntPtr]::Zero)`;
+    return runPowerShell(script);
+  }
+  if (action === 'fill') {
+    const x = integer(input.x, -32768, 32767);
+    const y = integer(input.y, -32768, 32767);
+    const text = String(input.text || '').slice(0, MAX_TEXT);
+    if (!text) return { ok: false, error: 'Testo mancante.' };
+    const submit = input.submit === true
+      ? '\n[VascendComputerInput]::keybd_event(13,0,0,[UIntPtr]::Zero)\n[VascendComputerInput]::keybd_event(13,0,2,[UIntPtr]::Zero)\n' : '';
+    const clear = input.clear === true
+      ? '[VascendComputerInput]::keybd_event(0x11,0,0,[UIntPtr]::Zero)\n[VascendComputerInput]::keybd_event(0x41,0,0,[UIntPtr]::Zero)\n[VascendComputerInput]::keybd_event(0x41,0,2,[UIntPtr]::Zero)\n[VascendComputerInput]::keybd_event(0x11,0,2,[UIntPtr]::Zero)\nStart-Sleep -Milliseconds 40\n'
+      : '';
+    const head = USER32_HEAD + focusGuard(input.windowId)
+      + `[VascendComputerInput]::SetCursorPos(${x}, ${y}) | Out-Null\n`
+      + '[VascendComputerInput]::mouse_event(2,0,0,0,[UIntPtr]::Zero)\n'
+      + '[VascendComputerInput]::mouse_event(4,0,0,0,[UIntPtr]::Zero)\n'
+      + 'Start-Sleep -Milliseconds 90\n' + clear;
+    if (text.length > PASTE_THRESHOLD || input.paste === true) {
+      return runPowerShell(head + PASTE_BODY
+        + '$text = [Console]::In.ReadToEnd()\n'
+        + 'if (-not (Invoke-VascendPaste $text)) { [Console]::Error.Write(\'Appunti non disponibili: il testo non e stato incollato.\'); exit 4 }\n'
+        + submit, { input: text, timeoutMs: 25000 });
+    }
+    return runPowerShell(head + TYPE_SCRIPT + submit, { input: text, timeoutMs: typingTimeout(text) });
+  }
+  if (action === 'focusWindow') {
+    const windowId = String(input.windowId || '');
+    if (!/^\d+$/.test(windowId)) return { ok: false, error: 'Finestra collegata non valida.' };
+    return runPowerShell(USER32_HEAD + focusGuard(windowId));
+  }
+  return { ok: false, error: 'Azione Computer Use sconosciuta.' };
+}
+
+// Applicazioni installate. E' l'elenco che rende possibile "apri Spotify"
+// quando l'app non e' in esecuzione, senza comporre comandi arbitrari: si apre
+// una voce che esiste gia' nel menu Start.
+//
+// Servono DUE fonti: le scorciatoie .lnk sul filesystem e le voci di
+// AppsFolder. Claude Desktop, Spotify e Blocco note su Windows 11 sono
+// pacchetti del Microsoft Store e non hanno alcun .lnk: cercandoli solo fra i
+// file non si trovavano proprio le app che l'utente nomina piu' spesso.
+const START_APPS_SCRIPT = String.raw`
+$apps = @()
+try { $apps = @(Get-StartApps | Select-Object Name, AppID) } catch {}
+[Console]::Out.Write((ConvertTo-Json -InputObject $apps -Depth 3 -Compress))
+`;
+
+async function startAppEntries() {
+  const rows = parseJsonOutput(await runPowerShell(START_APPS_SCRIPT, { timeoutMs: 12000, maxOutput: 128000 }), []);
+  return rows
+    .map((row) => ({
+      name: String(row && row.Name || row && row.name || '').slice(0, 160),
+      path: 'shell:AppsFolder\\' + String(row && row.AppID || row && row.appId || ''),
+    }))
+    .filter((row) => row.name && !row.path.endsWith('\\'));
+}
+
+async function collectShortcuts(dir, depth, out) {
+  if (depth < 0 || out.length >= 900) return;
+  let entries = [];
+  try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch (_) { return; }
+  for (const entry of entries) {
+    if (out.length >= 900) return;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await collectShortcuts(full, depth - 1, out);
+      continue;
+    }
+    if (!/\.(lnk|url)$/i.test(entry.name)) continue;
+    out.push({ name: entry.name.replace(/\.(lnk|url)$/i, ''), path: full });
+  }
+}
+
+async function defaultStartMenuApps() {
+  const roots = [
+    path.join(process.env.ProgramData || 'C:\\ProgramData', 'Microsoft', 'Windows', 'Start Menu', 'Programs'),
+    process.env.APPDATA ? path.join(process.env.APPDATA, 'Microsoft', 'Windows', 'Start Menu', 'Programs') : '',
+  ].filter(Boolean);
+  const shortcuts = [];
+  const [store] = await Promise.all([
+    startAppEntries().catch(() => []),
+    (async () => { for (const root of roots) await collectShortcuts(root, 3, shortcuts); })(),
+  ]);
+  // AppsFolder e' la fonte piu' vicina a quello che l'utente vede nel menu
+  // Start: vince sui .lnk a parita' di nome.
+  const byName = new Map();
+  for (const entry of [...shortcuts, ...store]) {
+    byName.set(entry.name.toLocaleLowerCase(), entry);
+  }
+  return [...byName.values()].slice(0, 900);
+}
+
+module.exports = {
+  VK,
+  EXTENDED_VK,
+  MAX_TEXT,
+  PASTE_THRESHOLD,
+  keyCodes,
+  keyChords,
+  keyFlags,
+  chordScript,
+  runPowerShell,
+  repairJsonText,
+  readJsonOutput,
+  focusGuard,
+  typingTimeout,
+  UIA_ACTION_SCRIPT,
+  uiaActionScript,
+  UI_ELEMENTS_SCRIPT,
+  PASTE_SCRIPT,
+  TYPE_SCRIPT,
+  defaultAction,
+  defaultDesktopInfo,
+  defaultWindows,
+  defaultProcesses,
+  defaultUiElements,
+  defaultUiAction,
+  defaultLaunch,
+  defaultOpenPath,
+  defaultStartMenuApps,
+};