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

package/assets/windows.cs

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

package/dist/accessibility.d.ts

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

package/dist/accessibility.js

@@ -0,0 +1,258 @@
+import { screenshot } from "./capture.js";
+import { nativeDesktop } from "./native.js";
+import { ocrDesktop } from "./ocr.js";
+const target = {
+    windowRef: { type: "string", minLength: 1 },
+    windowTitle: { type: "string" },
+    processId: { type: "integer", minimum: 1 },
+    nativeWindowHandle: { type: "integer", minimum: 1 },
+    activate: { type: "boolean" },
+};
+const view = {
+    viewMode: {
+        type: "string",
+        enum: ["control", "content", "raw"],
+        default: "control",
+    },
+    includeOffscreen: { type: "boolean", default: false },
+};
+const browser = {
+    browserTab: { type: "string", minLength: 1 },
+};
+const detail = {
+    detailLevel: {
+        type: "string",
+        enum: ["compact", "full"],
+        default: "compact",
+    },
+};
+const tree = {
+    scope: {
+        type: "string",
+        enum: ["active_window", "desktop"],
+        default: "active_window",
+    },
+    treeTimeoutMs: {
+        type: "integer",
+        minimum: 100,
+        maximum: 30000,
+        default: 5000,
+    },
+    maxDepth: { type: "integer", minimum: 0, maximum: 12, default: 6 },
+    maxNodes: { type: "integer", minimum: 1, maximum: 3000, default: 500 },
+};
+const definitions = {
+    accessibility_tree: {
+        properties: { ...target, ...browser, ...view, ...detail, ...tree },
+    },
+    snapshot: {
+        properties: {
+            ...target,
+            ...browser,
+            ...view,
+            ...detail,
+            ...tree,
+            maxDepth: { ...tree.maxDepth, default: 5 },
+            maxNodes: { ...tree.maxNodes, maximum: 2000, default: 250 },
+            includeScreenshot: { type: "boolean", default: true },
+            captureWindow: { type: "boolean", default: false },
+            maxWidth: { type: "integer", minimum: 0, maximum: 7680, default: 1600 },
+        },
+    },
+    find: {
+        properties: {
+            ...target,
+            ...browser,
+            ...view,
+            ...tree,
+            query: { type: "string", minLength: 1 },
+            controlType: { type: "string" },
+            ocrFallback: { type: "boolean", default: true },
+            maxDepth: { ...tree.maxDepth, default: 8 },
+            maxNodes: { ...tree.maxNodes, maximum: 5000, default: 1200 },
+            maxResults: { type: "integer", minimum: 1, maximum: 200, default: 25 },
+        },
+        required: ["query"],
+    },
+    element_info: {
+        properties: {
+            ...target,
+            ...view,
+            ...detail,
+            elementId: { type: "string", minLength: 1 },
+            x: { type: "integer" },
+            y: { type: "integer" },
+        },
+    },
+    focus: {
+        properties: {
+            ...target,
+            ...view,
+            elementId: { type: "string", minLength: 1 },
+        },
+        required: ["elementId"],
+    },
+    invoke: {
+        properties: {
+            ...target,
+            ...view,
+            elementId: { type: "string", minLength: 1 },
+            action: {
+                type: "string",
+                enum: ["default", "expand", "collapse", "scroll_into_view"],
+                default: "default",
+            },
+            fallbackClick: { type: "boolean", default: true },
+        },
+        required: ["elementId"],
+    },
+    set_value: {
+        properties: {
+            ...target,
+            ...view,
+            elementId: { type: "string", minLength: 1 },
+            value: { type: "string" },
+            fallbackType: { type: "boolean", default: true },
+            restoreClipboard: { type: "boolean", default: true },
+        },
+        required: ["elementId", "value"],
+    },
+    scroll: {
+        properties: {
+            ...target,
+            ...view,
+            ...browser,
+            elementId: { type: "string", minLength: 1 },
+            x: { type: "integer" },
+            y: { type: "integer" },
+            deltaY: { type: "integer", default: 480 },
+            deltaX: { type: "integer", default: 0 },
+        },
+    },
+};
+const toolDefinitions = Object.entries(definitions).map(([action, definition]) => ({
+    action,
+    parameters: { type: "object", additionalProperties: false, ...definition },
+}));
+export const observationTools = toolDefinitions.filter((tool) => ["snapshot", "accessibility_tree", "find", "element_info"].includes(tool.action));
+export const controlTools = toolDefinitions.filter((tool) => ["focus", "invoke", "set_value", "scroll"].includes(tool.action));
+export async function executeAccessibility(action, args, signal, execute) {
+    const definition = definitions[action];
+    if (!definition)
+        return { ok: false, action, error: "UNKNOWN_ACTION" };
+    const normalized = {};
+    const invalid = (message) => ({
+        ok: false,
+        action,
+        error: `INVALID_ARGUMENTS: ${message}`,
+    });
+    for (const key of Object.keys(args))
+        if (!(key in definition.properties))
+            return invalid(`unknown option ${key}`);
+    for (const [key, rule] of Object.entries(definition.properties)) {
+        const value = Object.hasOwn(args, key) ? args[key] : rule.default;
+        if (value === undefined) {
+            if (definition.required?.includes(key))
+                return invalid(`${key} is required`);
+            continue;
+        }
+        if (rule.type === "integer"
+            ? !Number.isSafeInteger(value)
+            : typeof value !== rule.type)
+            return invalid(`${key} must be ${rule.type}`);
+        if (typeof value === "number" &&
+            ((rule.minimum !== undefined && value < rule.minimum) ||
+                (rule.maximum !== undefined && value > rule.maximum)))
+            return invalid(`${key} is outside supported bounds`);
+        if (typeof value === "string" &&
+            ((rule.enum && !rule.enum.includes(value)) ||
+                (rule.minLength && value.length < rule.minLength)))
+            return invalid(`${key} has an unsupported value`);
+        normalized[key] = value;
+    }
+    if (action === "element_info" &&
+        !normalized.elementId &&
+        (normalized.x === undefined || normalized.y === undefined))
+        return invalid("provide elementId or both x and y");
+    if (action === "scroll" && !normalized.elementId) {
+        if (normalized.x === undefined || normalized.y === undefined)
+            return invalid("provide elementId or both x and y");
+        return {
+            ok: false,
+            action,
+            error: "INPUT_SAFETY_NOT_READY: coordinate scrolling requires guarded physical input",
+            inputRequired: true,
+        };
+    }
+    signal?.throwIfAborted();
+    let result;
+    // Guarded mutation failures retain the cleanup lease; do not translate them
+    // into ordinary observation errors or clear the outer input state.
+    if (execute)
+        return execute(normalized);
+    try {
+        result = await nativeDesktop.execute(action, normalized, signal);
+    }
+    catch (error) {
+        result = {
+            ok: false,
+            action,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    if (action === "snapshot" && normalized.includeScreenshot) {
+        delete result.screenshotPending;
+        const windowCapture = normalized.captureWindow && normalized.scope !== "desktop";
+        const captureArgs = {
+            scope: windowCapture ? "active_window" : "desktop",
+            maxWidth: normalized.maxWidth,
+        };
+        if (windowCapture) {
+            for (const key of [
+                "windowRef",
+                "windowTitle",
+                "processId",
+                "nativeWindowHandle",
+                "activate",
+            ]) {
+                const value = result[key] ?? normalized[key];
+                if (value !== undefined)
+                    captureArgs[key] = value;
+            }
+        }
+        const captured = await screenshot(captureArgs, signal);
+        if (captured.ok && captured.screenshot)
+            result.screenshot = captured.screenshot;
+        else {
+            result.partial = true;
+            result.screenshotError = String(captured.error ?? "SCREENSHOT_UNAVAILABLE");
+        }
+    }
+    if (action === "find" && result.ocrFallbackPending) {
+        delete result.ocrFallbackPending;
+        const ocrArgs = {
+            query: normalized.query,
+            scope: normalized.scope,
+        };
+        for (const key of [
+            "windowRef",
+            "windowTitle",
+            "processId",
+            "nativeWindowHandle",
+            "activate",
+        ]) {
+            const value = result[key] ?? normalized[key];
+            if (value !== undefined)
+                ocrArgs[key] = value;
+        }
+        const recognized = await ocrDesktop(ocrArgs, signal);
+        result.ocr = recognized;
+        if (recognized.ok)
+            result.ocrCandidates = recognized.matched ?? [];
+        else {
+            result.ocrError = recognized.error;
+            result.conclusive = false;
+        }
+    }
+    return result;
+}

package/dist/browser-actions.d.ts

@@ -0,0 +1,22 @@
+type Rule = {
+    type: string;
+    default?: unknown;
+    enum?: string[];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    minItems?: number;
+    items?: Rule;
+};
+export declare const browserActionTools: {
+    action: string;
+    parameters: {
+        properties: Record<string, Rule>;
+        required?: string[];
+        type: string;
+        additionalProperties: boolean;
+    };
+}[];
+export declare function browserActionRefusal(action: string, args: Record<string, unknown>): string | undefined;
+export declare function normalizeBrowserAction(action: string, args: Record<string, unknown>): Record<string, unknown> | undefined;
+export {};

package/dist/browser-actions.js

@@ -0,0 +1,246 @@
+import { timingMilliseconds } from "./input-timing.js";
+// Shared reference-compatible tool schemas; browser execution stays in browser.ts.
+const target = {
+    windowRef: { type: "string", minLength: 1 },
+    windowTitle: { type: "string" },
+    processId: { type: "integer", minimum: 1 },
+    nativeWindowHandle: { type: "integer", minimum: 1 },
+    activate: { type: "boolean", default: false },
+};
+const view = {
+    viewMode: {
+        type: "string",
+        enum: ["control", "content", "raw"],
+        default: "control",
+    },
+    includeOffscreen: { type: "boolean", default: false },
+};
+const tab = { browserTab: { type: "string", minLength: 1 } };
+const element = { elementId: { type: "string", minLength: 1 } };
+const point = { x: { type: "integer" }, y: { type: "integer" } };
+const button = {
+    type: "string",
+    enum: ["left", "right", "middle"],
+    default: "left",
+};
+const dispatch = {
+    type: "string",
+    enum: ["auto", "background", "foreground"],
+    default: "auto",
+};
+const definitions = {
+    click: {
+        properties: {
+            ...target,
+            ...view,
+            ...element,
+            ...point,
+            button,
+            dispatch,
+            holdMs: timingMilliseconds,
+            timeoutMs: timingMilliseconds,
+        },
+    },
+    double_click: {
+        properties: { ...target, ...view, ...element, ...point, button, dispatch },
+    },
+    move: { properties: { ...target, ...view, ...element, ...point } },
+    scroll: {
+        properties: {
+            ...target,
+            ...view,
+            ...tab,
+            ...element,
+            ...point,
+            deltaY: { type: "integer", default: 480 },
+            deltaX: { type: "integer", default: 0 },
+        },
+    },
+    type_text: {
+        required: ["text"],
+        properties: {
+            ...target,
+            ...tab,
+            text: { type: "string" },
+            method: {
+                type: "string",
+                enum: ["auto", "clipboard", "sendinput", "background"],
+                default: "auto",
+            },
+            focusMode: {
+                type: "string",
+                enum: ["preserve", "main"],
+                default: "preserve",
+            },
+            restoreClipboard: { type: "boolean", default: true },
+            inputDelayMs: timingMilliseconds,
+            timeoutMs: timingMilliseconds,
+        },
+    },
+    keypress: {
+        required: ["keys"],
+        properties: {
+            holdMs: timingMilliseconds,
+            timeoutMs: timingMilliseconds,
+            ...target,
+            ...tab,
+            keys: {
+                type: "array",
+                minItems: 1,
+                items: { type: "string", minLength: 1 },
+            },
+            dispatch: {
+                type: "string",
+                enum: ["foreground", "background"],
+                default: "foreground",
+            },
+        },
+    },
+    focus: {
+        required: ["elementId"],
+        properties: { ...target, ...view, ...element },
+    },
+    invoke: {
+        required: ["elementId"],
+        properties: {
+            ...target,
+            ...view,
+            ...element,
+            action: {
+                type: "string",
+                enum: ["default", "expand", "collapse", "scroll_into_view"],
+                default: "default",
+            },
+            fallbackClick: { type: "boolean", default: true },
+        },
+    },
+    set_value: {
+        required: ["elementId", "value"],
+        properties: {
+            ...target,
+            ...view,
+            ...element,
+            value: { type: "string" },
+            fallbackType: { type: "boolean", default: true },
+            restoreClipboard: { type: "boolean", default: true },
+        },
+    },
+    activate_window: { properties: { ...target, ...tab } },
+    close_window: { properties: { ...target, ...tab } },
+    wait_for: {
+        properties: {
+            ...target,
+            ...tab,
+            ...view,
+            condition: {
+                type: "string",
+                enum: ["window", "element", "text"],
+                default: "window",
+            },
+            query: { type: "string" },
+            controlType: { type: "string" },
+            scope: {
+                type: "string",
+                enum: ["active_window", "desktop"],
+                default: "active_window",
+            },
+            treeTimeoutMs: {
+                type: "integer",
+                minimum: 100,
+                maximum: 30000,
+                default: 1000,
+            },
+            maxDepth: { type: "integer", minimum: 0, maximum: 12, default: 8 },
+            maxNodes: { type: "integer", minimum: 1, maximum: 5000, default: 1200 },
+            appear: { type: "boolean", default: true },
+            timeoutMs: {
+                type: "integer",
+                minimum: 100,
+                maximum: 60000,
+                default: 5000,
+            },
+            intervalMs: { type: "integer", minimum: 50, maximum: 5000, default: 250 },
+        },
+    },
+};
+export const browserActionTools = Object.entries(definitions).map(([action, definition]) => ({
+    action,
+    parameters: { type: "object", additionalProperties: false, ...definition },
+}));
+export function browserActionRefusal(action, args) {
+    if (action === "click" &&
+        (args.holdMs !== undefined || args.timeoutMs !== undefined))
+        return "TIMING_UNSUPPORTED: click timing requires native foreground dispatch";
+    if (action === "keypress" &&
+        (args.holdMs !== undefined ||
+            args.timeoutMs !== undefined ||
+            (Array.isArray(args.keys) &&
+                args.keys.length === 1 &&
+                /^(ctrl|control|alt|option|shift)$/i.test(String(args.keys[0]).trim()))))
+        return "TIMING_UNSUPPORTED: keypress timing and standalone modifiers require native foreground dispatch";
+    if (action === "type_text" &&
+        (args.inputDelayMs !== undefined || args.timeoutMs !== undefined))
+        return "TIMING_UNSUPPORTED: text timing requires explicit native sendinput";
+    return undefined;
+}
+export function normalizeBrowserAction(action, args) {
+    const refusal = browserActionRefusal(action, args);
+    if (refusal)
+        throw new Error(refusal);
+    const definition = definitions[action];
+    if (!definition)
+        return undefined;
+    const properties = { ...definition.properties, ...tab };
+    for (const key of Object.keys(args))
+        if (!Object.hasOwn(properties, key))
+            throw new Error(`INVALID_ARGUMENTS: unknown option ${key}`);
+    const normalized = {};
+    const check = (name, value, rule) => {
+        if (rule.type === "array") {
+            if (!Array.isArray(value) ||
+                value.length < (rule.minItems ?? 0) ||
+                value.length > 10000)
+                throw new Error(`INVALID_ARGUMENTS: ${name} must be an array with supported length`);
+            if (rule.items)
+                for (const child of value)
+                    check(name, child, rule.items);
+        }
+        else if (rule.type === "integer"
+            ? !Number.isSafeInteger(value)
+            : typeof value !== rule.type)
+            throw new Error(`INVALID_ARGUMENTS: ${name} must be ${rule.type}`);
+        if ((typeof value === "number" &&
+            ((rule.minimum !== undefined && value < rule.minimum) ||
+                (rule.maximum !== undefined && value > rule.maximum))) ||
+            (typeof value === "string" &&
+                ((rule.enum && !rule.enum.includes(value)) ||
+                    (rule.minLength !== undefined && value.length < rule.minLength))))
+            throw new Error(`INVALID_ARGUMENTS: ${name} has an unsupported value`);
+    };
+    for (const [key, rule] of Object.entries(properties)) {
+        const value = Object.hasOwn(args, key) ? args[key] : rule.default;
+        if (value === undefined) {
+            if (definition.required?.includes(key))
+                throw new Error(`INVALID_ARGUMENTS: ${key} is required`);
+            continue;
+        }
+        check(key, value, rule);
+        normalized[key] = value;
+    }
+    if (action === "keypress") {
+        const keys = normalized.keys;
+        if (keys.some((key) => /^(win|windows|meta|cmd|command)$/i.test(key)))
+            throw new Error("INVALID_ARGUMENTS: Windows key is blocked");
+        if (keys.filter((key) => !/^(ctrl|control|alt|option|shift)$/i.test(key))
+            .length !== 1)
+            throw new Error("INVALID_ARGUMENTS: keypress needs exactly one non-modifier key");
+    }
+    if (action === "invoke" && normalized.action !== "default")
+        throw new Error("INVALID_ARGUMENTS: non-default invoke actions apply only to UI Automation elements");
+    if (action === "wait_for" &&
+        (normalized.condition === "window" ||
+            typeof normalized.query !== "string" ||
+            !normalized.query.trim()))
+        throw new Error("INVALID_ARGUMENTS: browser wait_for requires element/text condition and query");
+    return normalized;
+}