@google/adk 2.4.0 → 2.5.0

package/dist/esm/tools/computer_use/computer_use_actions.js

@@ -0,0 +1,477 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Type } from "@google/genai";
+import { isBrowser } from "../../utils/env_aware_utils.js";
+import { logger } from "../../utils/logger.js";
+import {
+  isHttpUrl,
+  isIpAddress,
+  isNonGlobalAddress,
+  normalizeHost,
+  resolveHostAddresses
+} from "../../utils/ssrf_guard.js";
+const LEGACY_ACTION_NAMES = [
+  "open_web_browser",
+  "click_at",
+  "hover_at",
+  "type_text_at",
+  "scroll_document",
+  "scroll_at",
+  "wait",
+  "go_back",
+  "go_forward",
+  "search",
+  "navigate",
+  "key_combination",
+  "drag_and_drop",
+  "current_state"
+];
+const OPTIONAL_MOUSE_ACTIONS = [
+  "double_click",
+  "triple_click",
+  "middle_click",
+  "right_click",
+  "mouse_down",
+  "mouse_up"
+];
+const OPTIONAL_KEY_ACTIONS = ["key_down", "key_up"];
+const MOUSE_METHODS = {
+  double_click: "doubleClick",
+  triple_click: "tripleClick",
+  middle_click: "middleClick",
+  right_click: "rightClick",
+  mouse_down: "mouseDown",
+  mouse_up: "mouseUp"
+};
+const KEY_METHODS = {
+  key_down: "keyDown",
+  key_up: "keyUp"
+};
+const SCROLL_DIRECTIONS = [
+  "up",
+  "down",
+  "left",
+  "right"
+];
+const BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "metadata", "metadata.goog"]);
+const BLOCKED_HOSTNAME_SUFFIXES = [
+  ".localhost",
+  ".local",
+  ".internal",
+  ".metadata.goog"
+];
+const URL_AUTHORITY = /^[a-z][a-z0-9+.-]*:\/\/([^/?#]*)/i;
+const URL_REFUSED_ERROR = "navigate refused: url must be http(s) and must not target a private or link-local address.";
+const INTEGER = { type: Type.INTEGER };
+const NUMBER = { type: Type.NUMBER };
+const STRING = { type: Type.STRING };
+const BOOLEAN = { type: Type.BOOLEAN };
+const STRING_ARRAY = { type: Type.ARRAY, items: { type: Type.STRING } };
+const DIRECTION = { type: Type.STRING, enum: [...SCROLL_DIRECTIONS] };
+function unimplementedOptionalActions(computer) {
+  return [
+    ...OPTIONAL_MOUSE_ACTIONS.filter(
+      (name) => typeof computer[MOUSE_METHODS[name]] !== "function"
+    ),
+    ...OPTIONAL_KEY_ACTIONS.filter(
+      (name) => typeof computer[KEY_METHODS[name]] !== "function"
+    )
+  ];
+}
+__name(unimplementedOptionalActions, "unimplementedOptionalActions");
+function createComputerActions(options) {
+  return [
+    ...createLegacyActions(options),
+    ...createModernActions(options.computer),
+    ...createOptionalActions(options.computer)
+  ];
+}
+__name(createComputerActions, "createComputerActions");
+function createLegacyActions({
+  computer,
+  allowPrivateNetworkAccess
+}) {
+  return [
+    {
+      name: "open_web_browser",
+      description: "Opens the web browser.",
+      parameters: objectSchema({}),
+      execute: /* @__PURE__ */ __name(() => computer.openWebBrowser(), "execute")
+    },
+    {
+      name: "click_at",
+      description: "Clicks at a specific x, y coordinate on the webpage.",
+      parameters: objectSchema({ x: INTEGER, y: INTEGER }),
+      execute: /* @__PURE__ */ __name((args) => computer.clickAt(readNumber(args, "x"), readNumber(args, "y")), "execute")
+    },
+    {
+      name: "hover_at",
+      description: "Hovers at a specific x, y coordinate on the webpage. May be used to explore sub-menus that appear on hover.",
+      parameters: objectSchema({ x: INTEGER, y: INTEGER }),
+      execute: /* @__PURE__ */ __name((args) => computer.hoverAt(readNumber(args, "x"), readNumber(args, "y")), "execute")
+    },
+    {
+      name: "type_text_at",
+      description: "Types text at a specific x, y coordinate. Presses ENTER after typing unless press_enter is false, and clears existing content before typing unless clear_before_typing is false.",
+      parameters: objectSchema(
+        {
+          x: INTEGER,
+          y: INTEGER,
+          text: STRING,
+          press_enter: BOOLEAN,
+          clear_before_typing: BOOLEAN
+        },
+        ["x", "y", "text"]
+      ),
+      execute: /* @__PURE__ */ __name((args) => computer.typeTextAt(
+        readNumber(args, "x"),
+        readNumber(args, "y"),
+        readString(args, "text"),
+        readBoolean(args, "press_enter", true),
+        readBoolean(args, "clear_before_typing", true)
+      ), "execute")
+    },
+    {
+      name: "scroll_document",
+      description: 'Scrolls the entire webpage "up", "down", "left" or "right" based on direction.',
+      parameters: objectSchema({ direction: DIRECTION }),
+      execute: /* @__PURE__ */ __name((args) => computer.scrollDocument(readDirection(args)), "execute")
+    },
+    {
+      name: "scroll_at",
+      description: "Scrolls up, down, right, or left at an x, y coordinate by magnitude.",
+      parameters: objectSchema({
+        x: INTEGER,
+        y: INTEGER,
+        direction: DIRECTION,
+        magnitude: INTEGER
+      }),
+      execute: /* @__PURE__ */ __name((args) => computer.scrollAt(
+        readNumber(args, "x"),
+        readNumber(args, "y"),
+        readDirection(args),
+        readNumber(args, "magnitude")
+      ), "execute")
+    },
+    {
+      name: "wait",
+      description: "Waits for the specified number of seconds.",
+      parameters: objectSchema({ seconds: NUMBER }, []),
+      execute: /* @__PURE__ */ __name((args) => computer.wait(Math.max(0, Math.ceil(readNumber(args, "seconds", 1)))), "execute")
+    },
+    {
+      name: "go_back",
+      description: "Navigates back to the previous webpage in the browser history.",
+      parameters: objectSchema({}),
+      execute: /* @__PURE__ */ __name(() => computer.goBack(), "execute")
+    },
+    {
+      name: "go_forward",
+      description: "Navigates forward to the next webpage in the browser history.",
+      parameters: objectSchema({}),
+      execute: /* @__PURE__ */ __name(() => computer.goForward(), "execute")
+    },
+    {
+      name: "search",
+      description: "Directly jumps to a search engine home page. Used when you need to start with a search.",
+      parameters: objectSchema({}),
+      execute: /* @__PURE__ */ __name(() => computer.search(), "execute")
+    },
+    {
+      name: "navigate",
+      description: "Navigates directly to a specified URL.",
+      parameters: objectSchema({ url: STRING }),
+      execute: /* @__PURE__ */ __name((args) => navigate({ computer, url: args["url"], allowPrivateNetworkAccess }), "execute")
+    },
+    {
+      name: "key_combination",
+      description: 'Presses keyboard keys and combinations, such as "control+c" or "enter".',
+      parameters: objectSchema({ keys: STRING_ARRAY }),
+      execute: /* @__PURE__ */ __name((args) => computer.keyCombination(readStringArray(args, "keys")), "execute")
+    },
+    {
+      name: "drag_and_drop",
+      description: "Drags an element from an x, y coordinate and drops it at a destination_x, destination_y coordinate.",
+      parameters: objectSchema({
+        x: INTEGER,
+        y: INTEGER,
+        destination_x: INTEGER,
+        destination_y: INTEGER
+      }),
+      execute: /* @__PURE__ */ __name((args) => computer.dragAndDrop(
+        readNumber(args, "x", args["start_x"]),
+        readNumber(args, "y", args["start_y"]),
+        readNumber(args, "destination_x", args["end_x"]),
+        readNumber(args, "destination_y", args["end_y"])
+      ), "execute")
+    },
+    {
+      name: "current_state",
+      description: "Returns the current state of the current webpage.",
+      parameters: objectSchema({}),
+      execute: /* @__PURE__ */ __name(() => computer.currentState(), "execute")
+    }
+  ];
+}
+__name(createLegacyActions, "createLegacyActions");
+function createModernActions(computer) {
+  var _a, _b, _c, _d, _e, _f, _g;
+  const click = (_a = computer.click) == null ? void 0 : _a.bind(computer);
+  const move = (_b = computer.move) == null ? void 0 : _b.bind(computer);
+  const type = (_c = computer.type) == null ? void 0 : _c.bind(computer);
+  const scroll = (_d = computer.scroll) == null ? void 0 : _d.bind(computer);
+  const takeScreenshot = (_e = computer.takeScreenshot) == null ? void 0 : _e.bind(computer);
+  const pressKey = (_f = computer.pressKey) == null ? void 0 : _f.bind(computer);
+  const hotkey = (_g = computer.hotkey) == null ? void 0 : _g.bind(computer);
+  return [
+    {
+      name: "click",
+      description: "Clicks at the specified (x, y) coordinates.",
+      parameters: click ? objectSchema({ x: INTEGER, y: INTEGER, button: STRING }, ["x", "y"]) : objectSchema({ x: INTEGER, y: INTEGER }),
+      execute: /* @__PURE__ */ __name((args) => {
+        const x = readNumber(args, "x");
+        const y = readNumber(args, "y");
+        return click ? click(x, y, readOptional(args, "button", readString)) : computer.clickAt(x, y);
+      }, "execute")
+    },
+    {
+      name: "move",
+      description: "Moves the cursor to the specified (x, y) coordinates.",
+      parameters: objectSchema({ x: INTEGER, y: INTEGER }),
+      execute: /* @__PURE__ */ __name((args) => (move != null ? move : computer.hoverAt.bind(computer))(
+        readNumber(args, "x"),
+        readNumber(args, "y")
+      ), "execute")
+    },
+    {
+      name: "type",
+      description: "Types text into the currently focused element.",
+      parameters: objectSchema({ text: STRING, press_enter: BOOLEAN }, ["text"]),
+      execute: /* @__PURE__ */ __name((args) => {
+        const text = readString(args, "text");
+        return type ? type(
+          text,
+          readOptional(
+            args,
+            "press_enter",
+            (a, n) => readBoolean(a, n, false)
+          )
+        ) : computer.typeText(text, readBoolean(args, "press_enter", false));
+      }, "execute")
+    },
+    {
+      name: "scroll",
+      description: "Scrolls the webpage at the specified coordinates.",
+      parameters: objectSchema(
+        {
+          x: INTEGER,
+          y: INTEGER,
+          direction: DIRECTION,
+          magnitude_in_pixels: INTEGER
+        },
+        scroll ? ["x", "y", "direction"] : ["x", "y"]
+      ),
+      execute: /* @__PURE__ */ __name((args) => {
+        const x = readNumber(args, "x");
+        const y = readNumber(args, "y");
+        return scroll ? scroll(
+          x,
+          y,
+          readDirection(args),
+          readOptional(args, "magnitude_in_pixels", readNumber)
+        ) : computer.scrollAt(
+          x,
+          y,
+          readDirection(args, "down"),
+          readNumber(args, "magnitude_in_pixels", 300)
+        );
+      }, "execute")
+    },
+    {
+      name: "take_screenshot",
+      description: "Takes a screenshot of the current webpage state.",
+      parameters: objectSchema({}),
+      execute: /* @__PURE__ */ __name(() => takeScreenshot ? takeScreenshot() : computer.currentState(), "execute")
+    },
+    {
+      name: "press_key",
+      description: "Presses a single keyboard key.",
+      parameters: objectSchema({ key: STRING }),
+      execute: /* @__PURE__ */ __name((args) => {
+        const key = readString(args, "key");
+        return pressKey ? pressKey(key) : computer.keyCombination([key]);
+      }, "execute")
+    },
+    {
+      name: "hotkey",
+      description: "Presses a combination of keyboard keys simultaneously.",
+      parameters: objectSchema({ keys: STRING_ARRAY }),
+      execute: /* @__PURE__ */ __name((args) => (hotkey != null ? hotkey : computer.keyCombination.bind(computer))(
+        readStringArray(args, "keys")
+      ), "execute")
+    }
+  ];
+}
+__name(createModernActions, "createModernActions");
+function createOptionalActions(computer) {
+  var _a, _b;
+  const actions = [];
+  for (const name of OPTIONAL_MOUSE_ACTIONS) {
+    const method = (_a = computer[MOUSE_METHODS[name]]) == null ? void 0 : _a.bind(computer);
+    if (!method) {
+      continue;
+    }
+    actions.push({
+      name,
+      description: `Performs ${name.replace("_", " ")} at the specified (x, y) coordinates.`,
+      parameters: objectSchema({ x: INTEGER, y: INTEGER, button: STRING }, [
+        "x",
+        "y"
+      ]),
+      execute: /* @__PURE__ */ __name((args) => {
+        const button = args["button"];
+        return button === void 0 ? method(readNumber(args, "x"), readNumber(args, "y")) : method(
+          readNumber(args, "x"),
+          readNumber(args, "y"),
+          readString(args, "button")
+        );
+      }, "execute")
+    });
+  }
+  for (const name of OPTIONAL_KEY_ACTIONS) {
+    const method = (_b = computer[KEY_METHODS[name]]) == null ? void 0 : _b.bind(computer);
+    if (!method) {
+      continue;
+    }
+    actions.push({
+      name,
+      description: name === "key_down" ? "Presses a keyboard key down and holds it." : "Releases a keyboard key.",
+      parameters: objectSchema({ key: STRING }),
+      execute: /* @__PURE__ */ __name((args) => method(readString(args, "key")), "execute")
+    });
+  }
+  return actions;
+}
+__name(createOptionalActions, "createOptionalActions");
+async function navigate({
+  computer,
+  url,
+  allowPrivateNetworkAccess
+}) {
+  if (typeof url === "string" && await isSafeNavigationUrl(url, allowPrivateNetworkAccess)) {
+    return computer.navigate(url);
+  }
+  logger.warn("Refusing navigate(): url failed safety validation.");
+  const state = await computer.currentState();
+  return { error: URL_REFUSED_ERROR, url: state.url };
+}
+__name(navigate, "navigate");
+async function isSafeNavigationUrl(url, allowPrivateNetworkAccess) {
+  var _a;
+  if ((_a = URL_AUTHORITY.exec(url)) == null ? void 0 : _a[1].includes("\\")) {
+    return false;
+  }
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  const hostname = normalizeHost(parsed.hostname);
+  if (!isHttpUrl(parsed) || !hostname) {
+    return false;
+  }
+  if (allowPrivateNetworkAccess) {
+    return true;
+  }
+  if (isBlockedHostname(hostname)) {
+    return false;
+  }
+  if (isBrowser() && !isIpAddress(hostname)) {
+    return true;
+  }
+  try {
+    const addresses = await resolveHostAddresses(hostname);
+    return !addresses.some(isNonGlobalAddress);
+  } catch {
+    return false;
+  }
+}
+__name(isSafeNavigationUrl, "isSafeNavigationUrl");
+function isBlockedHostname(hostname) {
+  const normalized = hostname.replace(/\.+$/, "").toLowerCase();
+  return BLOCKED_HOSTNAMES.has(normalized) || BLOCKED_HOSTNAME_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
+}
+__name(isBlockedHostname, "isBlockedHostname");
+function objectSchema(properties, required = Object.keys(properties)) {
+  return { type: Type.OBJECT, properties, required };
+}
+__name(objectSchema, "objectSchema");
+function readNumber(args, name, fallback) {
+  var _a;
+  const value = (_a = args[name]) != null ? _a : fallback;
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(argumentError(name, "a number", value));
+  }
+  return value;
+}
+__name(readNumber, "readNumber");
+function readString(args, name) {
+  const value = args[name];
+  if (typeof value !== "string") {
+    throw new Error(argumentError(name, "a string", value));
+  }
+  return value;
+}
+__name(readString, "readString");
+function readBoolean(args, name, fallback) {
+  var _a;
+  const value = (_a = args[name]) != null ? _a : fallback;
+  if (typeof value !== "boolean") {
+    throw new Error(argumentError(name, "a boolean", value));
+  }
+  return value;
+}
+__name(readBoolean, "readBoolean");
+function readOptional(args, name, read) {
+  return args[name] === void 0 ? void 0 : read(args, name);
+}
+__name(readOptional, "readOptional");
+function readStringArray(args, name) {
+  const value = args[name];
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+    throw new Error(argumentError(name, "a list of strings", value));
+  }
+  return value;
+}
+__name(readStringArray, "readStringArray");
+function readDirection(args, fallback) {
+  var _a;
+  const value = (_a = args["direction"]) != null ? _a : fallback;
+  const direction = SCROLL_DIRECTIONS.find((d) => d === value);
+  if (!direction) {
+    throw new Error(
+      argumentError("direction", "one of up, down, left, right", value)
+    );
+  }
+  return direction;
+}
+__name(readDirection, "readDirection");
+function argumentError(name, expected, value) {
+  return value === void 0 ? `Missing required argument '${name}'.` : `Argument '${name}' must be ${expected}, got ${typeof value}.`;
+}
+__name(argumentError, "argumentError");
+export {
+  LEGACY_ACTION_NAMES,
+  OPTIONAL_KEY_ACTIONS,
+  OPTIONAL_MOUSE_ACTIONS,
+  createComputerActions,
+  unimplementedOptionalActions
+};

package/dist/esm/tools/computer_use/computer_use_tool.js

@@ -0,0 +1,217 @@
+import {createRequire as topLevelCreateRequire} from 'module';
+const require = topLevelCreateRequire(import.meta.url);
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var _a, _b;
+import { base64Encode } from "../../utils/env_aware_utils.js";
+import { experimental } from "../../utils/experimental.js";
+import { logger } from "../../utils/logger.js";
+import { FunctionTool } from "../function_tool.js";
+import { checkComputerUseEnabled } from "./base_computer.js";
+const DEFAULT_VIRTUAL_SCREEN_SIZE = [1e3, 1e3];
+const X_COORDINATE_FIELDS = ["x", "destination_x", "start_x", "end_x"];
+const Y_COORDINATE_FIELDS = ["y", "destination_y", "start_y", "end_y"];
+const INTEGER_STRING = /^-?\d+$/;
+const REQUIRE_CONFIRMATION = "require_confirmation";
+const COMPUTER_USE_TOOL_SIGNATURE_SYMBOL = /* @__PURE__ */ Symbol.for(
+  "google.adk.computerUseTool"
+);
+function isComputerUseTool(obj) {
+  return typeof obj === "object" && obj !== null && COMPUTER_USE_TOOL_SIGNATURE_SYMBOL in obj && obj[COMPUTER_USE_TOOL_SIGNATURE_SYMBOL] === true;
+}
+__name(isComputerUseTool, "isComputerUseTool");
+let ComputerUseTool = class extends (_b = FunctionTool, _a = COMPUTER_USE_TOOL_SIGNATURE_SYMBOL, _b) {
+  /**
+   * @param options The options for the tool.
+   * @throws {Error} If `screenSize` or `virtualScreenSize` is not a pair of
+   *     positive numbers.
+   */
+  constructor(options) {
+    var _a2;
+    checkComputerUseEnabled();
+    const virtualScreenSize = (_a2 = options.virtualScreenSize) != null ? _a2 : DEFAULT_VIRTUAL_SCREEN_SIZE;
+    checkScreenSize("screenSize", options.screenSize);
+    checkScreenSize("virtualScreenSize", virtualScreenSize);
+    const func = options.execute;
+    super({
+      name: options.name,
+      description: options.description,
+      parameters: options.parameters,
+      execute: /* @__PURE__ */ __name((input, toolContext) => func(isRecord(input) ? input : {}, toolContext), "execute")
+    });
+    /** A unique symbol to identify ADK computer use tool class. */
+    this[_a] = true;
+    this.func = func;
+    this.screenSize = options.screenSize;
+    this.virtualScreenSize = virtualScreenSize;
+  }
+  /**
+   * Runs the computer control function with scaled coordinates.
+   *
+   * @param request The tool request containing arguments and tool context.
+   * @returns The function's result, with a {@link ComputerState} converted to
+   *     a response carrying the base64-encoded screenshot.
+   * @throws {Error} If a coordinate is not numeric, or the function returns a
+   *     state with no screenshot.
+   */
+  async runAsync({
+    args,
+    toolContext
+  }) {
+    const confirmation = toolContext.toolConfirmation;
+    if (!confirmation) {
+      const safetyDecision = getSafetyDecision(args);
+      if ((safetyDecision == null ? void 0 : safetyDecision.decision) === REQUIRE_CONFIRMATION) {
+        toolContext.requestConfirmation({
+          hint: typeof safetyDecision.explanation === "string" && safetyDecision.explanation ? safetyDecision.explanation : "This computer use action requires safety confirmation."
+        });
+        toolContext.actions.skipSummarization = true;
+        return {
+          error: "This tool call requires confirmation, please approve or reject."
+        };
+      }
+    } else if (!confirmation.confirmed) {
+      return { error: "This tool call is rejected." };
+    }
+    const scaledArgs = this.scaleCoordinates(args);
+    const result = await super.runAsync({ args: scaledArgs, toolContext });
+    let response = result;
+    if (isComputerState(result)) {
+      if (!result.screenshot) {
+        throw new Error(
+          "A computer action returned a state with no screenshot"
+        );
+      }
+      response = {
+        image: { mimetype: "image/png", data: base64Encode(result.screenshot) },
+        url: result.url
+      };
+    }
+    if (confirmation == null ? void 0 : confirmation.confirmed) {
+      const acknowledged = isRecord(response) ? response : { result: response };
+      acknowledged["safety_acknowledgement"] = "true";
+      return acknowledged;
+    }
+    return response;
+  }
+  /**
+   * Whether this call needs user confirmation: when the model marked it with
+   * a `safety_decision` of `require_confirmation`, or when the base tool says
+   * so.
+   *
+   * @param args The arguments the tool would run with.
+   * @param toolContext The context of the call, when there is one.
+   * @returns Whether the call requires confirmation.
+   */
+  async checkRequireConfirmation(args, toolContext) {
+    var _a2;
+    if (((_a2 = getSafetyDecision(args)) == null ? void 0 : _a2.decision) === REQUIRE_CONFIRMATION) {
+      return true;
+    }
+    return super.checkRequireConfirmation(args, toolContext);
+  }
+  /**
+   * Adds nothing to the request: {@link ComputerUseToolset} adds the single
+   * computer use configuration and registers its tools by name.
+   */
+  async processLlmRequest(_request) {
+  }
+  /** Returns a copy of `args` with every coordinate scaled to the screen. */
+  scaleCoordinates(args) {
+    const scaled = { ...args };
+    delete scaled["safety_decision"];
+    for (const field of X_COORDINATE_FIELDS) {
+      if (field in scaled) {
+        scaled[field] = scaleCoordinate({
+          field,
+          value: scaled[field],
+          virtual: this.virtualScreenSize[0],
+          actual: this.screenSize[0]
+        });
+      }
+    }
+    for (const field of Y_COORDINATE_FIELDS) {
+      if (field in scaled) {
+        scaled[field] = scaleCoordinate({
+          field,
+          value: scaled[field],
+          virtual: this.virtualScreenSize[1],
+          actual: this.screenSize[1]
+        });
+      }
+    }
+    return scaled;
+  }
+};
+__name(ComputerUseTool, "ComputerUseTool");
+ComputerUseTool = __decorateClass([
+  experimental
+], ComputerUseTool);
+function scaleCoordinate({
+  field,
+  value,
+  virtual,
+  actual
+}) {
+  const numeric = typeof value === "string" && INTEGER_STRING.test(value) ? Number(value) : value;
+  if (typeof numeric !== "number" || !Number.isFinite(numeric)) {
+    throw new Error(
+      `${field} coordinate must be numeric, got ${typeof value} ${JSON.stringify(value)}`
+    );
+  }
+  const scaled = Math.max(
+    0,
+    Math.min(Math.trunc(numeric / virtual * actual), actual - 1)
+  );
+  logger.debug(`Normalized ${field}: ${numeric} -> ${scaled}`);
+  return scaled;
+}
+__name(scaleCoordinate, "scaleCoordinate");
+function checkScreenSize(name, size) {
+  if (!Array.isArray(size) || size.length !== 2) {
+    throw new Error(`${name} must be a pair of (width, height)`);
+  }
+  if (!size.every((dimension) => Number.isFinite(dimension) && dimension > 0)) {
+    throw new Error(`${name} dimensions must be positive`);
+  }
+}
+__name(checkScreenSize, "checkScreenSize");
+function getSafetyDecision(args) {
+  const decision = args["safety_decision"];
+  return isRecord(decision) ? decision : void 0;
+}
+__name(getSafetyDecision, "getSafetyDecision");
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+__name(isRecord, "isRecord");
+function isComputerState(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  const keys = Object.keys(value);
+  if (keys.length === 0 || keys.some((k) => k !== "screenshot" && k !== "url")) {
+    return false;
+  }
+  const { screenshot, url } = value;
+  return (screenshot === void 0 || screenshot instanceof Uint8Array) && (url === void 0 || typeof url === "string");
+}
+__name(isComputerState, "isComputerState");
+export {
+  ComputerUseTool,
+  isComputerUseTool
+};