@google/adk 2.3.0 → 2.5.0

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

@@ -0,0 +1,502 @@
+/**
+  * @license
+  * Copyright 2026 Google LLC
+  * SPDX-License-Identifier: Apache-2.0
+  */
+
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var computer_use_actions_exports = {};
+__export(computer_use_actions_exports, {
+  LEGACY_ACTION_NAMES: () => LEGACY_ACTION_NAMES,
+  OPTIONAL_KEY_ACTIONS: () => OPTIONAL_KEY_ACTIONS,
+  OPTIONAL_MOUSE_ACTIONS: () => OPTIONAL_MOUSE_ACTIONS,
+  createComputerActions: () => createComputerActions,
+  unimplementedOptionalActions: () => unimplementedOptionalActions
+});
+module.exports = __toCommonJS(computer_use_actions_exports);
+var import_genai = require("@google/genai");
+var import_env_aware_utils = require("../../utils/env_aware_utils.js");
+var import_logger = require("../../utils/logger.js");
+var import_ssrf_guard = require("../../utils/ssrf_guard.js");
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+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: import_genai.Type.INTEGER };
+const NUMBER = { type: import_genai.Type.NUMBER };
+const STRING = { type: import_genai.Type.STRING };
+const BOOLEAN = { type: import_genai.Type.BOOLEAN };
+const STRING_ARRAY = { type: import_genai.Type.ARRAY, items: { type: import_genai.Type.STRING } };
+const DIRECTION = { type: import_genai.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);
+  }
+  import_logger.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 = (0, import_ssrf_guard.normalizeHost)(parsed.hostname);
+  if (!(0, import_ssrf_guard.isHttpUrl)(parsed) || !hostname) {
+    return false;
+  }
+  if (allowPrivateNetworkAccess) {
+    return true;
+  }
+  if (isBlockedHostname(hostname)) {
+    return false;
+  }
+  if ((0, import_env_aware_utils.isBrowser)() && !(0, import_ssrf_guard.isIpAddress)(hostname)) {
+    return true;
+  }
+  try {
+    const addresses = await (0, import_ssrf_guard.resolveHostAddresses)(hostname);
+    return !addresses.some(import_ssrf_guard.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: import_genai.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");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LEGACY_ACTION_NAMES,
+  OPTIONAL_KEY_ACTIONS,
+  OPTIONAL_MOUSE_ACTIONS,
+  createComputerActions,
+  unimplementedOptionalActions
+});