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

package/assets/stop.cs

@@ -0,0 +1,197 @@
+using System;
+using System.Collections.Generic;
+using System.Runtime.InteropServices;
+using System.Text;
+using System.Threading;
+using System.Web.Script.Serialization;
+using System.Windows.Forms;
+
+// The hook and overlays own an STA message pump and never enter UIA providers.
+partial class StopBridge {
+  delegate IntPtr KeyboardHook(int code, IntPtr wParam, IntPtr lParam);
+  [DllImport("user32.dll", SetLastError=true)] static extern IntPtr SetWindowsHookEx(int hook, KeyboardHook callback, IntPtr module, uint thread);
+  [DllImport("user32.dll")] static extern bool UnhookWindowsHookEx(IntPtr hook);
+  [DllImport("user32.dll")] static extern IntPtr CallNextHookEx(IntPtr hook, int code, IntPtr wParam, IntPtr lParam);
+  [DllImport("user32.dll")] static extern short GetAsyncKeyState(int key);
+  [DllImport("kernel32.dll", CharSet=CharSet.Unicode)] static extern IntPtr GetModuleHandle(string module);
+  [DllImport("user32.dll")] static extern bool SetProcessDpiAwarenessContext(IntPtr context);
+  [DllImport("user32.dll")] static extern IntPtr OpenInputDesktop(uint flags,bool inherit,uint access);
+  [DllImport("user32.dll")] static extern bool CloseDesktop(IntPtr desktop);
+  [DllImport("user32.dll")] static extern IntPtr GetThreadDesktop(uint thread);
+  [DllImport("kernel32.dll")] static extern uint GetCurrentThreadId();
+  [DllImport("user32.dll",EntryPoint="GetUserObjectInformationW",CharSet=CharSet.Unicode)] static extern bool DesktopInfo(IntPtr desktop,int kind,StringBuilder value,uint bytes,out uint needed);
+  static readonly object gate = new object();
+  static readonly JavaScriptSerializer json = new JavaScriptSerializer();
+  static readonly KeyboardHook callback = OnKey;
+  static readonly KeyboardHook mouseCallback = OnMouse;
+  static IntPtr installed, mouseHook;
+  static string operation;
+  static EventWaitHandle cancelled;
+  static EventWaitHandle exclusive;
+  static readonly HashSet<int> physicalDown = new HashSet<int>(), swallowed = new HashSet<int>();
+  static readonly HashSet<int> mouseDown = new HashSet<int>(), swallowedButtons = new HashSet<int>();
+  static int suppressedKeys, suppressedMouse,suppressedButtons;
+  static bool armed, stopped;
+  static string shortcut = "";
+  static int shortcutKey, shortcutModifiers;
+  static Presentation presentation;
+  static Control dispatcher;
+
+  static void Send(object value) { lock(gate) { Console.WriteLine(json.Serialize(value)); Console.Out.Flush(); } }
+  static void Stop() {
+    if (!armed || stopped) return;
+    stopped = true; cancelled.Set(); ReleaseControl();
+    string stoppedOperation=operation;
+    dispatcher.BeginInvoke((Action)delegate {
+      if(operation==stoppedOperation && stopped)presentation.Stop();Send(new Dictionary<string,object> {{"event","stopped"},{"operationId",stoppedOperation}});
+    });
+  }
+  static int Modifiers() {
+    return (physicalDown.Contains(0x11)||physicalDown.Contains(0xA2)||physicalDown.Contains(0xA3) ? 1 : 0) |
+      (physicalDown.Contains(0x12)||physicalDown.Contains(0xA4)||physicalDown.Contains(0xA5) ? 2 : 0) |
+      (physicalDown.Contains(0x10)||physicalDown.Contains(0xA0)||physicalDown.Contains(0xA1) ? 4 : 0) |
+      (physicalDown.Contains(0x5B)||physicalDown.Contains(0x5C) ? 8 : 0);
+  }
+  static IntPtr OnKey(int code, IntPtr wParam, IntPtr lParam) {
+    if (code >= 0) {
+      int flags=Marshal.ReadInt32(lParam,8), key=Marshal.ReadInt32(lParam);
+      // Agent-injected Escape dismisses UI; it must not stop its own operation.
+      if ((flags & 0x12)==0) {
+        bool down=wParam.ToInt64()==0x100 || wParam.ToInt64()==0x104;
+        if(down)physicalDown.Add(key);else physicalDown.Remove(key);
+        bool consume=(exclusive!=null && exclusive.WaitOne(0)) || swallowed.Contains(key);
+        if(down && armed && !stopped && (key==0x1B || (shortcutKey!=0 && key==shortcutKey && Modifiers()==shortcutModifiers))) {consume=true;Stop();}
+        if(down && consume)swallowed.Add(key);
+        if(!down && swallowed.Remove(key))consume=true;
+        if(consume){suppressedKeys++;return new IntPtr(1);}
+      }
+    }
+    return CallNextHookEx(installed,code,wParam,lParam);
+  }
+  static IntPtr OnMouse(int code,IntPtr message,IntPtr data) {
+    if(code>=0 && (Marshal.ReadInt32(data,12)&3)==0) {
+      int kind=message.ToInt32(),button=0;
+      bool down=kind==0x201 || kind==0x204 || kind==0x207 || kind==0x20B;
+      bool up=kind==0x202 || kind==0x205 || kind==0x208 || kind==0x20C;
+      if(kind==0x201 || kind==0x202)button=1;
+      else if(kind==0x204 || kind==0x205)button=2;
+      else if(kind==0x207 || kind==0x208)button=4;
+      else if(down || up)button=(Marshal.ReadInt32(data,8)>>16)==1?5:6;
+      if(down)mouseDown.Add(button);if(up)mouseDown.Remove(button);
+      bool consume=(exclusive!=null && exclusive.WaitOne(0)) || (button!=0 && swallowedButtons.Contains(button));
+      if(down && consume)swallowedButtons.Add(button);if(up)swallowedButtons.Remove(button);
+      if(consume){suppressedMouse++;if(down)suppressedButtons++;return new IntPtr(1);}
+    }
+    return CallNextHookEx(mouseHook,code,message,data);
+  }
+  static void ReleaseControl() {
+    if(exclusive!=null)exclusive.Reset();
+  }
+  static void TakeControl() {
+    if(!armed || stopped || exclusive==null)throw new InvalidOperationException("STOP_OPERATION_NOT_ARMED");
+    if(exclusive.WaitOne(0))return;
+    if(!InteractiveDesktop())throw new InvalidOperationException("DESKTOP_SESSION_UNAVAILABLE: unlock the interactive desktop");
+    if(physicalDown.Count>0 || mouseDown.Count>0)throw new InvalidOperationException("USER_INPUT_ACTIVE: release physical input before control begins");
+    for(int key=1;key<255;key++)if(GetAsyncKeyState(key)<0)throw new InvalidOperationException("USER_INPUT_ACTIVE: release held input before control begins");
+    if(mouseHook==IntPtr.Zero)mouseHook=SetWindowsHookEx(14,mouseCallback,GetModuleHandle(null),0);
+    if(mouseHook==IntPtr.Zero)throw new InvalidOperationException("EXCLUSIVE_CONTROL_UNAVAILABLE: mouse hook failed");
+    try {
+      presentation.Begin();if(stopped || cancelled.WaitOne(0))throw new InvalidOperationException("COMPUTER_USE_STOPPED");exclusive.Set();
+    } catch {ReleaseControl();presentation.Stop();throw;}
+  }
+  static bool InteractiveDesktop() {
+    IntPtr input=OpenInputDesktop(0,false,1);if(input==IntPtr.Zero)return false;
+    try {
+      StringBuilder current=new StringBuilder(256),own=new StringBuilder(256);uint needed;
+      return DesktopInfo(input,2,current,512,out needed) && DesktopInfo(GetThreadDesktop(GetCurrentThreadId()),2,own,512,out needed) && current.ToString()==own.ToString();
+    }finally {CloseDesktop(input);}
+  }
+  static void ConfigureShortcut(string value) {
+    shortcut=value; shortcutKey=0; shortcutModifiers=0;
+    if (String.IsNullOrEmpty(value)) return;
+    string[] parts=value.Split('+');
+    for(int i=0;i<parts.Length-1;i++) {
+      if(parts[i]=="Ctrl")shortcutModifiers|=1;else if(parts[i]=="Alt")shortcutModifiers|=2;
+      else if(parts[i]=="Shift")shortcutModifiers|=4;else if(parts[i]=="Win")shortcutModifiers|=8;
+      else throw new InvalidOperationException("INVALID_STOP_SHORTCUT");
+    }
+    string key=parts[parts.Length-1];
+    if(key.Length==1 && ((key[0]>='A' && key[0]<='Z') || (key[0]>='0' && key[0]<='9')))shortcutKey=key[0];
+    else if(key.StartsWith("F",StringComparison.Ordinal) && key.Length<=3) {
+      int number;if(Int32.TryParse(key.Substring(1),out number) && number>=1 && number<=24)shortcutKey=0x6F+number;
+    } else {
+      Dictionary<string,int> keys=new Dictionary<string,int> {{"Space",32},{"Enter",13},{"Tab",9},{"Backspace",8},{"Delete",46},{"Insert",45},{"Home",36},{"End",35},{"PageUp",33},{"PageDown",34},{"Up",38},{"Down",40},{"Left",37},{"Right",39},{"Pause",19},{"CapsLock",20},{"NumLock",144},{"ScrollLock",145}};
+      keys.TryGetValue(key,out shortcutKey);
+    }
+    if(shortcutKey==0)throw new InvalidOperationException("INVALID_STOP_SHORTCUT");
+  }
+  static void Configure(Dictionary<string,object> values) {
+    object value;
+    ConfigureShortcut(values.TryGetValue("stopShortcut",out value) ? Convert.ToString(value) : "");
+    presentation.Configure(values);
+  }
+  static Dictionary<string,object> Status(string action) {
+    return new Dictionary<string,object> {
+      {"ok",true},{"action",action},{"listenerProcessId",System.Diagnostics.Process.GetCurrentProcess().Id},
+      {"hookInstalled",installed!=IntPtr.Zero},{"armed",armed},{"stopped",stopped},{"operationId",operation},
+      {"exclusiveControl",exclusive!=null && exclusive.WaitOne(0)},{"suppressedKeys",suppressedKeys},{"suppressedMouse",suppressedMouse},
+      {"suppressedButtons",suppressedButtons},
+      {"physicalKeysHeld",physicalDown.Count},{"physicalButtonsHeld",mouseDown.Count},
+      {"cancelEventSet",cancelled!=null && cancelled.WaitOne(0)}, {"stopShortcut",shortcut},
+      {"shortcutVirtualKey",shortcutKey},{"shortcutModifiers",shortcutModifiers},{"escAlwaysEnabled",true},
+      {"injectedKeysIgnored",true},{"presentation",presentation.Status()}
+    };
+  }
+  static void Handle(Dictionary<string,object> request) {
+    string action=request.ContainsKey("action") ? Convert.ToString(request["action"]) : "invalid_request";
+    try {
+      Dictionary<string,object> args=(Dictionary<string,object>)request["args"];
+      string wanted=args.ContainsKey("operationId") ? Convert.ToString(args["operationId"]) : "";
+      if(action=="configure")Configure((Dictionary<string,object>)args["settings"]);
+      else if(action=="arm") {
+        if(String.IsNullOrWhiteSpace(wanted))throw new InvalidOperationException("INVALID_OPERATION");
+        ReleaseControl();if(exclusive!=null)exclusive.Dispose();if(cancelled!=null)cancelled.Dispose();
+        presentation.Stop(); operation=wanted; armed=true; stopped=false;
+        cancelled=new EventWaitHandle(false,EventResetMode.ManualReset,Convert.ToString(args["cancelEvent"]));
+        exclusive=new EventWaitHandle(false,EventResetMode.ManualReset,Convert.ToString(args["cancelEvent"])+"-exclusive");
+        suppressedKeys=0;suppressedMouse=0;suppressedButtons=0;
+      } else if(action=="stop") { if(wanted==operation)Stop(); }
+      else if(action=="take_control") {if(wanted!=operation)throw new InvalidOperationException("STOP_OPERATION_NOT_ARMED");TakeControl();}
+      else if(action=="disarm") { if(wanted==operation) { ReleaseControl();armed=false; presentation.Stop(); } }
+      else if(action=="capture") presentation.Suspend(Convert.ToBoolean(args["suspended"]));
+      else if(action=="preview") presentation.Preview(args.ContainsKey("show") ? Convert.ToBoolean(args["show"]) : true);
+      else if(action!="status")throw new InvalidOperationException("UNKNOWN_ACTION");
+      Send(new Dictionary<string,object> {{"id",request["id"]},{"result",Status(action)}});
+    } catch(Exception error) {
+      Send(new Dictionary<string,object> {{"id",request["id"]},{"result",new Dictionary<string,object> {{"ok",false},{"action",action},{"error",error.Message}}}});
+    }
+  }
+  [STAThread]
+  static void Main() {
+    Console.InputEncoding=new UTF8Encoding(false);Console.OutputEncoding=new UTF8Encoding(false);
+    try { SetProcessDpiAwarenessContext(new IntPtr(-4)); } catch(EntryPointNotFoundException) { }
+    Application.EnableVisualStyles();
+    dispatcher=new Control();IntPtr dispatcherHandle=dispatcher.Handle;
+    presentation=new Presentation();
+    var health=new System.Windows.Forms.Timer {Interval=100};
+    health.Tick+=delegate {if(exclusive!=null && exclusive.WaitOne(0) && (!InteractiveDesktop() || !presentation.BorderReady))Stop();};health.Start();
+    installed=SetWindowsHookEx(13,callback,GetModuleHandle(null),0);
+    if(installed==IntPtr.Zero)throw new InvalidOperationException("STOP_LISTENER_UNAVAILABLE: keyboard hook failed: "+Marshal.GetLastWin32Error());
+    Thread reader=new Thread(delegate() {
+      JavaScriptSerializer readerJson=new JavaScriptSerializer();
+      string line;
+      while((line=Console.ReadLine())!=null) {
+        try {
+          Dictionary<string,object> request=readerJson.Deserialize<Dictionary<string,object>>(line);
+          if(request.ContainsKey("cancel"))continue;
+          Dictionary<string,object> captured=request;
+          dispatcher.BeginInvoke((Action)delegate { Handle(captured); });
+        } catch(Exception error) { Console.Error.WriteLine("STOP_PROTOCOL_ERROR: "+error.Message); }
+      }
+      dispatcher.BeginInvoke((Action)delegate { Application.ExitThread(); });
+    });
+    reader.IsBackground=true;reader.Start();
+    try { Application.Run(); }
+    finally { health.Dispose();if(cancelled!=null)cancelled.Set();ReleaseControl();if(mouseHook!=IntPtr.Zero)UnhookWindowsHookEx(mouseHook);UnhookWindowsHookEx(installed);presentation.Dispose();if(exclusive!=null)exclusive.Dispose();if(cancelled!=null)cancelled.Dispose();dispatcher.Dispose(); }
+  }
+}

package/assets/text.cs

@@ -0,0 +1,279 @@
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Runtime.InteropServices;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using System.Web.Script.Serialization;
+using System.Windows.Automation;
+
+partial class WindowsBridge {
+  [StructLayout(LayoutKind.Sequential)] struct KeyboardInput {public ushort Key,Scan;public uint Flags,Time;public UIntPtr Extra;}
+  const int UnicodeInputDelayMs=50;
+  static bool textInputDispatched;
+  sealed class HeldKey {public ushort Key,Scan;public uint Flags;}
+  [DllImport("user32.dll")] static extern IntPtr GetKeyboardLayout(uint thread);
+  [DllImport("user32.dll",CharSet=CharSet.Unicode)] static extern short VkKeyScanEx(char value,IntPtr layout);
+  [DllImport("user32.dll",EntryPoint="SendMessageTimeoutW",CharSet=CharSet.Unicode,SetLastError=true)] static extern IntPtr ReadEditText(IntPtr window,uint message,UIntPtr count,StringBuilder text,uint flags,uint timeout,out UIntPtr result);
+  [StructLayout(LayoutKind.Sequential)] struct LastTextInput {public uint Size,Tick;}
+  [DllImport("user32.dll")] static extern bool GetLastInputInfo(ref LastTextInput info);
+  sealed class KnownTextFocus {public IntPtr Handle;public uint InputTick;}
+  static uint LastTextTick() {LastTextInput info=new LastTextInput{Size=(uint)Marshal.SizeOf(typeof(LastTextInput))};if(!GetLastInputInfo(ref info))throw new InvalidOperationException("TARGET_FOCUS_UNKNOWN: cannot verify user input history");return info.Tick;}
+  static readonly Dictionary<string,KnownTextFocus> textFocus=new Dictionary<string,KnownTextFocus>();
+  static void ForgetTextFocus() {textFocus.Clear();}
+  static void RememberTextFocus(IntPtr window,IntPtr focus) {if(focus!=IntPtr.Zero && IsWindow(focus) && GetAncestor(focus,2)==window && WindowOwner(focus)==WindowOwner(window)){textFocus.Clear();textFocus[PointerOriginKey(window)]=new KnownTextFocus {Handle=focus,InputTick=LastTextTick()};}}
+  static IntPtr TextFocus(IntPtr window,bool allowRemembered=true) {
+    uint owner;uint thread=GetWindowThreadProcessId(window,out owner);ControlGuiInfo info=new ControlGuiInfo{Size=(uint)Marshal.SizeOf(typeof(ControlGuiInfo))};
+    if(GetGUIThreadInfo(thread,ref info) && info.Focus!=IntPtr.Zero && GetAncestor(info.Focus,2)==window && WindowOwner(info.Focus)==owner){KnownTextFocus known;if(textFocus.TryGetValue(PointerOriginKey(window),out known) && known.Handle!=info.Focus)textFocus.Remove(PointerOriginKey(window));return info.Focus;}
+    KnownTextFocus remembered;
+    if(allowRemembered && textFocus.TryGetValue(PointerOriginKey(window),out remembered)) {
+      if(remembered.InputTick!=LastTextTick()){textFocus.Remove(PointerOriginKey(window));throw new InvalidOperationException("TARGET_FOCUS_CHANGED: user input invalidated remembered focus; focus the intended control again");}
+      if(IsWindow(remembered.Handle) && GetAncestor(remembered.Handle,2)==window && WindowOwner(remembered.Handle)==owner)return remembered.Handle;
+      textFocus.Remove(PointerOriginKey(window));throw new InvalidOperationException("TARGET_FOCUS_CHANGED: remembered native control is stale");
+    }
+    return IntPtr.Zero;
+  }
+  static bool IsNativeText(IntPtr focus) {
+    if(focus==IntPtr.Zero)return false;StringBuilder name=new StringBuilder(256);GetClassName(focus,name,name.Capacity);string value=name.ToString();
+    return value.Equals("Edit",StringComparison.OrdinalIgnoreCase) || value.StartsWith("WindowsForms10.EDIT",StringComparison.OrdinalIgnoreCase) || value.StartsWith("RichEdit",StringComparison.OrdinalIgnoreCase);
+  }
+  static string NativeTextValue(IntPtr focus) {
+    if((ControlStyle(focus,-16).ToInt64() & 0x20)!=0)return null;
+    StringBuilder text=new StringBuilder(201);UIntPtr ignored;
+    return ReadEditText(focus,0xD,new UIntPtr(201),text,2,200,out ignored)==IntPtr.Zero?null:text.ToString();
+  }
+  static void AssertWritableText(IntPtr focus) {
+    if(focus!=IntPtr.Zero && (!IsWindowEnabled(focus) || (IsNativeText(focus) && (ControlStyle(focus,-16).ToInt64() & 0x800)!=0)))throw new InvalidOperationException("READ_ONLY: focused control is disabled or read-only");
+  }
+  static bool BackgroundEdit(IntPtr window,string text,Dictionary<string,object> result) {
+    if(text.IndexOf('\r')>=0 || text.IndexOf('\n')>=0)return false;
+    IntPtr focus=TextFocus(window);if(!IsNativeText(focus))return false;AssertWritableText(focus);
+    UIntPtr before,after,ignored;
+    if(SendMessageTimeout(focus,0xE,UIntPtr.Zero,IntPtr.Zero,2,500,out before)==IntPtr.Zero)throw new InvalidOperationException("BACKGROUND_READ_UNCONFIRMED: no text sent");
+    CheckWindowReference(window);
+    BeginWindowDispatch();
+    // Never retry a refused/uncertain EM_REPLACESEL through physical input.
+    if(ControlText(focus,0xC2,new UIntPtr(1),text,2,1000,out ignored)==IntPtr.Zero)throw new InvalidOperationException("TEXT_DISPATCH_UNCONFIRMED: edit may have received partial text; observe before retrying");
+    string value=NativeTextValue(focus);bool lengthKnown=SendMessageTimeout(focus,0xE,UIntPtr.Zero,IntPtr.Zero,2,500,out after)!=IntPtr.Zero;
+    RememberTextFocus(window,focus);
+    result["method"]="background:EM_REPLACESEL";result["verification"]="sent";
+    result["verified"]=lengthKnown && ((long)after.ToUInt64()-(long)before.ToUInt64()==text.Length || (value!=null && value.Contains(text)));
+    if(value!=null)result["verifyValue"]=value;
+    return true;
+  }
+  static AutomationElement MainTextControl(IntPtr window) {
+    AutomationElement root=AutomationElement.FromHandle(window),best=null;double area=-1;
+    Condition controls=new OrCondition(new PropertyCondition(AutomationElement.ControlTypeProperty,ControlType.Edit),new PropertyCondition(AutomationElement.ControlTypeProperty,ControlType.Document));
+    AutomationElementCollection candidates=root.FindAll(TreeScope.Descendants,controls);
+    for(int i=0;i<candidates.Count;i++) {
+      AutomationElement candidate=candidates[i];var current=candidate.Current;if(!current.IsEnabled || !current.IsKeyboardFocusable || current.IsOffscreen || current.ProcessId!=(int)WindowOwner(window))continue;
+      object raw;if(candidate.TryGetCurrentPattern(ValuePattern.Pattern,out raw) && ((ValuePattern)raw).Current.IsReadOnly)continue;
+      double size=current.BoundingRectangle.Width*current.BoundingRectangle.Height;if(size>area){area=size;best=candidate;}
+    }
+    if(best==null)throw new InvalidOperationException("TEXT_FOCUS_NOT_FOUND: no writable main text control");return best;
+  }
+  static void TextCheck(EventWaitHandle cancel,Process listener,IntPtr window,uint owner,IntPtr expectedFocus,bool checkFocus,InteractionGuard interaction,bool requireForeground=true) {
+    CheckWindowReference(window);
+    if(cancel.WaitOne(0))throw new InvalidOperationException("COMPUTER_USE_STOPPED");
+    interaction.Check();
+    if(listener.HasExited)throw new InvalidOperationException("STOP_LISTENER_UNAVAILABLE");
+    if(!IsWindow(window) || WindowOwner(window)!=owner || !IsWindowEnabled(window) || !IsWindowVisible(window) || IsIconic(window))throw new InvalidOperationException("TARGET_IDENTITY_CHANGED");
+    if(requireForeground && GetForegroundWindow()!=window)throw new InvalidOperationException("TARGET_FOREGROUND_CHANGED: no more text sent");
+    if(checkFocus)foreach(int key in new int[]{1,2,4,16,17,18,91,92})if(GetAsyncKeyState(key)<0)throw new InvalidOperationException("USER_INPUT_ACTIVE: user button or modifier changed during typing");
+    if(checkFocus && TextFocus(window,false)!=expectedFocus)throw new InvalidOperationException("TARGET_FOCUS_CHANGED: no more text sent");
+  }
+  // SetFocus may return before the target thread applies it. Observe the exact
+  // requested field before input; never resend focus or type into the old field.
+  static IntPtr ConfirmTextFocus(AutomationElement requested,EventWaitHandle cancel,Process listener,IntPtr window,uint owner,InteractionGuard interaction) {
+    IntPtr requestedHandle=new IntPtr(requested.Current.NativeWindowHandle);
+    Stopwatch watch=Stopwatch.StartNew();
+    do {
+      TextCheck(cancel,listener,window,owner,IntPtr.Zero,false,interaction,false);
+      IntPtr focus=TextFocus(window,false);
+      if(GetForegroundWindow()==window && focus!=IntPtr.Zero && (requestedHandle!=IntPtr.Zero?focus==requestedHandle:requested.Current.HasKeyboardFocus))return focus;
+      if(cancel.WaitOne(10))throw new InvalidOperationException("COMPUTER_USE_STOPPED");
+    }while(watch.ElapsedMilliseconds<1000);
+    throw new InvalidOperationException("TARGET_FOCUS_CHANGED: requested text field focus was not confirmed; no text sent");
+  }
+  static void KeyEvent(HeldKey key,bool release) {
+    if(!release){BeginWindowDispatch();NotifyPhysicalInput(true);}
+    PointerInput input=new PointerInput{Type=1,Data=new InputUnion{Keyboard=new KeyboardInput{Key=key.Key,Scan=key.Scan,Flags=key.Flags | (release?2U:0U),Extra=OwnedInputMarker}}};
+    if(SendInput(1,new PointerInput[]{input},Marshal.SizeOf(typeof(PointerInput)))!=1)throw new InvalidOperationException("KEY_DISPATCH_UNCONFIRMED: partial input must not be replayed");
+    if(!release)textInputDispatched=true;
+  }
+  static void Down(List<HeldKey> held,HeldKey key) {held.Add(key);KeyEvent(key,false);}
+  static void Up(List<HeldKey> held,HeldKey key) {KeyEvent(key,true);held.Remove(key);}
+  static ushort SpecialKey(string key) {
+    switch(key){case "enter":case "return":return 13;case "tab":return 9;case "esc":case "escape":return 27;case "backspace":return 8;case "delete":case "del":return 46;case "home":return 36;case "end":return 35;case "pageup":case "pgup":return 33;case "pagedown":case "pgdn":return 34;case "up":return 38;case "down":return 40;case "left":return 37;case "right":return 39;case "space":return 32;case "insert":case "ins":return 45;case "pause":return 19;case "capslock":return 20;case "numlock":return 144;case "scrolllock":return 145;}
+    int number;if(key.StartsWith("f") && Int32.TryParse(key.Substring(1),out number) && number>=1 && number<=24)return (ushort)(111+number);return 0;
+  }
+  static void Chord(IEnumerable values,EventWaitHandle cancel,Process listener,IntPtr window,uint owner,List<HeldKey> held,InteractionGuard interaction,long holdMs=0,InputTiming timing=null) {
+    Action holdCheck=delegate {
+      TextCheck(cancel,listener,window,owner,IntPtr.Zero,false,interaction);
+    };
+    if(timing!=null)timing.Check();
+    List<ushort> modifiers=new List<ushort>();string main=null;
+    foreach(object item in values) {string key=Convert.ToString(item),name=key.Trim().ToLowerInvariant();if(name=="ctrl" || name=="control")modifiers.Add(17);else if(name=="alt" || name=="option")modifiers.Add(18);else if(name=="shift")modifiers.Add(16);else if(name=="win" || name=="windows" || name=="cmd" || name=="meta")throw new InvalidOperationException("KEY_BLOCKED");else if(main!=null)throw new InvalidOperationException("INVALID_ARGUMENTS: exactly one non-modifier key required");else main=key;}
+    if(main==null && modifiers.Count!=1)throw new InvalidOperationException("INVALID_ARGUMENTS: one main key or standalone modifier required");
+    ushort code=main==null?(ushort)0:SpecialKey(main.Trim().ToLowerInvariant());
+    if(main!=null && code==0) {
+      if(main.Length!=1)throw new InvalidOperationException("INVALID_ARGUMENTS: unsupported key");
+      uint ignored;uint thread=GetWindowThreadProcessId(window,out ignored);short mapping=VkKeyScanEx(main[0],GetKeyboardLayout(thread));
+      if(mapping==-1) {if(modifiers.Count>0)throw new InvalidOperationException("KEY_LAYOUT_UNSUPPORTED: chord cannot represent this character");TextCheck(cancel,listener,window,owner,IntPtr.Zero,false,interaction);HeldKey unicode=new HeldKey{Scan=main[0],Flags=4};Down(held,unicode);if(timing!=null && holdMs>0)timing.Wait(holdMs,cancel,holdCheck);Up(held,unicode);return;}
+      code=(ushort)(mapping & 255);
+      // A named shortcut letter is layout-mapped without adding implicit Shift.
+      if(modifiers.Count==0){if((mapping & 0x100)!=0)modifiers.Add(16);if((mapping & 0x200)!=0)modifiers.Add(17);if((mapping & 0x400)!=0)modifiers.Add(18);}
+    }
+    foreach(ushort modifier in modifiers){TextCheck(cancel,listener,window,owner,IntPtr.Zero,false,interaction);Down(held,new HeldKey{Key=modifier});}
+    TextCheck(cancel,listener,window,owner,IntPtr.Zero,false,interaction);
+    if(main!=null){HeldKey primary=new HeldKey{Key=code,Flags=(code>=33 && code<=46)?1U:0U};Down(held,primary);}
+    if(timing!=null && holdMs>0)timing.Wait(holdMs,cancel,holdCheck);
+    // Immediate presses release without post-dispatch checks: their effect may move focus.
+    // Positive holds retain the existing keypress target/protection checks during the wait.
+    // Release modifiers regardless of target/focus changes caused by the chord.
+    for(int i=held.Count-1;i>=0;i--){HeldKey key=held[i];Up(held,key);}
+  }
+  static Task<string> clipboardRead;
+  static Dictionary<string,object> ClipboardReply(Process child,int milliseconds) {
+    if(clipboardRead==null)clipboardRead=Task.Factory.StartNew(()=>child.StandardOutput.ReadLine());
+    if(!clipboardRead.Wait(milliseconds))throw new InvalidOperationException("CLIPBOARD_HELPER_TIMEOUT");
+    string line=clipboardRead.Result;clipboardRead=null;
+    if(line==null)throw new InvalidOperationException("CLIPBOARD_HELPER_EXITED");
+    return new JavaScriptSerializer().Deserialize<Dictionary<string,object>>(line);
+  }
+  static Dictionary<string,object> ClipboardPhase(Process child,string expected,int milliseconds) {
+    Dictionary<string,object> reply=ClipboardReply(child,milliseconds);
+    if(!Convert.ToBoolean(reply["ok"]) || Convert.ToString(reply["phase"])!=expected)throw new InvalidOperationException(Convert.ToString(reply["error"])??"CLIPBOARD_PHASE_FAILED");
+    return reply;
+  }
+  static Dictionary<string,object> ConfirmClipboardRestore(Process child) {
+    Stopwatch watch=Stopwatch.StartNew();
+    for(int i=0;i<4 && watch.ElapsedMilliseconds<2500;i++) {
+      var reply=ClipboardReply(child,Math.Max(1,2500-(int)watch.ElapsedMilliseconds));
+      if(Convert.ToString(reply["phase"])=="restored" && Convert.ToBoolean(reply["ok"]))return reply;
+    }
+    throw new InvalidOperationException("CLIPBOARD_RESTORE_UNCONFIRMED");
+  }
+  static object ExecuteText(string action,Dictionary<string,object> args) {
+    Dictionary<string,object> result=Result(true,action);result["cleanupConfirmed"]=true;textInputDispatched=false;
+    IntPtr before=IntPtr.Zero,window=IntPtr.Zero;ControlPoint pointer=new ControlPoint();
+    List<HeldKey> held=new List<HeldKey>();HashSet<long> popups=new HashSet<long>();
+    EventWaitHandle cancel=null;Process listener=null,clipboard=null;bool clipboardMayChange=false,clipboardReplaced=false;
+    InteractionGuard interaction=null;
+    AutomationElement main=null;bool cleanup=true;
+    try {
+      long holdMs=0,inputDelayMs=UnicodeInputDelayMs;InputTiming timing=null;
+      string text=TextOption(args,"text",""),method=TextOption(args,"method","auto");
+      if(text.IndexOf('\0')>=0)throw new InvalidOperationException("INVALID_ARGUMENTS: NUL text cannot be entered safely");
+      if(action=="type_text") {
+        inputDelayMs=InputTiming.Milliseconds(args,"inputDelayMs",UnicodeInputDelayMs);
+        if((args.ContainsKey("inputDelayMs") || args.ContainsKey("timeoutMs")) && (method!="sendinput" || args.ContainsKey("browserTab")))throw new InvalidOperationException("TIMING_UNSUPPORTED: text timing requires explicit native sendinput");
+        if(method=="sendinput") {
+          long units=text.Replace("\r\n","\n").Length;
+          if(inputDelayMs!=0 && units>9007199254740991L/inputDelayMs)throw new InvalidOperationException("INVALID_ARGUMENTS: requested pacing duration is not representable");
+          long duration=args.ContainsKey("inputDelayMs")?units*inputDelayMs:0;
+          timing=new InputTiming(args,duration,args.ContainsKey("inputDelayMs"),40000);
+          var policy=timing.Describe();policy["inputDelayMs"]=inputDelayMs;result["timing"]=policy;
+          result["inputDelayMs"]=inputDelayMs;result["inputUnitsDispatched"]=0;
+        }
+      }
+      if(action=="keypress") {
+        holdMs=InputTiming.Milliseconds(args,"holdMs",0);
+        timing=new InputTiming(args,holdMs,args.ContainsKey("holdMs"),40000);
+        var policy=timing.Describe();policy["holdMs"]=holdMs;result["timing"]=policy;
+        if((args.ContainsKey("holdMs") || args.ContainsKey("timeoutMs")) && TextOption(args,"dispatch","foreground")=="background")throw new InvalidOperationException("TIMING_UNSUPPORTED: keypress timing requires native foreground dispatch");
+      }
+      interaction=new InteractionGuard(TextOption(args,"_cancelEvent",""),NumberOption(args,"_stopProcessId",0));before=GetForegroundWindow();GetCursorPos(out pointer);
+      Dictionary<string,object> quiet=new Dictionary<string,object>(args);quiet["activate"]=false;
+      if(args.ContainsKey("_elementId")) {
+        main=ResolveObservedElement(TextOption(args,"_elementId",""),quiet,out window);
+        if(!main.Current.IsEnabled)throw new InvalidOperationException("ELEMENT_DISABLED");
+        object raw;if(main.TryGetCurrentPattern(ValuePattern.Pattern,out raw) && ((ValuePattern)raw).Current.IsReadOnly)throw new InvalidOperationException("READ_ONLY: fallback cannot bypass a read-only value");
+      } else window=ResolveObservationWindow(quiet);
+      ApplyVisibleIntent(args,window);
+      if(textFocus.Count>0 && !textFocus.ContainsKey(PointerOriginKey(window)))ForgetTextFocus();
+      uint owner=WindowOwner(window);popups=ControlPopups(owner,window);
+      if(action=="type_text" && method=="auto" && TextOption(args,"focusMode","preserve")=="preserve" && !Option(args,"activate",false) && BackgroundEdit(window,text,result)) {textInputDispatched=true;result["inputTargetHandle"]=window.ToInt64();result["inputTargetProcessId"]=owner;return result;}
+      bool background=action=="type_text"?method=="background":TextOption(args,"dispatch","foreground")=="background";
+      if(background) {
+        if(!args.ContainsKey("windowRef") && !args.ContainsKey("windowTitle") && !args.ContainsKey("processId") && !args.ContainsKey("nativeWindowHandle"))throw new InvalidOperationException("BACKGROUND_TARGET_REQUIRED");
+        string characters=action=="type_text"?text:Convert.ToString(((IList)args["keys"])[0]);
+        IntPtr recipient=TextFocus(window);if(recipient==IntPtr.Zero)recipient=window;AssertWritableText(recipient);
+        foreach(char character in characters) {CheckWindowReference(window);if(!IsWindow(window) || WindowOwner(window)!=owner || WindowOwner(recipient)!=owner)throw new InvalidOperationException("TARGET_IDENTITY_CHANGED");BeginWindowDispatch();if(!ControlPost(recipient,0x102,new IntPtr(character),new IntPtr(1)))throw new InvalidOperationException("TEXT_DISPATCH_UNCONFIRMED: some WM_CHAR messages may have been delivered; never replay");textInputDispatched=true;}
+        result["method"]="postmessage-wmchar";result["verification"]="unconfirmed";result["verified"]=false;result["inputTargetHandle"]=window.ToInt64();result["inputTargetProcessId"]=owner;return result;
+      }
+      if(TextOption(args,"_cancelEvent","").Length==0)throw new InvalidOperationException("WCU_NEEDS_INPUT: physical text/key input requires independent stopping");
+      cancel=EventWaitHandle.OpenExisting(Convert.ToString(args["_cancelEvent"]));listener=Process.GetProcessById(NumberOption(args,"_stopProcessId",0));IntPtr listenerHandle=listener.Handle;
+      if(cancel.WaitOne(0) || listener.HasExited)throw new InvalidOperationException("COMPUTER_USE_STOPPED");
+      ManagementEnsureUnlockedSession();
+      foreach(int key in new int[]{1,2,4,16,17,18,91,92})if(GetAsyncKeyState(key)<0)throw new InvalidOperationException("USER_INPUT_ACTIVE: button or modifier already held");
+      interaction.Check();
+      if(GetForegroundWindow()!=window) {
+        Dictionary<string,object> activation=new Dictionary<string,object>();
+        if(!ManagementActivate(window,owner,activation) || GetForegroundWindow()!=window){activation["foregroundAtRefusal"]=ManagementForegroundRelationship(GetForegroundWindow(),window,owner);result["activationDiagnostic"]=activation;throw new InvalidOperationException("TARGET_ACTIVATION_REFUSED");}
+      }
+      if(args.ContainsKey("_elementId")){CheckWindowReference(window);BeginWindowDispatch();main.SetFocus();}
+      else if(action=="type_text" && TextOption(args,"focusMode","preserve")=="main") {main=MainTextControl(window);CheckWindowReference(window);BeginWindowDispatch();main.SetFocus();result["focusedControl"]=main.Current.ControlType.ProgrammaticName;}
+      if(action=="type_text" && main==null && TextFocus(window,false)==IntPtr.Zero) {IntPtr remembered=TextFocus(window);if(remembered!=IntPtr.Zero){CheckWindowReference(window);BeginWindowDispatch();main=AutomationElement.FromHandle(remembered);main.SetFocus();}}
+      IntPtr expectedFocus=main!=null?ConfirmTextFocus(main,cancel,listener,window,owner,interaction):TextFocus(window,false);if(main!=null){result["focusConfirmed"]=true;result["inputFocusHandle"]=expectedFocus.ToInt64();}if(action=="type_text")AssertWritableText(expectedFocus);
+      TextCheck(cancel,listener,window,owner,expectedFocus,action=="type_text",interaction);
+      if(action=="type_text")RememberTextFocus(window,expectedFocus);
+      if(action=="keypress") {Chord((IEnumerable)args["keys"],cancel,listener,window,owner,held,interaction,holdMs,timing);result["method"]="sendinput-keychord";}
+      else if(method=="sendinput") {
+        // Preserve complete UTF-16 pairs and newline/tab handling at the selected pace.
+        // Dispatch is still not application verification.
+        for(int index=0;index<text.Length;index++) {
+          char character=text[index];
+          if(character=='\r' && index+1<text.Length && text[index+1]=='\n')index++;
+          timing.Check();TextCheck(cancel,listener,window,owner,expectedFocus,true,interaction);
+          HeldKey key=character=='\r' || character=='\n'?new HeldKey{Key=13}:character=='\t'?new HeldKey{Key=9}:new HeldKey{Scan=character,Flags=4};
+          Down(held,key);Up(held,key);
+          result["inputUnitsDispatched"]=Convert.ToInt32(result["inputUnitsDispatched"])+1;
+          timing.Wait(inputDelayMs,cancel,delegate {TextCheck(cancel,listener,window,owner,expectedFocus,true,interaction);});
+        }
+        result["method"]="sendinput-unicode";
+      }else {
+        // All UIA focus/provider calls finish BEFORE clipboard replacement.
+        ProcessStartInfo info=new ProcessStartInfo{FileName=TextOption(args,"_clipboardExecutable",""),UseShellExecute=false,CreateNoWindow=true,RedirectStandardInput=true,RedirectStandardOutput=true,RedirectStandardError=true,StandardOutputEncoding=Encoding.UTF8,StandardErrorEncoding=Encoding.UTF8};
+        clipboardRead=null;clipboard=Process.Start(info);clipboard.ErrorDataReceived+=delegate(object sender,DataReceivedEventArgs e){};clipboard.BeginErrorReadLine();
+        clipboard.StandardInput.WriteLine(new JavaScriptSerializer().Serialize(new Dictionary<string,object>{{"text",text},{"cancelEvent",args["_cancelEvent"]},{"parentProcessId",Process.GetCurrentProcess().Id}}));clipboard.StandardInput.Flush();
+        var snapshotReply=ClipboardPhase(clipboard,"snapshot",5000);
+        result["clipboardSnapshot"]=new Dictionary<string,object>{{"preservedFormats",snapshotReply["formats"]},{"oleMetadataExcluded",snapshotReply["oleMetadataExcluded"]},{"oleFormatsValidated",snapshotReply["oleFormatsValidated"]}};
+        TextCheck(cancel,listener,window,owner,expectedFocus,true,interaction);
+        clipboardMayChange=true;clipboard.StandardInput.WriteLine("replace");clipboard.StandardInput.Flush();ClipboardPhase(clipboard,"replaced",2000);clipboardReplaced=true;
+        TextCheck(cancel,listener,window,owner,expectedFocus,true,interaction);
+        if(Option(args,"_replaceAll",false)){Chord(new string[]{"Ctrl","A"},cancel,listener,window,owner,held,interaction);TextCheck(cancel,listener,window,owner,expectedFocus,true,interaction);}
+        Chord(new string[]{"Ctrl","V"},cancel,listener,window,owner,held,interaction);
+        if(cancel.WaitOne(60))throw new InvalidOperationException("COMPUTER_USE_STOPPED");
+        UIntPtr ignored;if(SendMessageTimeout(window,0,UIntPtr.Zero,IntPtr.Zero,2,200,out ignored)==IntPtr.Zero)throw new InvalidOperationException("PASTE_DISPATCH_UNCONFIRMED: target did not complete its bounded drain; observe before retrying");
+        result["method"]="clipboard-paste";result["restoreClipboard"]=Option(args,"restoreClipboard",true);
+      }
+      if(action=="type_text")RememberTextFocus(window,expectedFocus);
+      result["verification"]="sent";result["inputTargetHandle"]=window.ToInt64();result["inputTargetProcessId"]=owner;
+    }catch(Exception error){result["ok"]=false;result["error"]=error.Message;if(error.Message.StartsWith("WCU_NEEDS_INPUT",StringComparison.Ordinal))result["inputRequired"]=true;}
+    finally {
+      for(int i=held.Count-1;i>=0;i--)try{KeyEvent(held[i],true);}catch(Exception error){cleanup=false;result["ok"]=false;result["error"]="INPUT_CLEANUP_UNCONFIRMED: "+error.Message;}
+      if(clipboard!=null) {
+        try {
+          if(clipboardMayChange) {
+            if(!clipboard.HasExited){clipboard.StandardInput.WriteLine(result.ContainsKey("error") || !clipboardReplaced || Option(args,"restoreClipboard",true)?"restore":"keep");clipboard.StandardInput.Flush();}
+            var restoration=ConfirmClipboardRestore(clipboard);result["clipboardRestoreOutcome"]=restoration["restoreOutcome"];
+            if(!clipboard.WaitForExit(2000))throw new InvalidOperationException("CLIPBOARD_EXIT_UNCONFIRMED");
+          }else {clipboard.StandardInput.Close();if(!clipboard.WaitForExit(500)){clipboard.Kill();if(!clipboard.WaitForExit(1000))throw new InvalidOperationException("CLIPBOARD_EXIT_UNCONFIRMED");}result["clipboardRestoreOutcome"]="unchanged";}
+          result["clipboardCleanupConfirmed"]=true;
+        }catch(Exception error){if(!clipboardMayChange){try{if(!clipboard.HasExited){clipboard.Kill();clipboard.WaitForExit(1000);}}catch{} }else {cleanup=false;result["ok"]=false;result["error"]="CLIPBOARD_CLEANUP_UNCONFIRMED: "+error.Message;}}
+        if(!clipboardMayChange || cleanup)clipboard.Dispose();
+      }
+      if(cancel!=null)cancel.Dispose();if(listener!=null)listener.Dispose();
+      result["cleanupConfirmed"]=cleanup;
+      if(action=="keypress" || action=="type_text"){result["inputDispatched"]=textInputDispatched;result["interrupted"]=!Convert.ToBoolean(result["ok"]); }
+      // No potentially blocked UIA verification is permitted before clipboard cleanup.
+      if(cleanup)RestoreControlState(result,before,pointer,window,popups,Option(args,"activate",false),interaction);
+      else {result["pointer"]="left: cleanup unconfirmed";result["foreground"]="left: cleanup unconfirmed";}
+      if(cleanup)NotifyPhysicalInput(false);
+    }
+    return result;
+  }
+}