@aria-cli/tools 1.0.0

package/src/definitions/browser/browser.ts

@@ -0,0 +1,502 @@
+// Originally from OpenClaw (MIT License, Copyright 2025 Peter Steinberger)
+// https://github.com/openclaw/openclaw
+// Modified for ARIA — stripped OpenClaw runtime, rewired to ARIA Tool interface
+
+/**
+ * ARIA Browser Tool — Playwright-based browser automation.
+ *
+ * Single tool with an `action` discriminator that dispatches to the
+ * appropriate Playwright handler. The LLM calls `browser` with an action
+ * object; each action maps to a specific capability.
+ *
+ * Playwright is loaded dynamically so ARIA works without it installed.
+ */
+
+import type { JSONSchema7 } from "json-schema";
+import type { Tool, ToolResult } from "../../types.js";
+import type { BrowserAction, BrowserSession } from "./types.js";
+import {
+  launchBrowser,
+  closeBrowser,
+  getSession,
+  getRefs,
+  setRefs,
+  getConsoleMessages,
+  getNetworkRequests,
+  getPageErrors,
+  listTabs,
+  newTab,
+  selectTab,
+  closeTab,
+} from "./pw-session.js";
+import { snapshotPage, navigatePage } from "./pw-snapshot.js";
+import {
+  clickViaPlaywright,
+  hoverViaPlaywright,
+  dragViaPlaywright,
+  typeViaPlaywright,
+  selectOptionViaPlaywright,
+  pressKeyViaPlaywright,
+  evaluateViaPlaywright,
+  takeScreenshot,
+  scrollPage,
+  waitForCondition,
+  uploadFiles,
+} from "./pw-interactions.js";
+import { cookiesGet, cookiesSet, cookiesClear } from "./pw-state.js";
+import {
+  filterConsoleMessages,
+  filterNetworkRequests,
+  formatConsoleMessages,
+  formatNetworkRequests,
+  formatPageErrors,
+} from "./pw-responses.js";
+
+// ── JSON Schema for the action parameter ──────────────────────────────
+
+const browserParameterSchema: JSONSchema7 = {
+  type: "object",
+  properties: {
+    action: {
+      type: "string",
+      enum: [
+        "launch",
+        "close",
+        "navigate",
+        "snapshot",
+        "click",
+        "type",
+        "hover",
+        "drag",
+        "select_option",
+        "press_key",
+        "scroll",
+        "evaluate",
+        "screenshot",
+        "get_console",
+        "get_network",
+        "wait",
+        "tab_list",
+        "tab_new",
+        "tab_select",
+        "tab_close",
+        "cookies_get",
+        "cookies_set",
+        "cookies_clear",
+        "upload",
+      ],
+      description:
+        "The browser action to perform. 'launch' is optional; actions auto-start a session when needed. Use 'snapshot' to read page content, refs like [e1] with 'click'/'type'.",
+    },
+    // launch
+    url: { type: "string", description: "URL to navigate to (for launch/navigate/tab_new)" },
+    headless: {
+      type: "boolean",
+      description: "Run browser without visible window (default: true)",
+    },
+    // snapshot
+    interactive: {
+      type: "boolean",
+      description: "Only show interactive elements in snapshot (buttons, links, inputs)",
+    },
+    // click/type/hover/drag/select_option/upload
+    ref: {
+      type: "string",
+      description: "Element ref from snapshot (e.g. 'e1', 'e5')",
+    },
+    text: { type: "string", description: "Text to type (for 'type' action)" },
+    submit: {
+      type: "boolean",
+      description: "Press Enter after typing (for 'type' action)",
+    },
+    slowly: {
+      type: "boolean",
+      description: "Type character by character instead of filling (for 'type' action)",
+    },
+    button: {
+      type: "string",
+      enum: ["left", "right", "middle"],
+      description: "Mouse button (for 'click' action)",
+    },
+    modifiers: {
+      type: "array",
+      items: { type: "string" },
+      description: "Keyboard modifiers (for 'click': Alt, Control, Meta, Shift)",
+    },
+    doubleClick: {
+      type: "boolean",
+      description: "Double-click instead of single click",
+    },
+    startRef: {
+      type: "string",
+      description: "Source element ref (for 'drag' action)",
+    },
+    endRef: {
+      type: "string",
+      description: "Target element ref (for 'drag' action)",
+    },
+    values: {
+      type: "array",
+      items: { type: "string" },
+      description: "Values to select (for 'select_option' action)",
+    },
+    // press_key
+    key: {
+      type: "string",
+      description: "Key to press (for 'press_key': Enter, Tab, Escape, ArrowDown, etc.)",
+    },
+    // scroll
+    direction: {
+      type: "string",
+      enum: ["up", "down"],
+      description: "Scroll direction",
+    },
+    amount: {
+      type: "number",
+      description: "Scroll amount in pixels (default: 500)",
+    },
+    // evaluate
+    script: {
+      type: "string",
+      description: "JavaScript to evaluate in browser context (for 'evaluate' action)",
+    },
+    // get_console
+    level: {
+      type: "string",
+      description: "Minimum console level filter (debug/info/warning/error)",
+    },
+    // get_network
+    filter: {
+      type: "string",
+      description: "URL substring filter for network requests",
+    },
+    // wait
+    selector: {
+      type: "string",
+      description: "CSS selector to wait for (for 'wait' action)",
+    },
+    timeout: {
+      type: "number",
+      description: "Timeout in milliseconds (for 'wait' action)",
+    },
+    // tab_select
+    index: {
+      type: "number",
+      description: "Tab index (for 'tab_select'/'tab_close')",
+    },
+    // cookies_set
+    cookies: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          name: { type: "string" },
+          value: { type: "string" },
+          domain: { type: "string" },
+          path: { type: "string" },
+        },
+        required: ["name", "value", "domain"],
+      },
+      description: "Cookies to set (for 'cookies_set' action)",
+    },
+    // upload
+    paths: {
+      type: "array",
+      items: { type: "string" },
+      description: "File paths to upload (for 'upload' action)",
+    },
+  },
+  required: ["action"],
+};
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+function ok(message: string, data?: unknown): ToolResult {
+  return { success: true, message, data };
+}
+
+function fail(message: string): ToolResult {
+  return { success: false, message };
+}
+
+async function requireSession(): Promise<BrowserSession> {
+  const session = getSession();
+  if (session) {
+    return session;
+  }
+  return launchBrowser();
+}
+
+// ── Action dispatcher ─────────────────────────────────────────────────
+
+async function executeBrowserAction(input: unknown): Promise<ToolResult> {
+  const action = input as BrowserAction;
+
+  try {
+    switch (action.action) {
+      // ── Lifecycle ─────────────────────────────────────────────────
+      case "launch": {
+        const session = await launchBrowser({
+          headless: action.headless,
+          url: action.url,
+        });
+        const url = session.page.url();
+        return ok(
+          `Browser launched.${action.url ? ` Navigated to ${url}` : ""}\nUse 'snapshot' to see page content.`,
+          { url },
+        );
+      }
+      case "close": {
+        await closeBrowser();
+        return ok("Browser closed.");
+      }
+
+      // ── Navigation ────────────────────────────────────────────────
+      case "navigate": {
+        const session = await requireSession();
+        const result = await navigatePage(session.page, action.url);
+        setRefs({}); // Refs are stale after navigation
+        return ok(`Navigated to ${result.url}. Use 'snapshot' to see page content.`, result);
+      }
+
+      // ── Snapshot ──────────────────────────────────────────────────
+      case "snapshot": {
+        const session = await requireSession();
+        const result = await snapshotPage(session.page, {
+          interactive: action.interactive,
+        });
+        setRefs(result.refs);
+        const header =
+          `Page: ${result.title}\nURL: ${result.url}\n` +
+          `Elements: ${result.stats.refs} total, ${result.stats.interactive} interactive\n\n`;
+        return ok(header + result.snapshot, {
+          url: result.url,
+          title: result.title,
+          stats: result.stats,
+        });
+      }
+
+      // ── Click ─────────────────────────────────────────────────────
+      case "click": {
+        const session = await requireSession();
+        await clickViaPlaywright({
+          page: session.page,
+          refs: getRefs(),
+          ref: action.ref,
+          doubleClick: action.doubleClick,
+          button: action.button,
+          modifiers: action.modifiers,
+        });
+        return ok(`Clicked ${action.ref}. Use 'snapshot' to see updated page.`);
+      }
+
+      // ── Type ──────────────────────────────────────────────────────
+      case "type": {
+        const session = await requireSession();
+        await typeViaPlaywright({
+          page: session.page,
+          refs: getRefs(),
+          ref: action.ref,
+          text: action.text,
+          submit: action.submit,
+          slowly: action.slowly,
+        });
+        return ok(
+          `Typed "${action.text.length > 50 ? action.text.slice(0, 50) + "..." : action.text}" into ${action.ref}.${action.submit ? " Submitted with Enter." : ""}`,
+        );
+      }
+
+      // ── Hover ─────────────────────────────────────────────────────
+      case "hover": {
+        const session = await requireSession();
+        await hoverViaPlaywright({
+          page: session.page,
+          refs: getRefs(),
+          ref: action.ref,
+        });
+        return ok(`Hovered over ${action.ref}.`);
+      }
+
+      // ── Drag ──────────────────────────────────────────────────────
+      case "drag": {
+        const session = await requireSession();
+        await dragViaPlaywright({
+          page: session.page,
+          refs: getRefs(),
+          startRef: action.startRef,
+          endRef: action.endRef,
+        });
+        return ok(`Dragged ${action.startRef} to ${action.endRef}.`);
+      }
+
+      // ── Select option ─────────────────────────────────────────────
+      case "select_option": {
+        const session = await requireSession();
+        await selectOptionViaPlaywright({
+          page: session.page,
+          refs: getRefs(),
+          ref: action.ref,
+          values: action.values,
+        });
+        return ok(`Selected [${action.values.join(", ")}] in ${action.ref}.`);
+      }
+
+      // ── Key press ─────────────────────────────────────────────────
+      case "press_key": {
+        const session = await requireSession();
+        await pressKeyViaPlaywright({
+          page: session.page,
+          key: action.key,
+        });
+        return ok(`Pressed key: ${action.key}`);
+      }
+
+      // ── Scroll ────────────────────────────────────────────────────
+      case "scroll": {
+        const session = await requireSession();
+        await scrollPage({
+          page: session.page,
+          direction: action.direction,
+          amount: action.amount,
+        });
+        return ok(
+          `Scrolled ${action.direction} ${action.amount ?? 500}px. Use 'snapshot' to see updated content.`,
+        );
+      }
+
+      // ── Evaluate ──────────────────────────────────────────────────
+      case "evaluate": {
+        const session = await requireSession();
+        const result = await evaluateViaPlaywright({
+          page: session.page,
+          script: action.script,
+        });
+        const output =
+          result === undefined
+            ? "undefined"
+            : typeof result === "string"
+              ? result
+              : JSON.stringify(result, null, 2);
+        return ok(output, { result });
+      }
+
+      // ── Screenshot ────────────────────────────────────────────────
+      case "screenshot": {
+        const session = await requireSession();
+        const buffer = await takeScreenshot({ page: session.page });
+        const base64 = buffer.toString("base64");
+        return ok(`Screenshot taken (${buffer.length} bytes, base64-encoded).`, {
+          base64,
+          mimeType: "image/png",
+        });
+      }
+
+      // ── Console ───────────────────────────────────────────────────
+      case "get_console": {
+        await requireSession();
+        const messages = filterConsoleMessages(getConsoleMessages(), action.level);
+        return ok(formatConsoleMessages(messages), { count: messages.length });
+      }
+
+      // ── Network ───────────────────────────────────────────────────
+      case "get_network": {
+        await requireSession();
+        const requests = filterNetworkRequests(getNetworkRequests(), action.filter);
+        return ok(formatNetworkRequests(requests), { count: requests.length });
+      }
+
+      // ── Wait ──────────────────────────────────────────────────────
+      case "wait": {
+        const session = await requireSession();
+        await waitForCondition({
+          page: session.page,
+          selector: action.selector,
+          text: action.text,
+          timeout: action.timeout,
+        });
+        return ok("Wait condition satisfied. Use 'snapshot' to see current page.");
+      }
+
+      // ── Tab management ────────────────────────────────────────────
+      case "tab_list": {
+        const tabs = listTabs();
+        const desc = tabs
+          .map((t) => `[${t.index}]${t.active ? " (active)" : ""} ${t.url}`)
+          .join("\n");
+        return ok(desc || "No tabs open.", { tabs });
+      }
+      case "tab_new": {
+        const result = await newTab(action.url);
+        return ok(`Opened new tab [${result.index}]: ${result.url}`, result);
+      }
+      case "tab_select": {
+        await requireSession();
+        const result = await selectTab(action.index);
+        return ok(`Switched to tab ${action.index}: ${result.url}`, result);
+      }
+      case "tab_close": {
+        await closeTab(action.index);
+        return ok(`Tab closed.${action.index !== undefined ? ` (index ${action.index})` : ""}`);
+      }
+
+      // ── Cookies ───────────────────────────────────────────────────
+      case "cookies_get": {
+        const session = await requireSession();
+        const result = await cookiesGet(session.context);
+        const desc = result.cookies.length
+          ? result.cookies.map((c) => `${c.name}=${c.value} (${c.domain})`).join("\n")
+          : "No cookies.";
+        return ok(desc, result);
+      }
+      case "cookies_set": {
+        const session = await requireSession();
+        await cookiesSet(session.context, action.cookies);
+        return ok(`Set ${action.cookies.length} cookie(s).`);
+      }
+      case "cookies_clear": {
+        const session = await requireSession();
+        await cookiesClear(session.context);
+        return ok("All cookies cleared.");
+      }
+
+      // ── Upload ────────────────────────────────────────────────────
+      case "upload": {
+        const session = await requireSession();
+        await uploadFiles({
+          page: session.page,
+          refs: getRefs(),
+          ref: action.ref,
+          paths: action.paths,
+        });
+        return ok(`Uploaded ${action.paths.length} file(s) to ${action.ref}.`);
+      }
+
+      default: {
+        const exhaustive: never = action;
+        return fail(`Unknown browser action: ${(exhaustive as { action: string }).action}`);
+      }
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return fail(message);
+  }
+}
+
+// ── Tool definition ───────────────────────────────────────────────────
+
+export const browserTool: Tool = {
+  name: "browser",
+  description:
+    "Control a web browser via Playwright. Supports navigation, clicking, typing, taking snapshots of page content, and more. " +
+    "Actions auto-start a browser session; use 'launch' only when you want explicit startup control. Use 'snapshot' to see the current page state as an accessibility tree with element refs like [e1], [e2]. " +
+    "Use those refs with 'click', 'type', 'hover', etc. to interact with elements. " +
+    "Use 'evaluate' to run JavaScript in the page context. Use 'screenshot' to capture the page visually.",
+  category: "web",
+  parameters: browserParameterSchema,
+  riskLevel: "moderate",
+  isReadOnly: false,
+  loadingTier: "always",
+  async execute(input: unknown, _context) {
+    return executeBrowserAction(input);
+  },
+};

package/src/definitions/browser/index.ts

@@ -0,0 +1,5 @@
+// Originally from OpenClaw (MIT License, Copyright 2025 Peter Steinberger)
+// https://github.com/openclaw/openclaw
+// Modified for ARIA — stripped OpenClaw runtime, rewired to ARIA Tool interface
+
+export { browserTool } from "./browser.js";

package/src/definitions/browser/pw-downloads.ts

@@ -0,0 +1,142 @@
+// Originally from OpenClaw (MIT License, Copyright 2025 Peter Steinberger)
+// https://github.com/openclaw/openclaw
+// Modified for ARIA — stripped OpenClaw runtime, rewired to ARIA Tool interface
+
+/**
+ * File upload and download handling.
+ * Ported from OpenClaw's pw-tools-core.downloads.ts.
+ *
+ * Note: Upload is handled in pw-interactions.ts via setInputFiles.
+ * This module provides download capture via page "download" event.
+ */
+
+import { tmpdir } from "node:os";
+import { join, dirname, resolve, basename } from "node:path";
+import { mkdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import type { PwPage } from "./types.js";
+import { normalizeTimeoutMs } from "./pw-shared.js";
+
+// ── Filename sanitization ─────────────────────────────────────────────
+
+function sanitizeDownloadFileName(fileName: string): string {
+  const trimmed = String(fileName ?? "").trim();
+  if (!trimmed) {
+    return "download.bin";
+  }
+
+  // Force a basename so path separators/traversal can't escape the downloads dir.
+  let base = basename(trimmed);
+  let cleaned = "";
+  for (let i = 0; i < base.length; i++) {
+    const code = base.charCodeAt(i);
+    if (code < 0x20 || code === 0x7f) {
+      continue;
+    }
+    cleaned += base[i];
+  }
+  base = cleaned.trim();
+
+  if (!base || base === "." || base === "..") {
+    return "download.bin";
+  }
+  if (base.length > 200) {
+    base = base.slice(0, 200);
+  }
+  return base;
+}
+
+function buildTempDownloadPath(fileName: string): string {
+  const id = randomUUID();
+  const safeName = sanitizeDownloadFileName(fileName);
+  return join(tmpdir(), "aria-downloads", `${id}-${safeName}`);
+}
+
+// ── Download waiter ───────────────────────────────────────────────────
+
+function createPageDownloadWaiter(page: PwPage, timeoutMs: number) {
+  let done = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let handler: ((...args: unknown[]) => void) | undefined;
+
+  const cleanup = () => {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = undefined;
+    if (handler) {
+      page.off("download", handler);
+      handler = undefined;
+    }
+  };
+
+  const promise = new Promise<unknown>((resolveP, reject) => {
+    handler = (download: unknown) => {
+      if (done) {
+        return;
+      }
+      done = true;
+      cleanup();
+      resolveP(download);
+    };
+
+    page.on("download", handler);
+    timer = setTimeout(() => {
+      if (done) {
+        return;
+      }
+      done = true;
+      cleanup();
+      reject(new Error("Timeout waiting for download"));
+    }, timeoutMs);
+  });
+
+  return {
+    promise,
+    cancel: () => {
+      if (done) {
+        return;
+      }
+      done = true;
+      cleanup();
+    },
+  };
+}
+
+// ── Public API ────────────────────────────────────────────────────────
+
+/**
+ * Wait for the next download event on the page and save the file.
+ */
+export async function waitForDownload(opts: {
+  page: PwPage;
+  path?: string;
+  timeoutMs?: number;
+}): Promise<{
+  url: string;
+  suggestedFilename: string;
+  path: string;
+}> {
+  const timeout = normalizeTimeoutMs(opts.timeoutMs, 120_000);
+
+  const waiter = createPageDownloadWaiter(opts.page, timeout);
+  try {
+    const download = (await waiter.promise) as {
+      url?: () => string;
+      suggestedFilename?: () => string;
+      saveAs?: (outPath: string) => Promise<void>;
+    };
+    const suggested = download.suggestedFilename?.() || "download.bin";
+    const outPath = opts.path?.trim() || buildTempDownloadPath(suggested);
+    await mkdir(dirname(outPath), { recursive: true });
+    await download.saveAs?.(outPath);
+    return {
+      url: download.url?.() || "",
+      suggestedFilename: suggested,
+      path: resolve(outPath),
+    };
+  } catch (err) {
+    waiter.cancel();
+    throw err;
+  }
+}