@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/computer-access/computer/windows-helper-process.js

@@ -0,0 +1,93 @@
+import { spawn } from "node:child_process";
+export const WINDOWS_IMAGE_MAX_BYTES = 10 * 1024 * 1024;
+export const WINDOWS_HELPER_MAX_BYTES = Math.ceil(WINDOWS_IMAGE_MAX_BYTES / 3) * 4 + 256 * 1024;
+const HELPER_BOOTSTRAP = [
+    "$ErrorActionPreference='Stop'",
+    "[Console]::InputEncoding=[Text.UTF8Encoding]::new($false)",
+    "[Console]::OutputEncoding=[Text.UTF8Encoding]::new($false)",
+    "try {",
+    "$envelope=[Console]::In.ReadToEnd() | ConvertFrom-Json",
+    "Add-Type -ReferencedAssemblies @('System.Drawing','UIAutomationClient','UIAutomationTypes','WindowsBase','System.Web.Extensions') -TypeDefinition $envelope.source",
+    "[Console]::WriteLine([AbotComputer]::Run($envelope.request))",
+    "} catch { [Console]::WriteLine('{\"transportError\":\"windows_helper_unavailable\"}'); exit 1 }",
+].join(";");
+/** One invocation, no helper files, no child commands and no replay after interruption. */
+export function runWindowsComputerHelper(input) {
+    if (input.signal?.aborted)
+        return Promise.resolve({ status: "aborted", stdout: "", spawned: false });
+    const payload = JSON.stringify({ source: input.source, request: JSON.stringify(input.request) });
+    if (Buffer.byteLength(payload) > 512 * 1024)
+        return Promise.resolve({ status: "output_limit", stdout: "", spawned: false });
+    return new Promise((resolve) => {
+        let child;
+        let settled = false;
+        let spawned = false;
+        let status = "completed";
+        let bytes = 0;
+        const chunks = [];
+        let timeout;
+        let stopGrace;
+        const finish = (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeout)
+                clearTimeout(timeout);
+            if (stopGrace)
+                clearTimeout(stopGrace);
+            input.signal?.removeEventListener("abort", abort);
+            resolve({
+                status,
+                stdout: status === "completed" ? Buffer.concat(chunks).toString("utf8") : "",
+                spawned,
+                ...(exitCode !== undefined ? { exitCode } : {}),
+            });
+        };
+        const stop = (reason) => {
+            if (settled || status !== "completed")
+                return;
+            status = reason;
+            chunks.length = 0;
+            child.kill("SIGKILL");
+            // WSL transport termination does not prove termination of the Windows process.
+            stopGrace = setTimeout(() => finish(), 500);
+            stopGrace.unref();
+        };
+        const abort = () => stop("aborted");
+        try {
+            child = (input.spawnProcess ?? spawn)(input.executable, ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", HELPER_BOOTSTRAP], { windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
+        }
+        catch {
+            status = "spawn_failed";
+            finish();
+            return;
+        }
+        child.once("spawn", () => { spawned = true; });
+        child.once("error", () => { status = "spawn_failed"; finish(); });
+        child.once("close", (code) => finish(code ?? undefined));
+        child.stdout.on("data", (chunk) => {
+            if (settled || status !== "completed")
+                return;
+            bytes += chunk.length;
+            if (bytes > WINDOWS_HELPER_MAX_BYTES) {
+                stop("output_limit");
+                return;
+            }
+            chunks.push(Buffer.from(chunk));
+        });
+        // Diagnostics may contain machine paths or desktop content; never project them.
+        child.stderr.resume();
+        child.stdin.on("error", () => stop("spawn_failed"));
+        const deadline = input.request.operation === "act"
+            ? input.request.deadlineEpochMs - Date.now() + 2_000
+            : 25_000;
+        timeout = setTimeout(() => stop("timeout"), Math.max(1, Math.min(deadline, 30_000)));
+        timeout.unref();
+        input.signal?.addEventListener("abort", abort, { once: true });
+        if (input.signal?.aborted) {
+            abort();
+            return;
+        }
+        child.stdin.end(payload, "utf8");
+    });
+}

package/dist/src/computer-access/computer/windows-helper-script.d.ts

@@ -0,0 +1,2 @@
+/** Focused C# owners compose one ephemeral process; no passive observation is started. */
+export declare const WINDOWS_COMPUTER_SOURCE: string;

package/dist/src/computer-access/computer/windows-helper-script.js

@@ -0,0 +1,17 @@
+import { WINDOWS_ACCESSIBILITY_SCRIPT } from "./windows-accessibility-script.js";
+import { WINDOWS_CAPTURE_SCRIPT } from "./windows-capture-script.js";
+import { WINDOWS_DESKTOP_SCRIPT } from "./windows-desktop-script.js";
+import { WINDOWS_INPUT_SCRIPT } from "./windows-input-script.js";
+import { WINDOWS_KEYBOARD_SCRIPT } from "./windows-keyboard-script.js";
+import { WINDOWS_NATIVE_SCRIPT } from "./windows-native-script.js";
+import { WINDOWS_TOPOLOGY_SCRIPT } from "./windows-topology-script.js";
+/** Focused C# owners compose one ephemeral process; no passive observation is started. */
+export const WINDOWS_COMPUTER_SOURCE = [
+    WINDOWS_NATIVE_SCRIPT,
+    WINDOWS_TOPOLOGY_SCRIPT,
+    WINDOWS_DESKTOP_SCRIPT,
+    WINDOWS_CAPTURE_SCRIPT,
+    WINDOWS_ACCESSIBILITY_SCRIPT,
+    WINDOWS_INPUT_SCRIPT,
+    WINDOWS_KEYBOARD_SCRIPT,
+].join("\n");

package/dist/src/computer-access/computer/windows-input-script.d.ts

@@ -0,0 +1,2 @@
+/** Mechanical action binding, native input receipts and pointer operations. */
+export declare const WINDOWS_INPUT_SCRIPT: string;

package/dist/src/computer-access/computer/windows-input-script.js

@@ -0,0 +1,171 @@
+/** Mechanical action binding, native input receipts and pointer operations. */
+export const WINDOWS_INPUT_SCRIPT = String.raw `
+public static partial class AbotComputer {
+  [StructLayout(LayoutKind.Sequential)] struct MouseInput {
+    public int X,Y; public uint Data,Flags,Time; public UIntPtr Extra;
+  }
+  [StructLayout(LayoutKind.Sequential)] struct KeyboardInput {
+    public ushort Key,Scan; public uint Flags,Time; public UIntPtr Extra;
+  }
+  [StructLayout(LayoutKind.Explicit)] struct InputUnion {
+    [FieldOffset(0)] public MouseInput Mouse;
+    [FieldOffset(0)] public KeyboardInput Keyboard;
+  }
+  [StructLayout(LayoutKind.Sequential)] struct NativeInput { public uint Type; public InputUnion Data; }
+  [DllImport("user32.dll",SetLastError=true)] static extern uint SendInput(uint count,NativeInput[] inputs,int size);
+  [DllImport("user32.dll")] static extern IntPtr MonitorFromPoint(Point point,uint flags);
+
+  sealed class DispatchState {
+    public int Requested,Accepted; public bool Started,Uncertain; public string Failure;
+    public void Fail(Exception error) {
+      var fault=error as ComputerFault; Failure=fault==null?"native_action_failed":fault.Code;
+    }
+    public Dictionary<string,object> Result() {
+      string status="not_dispatched";
+      if(Started && Accepted>0) status=Failure==null && Accepted==Requested?"accepted":"partial";
+      if(Uncertain) status="unknown";
+      var result=Obj("status",status,"requestedInputCount",Requested,"acceptedInputCount",Accepted);
+      if(Failure!=null) result["reason"]=Failure;
+      return result;
+    }
+    public void Send(NativeInput[] inputs) {
+      if(inputs.Length==0) return;
+      Started=true; Requested+=inputs.Length;
+      uint accepted=SendInput((uint)inputs.Length,inputs,Marshal.SizeOf(typeof(NativeInput)));
+      Accepted+=(int)accepted;
+      if(accepted!=(uint)inputs.Length)
+        throw new ComputerFault("computer_input_not_accepted","Windows accepted only part or none of the input; UIPI or desktop state may restrict injection.");
+    }
+    public void Cleanup(NativeInput[] inputs) {
+      try { Send(inputs); } catch(Exception error) { Fail(error); }
+    }
+  }
+  static void VerifyActionPreconditions(Dictionary<string,object> request,Dictionary<string,object> result) {
+    RequireAvailableDesktop(result);
+    string binding=Text(request,"desktopBinding",4096);
+    if((string)Record(result["desktop"])["binding"]!=binding)
+      throw new ComputerFault("computer_desktop_changed","The action belongs to a different desktop observation.");
+    if(!SameRectangle(ParseRectangle(request["expectedGeometry"]),VirtualDesktopBounds()))
+      throw new ComputerFault("computer_geometry_changed","The display geometry changed before input dispatch.");
+    string expected=Field(request,"expectedWindow") as string;
+    if(expected!=null && NativeWindowBinding(GetForegroundWindow())!=expected)
+      throw new ComputerFault("computer_focus_changed","The focused window changed before input dispatch.");
+    VerifyActionLease(request);
+  }
+  static void VerifyActionLease(Dictionary<string,object> request) {
+    if(HasExpiredAction(request))
+      throw new ComputerFault("computer_action_expired","The action deadline passed; no remaining input will be sent.");
+    VerifyDesktopBinding(Text(request,"desktopBinding",4096));
+    if(!SameRectangle(ParseRectangle(request["expectedGeometry"]),VirtualDesktopBounds()))
+      throw new ComputerFault("computer_geometry_changed","The display geometry changed during input dispatch.");
+  }
+  static void VerifyInitialInputBinding(Dictionary<string,object> request) {
+    VerifyActionLease(request);
+    string expected=Field(request,"expectedWindow") as string;
+    if(expected!=null && NativeWindowBinding(GetForegroundWindow())!=expected)
+      throw new ComputerFault("computer_focus_changed","The focused window changed before input dispatch.");
+  }
+  static Point InputPoint(object raw) {
+    var point=Record(raw);
+    double x=Number(point,"x"),y=Number(point,"y");
+    if(x< -131072 || x>131072 || y< -131072 || y>131072)
+      throw new ComputerFault("computer_point_invalid","Input coordinates exceed the physical desktop range.");
+    var result=new Point { X=(int)Math.Round(x),Y=(int)Math.Round(y) };
+    Rect bounds=VirtualDesktopBounds();
+    if(result.X<bounds.Left || result.X>=bounds.Right || result.Y<bounds.Top || result.Y>=bounds.Bottom)
+      throw new ComputerFault("computer_point_invalid","Input coordinates are outside the physical desktop.");
+    if(MonitorFromPoint(result,0)==IntPtr.Zero)
+      throw new ComputerFault("computer_point_invalid","Input coordinates are in a gap between displays.");
+    return result;
+  }
+  static NativeInput Mouse(uint flags,int x,int y,uint data) {
+    return new NativeInput { Type=0,Data=new InputUnion { Mouse=new MouseInput { X=x,Y=y,Data=data,Flags=flags } } };
+  }
+  static NativeInput MoveInput(Point point) {
+    Rect bounds=VirtualDesktopBounds();
+    int x=(int)Math.Round((double)(point.X-bounds.Left)*65535/Math.Max(1,bounds.Right-bounds.Left-1));
+    int y=(int)Math.Round((double)(point.Y-bounds.Top)*65535/Math.Max(1,bounds.Bottom-bounds.Top-1));
+    return Mouse(0x0001|0x8000|0x4000,x,y,0);
+  }
+  static uint ButtonFlag(string button,bool up) {
+    if(button=="left") return up?0x0004u:0x0002u;
+    if(button=="right") return up?0x0010u:0x0008u;
+    if(button=="middle") return up?0x0040u:0x0020u;
+    throw new ComputerFault("computer_request_invalid","Unknown pointer button.");
+  }
+  static void RequireNoHeldInput() {
+    foreach(int key in new int[] {1,2,4,16,17,18,91,92}) {
+      if((GetAsyncKeyState(key)&0x8000)!=0)
+        throw new ComputerFault("computer_user_input_active","A pointer button or modifier is already held; wait for a fresh observation.");
+    }
+  }
+  static void Act(Dictionary<string,object> request,Dictionary<string,object> result,DispatchState dispatch) {
+    VerifyActionPreconditions(request,result);
+    var action=Record(Field(request,"action")); string kind=Text(action,"kind",32);
+    if(kind=="focus_window") { FocusWindow(action,request,dispatch); return; }
+    RequireNoHeldInput();
+    if(kind=="press_keys") { PressKeys(action,request,dispatch); return; }
+    if(kind=="type_text") { TypeText(action,request,dispatch); return; }
+    if(kind=="drag") { Drag(action,request,dispatch); return; }
+    if(kind=="scroll") { Scroll(action,request,dispatch); return; }
+    if(kind=="move") {
+      var move=MoveInput(InputPoint(Field(action,"point"))); VerifyActionPreconditions(request,result);
+      dispatch.Send(new NativeInput[] {move}); return;
+    }
+    if(kind!="click") throw new ComputerFault("computer_request_invalid","Unknown native input operation.");
+    var point=InputPoint(Field(action,"point")); string button=Text(action,"button",16);
+    int count=Integer(action,"count",1,2); uint down=ButtonFlag(button,false),up=ButtonFlag(button,true);
+    var inputs=new List<NativeInput>(); inputs.Add(MoveInput(point));
+    for(int i=0;i<count;i++) { inputs.Add(Mouse(down,0,0,0)); inputs.Add(Mouse(up,0,0,0)); }
+    VerifyActionPreconditions(request,result);
+    try { dispatch.Send(inputs.ToArray()); }
+    catch { dispatch.Cleanup(new NativeInput[] {Mouse(up,0,0,0)}); throw; }
+  }
+  static void FocusWindow(Dictionary<string,object> action,Dictionary<string,object> request,DispatchState dispatch) {
+    IntPtr window=ResolveWindowBinding(Text(action,"windowBinding",4096));
+    VerifyInitialInputBinding(request);
+    if(IsIconic(window)) {
+      dispatch.Requested++; dispatch.Started=true; dispatch.Uncertain=true;
+      ShowWindow(window,9);
+      if(IsIconic(window)) throw new ComputerFault("computer_window_restore_unconfirmed","The restore request could not be confirmed.");
+      dispatch.Accepted++; dispatch.Uncertain=false;
+    }
+    // Restore may itself have changed focus; only enforce the binding before that effect.
+    VerifyActionLease(request);
+    dispatch.Requested++; dispatch.Started=true; dispatch.Uncertain=true;
+    SetForegroundWindow(window);
+    if(GetForegroundWindow()!=window)
+      throw new ComputerFault("computer_focus_not_granted","Windows did not confirm focus on the selected window.");
+    dispatch.Accepted++; dispatch.Uncertain=false;
+  }
+  static void Scroll(Dictionary<string,object> action,Dictionary<string,object> request,DispatchState dispatch) {
+    int x=(int)Math.Round(Number(action,"deltaX")),y=(int)Math.Round(Number(action,"deltaY"));
+    if(Math.Abs((long)x)>5000 || Math.Abs((long)y)>5000)
+      throw new ComputerFault("computer_request_invalid","Scroll delta is out of range.");
+    var inputs=new List<NativeInput>();
+    if(x!=0) inputs.Add(Mouse(0x1000,0,0,unchecked((uint)x)));
+    // Public deltas use positive-down screen coordinates; Windows wheel uses positive-up.
+    if(y!=0) inputs.Add(Mouse(0x0800,0,0,unchecked((uint)-y)));
+    VerifyInitialInputBinding(request); dispatch.Send(inputs.ToArray());
+  }
+  static void Drag(Dictionary<string,object> action,Dictionary<string,object> request,DispatchState dispatch) {
+    Point from=InputPoint(Field(action,"from")),to=InputPoint(Field(action,"to"));
+    int duration=PhysicalPixel(action,"durationMs",0,5000); string button=Text(action,"button",16);
+    uint down=ButtonFlag(button,false),up=ButtonFlag(button,true);
+    int steps=Math.Max(1,Math.Min(100,duration/16)); bool pressed=false;
+    try {
+      VerifyInitialInputBinding(request); pressed=true;
+      dispatch.Send(new NativeInput[] {MoveInput(from),Mouse(down,0,0,0)});
+      string active=NativeWindowBinding(GetForegroundWindow());
+      for(int i=1;i<=steps;i++) {
+        if(duration>0) Thread.Sleep(duration/steps);
+        VerifyActionLease(request);
+        if(NativeWindowBinding(GetForegroundWindow())!=active)
+          throw new ComputerFault("computer_focus_changed","Focus changed during the drag.");
+        var point=new Point {X=from.X+(int)Math.Round((double)(to.X-from.X)*i/steps),Y=from.Y+(int)Math.Round((double)(to.Y-from.Y)*i/steps)};
+        dispatch.Send(new NativeInput[] {MoveInput(point)});
+      }
+    } finally { if(pressed) dispatch.Cleanup(new NativeInput[] {Mouse(up,0,0,0)}); }
+  }
+}
+`;

package/dist/src/computer-access/computer/windows-keyboard-script.d.ts

@@ -0,0 +1,2 @@
+/** Explicit key mapping and Unicode injection, with release records for partial dispatch. */
+export declare const WINDOWS_KEYBOARD_SCRIPT: string;

package/dist/src/computer-access/computer/windows-keyboard-script.js

@@ -0,0 +1,81 @@
+/** Explicit key mapping and Unicode injection, with release records for partial dispatch. */
+export const WINDOWS_KEYBOARD_SCRIPT = String.raw `
+public static partial class AbotComputer {
+  static ushort VirtualKey(string name) {
+    string key=name.Trim().ToUpperInvariant();
+    if(key.Length==1 && ((key[0]>='A' && key[0]<='Z') || (key[0]>='0' && key[0]<='9'))) return key[0];
+    int function;
+    if(key.StartsWith("F") && Int32.TryParse(key.Substring(1),out function) && function>=1 && function<=24)
+      return (ushort)(111+function);
+    switch(key) {
+      case "CONTROL": case "CTRL": return 17;
+      case "ALT": case "OPTION": return 18;
+      case "SHIFT": return 16;
+      case "META": case "WIN": case "WINDOWS": case "SUPER": return 91;
+      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 "SPACE": return 32;
+      case "LEFT": case "ARROWLEFT": return 37;
+      case "UP": case "ARROWUP": return 38;
+      case "RIGHT": case "ARROWRIGHT": return 39;
+      case "DOWN": case "ARROWDOWN": return 40;
+      case "HOME": return 36;
+      case "END": return 35;
+      case "PAGEUP": case "PGUP": return 33;
+      case "PAGEDOWN": case "PGDN": return 34;
+      case "INSERT": case "INS": return 45;
+      case "CAPSLOCK": return 20;
+      case "PRINTSCREEN": return 44;
+      default: throw new ComputerFault("computer_key_unsupported","Use explicit supported key names; text belongs in type_text.");
+    }
+  }
+  static bool IsExtendedKey(ushort key) {
+    if(key>=33 && key<=46) return true;
+    return key==91;
+  }
+  static NativeInput Key(ushort key,ushort scan,uint flags) {
+    return new NativeInput {Type=1,Data=new InputUnion {Keyboard=new KeyboardInput {Key=key,Scan=scan,Flags=flags}}};
+  }
+  static void PressKeys(Dictionary<string,object> action,Dictionary<string,object> request,DispatchState dispatch) {
+    var raw=Field(action,"keys") as object[];
+    if(raw==null || raw.Length<1 || raw.Length>8)
+      throw new ComputerFault("computer_request_invalid","Use one to eight explicit keys.");
+    var keys=new List<ushort>(); var seen=new HashSet<ushort>();
+    foreach(object value in raw) {
+      var text=value as string;
+      if(text==null || text.Length>32) throw new ComputerFault("computer_request_invalid","Invalid key name.");
+      ushort key=VirtualKey(text);
+      if(!seen.Add(key)) throw new ComputerFault("computer_request_invalid","A chord cannot repeat the same key.");
+      if((GetAsyncKeyState(key)&0x8000)!=0)
+        throw new ComputerFault("computer_user_input_active","A requested key is already physically held.");
+      keys.Add(key);
+    }
+    var inputs=new List<NativeInput>(); var releases=new List<NativeInput>();
+    foreach(ushort key in keys) inputs.Add(Key(key,0,IsExtendedKey(key)?1u:0u));
+    for(int i=keys.Count-1;i>=0;i--) releases.Add(Key(keys[i],0,2u|(IsExtendedKey(keys[i])?1u:0u)));
+    inputs.AddRange(releases); VerifyInitialInputBinding(request);
+    try { dispatch.Send(inputs.ToArray()); }
+    catch { dispatch.Cleanup(releases.ToArray()); throw; }
+  }
+  static void TypeText(Dictionary<string,object> action,Dictionary<string,object> request,DispatchState dispatch) {
+    string text=Text(action,"text",4096);
+    VerifyInitialInputBinding(request);
+    string foreground=NativeWindowBinding(GetForegroundWindow());
+    for(int start=0;start<text.Length;start+=128) {
+      VerifyActionLease(request);
+      if(NativeWindowBinding(GetForegroundWindow())!=foreground)
+        throw new ComputerFault("computer_focus_changed","Focus changed during Unicode text input.");
+      var inputs=new List<NativeInput>(); var releases=new List<NativeInput>();
+      int end=Math.Min(start+128,text.Length);
+      for(int i=start;i<end;i++) {
+        inputs.Add(Key(0,text[i],4)); inputs.Add(Key(0,text[i],6)); releases.Add(Key(0,text[i],6));
+      }
+      try { dispatch.Send(inputs.ToArray()); }
+      catch { dispatch.Cleanup(releases.ToArray()); throw; }
+    }
+  }
+}
+`;

package/dist/src/computer-access/computer/windows-native-script.d.ts

@@ -0,0 +1,2 @@
+/** Shared native declarations and strict mechanical decoding for the one-shot helper. */
+export declare const WINDOWS_NATIVE_SCRIPT: string;

package/dist/src/computer-access/computer/windows-native-script.js

@@ -0,0 +1,157 @@
+/** Shared native declarations and strict mechanical decoding for the one-shot helper. */
+export const WINDOWS_NATIVE_SCRIPT = String.raw `
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Drawing;
+using System.Drawing.Imaging;
+using System.IO;
+using System.Runtime.InteropServices;
+using System.Text;
+using System.Threading;
+using System.Web.Script.Serialization;
+using System.Windows.Automation;
+
+public static partial class AbotComputer {
+  static readonly JavaScriptSerializer Json = new JavaScriptSerializer { MaxJsonLength=15000000, RecursionLimit=64 };
+  const int ImageMaxBytes=10485760;
+  [StructLayout(LayoutKind.Sequential)] struct Rect { public int Left,Top,Right,Bottom; }
+  [StructLayout(LayoutKind.Sequential)] struct Point { public int X,Y; }
+  [StructLayout(LayoutKind.Sequential)] struct Luid { public uint Low; public int High; }
+  [StructLayout(LayoutKind.Sequential)] struct TokenStatistics {
+    public Luid TokenId,AuthenticationId; public long ExpirationTime;
+    public int TokenType,ImpersonationLevel; public uint DynamicCharged,DynamicAvailable,GroupCount,PrivilegeCount;
+    public Luid ModifiedId;
+  }
+  delegate bool EnumWindowCallback(IntPtr window,IntPtr parameter);
+  [DllImport("user32.dll")] static extern IntPtr GetForegroundWindow();
+  [DllImport("user32.dll")] static extern bool IsWindow(IntPtr window);
+  [DllImport("user32.dll")] static extern bool IsWindowVisible(IntPtr window);
+  [DllImport("user32.dll")] static extern bool IsIconic(IntPtr window);
+  [DllImport("user32.dll")] static extern bool GetWindowRect(IntPtr window,out Rect rectangle);
+  [DllImport("user32.dll")] static extern bool EnumWindows(EnumWindowCallback callback,IntPtr parameter);
+  [DllImport("user32.dll",CharSet=CharSet.Unicode)] static extern int GetWindowText(IntPtr window,StringBuilder text,int count);
+  [DllImport("user32.dll")] static extern uint GetWindowThreadProcessId(IntPtr window,out uint processId);
+  [DllImport("user32.dll")] static extern int GetSystemMetrics(int index);
+  [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",CharSet=CharSet.Unicode)] static extern bool GetUserObjectInformation(IntPtr obj,int index,StringBuilder text,int size,out int required);
+  [DllImport("user32.dll")] static extern IntPtr SetThreadDpiAwarenessContext(IntPtr context);
+  [DllImport("user32.dll")] static extern bool SetProcessDPIAware();
+  [DllImport("user32.dll")] static extern bool SetForegroundWindow(IntPtr window);
+  [DllImport("user32.dll")] static extern bool ShowWindow(IntPtr window,int command);
+  [DllImport("user32.dll")] static extern short GetAsyncKeyState(int key);
+  [DllImport("kernel32.dll")] static extern bool CloseHandle(IntPtr handle);
+  [DllImport("advapi32.dll",SetLastError=true)] static extern bool OpenProcessToken(IntPtr process,uint access,out IntPtr token);
+  [DllImport("advapi32.dll",SetLastError=true)] static extern bool GetTokenInformation(IntPtr token,int type,out TokenStatistics information,int length,out int needed);
+  [DllImport("dwmapi.dll")] static extern int DwmFlush();
+
+  sealed class ComputerFault : Exception {
+    public readonly string Code;
+    public ComputerFault(string code,string message):base(message) { Code=code; }
+  }
+  static Dictionary<string,object> Obj(params object[] pairs) {
+    var result=new Dictionary<string,object>();
+    for(int i=0;i<pairs.Length;i+=2) result.Add((string)pairs[i],pairs[i+1]);
+    return result;
+  }
+  static Dictionary<string,object> Record(object value) {
+    var result=value as Dictionary<string,object>;
+    if(result==null) throw new ComputerFault("computer_request_invalid","Expected a structured object.");
+    return result;
+  }
+  static object Field(Dictionary<string,object> value,string key) {
+    object result; return value.TryGetValue(key,out result)?result:null;
+  }
+  static string Text(Dictionary<string,object> value,string key,int limit) {
+    var result=Field(value,key) as string;
+    if(result==null || result.Length>limit) throw new ComputerFault("computer_request_invalid","Invalid text field: "+key);
+    return result;
+  }
+  static double Number(Dictionary<string,object> value,string key) {
+    object raw=Field(value,key);
+    if(!(raw is int) && !(raw is long) && !(raw is decimal) && !(raw is double))
+      throw new ComputerFault("computer_request_invalid","Invalid numeric field: "+key);
+    double result=Convert.ToDouble(raw);
+    if(Double.IsInfinity(result) || Double.IsNaN(result)) throw new ComputerFault("computer_request_invalid","Non-finite number.");
+    return result;
+  }
+  static int Integer(Dictionary<string,object> value,string key,int min,int max) {
+    double number=Number(value,key);
+    if(number!=Math.Truncate(number) || number<min || number>max)
+      throw new ComputerFault("computer_request_invalid","Out-of-range integer: "+key);
+    return (int)number;
+  }
+  static Dictionary<string,object> Rectangle(int x,int y,int width,int height) {
+    return Obj("x",x,"y",y,"width",width,"height",height);
+  }
+  static Rect ParseRectangle(object value) {
+    var data=Record(value);
+    int x=PhysicalPixel(data,"x",-131072,131072),y=PhysicalPixel(data,"y",-131072,131072);
+    int width=PhysicalPixel(data,"width",1,65536),height=PhysicalPixel(data,"height",1,65536);
+    return new Rect { Left=x,Top=y,Right=x+width,Bottom=y+height };
+  }
+  static int PhysicalPixel(Dictionary<string,object> data,string key,int min,int max) {
+    double number=Number(data,key);
+    if(number<min || number>max) throw new ComputerFault("computer_request_invalid","Invalid physical pixel field: "+key);
+    return (int)Math.Round(number);
+  }
+  static bool SameRectangle(Rect left,Rect right) {
+    if(left.Left!=right.Left) return false;
+    if(left.Top!=right.Top) return false;
+    if(left.Right!=right.Right) return false;
+    return left.Bottom==right.Bottom;
+  }
+  static bool ContainsRectangle(Rect outer,Rect inner) {
+    if(inner.Left<outer.Left || inner.Top<outer.Top) return false;
+    if(inner.Right>outer.Right || inner.Bottom>outer.Bottom) return false;
+    return inner.Right>inner.Left && inner.Bottom>inner.Top;
+  }
+  static bool HasExpiredAction(Dictionary<string,object> request) {
+    return DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()>Number(request,"deadlineEpochMs");
+  }
+  static void PreparePhysicalCoordinates() {
+    try { if(SetThreadDpiAwarenessContext(new IntPtr(-4))!=IntPtr.Zero) return; }
+    catch(EntryPointNotFoundException) {}
+    SetProcessDPIAware();
+  }
+  static void SetError(Dictionary<string,object> result,Exception error) {
+    if(result.ContainsKey("error")) return;
+    var fault=error as ComputerFault;
+    result["error"]=Obj("code",fault==null?"computer_native_failed":fault.Code,
+      "message",fault==null?"The native observation or input operation failed.":fault.Message);
+  }
+  public static string Run(string requestJson) {
+    Dictionary<string,object> result=UnavailableResult("computer_native_failed");
+    Dictionary<string,object> request=null;
+    DispatchState dispatch=null;
+    try {
+      request=Record(Json.DeserializeObject(requestJson));
+      string operation=Text(request,"operation",32);
+      if(operation!="inspect" && operation!="observe" && operation!="act")
+        throw new ComputerFault("computer_request_invalid","Unknown native operation.");
+      if(operation=="act") dispatch=new DispatchState();
+      PreparePhysicalCoordinates();
+      result=DesktopSnapshot();
+      if(operation=="inspect") return Json.Serialize(result);
+      if(operation=="observe") RequireObservationSource(request,result);
+      if(operation=="act") {
+        try {
+          Act(request,result,dispatch);
+          if(dispatch.Failure!=null) throw new ComputerFault(dispatch.Failure,"Input cleanup was not fully accepted by Windows.");
+        } catch(Exception error) { dispatch.Fail(error); SetError(result,error); }
+        object actionError=Field(result,"error");
+        result=DesktopSnapshot();
+        RequireObservationSource(request,result);
+        if(actionError!=null) result["error"]=actionError;
+        if(dispatch.Started) { try { DwmFlush(); } catch(DllNotFoundException) {} }
+      }
+      try { CaptureObservation(result,operation=="observe"?Field(request,"region"):null); }
+      catch(Exception error) { SetError(result,error); }
+    } catch(Exception error) { SetError(result,error); }
+    if(dispatch!=null) result["dispatch"]=dispatch.Result();
+    return Json.Serialize(result);
+  }
+}
+`;

package/dist/src/computer-access/computer/windows-result.d.ts

@@ -0,0 +1,4 @@
+import type { NativeComputerRequest, NativeComputerResult } from "./native-protocol.js";
+import { type WindowsHelperProcessResult } from "./windows-helper-process.js";
+export declare function windowsHelperUnavailable(request: NativeComputerRequest, reason: string, spawned: boolean): NativeComputerResult;
+export declare function decodeWindowsComputerResult(process: WindowsHelperProcessResult, request: NativeComputerRequest): NativeComputerResult;

package/dist/src/computer-access/computer/windows-result.js

@@ -0,0 +1,105 @@
+import { readNativeComputerResult } from "./native-validation.js";
+import { WINDOWS_IMAGE_MAX_BYTES } from "./windows-helper-process.js";
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+export function windowsHelperUnavailable(request, reason, spawned) {
+    const capability = { supported: true, available: false, reason };
+    return {
+        desktop: {
+            platform: "windows", binding: "windows:unavailable", name: "Windows desktop",
+            available: false, reason, bounds: { x: 0, y: 0, width: 1, height: 1 },
+            capabilities: { capture: capability, accessibility: capability, input: capability, windows: capability },
+            targetingGuarantee: "observed_surface",
+        },
+        windows: [],
+        ...(request.operation === "act" ? {
+            dispatch: {
+                status: spawned ? "unknown" : "not_dispatched",
+                requestedInputCount: 0,
+                ...(spawned ? {} : { acceptedInputCount: 0 }),
+                reason: spawned ? "native_receipt_unavailable" : reason,
+            },
+        } : {}),
+        error: {
+            code: reason,
+            message: spawned && request.operation === "act"
+                ? "The Windows action receipt is unavailable. Input may have occurred; observe the desktop before another action. No action was replayed."
+                : "The Windows desktop helper is unavailable for this operation.",
+        },
+    };
+}
+export function decodeWindowsComputerResult(process, request) {
+    if (process.status !== "completed")
+        return windowsHelperUnavailable(request, `computer_helper_${process.status}`, process.spawned);
+    let result;
+    let image;
+    try {
+        const wire = JSON.parse(process.stdout.trim());
+        if (wire === null || typeof wire !== "object" || Array.isArray(wire))
+            throw new Error("invalid result");
+        const { image: nativeImage, ...metadata } = wire;
+        result = readNativeComputerResult(metadata);
+        image = nativeImage;
+        if (result.desktop.platform !== "windows")
+            throw new Error("wrong platform");
+        if (request.operation === "act" && !result.dispatch)
+            throw new Error("missing dispatch");
+    }
+    catch {
+        return windowsHelperUnavailable(request, "computer_helper_protocol_invalid", process.spawned);
+    }
+    try {
+        if (image === undefined) {
+            if (request.operation !== "inspect" && !result.error)
+                throw new Error("missing observation");
+            return result;
+        }
+        const bytes = decodeWindowsImage(image, result);
+        return { ...result, image: { mimeType: "image/png", bytes } };
+    }
+    catch {
+        if (result.dispatch)
+            return {
+                ...result,
+                error: {
+                    code: "computer_image_decode_failed",
+                    message: "The native input receipt is preserved, but the captured image is invalid or unavailable. Observe again before another action.",
+                },
+            };
+        return windowsHelperUnavailable(request, "computer_helper_protocol_invalid", process.spawned);
+    }
+}
+function decodeWindowsImage(value, result) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("invalid image");
+    const image = value;
+    if (Object.keys(image).some((key) => key !== "mimeType" && key !== "base64"))
+        throw new Error("invalid image fields");
+    if (image.mimeType !== "image/png" || typeof image.base64 !== "string")
+        throw new Error("invalid image encoding");
+    if (image.base64.length > Math.ceil(WINDOWS_IMAGE_MAX_BYTES / 3) * 4)
+        throw new Error("image too large");
+    const bytes = Buffer.from(image.base64, "base64");
+    try {
+        validateWindowsImageBytes(bytes, image.base64, result);
+        return bytes;
+    }
+    catch (error) {
+        bytes.fill(0);
+        throw error;
+    }
+}
+function validateWindowsImageBytes(bytes, encoded, result) {
+    if (bytes.length > WINDOWS_IMAGE_MAX_BYTES || bytes.length < 33)
+        throw new Error("image size");
+    if (bytes.toString("base64") !== encoded)
+        throw new Error("noncanonical image encoding");
+    if (!bytes.subarray(0, 8).equals(PNG_SIGNATURE))
+        throw new Error("image signature");
+    if (bytes.readUInt32BE(8) !== 13 || bytes.toString("ascii", 12, 16) !== "IHDR")
+        throw new Error("image header");
+    const observation = result.observation;
+    if (!observation)
+        throw new Error("missing observation metadata");
+    if (bytes.readUInt32BE(16) !== observation.imageWidth || bytes.readUInt32BE(20) !== observation.imageHeight)
+        throw new Error("image dimensions disagree");
+}

package/dist/src/computer-access/computer/windows-topology-script.d.ts

@@ -0,0 +1,2 @@
+/** Monitor source arrangement is part of opaque desktop identity, not a new tool field. */
+export declare const WINDOWS_TOPOLOGY_SCRIPT: string;