@abot-ai/runtime 1.4.0 → 1.5.0

package/dist/src/computer-access/computer/native-validation.js

@@ -0,0 +1,152 @@
+import { computerFields, computerInputError, computerNumber, computerRecord, computerText, readNativeComputerAction, readPhysicalRectangle, } from "./action-input.js";
+export const COMPUTER_IMAGE_MAX_BYTES = 10 * 1024 * 1024;
+export const COMPUTER_FRAME_CHUNK_BYTES = 64 * 1024;
+export const COMPUTER_CAPABILITY = "computer_control_v1";
+export function readNativeComputerRequest(value) {
+    const request = computerRecord(value);
+    if (request.operation === "inspect") {
+        computerFields(request, ["operation"]);
+        return { operation: request.operation };
+    }
+    if (request.operation === "observe") {
+        return readNativeObservationRequest(request);
+    }
+    if (request.operation !== "act")
+        return computerInputError("Unknown desktop request.");
+    computerFields(request, [
+        "operation",
+        "desktopBinding",
+        "expectedWindow",
+        "expectedGeometry",
+        "action",
+        "deadlineEpochMs",
+    ]);
+    return {
+        operation: request.operation,
+        desktopBinding: computerText(request.desktopBinding),
+        ...(request.expectedWindow === undefined
+            ? {}
+            : { expectedWindow: computerText(request.expectedWindow) }),
+        expectedGeometry: readPhysicalRectangle(request.expectedGeometry),
+        action: readNativeComputerAction(request.action),
+        deadlineEpochMs: computerNumber(request.deadlineEpochMs, 0, Number.MAX_SAFE_INTEGER),
+    };
+}
+function readNativeObservationRequest(request) {
+    if (request.region === undefined) {
+        computerFields(request, ["operation"]);
+        return {
+            operation: "observe",
+        };
+    }
+    computerFields(request, [
+        "operation",
+        "region",
+        "desktopBinding",
+        "expectedGeometry",
+    ]);
+    return {
+        operation: "observe",
+        region: readPhysicalRectangle(request.region),
+        desktopBinding: computerText(request.desktopBinding),
+        expectedGeometry: readPhysicalRectangle(request.expectedGeometry),
+    };
+}
+/** Validate the private transport independently of trusted TypeScript declarations. */
+export function readNativeComputerResult(value) {
+    const result = computerRecord(value);
+    computerFields(result, [
+        "desktop",
+        "windows",
+        "focusedWindow",
+        "observation",
+        "dispatch",
+        "error",
+    ]);
+    if (Buffer.byteLength(JSON.stringify(value)) > 96 * 1024)
+        return computerInputError("Desktop metadata exceeds its limit.");
+    const desktop = computerRecord(result.desktop);
+    if (!["windows", "macos", "linux"].includes(String(desktop.platform)))
+        return computerInputError("Invalid desktop platform.");
+    computerText(desktop.binding);
+    computerText(desktop.name);
+    if (desktop.reason !== undefined)
+        computerText(desktop.reason);
+    if (desktop.coordinateSpace !== undefined &&
+        !["physical_pixels", "logical_points"].includes(String(desktop.coordinateSpace)))
+        return computerInputError("Invalid desktop coordinate space.");
+    if (typeof desktop.available !== "boolean")
+        return computerInputError("Invalid desktop availability.");
+    readPhysicalRectangle(desktop.bounds);
+    if (!["verified_window", "observed_surface"].includes(String(desktop.targetingGuarantee)))
+        return computerInputError("Invalid targeting guarantee.");
+    const capabilities = computerRecord(desktop.capabilities);
+    for (const kind of ["capture", "accessibility", "input", "windows"]) {
+        const capability = computerRecord(capabilities[kind]);
+        if (capability.reason !== undefined)
+            computerText(capability.reason);
+        if (typeof capability.supported !== "boolean" ||
+            typeof capability.available !== "boolean")
+            return computerInputError("Invalid desktop capability.");
+    }
+    if (!Array.isArray(result.windows) || result.windows.length > 256)
+        return computerInputError("Invalid window list.");
+    for (const raw of result.windows) {
+        const window = computerRecord(raw);
+        computerText(window.binding);
+        computerText(window.title);
+        if (window.application !== undefined)
+            computerText(window.application);
+        readPhysicalRectangle(window.bounds);
+        if (typeof window.focused !== "boolean")
+            return computerInputError("Invalid window focus.");
+    }
+    if (result.focusedWindow !== undefined)
+        computerText(result.focusedWindow);
+    if (result.observation !== undefined)
+        validateObservation(result.observation);
+    if (result.dispatch !== undefined) {
+        const dispatch = computerRecord(result.dispatch);
+        if (!["not_dispatched", "accepted", "partial", "unknown"].includes(String(dispatch.status)))
+            return computerInputError("Invalid input dispatch status.");
+        readInputCount(dispatch.requestedInputCount);
+        if (dispatch.acceptedInputCount !== undefined)
+            readInputCount(dispatch.acceptedInputCount);
+        if (dispatch.reason !== undefined)
+            computerText(dispatch.reason);
+    }
+    if (result.error !== undefined) {
+        const error = computerRecord(result.error);
+        computerText(error.code, 128);
+        computerText(error.message);
+    }
+    return value;
+}
+function readInputCount(value) {
+    const count = computerNumber(value, 0, 100000);
+    if (!Number.isInteger(count))
+        return computerInputError("Invalid input event count.");
+    return count;
+}
+function validateObservation(value) {
+    const observation = computerRecord(value);
+    computerText(observation.capturedAt, 128);
+    readPhysicalRectangle(observation.region);
+    computerNumber(observation.imageWidth, 1, 65536);
+    computerNumber(observation.imageHeight, 1, 65536);
+    if (!Array.isArray(observation.accessibility) ||
+        observation.accessibility.length > 512)
+        return computerInputError("Invalid accessibility observation.");
+    if (typeof observation.accessibilityTruncated !== "boolean")
+        return computerInputError("Invalid accessibility coverage.");
+    for (const raw of observation.accessibility) {
+        const node = computerRecord(raw);
+        computerText(node.role, 128);
+        if (node.name !== undefined)
+            computerText(node.name);
+        if (node.value !== undefined)
+            computerText(node.value);
+        if (node.bounds !== undefined)
+            readPhysicalRectangle(node.bounds);
+    }
+}

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

@@ -0,0 +1,12 @@
+import { spawn } from "node:child_process";
+import type { ComputerPlatform, NativeComputerBackend } from "./native-protocol.js";
+export type UnixNativeProcessOptions = Readonly<{
+    platform: ComputerPlatform;
+    file: string;
+    args: readonly string[];
+    spawnProcess?: typeof spawn;
+    timeoutMs?: number;
+    cancellationGraceMs?: number;
+}>;
+/** Owns one helper lifetime. Input is never replayed after timeout, abort or process loss. */
+export declare function createUnixNativeProcess(options: UnixNativeProcessOptions): NativeComputerBackend;

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;