@aria-cli/tools 1.0.19 → 1.0.31

package/dist/definitions/browser/pw-session.js

@@ -0,0 +1,311 @@
+// 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
+import { MAX_CONSOLE_MESSAGES, MAX_NETWORK_REQUESTS, MAX_PAGE_ERRORS } from "./pw-responses.js";
+// ── Module-level state (singleton per Node process) ───────────────────
+let currentSession = null;
+let currentRefs = {};
+const consoleMessages = [];
+const networkRequests = [];
+const pageErrors = [];
+let nextRequestId = 0;
+const DEFAULT_NAVIGATION_OPTIONS = {
+    timeout: 20_000,
+    waitUntil: "domcontentloaded",
+};
+// ── Accessors ─────────────────────────────────────────────────────────
+export function getSession() {
+    return currentSession;
+}
+export function getRefs() {
+    return currentRefs;
+}
+export function setRefs(refs) {
+    currentRefs = refs;
+}
+export function getConsoleMessages() {
+    return consoleMessages;
+}
+export function getNetworkRequests() {
+    return networkRequests;
+}
+export function getPageErrors() {
+    return pageErrors;
+}
+const defaultPlaywrightLoader = () => Function('return import("playwright")')();
+let playwrightLoader = defaultPlaywrightLoader;
+/**
+ * Test seam for injecting a mocked playwright loader.
+ * Passing null restores the production loader.
+ */
+export function setPlaywrightLoaderForTest(loader) {
+    playwrightLoader = loader ?? defaultPlaywrightLoader;
+}
+// ── Page listener wiring ──────────────────────────────────────────────
+const observedPages = new WeakSet();
+function wirePageListeners(page) {
+    if (observedPages.has(page)) {
+        return;
+    }
+    observedPages.add(page);
+    page.on("console", (...args) => {
+        const msg = args[0];
+        if (!msg)
+            return;
+        const entry = {
+            type: typeof msg.type === "function" ? msg.type() : "log",
+            text: typeof msg.text === "function" ? msg.text() : String(msg),
+            timestamp: new Date().toISOString(),
+        };
+        consoleMessages.push(entry);
+        if (consoleMessages.length > MAX_CONSOLE_MESSAGES) {
+            consoleMessages.shift();
+        }
+    });
+    page.on("pageerror", (...args) => {
+        const err = args[0];
+        pageErrors.push({
+            message: err?.message ? String(err.message) : String(err),
+            name: err?.name ? String(err.name) : undefined,
+            timestamp: new Date().toISOString(),
+        });
+        if (pageErrors.length > MAX_PAGE_ERRORS) {
+            pageErrors.shift();
+        }
+    });
+    page.on("request", (...args) => {
+        const req = args[0];
+        if (!req)
+            return;
+        nextRequestId += 1;
+        const entry = {
+            id: `r${nextRequestId}`,
+            timestamp: new Date().toISOString(),
+            method: typeof req.method === "function" ? req.method() : "GET",
+            url: typeof req.url === "function" ? req.url() : "",
+            resourceType: typeof req.resourceType === "function" ? req.resourceType() : undefined,
+        };
+        networkRequests.push(entry);
+        if (networkRequests.length > MAX_NETWORK_REQUESTS) {
+            networkRequests.shift();
+        }
+    });
+    page.on("response", (...args) => {
+        const resp = args[0];
+        if (!resp)
+            return;
+        const respUrl = typeof resp.url === "function" ? resp.url() : "";
+        // Match by URL (find most recent matching request)
+        for (let i = networkRequests.length - 1; i >= 0; i -= 1) {
+            const rec = networkRequests[i];
+            if (rec && rec.url === respUrl && rec.status === undefined) {
+                rec.status = typeof resp.status === "function" ? resp.status() : undefined;
+                rec.ok = typeof resp.ok === "function" ? resp.ok() : undefined;
+                break;
+            }
+        }
+    });
+    page.on("requestfailed", (...args) => {
+        const req = args[0];
+        if (!req)
+            return;
+        const failUrl = typeof req.url === "function" ? req.url() : "";
+        for (let i = networkRequests.length - 1; i >= 0; i -= 1) {
+            const rec = networkRequests[i];
+            if (rec && rec.url === failUrl && rec.ok === undefined) {
+                rec.ok = false;
+                rec.failureText = typeof req.failure === "function" ? req.failure()?.errorText : undefined;
+                break;
+            }
+        }
+    });
+}
+function isChromiumLike(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.launch === "function");
+}
+/**
+ * Resolve Playwright's chromium launcher across module interop shapes.
+ * Some runtimes expose `{ chromium }`, others only `{ default: { chromium } }`.
+ */
+export function resolveChromiumLauncher(moduleValue) {
+    const pw = moduleValue;
+    const chromium = pw?.chromium ?? pw?.default?.chromium;
+    if (isChromiumLike(chromium)) {
+        return chromium;
+    }
+    const keys = pw && typeof pw === "object"
+        ? Object.keys(pw)
+            .sort()
+            .join(", ")
+        : String(pw);
+    throw new Error(`Invalid playwright module shape: missing chromium.launch (module keys: ${keys || "(none)"}).`);
+}
+/**
+ * Launch a new Playwright browser session.
+ * Uses dynamic import so the tool module loads even without playwright installed.
+ */
+export async function launchBrowser(options) {
+    if (currentSession) {
+        // Already have a session — navigate if URL given, otherwise return existing
+        if (options?.url) {
+            try {
+                await currentSession.page.goto(options.url, DEFAULT_NAVIGATION_OPTIONS);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`Navigation to ${options.url} failed: ${message}. Session remains active; use 'snapshot' or retry 'navigate'.`);
+            }
+        }
+        return currentSession;
+    }
+    // Dynamic import: playwright is an optional peer dependency.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let pw;
+    try {
+        pw = await playwrightLoader();
+    }
+    catch {
+        throw new Error("playwright is not installed. Run: npx playwright install chromium\n" +
+            "Or: npm install playwright && npx playwright install chromium");
+    }
+    const chromium = resolveChromiumLauncher(pw);
+    const browser = await chromium.launch({
+        headless: options?.headless !== false, // default headless
+    });
+    const context = browser.newContext
+        ? await browser.newContext({
+            viewport: { width: 1280, height: 720 },
+            userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+        })
+        : (browser.contexts()[0] ??
+            (() => {
+                throw new Error("No browser context available");
+            })());
+    const page = context.pages?.().length
+        ? context.pages()[0]
+        : await context.newPage();
+    wirePageListeners(page);
+    // Persist session state before first navigation so launch+goto timeout
+    // cannot leave the tool in a "no session" state.
+    currentSession = { browser, context, page };
+    currentRefs = {};
+    consoleMessages.length = 0;
+    networkRequests.length = 0;
+    pageErrors.length = 0;
+    nextRequestId = 0;
+    if (options?.url) {
+        try {
+            await page.goto(options.url, DEFAULT_NAVIGATION_OPTIONS);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Browser launched, but initial navigation to ${options.url} failed: ${message}. Session remains active; use 'snapshot' or retry 'navigate'.`);
+        }
+    }
+    return currentSession;
+}
+/**
+ * Close the current browser session and clean up all state.
+ */
+export async function closeBrowser() {
+    const session = currentSession;
+    currentSession = null;
+    currentRefs = {};
+    consoleMessages.length = 0;
+    networkRequests.length = 0;
+    pageErrors.length = 0;
+    nextRequestId = 0;
+    if (session) {
+        try {
+            await session.browser.close();
+        }
+        catch {
+            // Best-effort close.
+        }
+    }
+}
+// ── Tab management ────────────────────────────────────────────────────
+/**
+ * List all open tabs (pages) in the current context.
+ */
+export function listTabs() {
+    if (!currentSession) {
+        return [];
+    }
+    const pages = currentSession.context.pages();
+    return pages.map((p, i) => ({
+        index: i,
+        url: p.url(),
+        active: p === currentSession.page,
+    }));
+}
+/**
+ * Open a new tab, optionally navigating to a URL.
+ */
+export async function newTab(url) {
+    if (!currentSession) {
+        const launched = await launchBrowser({ url });
+        return { index: 0, url: launched.page.url() };
+    }
+    const page = await currentSession.context.newPage();
+    wirePageListeners(page);
+    currentSession.page = page;
+    currentRefs = {};
+    if (url) {
+        await page.goto(url, DEFAULT_NAVIGATION_OPTIONS);
+    }
+    const pages = currentSession.context.pages();
+    return { index: pages.length - 1, url: page.url() };
+}
+/**
+ * Switch to a tab by index.
+ */
+export async function selectTab(index) {
+    if (!currentSession) {
+        await launchBrowser();
+    }
+    if (!currentSession) {
+        throw new Error("No tabs open.");
+    }
+    const pages = currentSession.context.pages();
+    if (index < 0 || index >= pages.length) {
+        throw new Error(`Tab index ${index} out of range (0..${pages.length - 1})`);
+    }
+    const page = pages[index];
+    currentSession.page = page;
+    wirePageListeners(page);
+    currentRefs = {};
+    return { url: page.url() };
+}
+/**
+ * Close a tab by index (defaults to current tab).
+ */
+export async function closeTab(index) {
+    if (!currentSession) {
+        throw new Error("No tabs open.");
+    }
+    const pages = currentSession.context.pages();
+    const targetIndex = index ?? pages.indexOf(currentSession.page);
+    if (targetIndex < 0 || targetIndex >= pages.length) {
+        throw new Error(`Tab index ${targetIndex} out of range`);
+    }
+    const targetPage = pages[targetIndex];
+    await targetPage.close();
+    // Update current page if we closed the active one
+    const remaining = currentSession.context.pages();
+    if (!remaining.length) {
+        // All tabs closed — create a fresh one
+        const page = await currentSession.context.newPage();
+        currentSession.page = page;
+        wirePageListeners(page);
+    }
+    else if (targetPage === currentSession.page) {
+        const newIndex = Math.min(targetIndex, remaining.length - 1);
+        currentSession.page = remaining[newIndex];
+        wirePageListeners(currentSession.page);
+    }
+    currentRefs = {};
+}
+//# sourceMappingURL=pw-session.js.map

package/dist/definitions/browser/pw-shared.js

@@ -0,0 +1,67 @@
+// 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
+/**
+ * Shared utilities for Playwright-based browser tool functions.
+ * Ported from OpenClaw's pw-tools-core.shared.ts.
+ */
+/**
+ * Parse a raw ref string into its canonical "eN" form.
+ * Accepts: "e1", "@e1", "ref=e1" -> "e1". Returns null if invalid.
+ */
+export function parseRoleRef(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const normalized = trimmed.startsWith("@")
+        ? trimmed.slice(1)
+        : trimmed.startsWith("ref=")
+            ? trimmed.slice(4)
+            : trimmed;
+    return /^e\d+$/.test(normalized) ? normalized : null;
+}
+/**
+ * Validate and normalize a ref string. Throws if the ref is empty/invalid.
+ */
+export function requireRef(value) {
+    const raw = typeof value === "string" ? value.trim() : "";
+    const roleRef = raw ? parseRoleRef(raw) : null;
+    const ref = roleRef ?? (raw.startsWith("@") ? raw.slice(1) : raw);
+    if (!ref) {
+        throw new Error("ref is required");
+    }
+    return ref;
+}
+/**
+ * Clamp a timeout value to a safe range (500ms .. 120s).
+ */
+export function normalizeTimeoutMs(timeoutMs, fallback) {
+    return Math.max(500, Math.min(120_000, timeoutMs ?? fallback));
+}
+/**
+ * Rewrite Playwright errors into messages that guide the LLM to take
+ * corrective action (re-snapshot, scroll, etc.).
+ */
+export function toAIFriendlyError(error, selector) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("strict mode violation")) {
+        const countMatch = message.match(/resolved to (\d+) elements/);
+        const count = countMatch ? countMatch[1] : "multiple";
+        return new Error(`Selector "${selector}" matched ${count} elements. ` +
+            `Run a new snapshot to get updated refs, or use a different ref.`);
+    }
+    if ((message.includes("Timeout") || message.includes("waiting for")) &&
+        (message.includes("to be visible") || message.includes("not visible"))) {
+        return new Error(`Element "${selector}" not found or not visible. ` +
+            `Run a new snapshot to see current page elements.`);
+    }
+    if (message.includes("intercepts pointer events") ||
+        message.includes("not visible") ||
+        message.includes("not receive pointer events")) {
+        return new Error(`Element "${selector}" is not interactable (hidden or covered). ` +
+            `Try scrolling it into view, closing overlays, or re-snapshotting.`);
+    }
+    return error instanceof Error ? error : new Error(message);
+}
+//# sourceMappingURL=pw-shared.js.map

package/dist/definitions/browser/pw-snapshot.js

@@ -0,0 +1,302 @@
+// 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
+// ── Role classification sets ──────────────────────────────────────────
+const INTERACTIVE_ROLES = new Set([
+    "button",
+    "link",
+    "textbox",
+    "checkbox",
+    "radio",
+    "combobox",
+    "listbox",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "option",
+    "searchbox",
+    "slider",
+    "spinbutton",
+    "switch",
+    "tab",
+    "treeitem",
+]);
+const CONTENT_ROLES = new Set([
+    "heading",
+    "cell",
+    "gridcell",
+    "columnheader",
+    "rowheader",
+    "listitem",
+    "article",
+    "region",
+    "main",
+    "navigation",
+]);
+const STRUCTURAL_ROLES = new Set([
+    "generic",
+    "group",
+    "list",
+    "table",
+    "row",
+    "rowgroup",
+    "grid",
+    "treegrid",
+    "menu",
+    "menubar",
+    "toolbar",
+    "tablist",
+    "tree",
+    "directory",
+    "document",
+    "application",
+    "presentation",
+    "none",
+]);
+// ── Stats ─────────────────────────────────────────────────────────────
+export function getRoleSnapshotStats(snapshot, refs) {
+    const interactive = Object.values(refs).filter((r) => INTERACTIVE_ROLES.has(r.role)).length;
+    return {
+        lines: snapshot.split("\n").length,
+        chars: snapshot.length,
+        refs: Object.keys(refs).length,
+        interactive,
+    };
+}
+// ── Internal helpers ──────────────────────────────────────────────────
+function getIndentLevel(line) {
+    const match = line.match(/^(\s*)/);
+    return match ? Math.floor(match[1].length / 2) : 0;
+}
+function createRoleNameTracker() {
+    const counts = new Map();
+    const refsByKey = new Map();
+    return {
+        counts,
+        refsByKey,
+        getKey(role, name) {
+            return `${role}:${name ?? ""}`;
+        },
+        getNextIndex(role, name) {
+            const key = this.getKey(role, name);
+            const current = counts.get(key) ?? 0;
+            counts.set(key, current + 1);
+            return current;
+        },
+        trackRef(role, name, ref) {
+            const key = this.getKey(role, name);
+            const list = refsByKey.get(key) ?? [];
+            list.push(ref);
+            refsByKey.set(key, list);
+        },
+        getDuplicateKeys() {
+            const out = new Set();
+            for (const [key, refs] of refsByKey) {
+                if (refs.length > 1) {
+                    out.add(key);
+                }
+            }
+            return out;
+        },
+    };
+}
+function removeNthFromNonDuplicates(refs, tracker) {
+    const duplicates = tracker.getDuplicateKeys();
+    for (const [ref, data] of Object.entries(refs)) {
+        const key = tracker.getKey(data.role, data.name);
+        if (!duplicates.has(key)) {
+            delete refs[ref]?.nth;
+        }
+    }
+}
+function compactTree(tree) {
+    const lines = tree.split("\n");
+    const result = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (line.includes("[ref=")) {
+            result.push(line);
+            continue;
+        }
+        if (line.includes(":") && !line.trimEnd().endsWith(":")) {
+            result.push(line);
+            continue;
+        }
+        const currentIndent = getIndentLevel(line);
+        let hasRelevantChildren = false;
+        for (let j = i + 1; j < lines.length; j += 1) {
+            const childIndent = getIndentLevel(lines[j]);
+            if (childIndent <= currentIndent) {
+                break;
+            }
+            if (lines[j]?.includes("[ref=")) {
+                hasRelevantChildren = true;
+                break;
+            }
+        }
+        if (hasRelevantChildren) {
+            result.push(line);
+        }
+    }
+    return result.join("\n");
+}
+function matchInteractiveSnapshotLine(line, options) {
+    const depth = getIndentLevel(line);
+    if (options.maxDepth !== undefined && depth > options.maxDepth) {
+        return null;
+    }
+    const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
+    if (!match) {
+        return null;
+    }
+    const [, , roleRaw, name, suffix] = match;
+    if (roleRaw.startsWith("/")) {
+        return null;
+    }
+    const role = roleRaw.toLowerCase();
+    return {
+        roleRaw: roleRaw,
+        role,
+        ...(name ? { name } : {}),
+        suffix: suffix,
+    };
+}
+function processLine(line, refs, options, tracker, nextRef) {
+    const depth = getIndentLevel(line);
+    if (options.maxDepth !== undefined && depth > options.maxDepth) {
+        return null;
+    }
+    const match = line.match(/^(\s*-\s*)(\w+)(?:\s+"([^"]*)")?(.*)$/);
+    if (!match) {
+        return options.interactive ? null : line;
+    }
+    const [, prefix, roleRaw, name, suffix] = match;
+    if (roleRaw.startsWith("/")) {
+        return options.interactive ? null : line;
+    }
+    const role = roleRaw.toLowerCase();
+    const isInteractive = INTERACTIVE_ROLES.has(role);
+    const isContent = CONTENT_ROLES.has(role);
+    const isStructural = STRUCTURAL_ROLES.has(role);
+    if (options.interactive && !isInteractive) {
+        return null;
+    }
+    if (options.compact && isStructural && !name) {
+        return null;
+    }
+    const shouldHaveRef = isInteractive || (isContent && !!name);
+    if (!shouldHaveRef) {
+        return line;
+    }
+    const ref = nextRef();
+    const nth = tracker.getNextIndex(role, name);
+    tracker.trackRef(role, name, ref);
+    refs[ref] = { role, name, nth };
+    let enhanced = `${prefix}${roleRaw}`;
+    if (name) {
+        enhanced += ` "${name}"`;
+    }
+    enhanced += ` [ref=${ref}]`;
+    if (nth > 0) {
+        enhanced += ` [nth=${nth}]`;
+    }
+    if (suffix) {
+        enhanced += suffix;
+    }
+    return enhanced;
+}
+// ── Public API ────────────────────────────────────────────────────────
+/**
+ * Build a role-ref snapshot from Playwright's ariaSnapshot() output.
+ * This is the core transform: raw ARIA tree text -> annotated tree + ref map.
+ */
+export function buildRoleSnapshotFromAriaSnapshot(ariaSnapshot, options = {}) {
+    const lines = ariaSnapshot.split("\n");
+    const refs = {};
+    const tracker = createRoleNameTracker();
+    let counter = 0;
+    const nextRef = () => {
+        counter += 1;
+        return `e${counter}`;
+    };
+    if (options.interactive) {
+        const result = [];
+        for (const line of lines) {
+            const parsed = matchInteractiveSnapshotLine(line, options);
+            if (!parsed) {
+                continue;
+            }
+            const { roleRaw, role, name, suffix } = parsed;
+            if (!INTERACTIVE_ROLES.has(role)) {
+                continue;
+            }
+            const ref = nextRef();
+            const nth = tracker.getNextIndex(role, name);
+            tracker.trackRef(role, name, ref);
+            refs[ref] = { role, name, nth };
+            let enhanced = `- ${roleRaw}`;
+            if (name) {
+                enhanced += ` "${name}"`;
+            }
+            enhanced += ` [ref=${ref}]`;
+            if (nth > 0) {
+                enhanced += ` [nth=${nth}]`;
+            }
+            if (suffix.includes("[")) {
+                enhanced += suffix;
+            }
+            result.push(enhanced);
+        }
+        removeNthFromNonDuplicates(refs, tracker);
+        return {
+            snapshot: result.join("\n") || "(no interactive elements)",
+            refs,
+        };
+    }
+    const result = [];
+    for (const line of lines) {
+        const processed = processLine(line, refs, options, tracker, nextRef);
+        if (processed !== null) {
+            result.push(processed);
+        }
+    }
+    removeNthFromNonDuplicates(refs, tracker);
+    const tree = result.join("\n") || "(empty)";
+    return {
+        snapshot: options.compact ? compactTree(tree) : tree,
+        refs,
+    };
+}
+/**
+ * Take a role-based accessibility snapshot of a page.
+ * Uses Playwright's built-in ariaSnapshot() on the :root locator,
+ * then annotates elements with [ref=eN] markers.
+ */
+export async function snapshotPage(page, options) {
+    const locator = page.locator(":root");
+    const ariaSnapshot = await locator.ariaSnapshot();
+    const built = buildRoleSnapshotFromAriaSnapshot(String(ariaSnapshot ?? ""), options);
+    const stats = getRoleSnapshotStats(built.snapshot, built.refs);
+    return {
+        snapshot: built.snapshot,
+        refs: built.refs,
+        stats,
+        url: page.url(),
+        title: await page.title(),
+    };
+}
+/**
+ * Navigate a page to a URL.
+ */
+export async function navigatePage(page, url, timeoutMs) {
+    const target = String(url ?? "").trim();
+    if (!target) {
+        throw new Error("url is required");
+    }
+    await page.goto(target, {
+        timeout: Math.max(1000, Math.min(120_000, timeoutMs ?? 20_000)),
+        waitUntil: "domcontentloaded",
+    });
+    return { url: page.url() };
+}
+//# sourceMappingURL=pw-snapshot.js.map