@ycheung5/pi-computer-use 0.0.0-stage → 0.1.0

package/assets/window-management.cs

@@ -0,0 +1,217 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Runtime.InteropServices;
+using System.Text;
+using System.Threading;
+using Microsoft.Win32;
+
+partial class WindowsBridge {
+  [DllImport("user32.dll",EntryPoint="ShowWindowAsync")] static extern bool ManagementShow(IntPtr window,int command);
+  [DllImport("user32.dll",EntryPoint="SetWindowPos",SetLastError=true)] static extern bool ManagementMove(IntPtr window,IntPtr after,int x,int y,int width,int height,uint flags);
+  [DllImport("user32.dll",EntryPoint="PostMessageW",SetLastError=true)] static extern bool ManagementPost(IntPtr window,uint message,IntPtr wParam,IntPtr lParam);
+  [DllImport("user32.dll",EntryPoint="AttachThreadInput")] static extern bool ManagementAttach(uint from,uint to,bool attach);
+  [DllImport("kernel32.dll",EntryPoint="GetCurrentThreadId")] static extern uint ManagementThread();
+  static uint ManagementOwner(IntPtr window) {uint owner;GetWindowThreadProcessId(window,out owner);return owner;}
+  static void ManagementAssert(IntPtr window,uint owner) {CheckWindowReference(window);if(!IsWindow(window)||ManagementOwner(window)!=owner)throw new InvalidOperationException("WINDOW_IDENTITY_CHANGED: refresh window observations before acting");}
+  static bool? ManagementResponsive(IntPtr window) {UIntPtr ignored;bool answered=SendMessageTimeout(window,0,UIntPtr.Zero,IntPtr.Zero,3,100,out ignored)!=IntPtr.Zero;int error=Marshal.GetLastWin32Error();return !answered&&error==5?(bool?)null:answered;}
+  static Dictionary<string,object> ManagementWindow(IntPtr window,uint owner) {
+    Rect bounds;if(!GetWindowRect(window,out bounds))throw new InvalidOperationException("WINDOW_BOUNDS_UNAVAILABLE");
+    StringBuilder title=new StringBuilder(2048);GetWindowText(window,title,title.Capacity);
+    return new Dictionary<string,object>{{"nativeWindowHandle",window.ToInt64()},{"processId",owner},{"name",title.ToString()},{"boundingBox",new Dictionary<string,object>{{"x",bounds.Left},{"y",bounds.Top},{"width",bounds.Right-bounds.Left},{"height",bounds.Bottom-bounds.Top}}}};
+  }
+  // Read only the documented, 8-byte-aligned WTSINFOEX level-1 prefix;
+  // account-name fields are never copied or reported.
+  [StructLayout(LayoutKind.Explicit,Size=20)]struct ManagementSessionHeader {
+    [FieldOffset(0)]public uint Level;[FieldOffset(8)]public uint Session;
+    [FieldOffset(12)]public uint Connection;[FieldOffset(16)]public int Flags;
+  }
+  [DllImport("kernel32.dll",EntryPoint="GetCurrentProcessId")]static extern uint ManagementProcessId();
+  [DllImport("kernel32.dll",EntryPoint="ProcessIdToSessionId")]static extern bool ManagementSessionId(uint process,out uint session);
+  [DllImport("wtsapi32.dll",EntryPoint="WTSQuerySessionInformationW")]static extern bool ManagementQuerySession(IntPtr server,uint session,int kind,out IntPtr buffer,out uint bytes);
+  [DllImport("wtsapi32.dll",EntryPoint="WTSFreeMemory")]static extern void ManagementFreeSession(IntPtr buffer);
+  static void ManagementEnsureUnlockedSession() {
+    uint session;if(!ManagementSessionId(ManagementProcessId(),out session))return;
+    IntPtr buffer=IntPtr.Zero;uint bytes;
+    try {
+      if(!ManagementQuerySession(IntPtr.Zero,session,25,out buffer,out bytes) || buffer==IntPtr.Zero || bytes<20)return;
+      ManagementSessionHeader state=(ManagementSessionHeader)Marshal.PtrToStructure(buffer,typeof(ManagementSessionHeader));
+      if(state.Level==1 && state.Session==session && state.Flags==0)throw new InvalidOperationException("DESKTOP_SESSION_LOCKED: unlock Windows before requesting foreground input");
+    }finally {if(buffer!=IntPtr.Zero)ManagementFreeSession(buffer);}
+    // Unknown/unavailable session state does not invent a lock diagnosis;
+    // the existing identity, foreground and input guards still apply.
+  }
+  [DllImport("user32.dll",EntryPoint="BringWindowToTop")]static extern bool ManagementBringToTop(IntPtr window);
+  sealed class ActivationRefusedException : InvalidOperationException {
+    public readonly Dictionary<string,object> Diagnostic;
+    public ActivationRefusedException(Dictionary<string,object> diagnostic) : base("TARGET_ACTIVATION_REFUSED: Windows did not grant foreground access") {Diagnostic=diagnostic;}
+  }
+  static string ManagementForegroundRelationship(IntPtr foreground,IntPtr window,uint owner) {
+    if(foreground==IntPtr.Zero)return "unavailable";
+    if(foreground==window)return "target";
+    if(GetAncestor(foreground,2)==window)return "target_child";
+    return ManagementOwner(foreground)==owner?"same_process":"other_process";
+  }
+  static bool ManagementActivate(IntPtr window,uint owner) {return ManagementActivate(window,owner,null);}
+  // One active operation per desktop; retain the existing lifetime witness,
+  // not another element cache. A helper restart forgets visible intent safely.
+  static string visibleOperation;
+  static WindowReference visibleTarget;
+  static void ApplyVisibleIntent(Dictionary<string,object> args,IntPtr window) {
+    if(args.ContainsKey("activate") || TextOption(args,"dispatch","")=="background" || TextOption(args,"method","")=="background")return;
+    if(visibleTarget!=null && visibleOperation==pointerOperation && visibleTarget.Window==window && visibleTarget.Owner==WindowOwner(window) && WindowMarker.Matches(window,visibleTarget.Owner,visibleTarget.Marker))args["activate"]=true;
+  }
+  static bool ManagementActivate(IntPtr window,uint owner,Dictionary<string,object> diagnostics) {
+    ManagementAssert(window,owner);ManagementEnsureUnlockedSession();
+    if(IsIconic(window)){BeginWindowDispatch();ManagementShow(window,9);}
+    if(GetForegroundWindow()==window)return true;
+    BeginWindowDispatch();bool initial=SetForegroundWindow(window);
+    if(diagnostics!=null)diagnostics["initialRequestAccepted"]=initial;
+    if(GetForegroundWindow()==window)return true;
+    IntPtr front=GetForegroundWindow();uint ignored;uint frontThread=GetWindowThreadProcessId(front,out ignored),own=ManagementThread();bool attached=false;
+    if(diagnostics!=null)diagnostics["foregroundBeforeFallback"]=ManagementForegroundRelationship(front,window,owner);
+    try {
+      bool attempted=frontThread!=0&&frontThread!=own;
+      if(attempted)attached=ManagementAttach(own,frontThread,true);
+      if(diagnostics!=null){diagnostics["inputThreadAttachAttempted"]=attempted;if(attempted)diagnostics["inputThreadAttached"]=attached;}
+      ManagementAssert(window,owner);BeginWindowDispatch();bool raised=ManagementBringToTop(window);ManagementAssert(window,owner);BeginWindowDispatch();bool requested=SetForegroundWindow(window);
+      if(diagnostics!=null){diagnostics["raiseAccepted"]=raised;diagnostics["fallbackRequestAccepted"]=requested;}
+    }
+    finally {if(attached)ManagementAttach(own,frontThread,false);}
+    for(int index=0;index<8&&GetForegroundWindow()!=window;index++)Thread.Sleep(10);
+    IntPtr finalForeground=GetForegroundWindow();
+    if(diagnostics!=null)diagnostics["foregroundAfterFallback"]=ManagementForegroundRelationship(finalForeground,window,owner);
+    return finalForeground==window;
+  }
+  static object ManageNativeWindow(string action,Dictionary<string,object> args) {
+    if(action=="launch_app")return LaunchFromDesktop(args);
+    // Shared Win32 capture resolver performs HWND/PID/title matching without resolving UIA.
+    IntPtr window=ResolveCaptureWindow(args);uint owner=ManagementOwner(window);ManagementAssert(window,owner);
+    Dictionary<string,object> result=Result(true,action);result["nativeWindowHandle"]=window.ToInt64();result["processId"]=owner;result["window"]=ManagementWindow(window,owner);
+    bool? responsive=ManagementResponsive(window);result["targetResponsive"]=responsive;
+    ManagementAssert(window,owner);
+    if(action=="close_window") {
+      BeginWindowDispatch();bool posted=ManagementPost(window,0x0010,IntPtr.Zero,IntPtr.Zero);result["posted"]=posted;result["verification"]=posted?"sent":"unconfirmed";result["note"]=posted?"WM_CLOSE was dispatched; the application may veto closure or show a save dialog. Observe windows to verify.":"Windows refused posting WM_CLOSE; no closure was confirmed.";if(!posted)result["nativeError"]=Marshal.GetLastWin32Error();return result;
+    }
+    if(action=="move_window") {
+      int x=Convert.ToInt32(args["x"]),y=Convert.ToInt32(args["y"]);
+      BeginWindowDispatch();bool moved=ManagementMove(window,IntPtr.Zero,x,y,0,0,0x0001|0x0004|0x0010|0x4000);
+      result["moved"]=moved;result["x"]=x;result["y"]=y;result["verification"]=moved?"sent":"unconfirmed";
+      if(!moved)result["warning"]="SetWindowPos refused the move; the window may be unavailable or maximized.";
+      if(!args.ContainsKey("activate")||!Convert.ToBoolean(args["activate"]))return result;
+    }
+    bool activated=responsive==true&&ManagementActivate(window,owner);result["activated"]=activated;
+    if(activated){visibleOperation=pointerOperation;visibleTarget=ObserveWindowReference(window,result);if(visibleTarget!=null){currentReference=visibleTarget;result["windowRef"]=visibleTarget.Id;}}
+    if(!activated){result["verification"]="unconfirmed";result["warning"]=responsive==true?"Windows foreground rules refused activation; no keyboard or mouse workaround was sent.":"The target is unresponsive or inaccessible; activation was not attempted.";}
+    else if(action=="activate_window")result["verification"]="sent";
+    return result;
+  }
+
+  static readonly HashSet<string> ManagementCommandHosts=new HashSet<string>(StringComparer.OrdinalIgnoreCase){"cmd","powershell","pwsh","wt","wsl","bash","conhost","wscript","cscript","mshta","rundll32","regsvr32","msiexec","forfiles","schtasks"};
+  [DllImport("shlwapi.dll",CharSet=CharSet.Unicode,EntryPoint="AssocQueryStringW")]static extern int ManagementAssociation(uint flags,int kind,string association,string verb,StringBuilder output,ref uint length);
+  static string AssociationString(string association,bool protocol,int kind) {
+    // ASSOCF_INIT_IGNOREUNKNOWN refuses the generic Open-With fallback;
+    // ASSOCF_IS_PROTOCOL honors current-user HTTP(S) associations.
+    uint length=0;uint flags=0x400u|(protocol?0x1000u:0u);
+    ManagementAssociation(flags,kind,association,"open",null,ref length);
+    if(length==0 || length>32768)return "";
+    StringBuilder output=new StringBuilder((int)length);
+    return ManagementAssociation(flags,kind,association,"open",output,ref length)==0?output.ToString():"";
+  }
+  static Dictionary<string,object> DefaultLaunchHandler(string association,bool protocol) {
+    string executable=AssociationString(association,protocol,2),name=AssociationString(association,protocol,4),progId=AssociationString(association,protocol,20);
+    if(executable.Length==0 && name.Length==0 && progId.Length==0)throw new InvalidOperationException("DEFAULT_APP_UNAVAILABLE: Windows did not resolve an open handler for "+association);
+    return new Dictionary<string,object>{{"association",association},{"executable",executable},{"name",name},{"progId",progId},{"source","windows-association"}};
+  }
+  static void ReleaseLaunchCom(object value) {try{if(value!=null&&Marshal.IsComObject(value))Marshal.ReleaseComObject(value);}catch(InvalidComObjectException){}}
+  static bool FullyQualifiedLaunchPath(string value) {return value.Length>=3&&Char.IsLetter(value[0])&&value[1]==':'&&(value[2]=='\\'||value[2]=='/')||value.StartsWith("\\\\",StringComparison.Ordinal)&&value.TrimStart('\\').Split('\\').Length>=2;}
+  static string ResolveLaunchFile(string target) {
+    if(Path.IsPathRooted(target)) {
+      if(!FullyQualifiedLaunchPath(target))throw new InvalidOperationException("LAUNCH_INVALID_TARGET: use a fully qualified absolute path");
+      if(!File.Exists(target))throw new InvalidOperationException("LAUNCH_NOT_FOUND: target file does not exist");
+      return Path.GetFullPath(target);
+    }
+    if(target.IndexOfAny(new char[]{'\\','/',':'})>=0)return null;
+    string[] extensions=Path.GetExtension(target).Length>0?new string[]{""}:new string[]{".exe",".com",".lnk"};
+    foreach(string directory in (Environment.GetEnvironmentVariable("PATH")??"").Split(';'))foreach(string extension in extensions) {
+      string candidate;try{candidate=Path.Combine(directory.Trim('"'),target+extension);}catch(ArgumentException){continue;}
+      if(File.Exists(candidate))return Path.GetFullPath(candidate);
+    }
+    string name=target.EndsWith(".exe",StringComparison.OrdinalIgnoreCase)?target:target+".exe";
+    foreach(RegistryHive hive in new RegistryHive[]{RegistryHive.CurrentUser,RegistryHive.LocalMachine})foreach(RegistryView view in new RegistryView[]{RegistryView.Registry64,RegistryView.Registry32}) {
+      try{using(RegistryKey root=RegistryKey.OpenBaseKey(hive,view))using(RegistryKey key=root.OpenSubKey("SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\"+name)){
+        string candidate=key==null?null:Convert.ToString(key.GetValue(""));if(String.IsNullOrEmpty(candidate))continue;candidate=Environment.ExpandEnvironmentVariables(candidate.Trim('"'));if(File.Exists(candidate))return Path.GetFullPath(candidate);
+      }}catch(System.Security.SecurityException){}
+    }
+    return null;
+  }
+  static string ResolveInstalledLaunch(string target) {
+    object application=null,folder=null,items=null;List<string> matches=new List<string>();
+    try{
+      application=Activator.CreateInstance(Type.GetTypeFromProgID("Shell.Application"));folder=((dynamic)application).NameSpace("shell:AppsFolder");if(folder==null)throw new InvalidOperationException("Installed app enumeration is unavailable");items=((dynamic)folder).Items();int count=((dynamic)items).Count;
+      for(int index=0;index<count;index++) {
+        object item=null;try{item=((dynamic)items).Item(index);string name=Convert.ToString(((dynamic)item).Name),id=Convert.ToString(((dynamic)item).ExtendedProperty("System.AppUserModel.ID"));
+          if(String.Equals(target,name,StringComparison.OrdinalIgnoreCase)||String.Equals(target,id,StringComparison.OrdinalIgnoreCase)){if(String.IsNullOrEmpty(id))id=Convert.ToString(((dynamic)item).Path);if(!String.IsNullOrEmpty(id))matches.Add(id);}
+        }finally{ReleaseLaunchCom(item);}
+      }
+    }finally{ReleaseLaunchCom(items);ReleaseLaunchCom(folder);ReleaseLaunchCom(application);}
+    if(matches.Count==0)throw new InvalidOperationException("LAUNCH_NOT_FOUND: use an executable path or exact installed app name/AppUserModelID");
+    if(matches.Count!=1)throw new InvalidOperationException("LAUNCH_AMBIGUOUS: use a full executable path or AppUserModelID");
+    return "shell:AppsFolder\\"+matches[0];
+  }
+  static void CheckLaunchProgram(string file,string arguments) {
+    string program=file,embedded="";HashSet<string> seen=new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+    while(String.Equals(Path.GetExtension(program),".lnk",StringComparison.OrdinalIgnoreCase)){
+      if(!seen.Add(program)||seen.Count>8)throw new InvalidOperationException("LAUNCH_INVALID_TARGET: shortcut chain is cyclic or too deep");
+      object shell=null,link=null;try{shell=Activator.CreateInstance(Type.GetTypeFromProgID("WScript.Shell"));link=((dynamic)shell).CreateShortcut(program);embedded+=" "+Convert.ToString(((dynamic)link).Arguments);program=Environment.ExpandEnvironmentVariables(Convert.ToString(((dynamic)link).TargetPath));if(String.IsNullOrWhiteSpace(program))throw new InvalidOperationException("LAUNCH_INVALID_TARGET: shortcut has no executable target");}finally{ReleaseLaunchCom(link);ReleaseLaunchCom(shell);}
+    }
+    if((arguments.Trim().Length>0||embedded.Trim().Length>0)&&ManagementCommandHosts.Contains(Path.GetFileNameWithoutExtension(program)))throw new InvalidOperationException("LAUNCH_COMMAND_REFUSED: command/script hosts accept no arguments through launch_app; use Pi's shell tool");
+  }
+  static object LaunchFromDesktop(Dictionary<string,object> args) {
+    Dictionary<string,object> result=null;Exception failure=null;
+    Thread thread=new Thread(delegate(){
+      try{
+        string target=Convert.ToString(args["target"]).Trim(),arguments=Convert.ToString(args["arguments"]),directory=Convert.ToString(args["workingDirectory"]);
+        Uri uri;bool protocol=Uri.TryCreate(target,UriKind.Absolute,out uri)&&(uri.Scheme=="http"||uri.Scheme=="https");
+        if(!protocol)target=Environment.ExpandEnvironmentVariables(target);
+        if(protocol && String.IsNullOrEmpty(uri.Host))throw new InvalidOperationException("LAUNCH_INVALID_TARGET: HTTP(S) URL requires a host");
+        bool browser=String.Equals(target,"browser",StringComparison.OrdinalIgnoreCase);
+        string file=protocol||browser?null:ResolveLaunchFile(target),kind=browser?"default-browser":protocol?"url":file==null?"installed-app":"file";
+        Dictionary<string,object> handler=null;
+        if(file!=null){string extension=Path.GetExtension(file);if(String.Equals(extension,".exe",StringComparison.OrdinalIgnoreCase)||String.Equals(extension,".com",StringComparison.OrdinalIgnoreCase)||String.Equals(extension,".lnk",StringComparison.OrdinalIgnoreCase))CheckLaunchProgram(file,arguments);else {
+          if(new HashSet<string>(StringComparer.OrdinalIgnoreCase){".bat",".cmd",".ps1",".vbs",".vbe",".js",".jse",".wsf",".wsh",".hta",".reg",".msi",".msp",".scr",".cpl"}.Contains(extension))throw new InvalidOperationException("LAUNCH_COMMAND_REFUSED: use Pi's shell tool for scripts/installers");
+          kind="document";handler=DefaultLaunchHandler(Path.GetExtension(file),false);
+        }target=file;}
+        else if(browser)handler=DefaultLaunchHandler("https",true);
+        else if(protocol)handler=DefaultLaunchHandler(uri.Scheme,true);
+        else target=ResolveInstalledLaunch(target);
+        if(handler!=null) {
+          if(arguments.Length>0||directory.Length>0)throw new InvalidOperationException("LAUNCH_INVALID_ARGUMENTS: default-handler URLs/documents do not accept arguments or workingDirectory");
+          string handlerExecutable=Convert.ToString(handler["executable"]);
+          if(ManagementCommandHosts.Contains(Path.GetFileNameWithoutExtension(handlerExecutable)))throw new InvalidOperationException("LAUNCH_COMMAND_REFUSED: default handler is a command/script host; use Pi's shell tool");
+        }
+        if(directory.Length>0){directory=Environment.ExpandEnvironmentVariables(directory);if(!FullyQualifiedLaunchPath(directory)||!Directory.Exists(directory))throw new InvalidOperationException("LAUNCH_INVALID_DIRECTORY: use an existing fully qualified directory");directory=Path.GetFullPath(directory);}
+        if(kind=="installed-app"&&(arguments.Length>0||directory.Length>0))throw new InvalidOperationException("LAUNCH_INVALID_ARGUMENTS: installed AppUserModelID launches do not accept arguments or workingDirectory");
+        if(Option(args,"resolveOnly",false)) {
+          result=Result(true,"launch_app");result["target"]=target;result["targetKind"]=kind;result["handler"]=handler;result["verification"]="resolved";result["launched"]=false;
+          result["note"]="Resolution only; no app was opened. Select and observe the intended existing window before creating a task tab/document. Handler metadata is not a window identity.";return;
+        }
+        if(browser){target=Convert.ToString(handler["executable"]);if(target.Length==0)throw new InvalidOperationException("DEFAULT_APP_UNAVAILABLE: Windows resolved the browser but did not provide a blank-window launch executable; reuse its observed window or open a requested HTTP(S) URL");}
+        object windows=null,desktop=null,document=null,application=null;
+        try{
+          windows=Activator.CreateInstance(Type.GetTypeFromCLSID(new Guid("9BA05972-F6A8-11CF-A442-00A0C90A8F39")));
+          object location=0,root=null;int handle=0;desktop=((dynamic)windows).FindWindowSW(ref location,ref root,8,out handle,1);
+          if(desktop==null)throw new InvalidOperationException("interactive Explorer desktop is unavailable");
+          document=((dynamic)desktop).Document;application=((dynamic)document).Application;
+          ((dynamic)application).ShellExecute(target,arguments,directory,"open",Convert.ToBoolean(args["activate"])?1:4);
+        }catch(Exception error){throw new InvalidOperationException("LAUNCH_SHELL_FAILED: "+error.Message+"; no child-process fallback or replay was attempted",error);}
+        finally{ReleaseLaunchCom(application);ReleaseLaunchCom(document);ReleaseLaunchCom(desktop);ReleaseLaunchCom(windows);}
+        result=Result(true,"launch_app");result["target"]=target;result["targetKind"]=kind;if(handler!=null)result["handler"]=handler;result["launchMethod"]="explorer-shell";result["verification"]="dispatched";result["note"]="Explorer accepted the launch. New windows are observations, not confirmed matches. The app can reuse a window or activate itself; use list_windows/wait_for to verify. No elevation was requested.";
+      }catch(Exception error){failure=error;}
+    });
+    thread.IsBackground=true;thread.SetApartmentState(ApartmentState.STA);thread.Start();
+    if(!thread.Join(15000))throw new InvalidOperationException("LAUNCH_PENDING_TIMEOUT: Explorer outcome is unknown; do not replay the launch");
+    if(failure!=null)throw failure;
+    return result;
+  }
+}

package/assets/window-marker.cs

@@ -0,0 +1,23 @@
+using System;
+using System.Runtime.InteropServices;
+
+// Stateless witness checks shared by the authoritative bridge and delegated WGC.
+static class WindowMarker {
+  [DllImport("user32.dll",CharSet=CharSet.Unicode,SetLastError=true)] static extern bool SetProp(IntPtr window,string name,IntPtr value);
+  [DllImport("user32.dll",CharSet=CharSet.Unicode)] static extern IntPtr GetProp(IntPtr window,string name);
+  [DllImport("user32.dll",CharSet=CharSet.Unicode)] static extern IntPtr RemoveProp(IntPtr window,string name);
+  [DllImport("user32.dll")] static extern bool IsWindow(IntPtr window);
+  [DllImport("user32.dll")] static extern uint GetWindowThreadProcessId(IntPtr window,out uint owner);
+  internal static bool Matches(IntPtr window,uint owner,string name) {
+    uint actual;GetWindowThreadProcessId(window,out actual);
+    return owner!=0 && actual==owner && IsWindow(window) && GetProp(window,name)==new IntPtr(1);
+  }
+  internal static bool Bind(IntPtr window,uint owner,string name,out int error) {
+    uint actual;GetWindowThreadProcessId(window,out actual);error=0;
+    if(actual!=owner || owner==0 || !IsWindow(window))return false;
+    if(!SetProp(window,name,new IntPtr(1))){error=Marshal.GetLastWin32Error();return false;}
+    if(Matches(window,owner,name))return true;
+    Remove(window,owner,name);return false;
+  }
+  internal static void Remove(IntPtr window,uint owner,string name) {if(Matches(window,owner,name))RemoveProp(window,name);}
+}

package/assets/window-references.cs

@@ -0,0 +1,80 @@
+using System;
+using System.Collections.Generic;
+
+partial class WindowsBridge {
+  sealed class WindowReference {
+    internal string Id,Marker;internal IntPtr Window;internal uint Owner;internal DateTime Seen;
+  }
+  static readonly string referenceEpoch=Convert.ToBase64String(Guid.NewGuid().ToByteArray()).TrimEnd('=').Replace('+','-').Replace('/','_');
+  static long referenceSequence,elementSequence;
+  static readonly Dictionary<string,WindowReference> windowReferences=new Dictionary<string,WindowReference>();
+  static WindowReference currentReference;
+  static bool windowDispatchAttempted;
+  static void BeginWindowDispatch(){CheckReferenceBeforeDispatch();windowDispatchAttempted=true;}
+  static void FinishWindowReference(Dictionary<string,object> payload){
+    if(currentReference==null)return;
+    bool cleanupFailed=payload.ContainsKey("cleanupConfirmed") && !Convert.ToBoolean(payload["cleanupConfirmed"]);
+    if(!cleanupFailed && Convert.ToString(payload["action"])=="close_window" && windowDispatchAttempted && payload.ContainsKey("posted") && Convert.ToBoolean(payload["posted"]) && !IsWindow(currentReference.Window)){
+      // WM_CLOSE was posted; observing its intended disappearance is not a failed action.
+      payload["targetState"]="absent";payload["windowRef"]=currentReference.Id;return;
+    }
+    if(!CurrentReferenceIntact()){
+      payload["ok"]=false;payload.Remove("inputRequired");payload["dispatchAttempted"]=windowDispatchAttempted;
+      string warning=windowDispatchAttempted?"WINDOW_REFERENCE_LOST_AFTER_DISPATCH: app effects may have occurred; observe before further action; never replay":"WINDOW_REFERENCE_LOST: lifetime proof is unavailable; observe again";
+      if(payload.ContainsKey("cleanupConfirmed") && !Convert.ToBoolean(payload["cleanupConfirmed"]))payload["identityWarning"]=warning;else payload["error"]=warning;
+      if(windowDispatchAttempted){payload["effectsUncertain"]=true;if(!payload.ContainsKey("verification"))payload["verification"]="unconfirmed";}
+    }
+    payload["windowRef"]=currentReference.Id;
+  }
+  static bool CurrentReferenceIntact() {return currentReference==null || WindowMarker.Matches(currentReference.Window,currentReference.Owner,currentReference.Marker);}
+  static void CheckReferenceBeforeDispatch() {if(currentReference!=null)CheckWindowReference(currentReference.Window);}
+  static void CheckWindowReference(IntPtr window) {
+    if(currentReference!=null && currentReference.Window==window && !WindowMarker.Matches(window,currentReference.Owner,currentReference.Marker))throw new InvalidOperationException("WINDOW_REFERENCE_LOST: lifetime proof is unavailable; observe again; never replay uncertain effects");
+  }
+  static WindowReference ResolveWindowReference(Dictionary<string,object> args) {
+    if(!args.ContainsKey("windowRef"))return null;
+    string id=Convert.ToString(args["windowRef"]);WindowReference entry;
+    if(!windowReferences.TryGetValue(id,out entry))throw new InvalidOperationException("STALE_WINDOW_REFERENCE: unknown or expired reference; observe again");
+    if(entry.Seen<DateTime.UtcNow.AddMinutes(-5)){WindowMarker.Remove(entry.Window,entry.Owner,entry.Marker);windowReferences.Remove(id);throw new InvalidOperationException("STALE_WINDOW_REFERENCE: reference expired; observe again");}
+    if(!WindowMarker.Matches(entry.Window,entry.Owner,entry.Marker))throw new InvalidOperationException("WINDOW_REFERENCE_LOST: lifetime proof is unavailable; observe again");
+    if((args.ContainsKey("nativeWindowHandle") && Convert.ToInt64(args["nativeWindowHandle"])!=entry.Window.ToInt64()) || (args.ContainsKey("processId") && Convert.ToUInt32(args["processId"])!=entry.Owner) || (args.ContainsKey("windowTitle") && WindowTitle(entry.Window).IndexOf(Convert.ToString(args["windowTitle"]),StringComparison.OrdinalIgnoreCase)<0))throw new InvalidOperationException("WINDOW_REFERENCE_CONFLICT: selectors disagree with the observed lifetime");
+    if(TextOption(args,"scope","")=="desktop" || args.ContainsKey("browserTab"))throw new InvalidOperationException("WINDOW_REFERENCE_CONFLICT: window reference cannot target desktop or browser channel");
+    entry.Seen=DateTime.UtcNow;currentReference=entry;return entry;
+  }
+  static object ObserveReferencePresence(Dictionary<string,object> args) {
+    WindowReference entry;string id=Convert.ToString(args["windowRef"]);
+    if(windowReferences.TryGetValue(id,out entry) && ((args.ContainsKey("nativeWindowHandle") && Convert.ToInt64(args["nativeWindowHandle"])!=entry.Window.ToInt64()) || (args.ContainsKey("processId") && Convert.ToUInt32(args["processId"])!=entry.Owner)))throw new InvalidOperationException("WINDOW_REFERENCE_CONFLICT: selectors disagree with the observed lifetime");
+    if(windowReferences.TryGetValue(id,out entry) && entry.Seen>=DateTime.UtcNow.AddMinutes(-5) && !IsWindow(entry.Window)){
+      if(args.ContainsKey("windowTitle"))throw new InvalidOperationException("WINDOW_REFERENCE_CONSTRAINT_UNAVAILABLE: destroyed window title cannot be verified");
+      return new Dictionary<string,object>{{"ok",true},{"action","list_windows"},{"referencePresent",false},{"windows",new List<object>()}};
+    }
+    entry=ResolveWindowReference(args);
+    return new Dictionary<string,object>{{"ok",true},{"action","list_windows"},{"referencePresent",true},{"windows",new List<object>()}};
+  }
+  static void PruneWindowReferences() {
+    var remove=new List<string>();
+    foreach(var pair in windowReferences)if(pair.Value.Seen<DateTime.UtcNow.AddMinutes(-5) || !WindowMarker.Matches(pair.Value.Window,pair.Value.Owner,pair.Value.Marker))remove.Add(pair.Key);
+    foreach(string id in remove){WindowReference entry=windowReferences[id];WindowMarker.Remove(entry.Window,entry.Owner,entry.Marker);windowReferences.Remove(id);}
+  }
+  static WindowReference ObserveWindowReference(IntPtr window,Dictionary<string,object> metadata) {
+    if(window==IntPtr.Zero){metadata["windowRefUnavailable"]="WINDOW_REFERENCE_UNAVAILABLE: no native root could be established";return null;}
+    CheckWindowReference(window);uint owner=WindowOwner(window);
+    foreach(var pair in windowReferences)if(pair.Value.Window==window && pair.Value.Owner==owner && pair.Value.Seen>=DateTime.UtcNow.AddMinutes(-5) && WindowMarker.Matches(window,owner,pair.Value.Marker)){pair.Value.Seen=DateTime.UtcNow;return pair.Value;}
+    PruneWindowReferences();
+    if(windowReferences.Count>=4096){metadata["windowRefUnavailable"]="REFERENCE_CAPACITY: observe again after expiry";return null;}
+    string serial=(++referenceSequence).ToString("x"),marker="PiComputerUse.Window."+referenceEpoch+"."+serial;int error;
+    if(!WindowMarker.Bind(window,owner,marker,out error)){metadata["windowRefUnavailable"]="WINDOW_REFERENCE_UNAVAILABLE: marker acquisition failed (native error "+error+")";return null;}
+    var entry=new WindowReference {Id="w:"+referenceEpoch+":"+serial,Marker=marker,Window=window,Owner=owner,Seen=DateTime.UtcNow};windowReferences.Add(entry.Id,entry);return entry;
+  }
+  static void AddWindowReference(Dictionary<string,object> metadata,IntPtr window) {
+    WindowReference entry=ObserveWindowReference(window,metadata);if(entry!=null)metadata["windowRef"]=entry.Id;
+  }
+  static Dictionary<string,object> WindowReferenceDescriptor(IntPtr window) {
+    WindowReference entry=currentReference!=null && currentReference.Window==window?currentReference:ObserveWindowReference(window,new Dictionary<string,object>());
+    return entry==null?null:new Dictionary<string,object>{{"name",entry.Marker},{"windowRef",entry.Id}};
+  }
+  static void CleanupWindowReferences() {
+    foreach(var pair in windowReferences)WindowMarker.Remove(pair.Value.Window,pair.Value.Owner,pair.Value.Marker);
+    windowReferences.Clear();observed.Clear();elementKeys.Clear();
+  }
+}

package/assets/windows.cs

@@ -0,0 +1,127 @@
+using System;
+using System.Collections.Generic;
+using System.Runtime.InteropServices;
+using System.Text;
+using System.Web.Script.Serialization;
+
+// Focused Win32 bridge; guarded input lives in pointer.cs.
+partial class WindowsBridge {
+  static bool physicalInputAnnounced;
+  static void NotifyPhysicalInput(bool active) {
+    if(physicalInputAnnounced==active)return;
+    physicalInputAnnounced=active;
+    Console.WriteLine(new JavaScriptSerializer().Serialize(new Dictionary<string,object> {{"event","input_state"},{"active",active},{"operationId",pointerOperation}}));
+    Console.Out.Flush();
+  }
+  delegate bool EnumWindow(IntPtr handle, IntPtr parameter);
+  [StructLayout(LayoutKind.Sequential)] struct Rect { public int Left, Top, Right, Bottom; }
+  [DllImport("user32.dll")] static extern bool EnumWindows(EnumWindow callback, IntPtr parameter);
+  [DllImport("user32.dll")] static extern bool IsWindow(IntPtr handle);
+  [DllImport("user32.dll")] static extern bool IsWindowVisible(IntPtr handle);
+  [DllImport("user32.dll")] static extern bool IsWindowEnabled(IntPtr handle);
+  [DllImport("user32.dll")] static extern bool IsIconic(IntPtr handle);
+  [DllImport("user32.dll")] static extern IntPtr GetForegroundWindow();
+  [DllImport("user32.dll")] static extern bool GetWindowRect(IntPtr handle, out Rect rect);
+  [DllImport("user32.dll", CharSet=CharSet.Unicode)] static extern int GetWindowText(IntPtr handle, StringBuilder text, int count);
+  [DllImport("user32.dll", CharSet=CharSet.Unicode)] static extern int GetClassName(IntPtr handle, StringBuilder text, int count);
+  [DllImport("user32.dll")] static extern uint GetWindowThreadProcessId(IntPtr handle, out uint process);
+  [DllImport("user32.dll", SetLastError=true)] static extern IntPtr SendMessageTimeout(IntPtr handle, uint message, UIntPtr wParam, IntPtr lParam, uint flags, uint timeout, out UIntPtr result);
+  [DllImport("user32.dll")] static extern bool SetProcessDPIAware();
+  [DllImport("user32.dll")] static extern bool SetProcessDpiAwarenessContext(IntPtr context);
+
+  static Dictionary<string, object> Result(bool ok, string action) {
+    return new Dictionary<string, object> { { "ok", ok }, { "action", action } };
+  }
+
+  static object ListWindows(Dictionary<string, object> args) {
+    if(args.ContainsKey("windowRef"))return ObserveReferencePresence(args);
+    int maximum = Convert.ToInt32(args["maxWindows"]);
+    bool invisible = Convert.ToBoolean(args["includeInvisible"]);
+    List<object> windows = new List<object>();
+    bool truncated=false,identityChanged=false,metadataOnly=Option(args,"_metadataOnly",false);
+    EnumWindows(delegate(IntPtr handle,IntPtr parameter) {
+      // Eligibility probes are not retained metadata. Re-read retained fields after binding.
+      if(!invisible && (!IsWindowVisible(handle) || IsIconic(handle)))return true;
+      uint pid;GetWindowThreadProcessId(handle,out pid);
+      if(pid==0 || !IsWindow(handle))return true;
+      if(windows.Count==maximum){truncated=true;return false;}
+      var bindingMetadata=new Dictionary<string,object>();
+      WindowReference binding=metadataOnly?null:ObserveWindowReference(handle,bindingMetadata);
+      bool visible=IsWindowVisible(handle),offscreen=!visible || IsIconic(handle);
+      if(!invisible && offscreen){if(binding!=null && !WindowMarker.Matches(handle,binding.Owner,binding.Marker))identityChanged=true;return true;}
+      Rect bounds;if(!GetWindowRect(handle,out bounds)){if(binding!=null)identityChanged=true;return true;}
+      var title=new StringBuilder(2048);var className=new StringBuilder(256);
+      GetWindowText(handle,title,title.Capacity);GetClassName(handle,className,className.Capacity);
+      UIntPtr ignored;bool answered=SendMessageTimeout(handle,0,UIntPtr.Zero,IntPtr.Zero,3,100,out ignored)!=IntPtr.Zero;
+      int responseError=answered?0:Marshal.GetLastWin32Error();
+      uint ownerAfter;GetWindowThreadProcessId(handle,out ownerAfter);
+      if(!IsWindow(handle) || ownerAfter!=pid || (binding!=null && !WindowMarker.Matches(handle,binding.Owner,binding.Marker))){if(binding!=null)identityChanged=true;return true;}
+      Dictionary<string,object> item=new Dictionary<string,object>{
+        {"depth",1},{"name",title.ToString()},{"className",className.ToString()},
+        {"controlType","Window"},{"processId",pid},{"nativeWindowHandle",handle.ToInt64()},
+        {"boundingBox",new Dictionary<string,object>{{"x",bounds.Left},{"y",bounds.Top},{"width",bounds.Right-bounds.Left},{"height",bounds.Bottom-bounds.Top},{"centerX",(bounds.Left+(double)bounds.Right)/2},{"centerY",(bounds.Top+(double)bounds.Bottom)/2}}},
+        {"isEnabled",IsWindowEnabled(handle)},{"isOffscreen",offscreen},{"hasKeyboardFocus",handle==GetForegroundWindow()},{"source","win32"},
+        {"responsive",responseError==5?(object)null:answered},{"responsiveness",answered?"responsive":responseError==5?"access_denied":"unresponsive_or_unknown"}
+      };
+      if(binding!=null){item["id"]="uia:hwnd:"+handle.ToInt64()+":pid:"+pid;item["windowRef"]=binding.Id;}
+      else if(metadataOnly)item["windowRefUnavailable"]="UNBOUND_METADATA: observe the selected window to obtain a reference";
+      else foreach(var pair in bindingMetadata)item[pair.Key]=pair.Value;
+      RememberPointerOrigin(handle);
+      if(binding!=null && !WindowMarker.Matches(handle,binding.Owner,binding.Marker)){identityChanged=true;return true;}
+      windows.Add(item);return true;
+    },IntPtr.Zero);
+    Dictionary<string, object> result = Result(true, "list_windows");
+    result["windows"] = windows;
+    result["truncated"] = truncated || identityChanged;
+    if(identityChanged){result["conclusive"]=false;result["observationError"]="WINDOW_REFERENCE_LOST: a lifetime changed during enumeration; incomplete observation";}
+    result["source"] = "win32";
+    return result;
+  }
+
+  [MTAThread]
+  static void Main() {
+    Console.InputEncoding = new UTF8Encoding(false);
+    Console.OutputEncoding = new UTF8Encoding(false);
+    try { if (!SetProcessDpiAwarenessContext(new IntPtr(-4))) SetProcessDPIAware(); }
+    catch (EntryPointNotFoundException) { SetProcessDPIAware(); }
+    JavaScriptSerializer json = new JavaScriptSerializer { MaxJsonLength = 32 * 1024 * 1024 };
+    string line;
+    while ((line = Console.ReadLine()) != null) {
+      Dictionary<string, object> request = null;
+      try {
+        request = json.Deserialize<Dictionary<string, object>>(line);
+        if (request.ContainsKey("cancel")) continue;
+        string action = Convert.ToString(request["action"]);
+        currentReference=null;windowDispatchAttempted=false;
+        pointerInputAction=action=="click" || action=="double_click" || action=="move" || action=="drag" || action=="scroll" || action=="type_text" || action=="keypress";
+        pointerOperation=request.ContainsKey("operationId")?Convert.ToString(request["operationId"]):"";
+        object result;
+        try {
+          Dictionary<string, object> args = (Dictionary<string, object>)request["args"];
+          if (action == "type_text" || action == "keypress") result = ExecuteText(action,args);
+          else if (action == "click" || action == "double_click" || action == "move" || action == "drag" || (action == "scroll" && (!args.ContainsKey("elementId") || (args.ContainsKey("_cancelEvent") && !Option(args,"_quietScroll",false))))) result = ExecutePointer(action,args);
+          else if (action == "list_windows") result = ListWindows(args);
+          else if (action == "browser_frame") result = MarkBrowserFrame(args);
+          else if (action == "focus" || action == "invoke" || action == "set_value" || action == "scroll") result = ExecuteControl(action,args);
+          else if (action == "launch_app" || action == "activate_window" || action == "move_window" || action == "close_window") result = ManageNativeWindow(action,args);
+          else if (action == "screenshot") result = CaptureScreenshot(args);
+          else if (action == "snapshot" || action == "accessibility_tree" || action == "find" || action == "element_info") result = ObserveAccessibility(action, args);
+          else throw new InvalidOperationException("UNKNOWN_ACTION");
+        } catch (Exception error) {
+          Dictionary<string, object> failure = Result(false, action);
+          failure["error"] = "WINDOWS_ERROR: " + error.Message;
+          ActivationRefusedException refused=error as ActivationRefusedException;
+          if(refused!=null)failure["activationDiagnostic"]=refused.Diagnostic;
+          result = failure;
+        }
+        var payload=result as Dictionary<string,object>;
+        if(payload!=null)FinishWindowReference(payload);
+        Console.WriteLine(json.Serialize(new Dictionary<string, object> { { "id", request["id"] }, { "result", result } }));
+        Console.Out.Flush();
+      } catch (Exception error) {
+        Console.Error.WriteLine("NATIVE_PROTOCOL_ERROR: " + error.Message);
+      }
+    }
+    CleanupWindowReferences();
+  }
+}

package/dist/accessibility.d.ts

@@ -0,0 +1,29 @@
+import type { WorkerResult } from "./protocol.js";
+type Property = {
+    type: "string" | "integer" | "boolean";
+    default?: unknown;
+    enum?: readonly string[];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+};
+export declare const observationTools: {
+    action: string;
+    parameters: {
+        properties: Record<string, Property>;
+        required?: string[];
+        type: string;
+        additionalProperties: boolean;
+    };
+}[];
+export declare const controlTools: {
+    action: string;
+    parameters: {
+        properties: Record<string, Property>;
+        required?: string[];
+        type: string;
+        additionalProperties: boolean;
+    };
+}[];
+export declare function executeAccessibility(action: string, args: Record<string, unknown>, signal?: AbortSignal, execute?: (normalized: Record<string, unknown>) => Promise<WorkerResult>): Promise<WorkerResult>;
+export {};