@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/computer-access/computer/unix-native-process.js

@@ -0,0 +1,155 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { NATIVE_JSON_LIMIT, readUnixDispatch, readUnixNativeResult, unavailableUnixDesktop, } from "./unix-native-results.js";
+/** Owns one helper lifetime. Input is never replayed after timeout, abort or process loss. */
+export function createUnixNativeProcess(options) {
+    let child;
+    let pending;
+    let closed = false;
+    let failedReason;
+    let buffer = Buffer.alloc(0);
+    let queue = Promise.resolve();
+    let lastResult;
+    function interruptedResult(reason) {
+        const dispatch = pending?.request.operation === "act"
+            ? (pending.dispatch ?? {
+                status: "unknown",
+                requestedInputCount: 1,
+                reason,
+            })
+            : undefined;
+        const result = unavailableUnixDesktop(options.platform, reason, dispatch);
+        if (!lastResult)
+            return result;
+        return {
+            ...result,
+            desktop: { ...lastResult.desktop, available: false, reason },
+            windows: lastResult.windows,
+        };
+    }
+    function terminate(reason) {
+        failedReason = reason;
+        pending?.finish(interruptedResult(reason));
+        const retiring = child;
+        retiring?.kill("SIGTERM");
+        if (retiring) {
+            const hardStop = setTimeout(() => retiring.kill("SIGKILL"), 3000);
+            hardStop.unref();
+            retiring.once("exit", () => clearTimeout(hardStop));
+        }
+        child = undefined;
+        buffer = Buffer.alloc(0);
+    }
+    function receiveLine(line) {
+        const value = JSON.parse(line);
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error("native_protocol_invalid");
+        const message = value;
+        if (!pending || message.id !== pending.id)
+            throw new Error("native_response_identity_invalid");
+        if (message.type === "dispatch") {
+            pending.dispatch = readUnixDispatch(message.dispatch);
+            return;
+        }
+        if (message.type !== "result")
+            throw new Error("native_protocol_invalid");
+        const result = readUnixNativeResult(message.result, options.platform);
+        lastResult = result;
+        pending.finish(result);
+    }
+    function ensureHelper() {
+        if (child)
+            return;
+        child = (options.spawnProcess ?? spawn)(options.file, [...options.args], {
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        child.stdin.on("error", () => terminate("computer_native_pipe_failed"));
+        child.stderr.resume();
+        child.stdout.on("data", (chunk) => {
+            if (closed || failedReason)
+                return;
+            buffer = Buffer.concat([buffer, chunk]);
+            if (buffer.length > NATIVE_JSON_LIMIT) {
+                terminate("computer_native_result_limit");
+                return;
+            }
+            let boundary = buffer.indexOf(10);
+            while (boundary >= 0) {
+                const line = buffer.subarray(0, boundary).toString("utf8");
+                buffer = buffer.subarray(boundary + 1);
+                try {
+                    receiveLine(line);
+                }
+                catch {
+                    terminate("computer_native_protocol_invalid");
+                    return;
+                }
+                boundary = buffer.indexOf(10);
+            }
+        });
+        child.once("error", () => terminate("computer_native_dependency_unavailable"));
+        child.once("exit", () => {
+            if (!closed)
+                terminate("computer_native_helper_stopped");
+        });
+    }
+    function executeOne(request, signal) {
+        if (closed || failedReason)
+            return Promise.resolve(unavailableUnixDesktop(options.platform, failedReason ?? "computer_native_closed"));
+        if (signal?.aborted)
+            return Promise.resolve(unavailableUnixDesktop(options.platform, "computer_native_aborted", request.operation === "act"
+                ? {
+                    status: "not_dispatched",
+                    requestedInputCount: 1,
+                    acceptedInputCount: 0,
+                }
+                : undefined));
+        return new Promise((resolve) => {
+            const id = randomUUID();
+            let settled = false;
+            let cancelTimer;
+            const timeout = setTimeout(() => terminate("computer_native_timeout"), options.timeoutMs ?? 45_000);
+            function finish(result) {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timeout);
+                if (cancelTimer)
+                    clearTimeout(cancelTimer);
+                signal?.removeEventListener("abort", abort);
+                pending = undefined;
+                resolve(result);
+            }
+            function abort() {
+                child?.stdin.write(JSON.stringify({ type: "cancel", id }) + "\n");
+                cancelTimer = setTimeout(() => terminate("computer_native_cancelled_unknown"), options.cancellationGraceMs ?? 1000);
+            }
+            pending = { id, request, finish };
+            try {
+                ensureHelper();
+                child.stdin.write(JSON.stringify({ type: "request", id, request }) + "\n");
+                signal?.addEventListener("abort", abort, { once: true });
+                if (signal?.aborted)
+                    abort();
+            }
+            catch {
+                terminate("computer_native_dependency_unavailable");
+            }
+        });
+    }
+    return {
+        execute(request, signal) {
+            const result = queue.then(() => executeOne(request, signal));
+            queue = result.then(() => undefined, () => undefined);
+            return result;
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            child?.stdin.write(JSON.stringify({ type: "close" }) + "\n");
+            terminate("computer_native_closed");
+        },
+    };
+}

package/dist/src/computer-access/computer/unix-native-results.d.ts

@@ -0,0 +1,7 @@
+import type { ComputerPlatform, NativeComputerDispatch, NativeComputerResult } from "./native-protocol.js";
+export declare const NATIVE_PNG_LIMIT: number;
+export declare const NATIVE_JSON_LIMIT: number;
+export declare function unavailableUnixDesktop(platform: ComputerPlatform, reason: string, dispatch?: NativeComputerDispatch): NativeComputerResult;
+export declare function readUnixDispatch(value: unknown): NativeComputerDispatch;
+/** JSON is mechanical helper data; only validated native image bytes cross this boundary. */
+export declare function readUnixNativeResult(value: unknown, platform: ComputerPlatform): NativeComputerResult;

package/dist/src/computer-access/computer/unix-native-results.js

@@ -0,0 +1,73 @@
+import { readNativeComputerResult } from "./native-validation.js";
+export const NATIVE_PNG_LIMIT = 10 * 1024 * 1024;
+export const NATIVE_JSON_LIMIT = Math.ceil(NATIVE_PNG_LIMIT / 3) * 4 + 512 * 1024;
+export function unavailableUnixDesktop(platform, reason, dispatch) {
+    const unavailable = { supported: true, available: false, reason };
+    return {
+        desktop: {
+            platform,
+            binding: `unavailable:${platform}`,
+            name: "User desktop",
+            available: false,
+            reason,
+            bounds: { x: 0, y: 0, width: 1, height: 1 },
+            capabilities: {
+                capture: unavailable,
+                input: unavailable,
+                accessibility: unavailable,
+                windows: unavailable,
+            },
+            targetingGuarantee: "observed_surface",
+        },
+        windows: [],
+        ...(dispatch ? { dispatch } : {}),
+        error: {
+            code: reason,
+            message: "The native desktop operation is unavailable. Inspect the reported prerequisite before trying again.",
+        },
+    };
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function readUnixDispatch(value) {
+    if (!isRecord(value))
+        throw new Error("native_dispatch_invalid");
+    if (!["not_dispatched", "accepted", "partial", "unknown"].includes(String(value.status)))
+        throw new Error("native_dispatch_invalid");
+    if (!Number.isSafeInteger(value.requestedInputCount) ||
+        Number(value.requestedInputCount) < 0)
+        throw new Error("native_dispatch_invalid");
+    if (value.acceptedInputCount !== undefined &&
+        (!Number.isSafeInteger(value.acceptedInputCount) ||
+            Number(value.acceptedInputCount) < 0))
+        throw new Error("native_dispatch_invalid");
+    return value;
+}
+/** JSON is mechanical helper data; only validated native image bytes cross this boundary. */
+export function readUnixNativeResult(value, platform) {
+    if (!isRecord(value))
+        throw new Error("native_result_invalid");
+    const { imageBase64, ...metadata } = value;
+    const result = readNativeComputerResult(metadata);
+    if (result.desktop.platform !== platform)
+        throw new Error("native_desktop_invalid");
+    let image;
+    if (imageBase64 !== undefined) {
+        if (typeof imageBase64 !== "string" ||
+            imageBase64.length > Math.ceil(NATIVE_PNG_LIMIT / 3) * 4)
+            throw new Error("native_image_limit");
+        if (!/^[A-Za-z0-9+/]*={0,2}$/u.test(imageBase64))
+            throw new Error("native_image_invalid");
+        const bytes = Buffer.from(imageBase64, "base64");
+        if (bytes.length > NATIVE_PNG_LIMIT ||
+            !bytes
+                .subarray(0, 8)
+                .equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+            throw new Error("native_image_invalid");
+        if (!result.observation)
+            throw new Error("native_image_without_observation");
+        image = { mimeType: "image/png", bytes };
+    }
+    return { ...result, ...(image ? { image } : {}) };
+}

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

@@ -0,0 +1,2 @@
+/** Bounded UIA view rooted in the focused document; unrelated document trees are excluded. */
+export declare const WINDOWS_ACCESSIBILITY_SCRIPT: string;

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

@@ -0,0 +1,87 @@
+/** Bounded UIA view rooted in the focused document; unrelated document trees are excluded. */
+export const WINDOWS_ACCESSIBILITY_SCRIPT = String.raw `
+public static partial class AbotComputer {
+  static AutomationElement FocusedDocument(AutomationElement root) {
+    try {
+      var item=AutomationElement.FocusedElement;
+      AutomationElement document=null;
+      for(int depth=0;depth<64 && item!=null;depth++) {
+        if(item.Equals(root)) return document;
+        if(item.Current.ControlType==ControlType.Document) document=item;
+        item=TreeWalker.ControlViewWalker.GetParent(item);
+      }
+    } catch {}
+    return null;
+  }
+  static bool HasVisibleIntersection(System.Windows.Rect bounds,Rect region) {
+    if(bounds.IsEmpty || bounds.Width<1 || bounds.Height<1) return false;
+    if(Double.IsInfinity(bounds.X) || Double.IsInfinity(bounds.Y)) return false;
+    if(bounds.Right<=region.Left || bounds.Bottom<=region.Top) return false;
+    return bounds.Left<region.Right && bounds.Top<region.Bottom;
+  }
+  static string BoundedText(string text,int maximum) {
+    if(text==null) return "";
+    return text.Length<=maximum?text:text.Substring(0,maximum);
+  }
+  static Dictionary<string,object> AccessibilityNode(AutomationElement element,bool leaf,Rect region) {
+    var current=element.Current;
+    if(current.IsOffscreen || current.IsPassword) return null;
+    var bounds=current.BoundingRectangle;
+    if(!HasVisibleIntersection(bounds,region)) return null;
+    var node=Obj("role",current.ControlType.ProgrammaticName.Replace("ControlType.",""),
+      "name",BoundedText(current.Name,512),"focused",current.HasKeyboardFocus,
+      "bounds",Rectangle((int)Math.Round(bounds.X),(int)Math.Round(bounds.Y),
+        Math.Max(1,(int)Math.Round(bounds.Width)),Math.Max(1,(int)Math.Round(bounds.Height))));
+    // Parent text/value patterns can include invisible or protected descendants.
+    if(!leaf) return node;
+    object pattern;
+    if(element.TryGetCurrentPattern(ValuePattern.Pattern,out pattern)) {
+      node["value"]=BoundedText(((ValuePattern)pattern).Current.Value,2048);
+      return node;
+    }
+    if(!element.TryGetCurrentPattern(TextPattern.Pattern,out pattern)) return node;
+    var parts=new List<string>(); int remaining=2048;
+    foreach(var range in ((TextPattern)pattern).GetVisibleRanges()) {
+      if(remaining<=0) break;
+      string text=range.GetText(remaining);
+      parts.Add(text); remaining-=text.Length;
+    }
+    node["value"]=BoundedText(String.Join("\n",parts.ToArray()),2048);
+    return node;
+  }
+  static List<object> ReadAccessibility(Rect region,out bool truncated) {
+    var nodes=new List<object>(); truncated=true;
+    try {
+      IntPtr foreground=GetForegroundWindow();
+      if(foreground==IntPtr.Zero) return nodes;
+      var root=AutomationElement.FromHandle(foreground);
+      var document=FocusedDocument(root);
+      var queue=new Queue<AutomationElement>(); queue.Enqueue(document ?? root);
+      var walker=TreeWalker.ControlViewWalker;
+      var watch=Stopwatch.StartNew(); int visited=0,bytes=0;
+      while(queue.Count>0 && nodes.Count<128 && visited<600 && watch.ElapsedMilliseconds<500) {
+        var element=queue.Dequeue(); visited++;
+        try {
+          if(element.Current.IsPassword || element.Current.IsOffscreen) continue;
+          if(document==null && element.Current.ControlType==ControlType.Document) continue;
+          var child=walker.GetFirstChild(element);
+          var node=AccessibilityNode(element,child==null,region);
+          if(node!=null) {
+            int nodeBytes=Encoding.UTF8.GetByteCount(Json.Serialize(node));
+            if(bytes+nodeBytes>32768) return nodes;
+            nodes.Add(node); bytes+=nodeBytes;
+          }
+          int siblings=0;
+          while(child!=null && siblings<600 && queue.Count<600 && watch.ElapsedMilliseconds<500) {
+            queue.Enqueue(child); siblings++; child=walker.GetNextSibling(child);
+          }
+        } catch(ElementNotAvailableException) {}
+        catch(InvalidOperationException) {}
+      }
+      // Visible UIA is a subset of pixels even when its bounded traversal exhausted the queue.
+      truncated=true;
+    } catch {}
+    return nodes;
+  }
+}
+`;

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

@@ -0,0 +1,7 @@
+import type { SystemTarget } from "../contracts.js";
+import type { NativeComputerBackend } from "./native-protocol.js";
+import { runWindowsComputerHelper } from "./windows-helper-process.js";
+/** Native Windows and WSL interop use the same target-owned PowerShell executable. */
+export declare function createWindowsComputerBackend(target: SystemTarget, dependencies?: {
+    runHelper?: typeof runWindowsComputerHelper;
+}): NativeComputerBackend;

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

@@ -0,0 +1,50 @@
+import { readNativeComputerRequest } from "./native-validation.js";
+import { runWindowsComputerHelper } from "./windows-helper-process.js";
+import { WINDOWS_COMPUTER_SOURCE } from "./windows-helper-script.js";
+import { decodeWindowsComputerResult, windowsHelperUnavailable } from "./windows-result.js";
+/** Native Windows and WSL interop use the same target-owned PowerShell executable. */
+export function createWindowsComputerBackend(target, dependencies = {}) {
+    if (target.id !== "windows")
+        throw new Error("Windows backend requires a Windows target.");
+    const runHelper = dependencies.runHelper ?? runWindowsComputerHelper;
+    const active = new Map();
+    let closed = false;
+    return {
+        async execute(request, signal) {
+            if (closed)
+                return windowsHelperUnavailable(request, "computer_backend_closed", false);
+            if (signal?.aborted)
+                return windowsHelperUnavailable(request, "computer_helper_aborted", false);
+            let validated;
+            try {
+                validated = readNativeComputerRequest(request);
+            }
+            catch {
+                return windowsHelperUnavailable(request, "computer_input_invalid", false);
+            }
+            if (validated.operation === "act" && validated.deadlineEpochMs <= Date.now())
+                return windowsHelperUnavailable(validated, "computer_action_expired", false);
+            const controller = new AbortController();
+            const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+            const pending = runHelper({
+                executable: target.shell,
+                source: WINDOWS_COMPUTER_SOURCE,
+                request: validated,
+                signal: combined,
+            }).then((result) => decodeWindowsComputerResult(result, validated));
+            active.set(controller, pending);
+            try {
+                return await pending;
+            }
+            finally {
+                active.delete(controller);
+            }
+        },
+        async close() {
+            closed = true;
+            for (const controller of active.keys())
+                controller.abort();
+            await Promise.allSettled(active.values());
+        },
+    };
+}

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

@@ -0,0 +1,2 @@
+/** Pixel capture and image bounds. Cropped pixels remain visible desktop pixels, including occlusion. */
+export declare const WINDOWS_CAPTURE_SCRIPT: string;

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

@@ -0,0 +1,69 @@
+/** Pixel capture and image bounds. Cropped pixels remain visible desktop pixels, including occlusion. */
+export const WINDOWS_CAPTURE_SCRIPT = String.raw `
+public static partial class AbotComputer {
+  static void RequireObservationSource(Dictionary<string,object> request,Dictionary<string,object> result) {
+    if(Field(request,"region")==null && Field(request,"operation") as string!="act") return;
+    var desktop=Record(result["desktop"]);
+    if(Text(request,"desktopBinding",4096)!=(string)desktop["binding"])
+      throw new ComputerFault("computer_desktop_stale","The capture belongs to a different desktop observation.");
+    if(!SameRectangle(ParseRectangle(request["expectedGeometry"]),ParseRectangle(desktop["bounds"])))
+      throw new ComputerFault("computer_geometry_changed","The display geometry changed before capture.");
+  }
+  static void CaptureObservation(Dictionary<string,object> result,object requestedRegion) {
+    RequireAvailableDesktop(result);
+    var desktop=Record(result["desktop"]);
+    string binding=(string)desktop["binding"];
+    Rect virtualBounds=ParseRectangle(desktop["bounds"]);
+    Rect region=requestedRegion==null?virtualBounds:ParseRectangle(requestedRegion);
+    if(!ContainsRectangle(virtualBounds,region))
+      throw new ComputerFault("computer_region_outside_desktop","The requested region is outside the physical desktop.");
+    int width=region.Right-region.Left,height=region.Bottom-region.Top;
+    if((long)width*height>64000000)
+      throw new ComputerFault("computer_capture_too_large","Select a smaller physical capture region.");
+    string foreground=NativeWindowBinding(GetForegroundWindow());
+    if(!Object.Equals(Field(result,"focusedWindow"),foreground))
+      throw new ComputerFault("computer_focus_changed","Focus changed before capture; obtain a fresh observation.");
+    VerifyDesktopBinding(binding);
+    int imageWidth,imageHeight;
+    byte[] image=CapturePixels(region,out imageWidth,out imageHeight);
+    bool truncated;
+    var accessibility=ReadAccessibility(region,out truncated);
+    VerifyDesktopBinding(binding);
+    if(!SameRectangle(VirtualDesktopBounds(),virtualBounds))
+      throw new ComputerFault("computer_geometry_changed","The display geometry changed during observation.");
+    if(NativeWindowBinding(GetForegroundWindow())!=foreground)
+      throw new ComputerFault("computer_focus_changed","Focus changed during observation; obtain a fresh observation.");
+    result["observation"]=Obj("capturedAt",DateTime.UtcNow.ToString("o"),
+      "region",Rectangle(region.Left,region.Top,width,height),"imageWidth",imageWidth,"imageHeight",imageHeight,
+      "accessibility",accessibility,"accessibilityTruncated",truncated);
+    result["image"]=Obj("mimeType","image/png","base64",Convert.ToBase64String(image));
+  }
+  static byte[] CapturePixels(Rect region,out int imageWidth,out int imageHeight) {
+    int width=region.Right-region.Left,height=region.Bottom-region.Top;
+    using(var original=new Bitmap(width,height,PixelFormat.Format32bppArgb)) {
+      using(var graphics=Graphics.FromImage(original)) {
+        graphics.CopyFromScreen(region.Left,region.Top,0,0,new Size(width,height),CopyPixelOperation.SourceCopy);
+      }
+      int maxDimension=2048;
+      while(maxDimension>=256) {
+        double scale=Math.Min(1.0,(double)maxDimension/Math.Max(width,height));
+        imageWidth=Math.Max(1,(int)Math.Round(width*scale));
+        imageHeight=Math.Max(1,(int)Math.Round(height*scale));
+        using(var resized=new Bitmap(imageWidth,imageHeight,PixelFormat.Format32bppArgb)) {
+          using(var graphics=Graphics.FromImage(resized)) {
+            graphics.InterpolationMode=System.Drawing.Drawing2D.InterpolationMode.HighQualityBicubic;
+            graphics.DrawImage(original,0,0,imageWidth,imageHeight);
+          }
+          using(var stream=new MemoryStream()) {
+            resized.Save(stream,ImageFormat.Png);
+            if(stream.Length<=ImageMaxBytes) return stream.ToArray();
+          }
+        }
+        maxDimension/=2;
+      }
+    }
+    imageWidth=0; imageHeight=0;
+    throw new ComputerFault("computer_capture_too_large","The screenshot exceeds the image byte limit.");
+  }
+}
+`;

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

@@ -0,0 +1,2 @@
+/** Native login/desktop identity and window inspection; never infers browser tabs. */
+export declare const WINDOWS_DESKTOP_SCRIPT: string;

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

@@ -0,0 +1,129 @@
+/** Native login/desktop identity and window inspection; never infers browser tabs. */
+export const WINDOWS_DESKTOP_SCRIPT = String.raw `
+public static partial class AbotComputer {
+  static Dictionary<string,object> Capability(bool available,string reason) {
+    var result=Obj("supported",true,"available",available);
+    if(!String.IsNullOrEmpty(reason)) result["reason"]=reason;
+    return result;
+  }
+  static Dictionary<string,object> UnavailableResult(string reason) {
+    return Obj("desktop",Obj("platform","windows","binding","windows:unavailable",
+      "name","Windows desktop","available",false,"reason",reason,"bounds",Rectangle(0,0,1,1),
+      "capabilities",Obj("capture",Capability(false,reason),"accessibility",Capability(false,reason),
+        "input",Capability(false,reason),"windows",Capability(false,reason)),
+      "targetingGuarantee","observed_surface"),"windows",new object[0]);
+  }
+  static string NativeLogonIdentity() {
+    IntPtr token;
+    if(!OpenProcessToken(Process.GetCurrentProcess().Handle,0x0008,out token)) return null;
+    try {
+      TokenStatistics information; int needed;
+      if(!GetTokenInformation(token,10,out information,Marshal.SizeOf(typeof(TokenStatistics)),out needed)) return null;
+      return information.AuthenticationId.High.ToString("X8")+information.AuthenticationId.Low.ToString("X8");
+    } finally { CloseHandle(token); }
+  }
+  static string InputDesktopName() {
+    IntPtr desktop=OpenInputDesktop(0,false,0x0001);
+    if(desktop==IntPtr.Zero) return null;
+    try {
+      var name=new StringBuilder(128); int needed;
+      if(!GetUserObjectInformation(desktop,2,name,name.Capacity*2,out needed)) return null;
+      return name.ToString();
+    } finally { CloseDesktop(desktop); }
+  }
+  static Rect VirtualDesktopBounds() {
+    int x=GetSystemMetrics(76),y=GetSystemMetrics(77);
+    return new Rect { Left=x,Top=y,Right=x+GetSystemMetrics(78),Bottom=y+GetSystemMetrics(79) };
+  }
+  static string ReadDesktopBinding(out string reason) {
+    reason=null;
+    int session=Process.GetCurrentProcess().SessionId;
+    if(session==0) { reason="interactive_session_unavailable"; return null; }
+    string desktop=InputDesktopName();
+    if(desktop!="Default") { reason="screen_locked_or_secure_desktop"; return null; }
+    string logon=NativeLogonIdentity();
+    if(logon==null) { reason="login_identity_unavailable"; return null; }
+    string topology;
+    try { topology=ReadCaptureTopology(); }
+    catch(ComputerFault fault) { reason=fault.Code; return null; }
+    return "windows:"+Environment.MachineName+":"+session+":"+logon+":"+desktop+":"+topology;
+  }
+  static string NativeWindowBinding(IntPtr window) {
+    if(window==IntPtr.Zero || !IsWindow(window)) return null;
+    uint processId; GetWindowThreadProcessId(window,out processId);
+    if(processId==0) return null;
+    try {
+      using(var process=Process.GetProcessById((int)processId)) {
+        return window.ToInt64().ToString("X")+":"+processId+":"+process.StartTime.ToUniversalTime().Ticks;
+      }
+    } catch { return null; }
+  }
+  static IntPtr ResolveWindowBinding(string binding) {
+    string[] parts=binding.Split(':'); long handle;
+    if(parts.Length!=3 || !Int64.TryParse(parts[0],System.Globalization.NumberStyles.HexNumber,
+      System.Globalization.CultureInfo.InvariantCulture,out handle))
+      throw new ComputerFault("computer_window_stale","The window reference is invalid.");
+    var window=new IntPtr(handle);
+    if(NativeWindowBinding(window)!=binding)
+      throw new ComputerFault("computer_window_stale","The selected native window no longer exists.");
+    return window;
+  }
+  static Dictionary<string,object> ReadWindow(IntPtr window,IntPtr foreground) {
+    if(!IsWindowVisible(window)) return null;
+    string binding=NativeWindowBinding(window);
+    if(binding==null) return null;
+    Rect bounds;
+    if(!GetWindowRect(window,out bounds)) return null;
+    if(bounds.Right<=bounds.Left || bounds.Bottom<=bounds.Top) return null;
+    var title=new StringBuilder(513); GetWindowText(window,title,title.Capacity);
+    var result=Obj("binding",binding,"title",title.ToString(),
+      "bounds",Rectangle(bounds.Left,bounds.Top,bounds.Right-bounds.Left,bounds.Bottom-bounds.Top),
+      "focused",window==foreground);
+    try {
+      uint processId; GetWindowThreadProcessId(window,out processId);
+      using(var process=Process.GetProcessById((int)processId)) result["application"]=process.ProcessName;
+    } catch {}
+    return result;
+  }
+  static Dictionary<string,object> DesktopSnapshot() {
+    string reason; string binding=ReadDesktopBinding(out reason);
+    if(binding==null) return UnavailableResult(reason);
+    Rect bounds=VirtualDesktopBounds();
+    if(bounds.Right<=bounds.Left || bounds.Bottom<=bounds.Top) return UnavailableResult("desktop_geometry_unavailable");
+    IntPtr foreground=GetForegroundWindow();
+    string focused=NativeWindowBinding(foreground);
+    var windows=new List<object>(); int windowBytes=0;
+    // Capture the foreground first so bounded enumeration cannot omit the selected source.
+    var active=ReadWindow(foreground,foreground);
+    if(active!=null) { windows.Add(active); windowBytes=Encoding.UTF8.GetByteCount(Json.Serialize(active)); }
+    EnumWindowCallback callback=(window,parameter)=> {
+      if(window==foreground) return true;
+      if(windows.Count>=128 || windowBytes>=32768) return false;
+      var value=ReadWindow(window,foreground);
+      if(value==null) return true;
+      int bytes=Encoding.UTF8.GetByteCount(Json.Serialize(value));
+      if(windowBytes+bytes>32768) return false;
+      windows.Add(value); windowBytes+=bytes; return true;
+    };
+    EnumWindows(callback,IntPtr.Zero);
+    var result=Obj("desktop",Obj("platform","windows","binding",binding,
+      "name",Environment.MachineName+" / Windows desktop","available",true,
+      "bounds",Rectangle(bounds.Left,bounds.Top,bounds.Right-bounds.Left,bounds.Bottom-bounds.Top),
+      "capabilities",Obj("capture",Capability(true,null),"accessibility",Capability(true,"visible_accessibility_subset"),
+        "input",Capability(true,"uipi_may_restrict_input"),"windows",Capability(true,"window_enumeration_bounded")),
+      "targetingGuarantee",focused==null?"observed_surface":"verified_window"),"windows",windows);
+    if(focused!=null) result["focusedWindow"]=focused;
+    return result;
+  }
+  static void RequireAvailableDesktop(Dictionary<string,object> result) {
+    var desktop=Record(result["desktop"]);
+    if(!Object.Equals(Field(desktop,"available"),true))
+      throw new ComputerFault("computer_desktop_unavailable","The interactive desktop is unavailable or locked.");
+  }
+  static void VerifyDesktopBinding(string expected) {
+    string reason;
+    if(ReadDesktopBinding(out reason)!=expected)
+      throw new ComputerFault("computer_desktop_changed","The login or interactive desktop changed.");
+  }
+}
+`;

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

@@ -0,0 +1,18 @@
+import { spawn } from "node:child_process";
+import type { NativeComputerRequest } from "./native-protocol.js";
+export declare const WINDOWS_IMAGE_MAX_BYTES: number;
+export declare const WINDOWS_HELPER_MAX_BYTES: number;
+export type WindowsHelperProcessResult = Readonly<{
+    status: "completed" | "aborted" | "timeout" | "spawn_failed" | "output_limit";
+    stdout: string;
+    spawned: boolean;
+    exitCode?: number;
+}>;
+/** One invocation, no helper files, no child commands and no replay after interruption. */
+export declare function runWindowsComputerHelper(input: {
+    executable: string;
+    source: string;
+    request: NativeComputerRequest;
+    signal?: AbortSignal;
+    spawnProcess?: typeof spawn;
+}): Promise<WindowsHelperProcessResult>;