@proagentstore/cli 0.1.18 → 0.1.19

package/dist/browser-runner/browser-actions.js

@@ -0,0 +1,177 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { RunnerInputError } from "./errors.js";
+/**
+ * Execute one selector-free browser action — address by ARIA role + accessible
+ * name, with robust fallbacks for custom comboboxes, typeaheads, fuzzy <select>
+ * matches, hidden checkboxes, and hidden file inputs. Pure over `page`; the
+ * runner passes its clickRobustly helper. The caller handles post-action settle.
+ */
+export async function performBrowserAction(page, action, clickRobustly) {
+    const locate = () => {
+        const role = action.role;
+        let loc = role
+            ? page.getByRole(role, action.name ? { name: action.name } : undefined)
+            : page.getByText(action.name ?? "", { exact: false });
+        loc = typeof action.nth === "number" ? loc.nth(action.nth) : loc.first();
+        return loc;
+    };
+    switch (action.action) {
+        case "navigate":
+            if (!action.url || !/^https?:\/\//.test(action.url))
+                throw new RunnerInputError("navigate requires an http(s) url");
+            await page.goto(action.url, { waitUntil: "domcontentloaded", timeout: 30_000 });
+            break;
+        case "type": {
+            const text = String(action.text ?? "");
+            const loc = locate();
+            // Plain fill, then combobox/label fill (the field may be a combobox or
+            // typeahead, not a bare textbox), then click + keyboard type (typeaheads).
+            if (await loc.fill(text, { timeout: 6_000 }).then(() => true).catch(() => false))
+                break;
+            if (action.name && (await page.getByRole("combobox", { name: action.name }).fill(text, { timeout: 3_000 }).then(() => true).catch(() => false)))
+                break;
+            if (action.name && (await page.getByLabel(action.name).fill(text, { timeout: 3_000 }).then(() => true).catch(() => false)))
+                break;
+            await clickRobustly(page, loc);
+            await page.keyboard.type(text, { delay: 15 }).catch(() => undefined);
+            break;
+        }
+        case "click":
+            if (!(await clickRobustly(page, locate())))
+                throw new RunnerInputError("could not click the target");
+            break;
+        case "select": {
+            const value = String(action.text ?? "");
+            const loc = locate();
+            const pickOption = async () => {
+                const opt = page.getByRole("option", { name: value, exact: false }).first();
+                if ((await opt.count().catch(() => 0)) === 0)
+                    return false;
+                return opt.click({ timeout: 2_500 }).then(() => true).catch(() => false);
+            };
+            // 1. Native <select>: exact label/value, then a fuzzy (case/punctuation
+            //    -insensitive) match so "Decline to self-identify" hits the option
+            //    "Decline To Self Identify".
+            if (await loc.selectOption({ label: value }, { timeout: 4_000 }).then(() => true).catch(() => false))
+                break;
+            if (await loc.selectOption(value, { timeout: 2_500 }).then(() => true).catch(() => false))
+                break;
+            const fuzzy = await loc.evaluate((el, want) => {
+                if (!(el instanceof HTMLSelectElement))
+                    return false;
+                const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "");
+                const w = norm(want);
+                const opt = Array.from(el.options).find((o) => { const t = norm(o.textContent || ""); return t === w || (w.length > 3 && (t.includes(w) || w.includes(t))); });
+                if (!opt)
+                    return false;
+                el.value = opt.value;
+                el.dispatchEvent(new Event("input", { bubbles: true }));
+                el.dispatchEvent(new Event("change", { bubbles: true }));
+                return true;
+            }, value).catch(() => false);
+            if (fuzzy)
+                break;
+            // 2. Custom combobox / typeahead: open it, try a visible matching option.
+            await clickRobustly(page, loc);
+            await page.waitForTimeout(350).catch(() => undefined);
+            if (await pickOption())
+                break;
+            // 3. Typeahead: type to filter, then pick the suggestion — by click, else
+            //    keyboard (ArrowDown+Enter), which beats clicking a dropdown that
+            //    closes on blur.
+            await page.keyboard.type(value, { delay: 15 }).catch(() => undefined);
+            await page.waitForTimeout(550).catch(() => undefined);
+            if (await pickOption())
+                break;
+            await page.keyboard.press("ArrowDown").catch(() => undefined);
+            await page.keyboard.press("Enter").catch(() => undefined);
+            break;
+        }
+        case "check": {
+            const loc = locate();
+            // Custom checkboxes hide the real <input> (opacity:0 / behind a label /
+            // a div[role=checkbox]). Try Playwright's check, then force, then a
+            // direct DOM tick matched by the checkbox's label text.
+            if (await loc.check({ timeout: 5_000 }).then(() => true).catch(() => false))
+                break;
+            if (await loc.check({ force: true, timeout: 3_000 }).then(() => true).catch(() => false))
+                break;
+            const ticked = await page
+                .evaluate((rawName) => {
+                const norm = (s) => (s || "").toLowerCase().replace(/\s+/g, " ").trim();
+                const needle = norm(rawName).slice(0, 30);
+                const boxes = Array.from(document.querySelectorAll('input[type="checkbox"], [role="checkbox"]'));
+                const labelOf = (b) => {
+                    const forId = b.id ? document.querySelector(`label[for="${b.id}"]`)?.textContent : "";
+                    return norm(b.closest("label")?.textContent || b.getAttribute("aria-label") || forId || b.parentElement?.textContent || "");
+                };
+                const tick = (b) => {
+                    if (b instanceof HTMLInputElement) {
+                        b.checked = true;
+                        b.dispatchEvent(new Event("input", { bubbles: true }));
+                        b.dispatchEvent(new Event("change", { bubbles: true }));
+                    }
+                    else {
+                        b.setAttribute("aria-checked", "true");
+                    }
+                    b.click?.();
+                };
+                const match = boxes.find((b) => { const l = labelOf(b); return needle && (l.includes(needle) || (l.length > 12 && needle.includes(l.slice(0, 12)))); });
+                const target = match || (boxes.length === 1 ? boxes[0] : undefined);
+                if (!target)
+                    return false;
+                tick(target);
+                return true;
+            }, action.name ?? "")
+                .catch(() => false);
+            if (ticked)
+                break;
+            if (!(await clickRobustly(page, locate())))
+                throw new RunnerInputError("could not find/tick the checkbox");
+            break;
+        }
+        case "upload": {
+            // Always attach via Playwright — never a native dialog. Handles both a
+            // direct <input type=file> (set files on it) and a styled "Upload"
+            // button that opens a native chooser (intercept the filechooser).
+            const file = resolve(String(action.file ?? ""));
+            if (!file || !existsSync(file))
+                throw new RunnerInputError("upload requires an existing local file path");
+            let done = false;
+            // 1. Label-associated input (some forms).
+            if (action.name) {
+                done = await page.getByLabel(action.name).setInputFiles(file, { timeout: 4_000 }).then(() => true).catch(() => false);
+            }
+            // 2. The real <input type=file> directly — most ATS (Greenhouse, Lever…)
+            //    hide it behind a styled "Attach" button; setInputFiles works on a
+            //    hidden input and fires the change event, no native dialog.
+            if (!done) {
+                done = await page.locator('input[type="file"]').first().setInputFiles(file, { timeout: 4_000 }).then(() => true).catch(() => false);
+            }
+            // 3. Styled uploader with no input at all: click the trigger + intercept
+            //    the native file chooser.
+            if (!done) {
+                const chooserP = page.waitForEvent("filechooser", { timeout: 8_000 }).catch(() => null);
+                await locate().click({ timeout: 8_000 }).catch(() => undefined);
+                const chooser = await chooserP;
+                if (chooser)
+                    await chooser.setFiles(file);
+                else
+                    throw new RunnerInputError("no file upload control found for upload action");
+            }
+            break;
+        }
+        case "key":
+            await page.keyboard.press(String(action.key ?? "Enter"));
+            break;
+        case "scroll":
+            await page.mouse.wheel(0, action.dy ?? 600);
+            break;
+        case "wait":
+            await page.waitForTimeout(Math.min(5_000, action.ms ?? 1_000));
+            break;
+        default:
+            throw new RunnerInputError(`Unknown browser action: ${action.action}`);
+    }
+}

package/dist/browser-runner/browser-profile.js

@@ -0,0 +1,78 @@
+import { copyFileSync, cpSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Seed a dedicated profile directory with a copy of the user's real Chrome
+ * profile — cookies, logins, history, local storage. This gives the runner the
+ * user's signed-in sessions and a human browsing reputation WITHOUT attaching to
+ * the live profile, so it never fights Chrome's single-instance lock and the
+ * user can keep their normal Chrome open. Seeds once; delete the dir to refresh.
+ * Returns the seeded user-data-dir, or null if the source profile is unreadable.
+ */
+export function seedProfileCopy(real, destUserDataDir) {
+    if (existsSync(destUserDataDir))
+        return destUserDataDir; // already seeded
+    const srcProfile = join(real.userDataDir, real.profile);
+    if (!existsSync(srcProfile))
+        return null;
+    const destProfile = join(destUserDataDir, "Default");
+    mkdirSync(destProfile, { recursive: true });
+    try {
+        // "Local State" holds the os_crypt key (Keychain-wrapped) that decrypts
+        // cookies + saved passwords — without it the copied cookies are unreadable.
+        copyFileSync(join(real.userDataDir, "Local State"), join(destUserDataDir, "Local State"));
+    }
+    catch {
+        // best-effort
+    }
+    const items = [
+        "Cookies",
+        "Cookies-journal",
+        "Login Data",
+        "Login Data-journal",
+        "Web Data",
+        "History",
+        "Preferences",
+        "Bookmarks",
+        "Favicons",
+        "Network",
+        "Local Storage",
+        "Session Storage",
+        "Sessions",
+        "IndexedDB",
+    ];
+    for (const item of items) {
+        try {
+            cpSync(join(srcProfile, item), join(destProfile, item), { recursive: true });
+        }
+        catch {
+            // best-effort per item
+        }
+    }
+    return destUserDataDir;
+}
+/**
+ * Resolve the user's real Chrome profile when real-profile mode is enabled
+ * (PAGS_RUNNER_REAL_PROFILE=1 or an explicit PAGS_RUNNER_CHROME_USER_DATA_DIR),
+ * so the runner reuses their cookies/logins/history. Returns null otherwise.
+ */
+export function resolveRealChromeProfileDir() {
+    const explicit = process.env.PAGS_RUNNER_CHROME_USER_DATA_DIR;
+    if (process.env.PAGS_RUNNER_REAL_PROFILE !== "1" && !explicit)
+        return null;
+    const expand = (p) => (p.startsWith("~") ? join(homedir(), p.slice(1)) : p);
+    const profile = process.env.PAGS_RUNNER_CHROME_PROFILE || "Default";
+    if (explicit)
+        return { userDataDir: expand(explicit), profile };
+    let userDataDir;
+    if (process.platform === "darwin") {
+        userDataDir = join(homedir(), "Library", "Application Support", "Google", "Chrome");
+    }
+    else if (process.platform === "win32") {
+        userDataDir = join(homedir(), "AppData", "Local", "Google", "Chrome", "User Data");
+    }
+    else {
+        userDataDir = join(homedir(), ".config", "google-chrome");
+    }
+    return existsSync(userDataDir) ? { userDataDir, profile } : null;
+}

package/dist/browser-runner/challenge.js

@@ -0,0 +1,86 @@
+/**
+ * Detect an anti-bot human challenge on the page (reCAPTCHA, hCaptcha,
+ * Cloudflare Turnstile, generic captcha). These can't be solved by the model,
+ * so they trigger a handoff to a human rather than wasted retries.
+ */
+export async function detectHumanChallenge(page) {
+    // hCaptcha + Turnstile mount as explicit widgets — their presence means a
+    // human challenge (these aren't sprinkled invisibly across the web).
+    for (const [type, selector] of [
+        ["hcaptcha", 'iframe[src*="hcaptcha.com"], .h-captcha'],
+        ["cloudflare-turnstile", 'iframe[src*="challenges.cloudflare.com"], .cf-turnstile'],
+        ["arkose-funcaptcha", 'iframe[src*="arkoselabs"], iframe[src*="funcaptcha"], #arkose, #FunCaptcha, [data-callback*="arkose"]'],
+        ["geetest", '.geetest_holder, .geetest_panel, [class*="geetest_"]'],
+    ]) {
+        if ((await page.locator(selector).count().catch(() => 0)) > 0)
+            return type;
+    }
+    // reCAPTCHA is the trap: the invisible v3 "protected by reCAPTCHA" badge is on
+    // countless pages and needs NO human. Only hand off for a VISIBLE, interactive
+    // widget — the "I'm not a robot" checkbox (anchor) or the image-challenge popup
+    // (bframe) — never the badge or the size=invisible variant.
+    const recaptcha = await page
+        .evaluate(() => {
+        const visible = (el) => {
+            const r = el.getBoundingClientRect();
+            const s = getComputedStyle(el);
+            return r.width > 100 && r.height > 50 && s.visibility !== "hidden" && s.display !== "none" && s.opacity !== "0";
+        };
+        for (const f of Array.from(document.querySelectorAll("iframe"))) {
+            const src = f.getAttribute("src") || "";
+            if (!/recaptcha/.test(src))
+                continue;
+            if (f.closest(".grecaptcha-badge"))
+                continue; // invisible v3 badge
+            if (/size=invisible/.test(src))
+                continue; // invisible variant
+            if (/bframe/.test(src) && visible(f))
+                return true; // image-challenge popup
+            if (/anchor/.test(src) && visible(f))
+                return true; // checkbox
+        }
+        const div = document.querySelector('.g-recaptcha:not([data-size="invisible"])');
+        return !!(div && visible(div));
+    })
+        .catch(() => false);
+    if (recaptcha)
+        return "recaptcha";
+    // Unknown-vendor captchas (e.g. PageUp/Bendigo): an explicit "confirm you are
+    // not a robot" prompt is a near-certain human challenge. Match the specific
+    // phrasing (not just the word "robot") to avoid flagging article text.
+    const robotPrompt = await page
+        .evaluate(() => {
+        const t = (document.body?.innerText || "").toLowerCase();
+        return /confirm (that )?you('?re| are) not a robot|i'?m not a robot|verify (that )?you('?re| are) (a )?human|prove you('?re| are) (not a robot|human)/.test(t);
+    })
+        .catch(() => false);
+    return robotPrompt ? "captcha" : null;
+}
+/**
+ * Whether a detected challenge has actually been solved — i.e. the widget has
+ * produced a response token. A solved captcha keeps its widget in the DOM, so
+ * presence alone isn't "still blocked"; the token is the real signal.
+ */
+export async function challengeSolved(page) {
+    return page
+        .evaluate(() => {
+        const names = ["h-captcha-response", "g-recaptcha-response", "cf-turnstile-response"];
+        for (const n of names) {
+            const el = document.querySelector(`textarea[name="${n}"], input[name="${n}"]`);
+            if (el && typeof el.value === "string" && el.value.length > 0)
+                return true;
+        }
+        return false;
+    })
+        .catch(() => false);
+}
+/** Capture a downscaled JPEG screenshot as a data URL for the human-takeover UI. */
+export async function captureScreenshotDataUrl(page) {
+    try {
+        const buf = await page.screenshot({ type: "jpeg", quality: 55 });
+        return `data:image/jpeg;base64,${buf.toString("base64")}`;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/browser-runner/errors.js

@@ -0,0 +1,13 @@
+/** Raised when the model/runner cannot proceed and a human must take over. */
+export class HumanHandoffError extends Error {
+    handoff;
+    constructor(message, handoff) {
+        super(message);
+        this.handoff = handoff;
+        this.name = "HumanHandoffError";
+    }
+}
+/** A bad client request to the runner (maps to HTTP 400). */
+export class RunnerInputError extends Error {
+    status = 400;
+}

package/dist/browser-runner/human-mouse.js

@@ -0,0 +1,71 @@
+const rand = (min, max) => min + Math.random() * (max - min);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// easeInOutQuad — slow start, fast middle, slow approach (how a hand decelerates onto a target).
+const ease = (t) => (t < 0.5 ? 2 * t * t : 1 - (-2 * t + 2) ** 2 / 2);
+function cubicBezier(p0, p1, p2, p3, t) {
+    const u = 1 - t;
+    return {
+        x: u * u * u * p0.x + 3 * u * u * t * p1.x + 3 * u * t * t * p2.x + t * t * t * p3.x,
+        y: u * u * u * p0.y + 3 * u * u * t * p1.y + 3 * u * t * t * p2.y + t * t * t * p3.y,
+    };
+}
+/** Move the cursor from `from` to `to` along a randomized human-like arc. */
+export async function humanMoveTo(cdp, from, to) {
+    const dist = Math.hypot(to.x - from.x, to.y - from.y);
+    const steps = Math.max(12, Math.min(42, Math.round(dist / 9)));
+    // Control points pushed off the straight line so the path bows like a real
+    // hand's arc — bigger arc for longer travel.
+    const off = Math.min(90, dist * 0.3);
+    const c1 = {
+        x: from.x + (to.x - from.x) * 0.33 + rand(-off, off),
+        y: from.y + (to.y - from.y) * 0.33 + rand(-off, off),
+    };
+    const c2 = {
+        x: from.x + (to.x - from.x) * 0.66 + rand(-off, off),
+        y: from.y + (to.y - from.y) * 0.66 + rand(-off, off),
+    };
+    for (let i = 1; i <= steps; i++) {
+        const p = cubicBezier(from, c1, c2, to, ease(i / steps));
+        await cdp.send("Input.dispatchMouseEvent", {
+            type: "mouseMoved",
+            x: p.x + rand(-0.6, 0.6),
+            y: p.y + rand(-0.6, 0.6),
+        });
+        await sleep(rand(5, 15));
+    }
+}
+/** Click `to` with a human approach + natural press/release dwell. */
+export async function humanClickAt(cdp, from, to) {
+    await humanMoveTo(cdp, from, to);
+    await sleep(rand(40, 130));
+    await cdp.send("Input.dispatchMouseEvent", { type: "mousePressed", x: to.x, y: to.y, button: "left", buttons: 1, clickCount: 1 });
+    await sleep(rand(40, 100));
+    await cdp.send("Input.dispatchMouseEvent", { type: "mouseReleased", x: to.x, y: to.y, button: "left", buttons: 0, clickCount: 1 });
+}
+/** Pick a natural target point inside a box (not dead-center) + an off-screen-ish start. */
+export function targetIn(box) {
+    const to = {
+        x: box.x + box.width / 2 + rand(-box.width * 0.2, box.width * 0.2),
+        y: box.y + box.height / 2 + rand(-box.height * 0.25, box.height * 0.25),
+    };
+    const from = { x: to.x + rand(-260, -40), y: to.y - rand(60, 260) };
+    return { from, to };
+}
+/**
+ * Best-effort humanized approach to an element before the caller's real click,
+ * so the cursor arrives the way a hand would. Never throws — humanization must
+ * not break the underlying action.
+ */
+export async function humanApproach(page, box) {
+    if (!box)
+        return;
+    try {
+        const cdp = await page.context().newCDPSession(page);
+        const { from, to } = targetIn(box);
+        await humanMoveTo(cdp, from, to);
+        await cdp.detach().catch(() => undefined);
+    }
+    catch {
+        // humanization is an enhancement, never a hard dependency
+    }
+}