tuna-agent 0.1.0 → 0.1.2

package/dist/browser/connection.js

@@ -0,0 +1,359 @@
+import { chromium } from 'playwright-core';
+import { getChromeWebSocketUrl } from './chrome-launcher.js';
+// ── Persistent Connection Cache ──
+let cached = null;
+const connectingByUrl = new Map();
+const pageStates = new WeakMap();
+const observedContexts = new WeakSet();
+const observedPages = new WeakSet();
+// Ref cache: keyed by "cdpUrl::targetId"
+const roleRefsByTarget = new Map();
+const MAX_ROLE_REFS_CACHE = 50;
+const MAX_CONSOLE_MESSAGES = 500;
+const MAX_PAGE_ERRORS = 200;
+const MAX_NETWORK_REQUESTS = 500;
+function normalizeCdpUrl(raw) {
+    return raw.replace(/\/$/, '');
+}
+function roleRefsKey(cdpUrl, targetId) {
+    return `${normalizeCdpUrl(cdpUrl)}::${targetId}`;
+}
+// ── Page State Management ──
+export function ensurePageState(page) {
+    const existing = pageStates.get(page);
+    if (existing)
+        return existing;
+    const state = {
+        console: [],
+        errors: [],
+        requests: [],
+        requestIds: new WeakMap(),
+        nextRequestId: 0,
+    };
+    pageStates.set(page, state);
+    if (!observedPages.has(page)) {
+        observedPages.add(page);
+        page.on('console', (msg) => {
+            state.console.push({
+                type: msg.type(),
+                text: msg.text(),
+                timestamp: new Date().toISOString(),
+                location: msg.location(),
+            });
+            if (state.console.length > MAX_CONSOLE_MESSAGES)
+                state.console.shift();
+        });
+        page.on('pageerror', (err) => {
+            state.errors.push({
+                message: err?.message ? String(err.message) : String(err),
+                name: err?.name ? String(err.name) : undefined,
+                stack: err?.stack ? String(err.stack) : undefined,
+                timestamp: new Date().toISOString(),
+            });
+            if (state.errors.length > MAX_PAGE_ERRORS)
+                state.errors.shift();
+        });
+        page.on('request', (req) => {
+            state.nextRequestId += 1;
+            const id = `r${state.nextRequestId}`;
+            state.requestIds.set(req, id);
+            state.requests.push({
+                id,
+                timestamp: new Date().toISOString(),
+                method: req.method(),
+                url: req.url(),
+                resourceType: req.resourceType(),
+            });
+            if (state.requests.length > MAX_NETWORK_REQUESTS)
+                state.requests.shift();
+        });
+        page.on('response', (resp) => {
+            const req = resp.request();
+            const id = state.requestIds.get(req);
+            if (!id)
+                return;
+            for (let i = state.requests.length - 1; i >= 0; i--) {
+                const rec = state.requests[i];
+                if (rec && rec.id === id) {
+                    rec.status = resp.status();
+                    rec.ok = resp.ok();
+                    break;
+                }
+            }
+        });
+        page.on('requestfailed', (req) => {
+            const id = state.requestIds.get(req);
+            if (!id)
+                return;
+            for (let i = state.requests.length - 1; i >= 0; i--) {
+                const rec = state.requests[i];
+                if (rec && rec.id === id) {
+                    rec.failureText = req.failure()?.errorText;
+                    rec.ok = false;
+                    break;
+                }
+            }
+        });
+        page.on('close', () => {
+            pageStates.delete(page);
+            observedPages.delete(page);
+        });
+    }
+    return state;
+}
+// ── Stealth: hide navigator.webdriver ──
+const STEALTH_SCRIPT = `Object.defineProperty(navigator, 'webdriver', { get: () => undefined })`;
+/** Skip stealth injection (sites like X.com detect it and force logout) */
+let stealthEnabled = true;
+export function setStealthEnabled(enabled) {
+    stealthEnabled = enabled;
+}
+function applyStealthToPage(page) {
+    if (!stealthEnabled)
+        return;
+    page.evaluate(STEALTH_SCRIPT).catch((e) => {
+        if (process.env.DEBUG)
+            console.warn('[browserclaw] stealth evaluate failed:', e.message);
+    });
+}
+function observeContext(context) {
+    if (observedContexts.has(context))
+        return;
+    observedContexts.add(context);
+    if (stealthEnabled) {
+        context.addInitScript(STEALTH_SCRIPT).catch((e) => {
+            if (process.env.DEBUG)
+                console.warn('[browserclaw] stealth initScript failed:', e.message);
+        });
+    }
+    for (const page of context.pages()) {
+        ensurePageState(page);
+        applyStealthToPage(page);
+    }
+    context.on('page', (page) => {
+        ensurePageState(page);
+        applyStealthToPage(page);
+    });
+}
+function observeBrowser(browser) {
+    for (const context of browser.contexts())
+        observeContext(context);
+}
+// ── Role Refs Storage ──
+export function storeRoleRefsForTarget(opts) {
+    const state = ensurePageState(opts.page);
+    state.roleRefs = opts.refs;
+    state.roleRefsFrameSelector = opts.frameSelector;
+    state.roleRefsMode = opts.mode;
+    const targetId = opts.targetId?.trim();
+    if (!targetId)
+        return;
+    roleRefsByTarget.set(roleRefsKey(opts.cdpUrl, targetId), {
+        refs: opts.refs,
+        ...(opts.frameSelector ? { frameSelector: opts.frameSelector } : {}),
+        ...(opts.mode ? { mode: opts.mode } : {}),
+    });
+    while (roleRefsByTarget.size > MAX_ROLE_REFS_CACHE) {
+        const first = roleRefsByTarget.keys().next();
+        if (first.done)
+            break;
+        roleRefsByTarget.delete(first.value);
+    }
+}
+export function restoreRoleRefsForTarget(opts) {
+    const targetId = opts.targetId?.trim() || '';
+    if (!targetId)
+        return;
+    const entry = roleRefsByTarget.get(roleRefsKey(opts.cdpUrl, targetId));
+    if (!entry)
+        return;
+    const state = ensurePageState(opts.page);
+    if (state.roleRefs)
+        return;
+    state.roleRefs = entry.refs;
+    state.roleRefsFrameSelector = entry.frameSelector;
+    state.roleRefsMode = entry.mode;
+}
+// ── Connect to Browser ──
+export async function connectBrowser(cdpUrl, authToken) {
+    const normalized = normalizeCdpUrl(cdpUrl);
+    if (cached?.cdpUrl === normalized)
+        return cached;
+    const existing = connectingByUrl.get(normalized);
+    if (existing)
+        return await existing;
+    const connectWithRetry = async () => {
+        let lastErr;
+        for (let attempt = 0; attempt < 3; attempt++) {
+            try {
+                const timeout = 5000 + attempt * 2000;
+                const endpoint = await getChromeWebSocketUrl(normalized, timeout, authToken).catch(() => null) ?? normalized;
+                const headers = {};
+                if (authToken)
+                    headers['Authorization'] = `Bearer ${authToken}`;
+                const browser = await chromium.connectOverCDP(endpoint, { timeout, headers });
+                const connected = { browser, cdpUrl: normalized, authToken };
+                cached = connected;
+                observeBrowser(browser);
+                browser.on('disconnected', () => {
+                    if (cached?.browser === browser)
+                        cached = null;
+                    for (const key of roleRefsByTarget.keys()) {
+                        if (key.startsWith(normalized + '::'))
+                            roleRefsByTarget.delete(key);
+                    }
+                });
+                return connected;
+            }
+            catch (err) {
+                lastErr = err;
+                await new Promise(r => setTimeout(r, 250 + attempt * 250));
+            }
+        }
+        throw lastErr instanceof Error ? lastErr : new Error('CDP connect failed');
+    };
+    const promise = connectWithRetry().finally(() => { connectingByUrl.delete(normalized); });
+    connectingByUrl.set(normalized, promise);
+    return await promise;
+}
+export async function disconnectBrowser() {
+    if (connectingByUrl.size) {
+        for (const p of connectingByUrl.values()) {
+            try {
+                await p;
+            }
+            catch { }
+        }
+    }
+    const cur = cached;
+    cached = null;
+    if (cur)
+        await cur.browser.close().catch(() => { });
+}
+export async function getAllPages(browser) {
+    return browser.contexts().flatMap(c => c.pages());
+}
+export async function pageTargetId(page) {
+    const session = await page.context().newCDPSession(page);
+    try {
+        const info = await session.send('Target.getTargetInfo');
+        const targetInfo = info.targetInfo;
+        return String(targetInfo?.targetId ?? '').trim() || null;
+    }
+    finally {
+        await session.detach().catch(() => { });
+    }
+}
+export async function findPageByTargetId(browser, targetId, cdpUrl) {
+    const pages = await getAllPages(browser);
+    let resolvedViaCdp = false;
+    for (const page of pages) {
+        let tid = null;
+        try {
+            tid = await pageTargetId(page);
+            resolvedViaCdp = true;
+        }
+        catch {
+            tid = null;
+        }
+        if (tid && tid === targetId)
+            return page;
+    }
+    // Extension relays can block CDP attachment APIs entirely. If that happens and
+    // Playwright only exposes one page, return it as the best available mapping.
+    if (!resolvedViaCdp && pages.length === 1) {
+        return pages[0];
+    }
+    // Fallback: match by URL from /json/list
+    if (cdpUrl) {
+        try {
+            const listUrl = `${cdpUrl.replace(/\/+$/, '').replace(/^ws:/, 'http:').replace(/\/cdp$/, '')}/json/list`;
+            const headers = {};
+            if (cached?.authToken)
+                headers['Authorization'] = `Bearer ${cached.authToken}`;
+            const response = await fetch(listUrl, { headers });
+            if (response.ok) {
+                const targets = await response.json();
+                const target = targets.find(t => t.id === targetId);
+                if (target) {
+                    const urlMatch = pages.filter(p => p.url() === target.url);
+                    if (urlMatch.length === 1)
+                        return urlMatch[0];
+                    if (urlMatch.length > 1) {
+                        const sameUrlTargets = targets.filter(t => t.url === target.url);
+                        if (sameUrlTargets.length === urlMatch.length) {
+                            const idx = sameUrlTargets.findIndex(t => t.id === targetId);
+                            if (idx >= 0 && idx < urlMatch.length)
+                                return urlMatch[idx];
+                        }
+                    }
+                }
+            }
+        }
+        catch { }
+    }
+    return null;
+}
+export async function getPageForTargetId(opts) {
+    const { browser } = await connectBrowser(opts.cdpUrl);
+    const pages = await getAllPages(browser);
+    if (!pages.length)
+        throw new Error('No pages available in the connected browser.');
+    const first = pages[0];
+    if (!opts.targetId)
+        return first;
+    const found = await findPageByTargetId(browser, opts.targetId, opts.cdpUrl);
+    if (!found) {
+        if (pages.length === 1)
+            return first;
+        throw new Error(`Tab not found (targetId: ${opts.targetId}). Call browser.tabs() to list open tabs.`);
+    }
+    return found;
+}
+// ── Ref Locator ──
+export function refLocator(page, ref) {
+    const normalized = ref.startsWith('@') ? ref.slice(1) : ref.startsWith('ref=') ? ref.slice(4) : ref;
+    if (!normalized.trim())
+        throw new Error('ref is required');
+    if (/^e\d+$/.test(normalized)) {
+        const state = pageStates.get(page);
+        // Aria mode: use aria-ref locator
+        if (state?.roleRefsMode === 'aria') {
+            return (state.roleRefsFrameSelector ? page.frameLocator(state.roleRefsFrameSelector) : page)
+                .locator(`aria-ref=${normalized}`);
+        }
+        // Role mode: use getByRole
+        const info = state?.roleRefs?.[normalized];
+        if (!info)
+            throw new Error(`Unknown ref "${normalized}". Run a new snapshot and use a ref from that snapshot.`);
+        const locAny = state?.roleRefsFrameSelector
+            ? page.frameLocator(state.roleRefsFrameSelector)
+            : page;
+        const role = info.role;
+        const locator = info.name
+            ? locAny.getByRole(role, { name: info.name, exact: true })
+            : locAny.getByRole(role);
+        return info.nth !== undefined ? locator.nth(info.nth) : locator;
+    }
+    return page.locator(`aria-ref=${normalized}`);
+}
+// ── Error Helpers ──
+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);
+}
+export function normalizeTimeoutMs(timeoutMs, fallback, maxMs = 120000) {
+    return Math.max(500, Math.min(maxMs, timeoutMs ?? fallback));
+}

package/dist/browser/index.d.ts

@@ -0,0 +1,6 @@
+export { BrowserClaw, CrawlPage } from './browser.js';
+export { setStealthEnabled } from './connection.js';
+export { InvalidBrowserNavigationUrlError, withBrowserNavigationPolicy, assertBrowserNavigationAllowed } from './security.js';
+export type { BrowserNavigationPolicyOptions, LookupFn } from './security.js';
+export type { FrameEvalResult } from './actions/evaluate.js';
+export type { SsrfPolicy, LaunchOptions, ConnectOptions, SnapshotResult, SnapshotOptions, SnapshotStats, UntrustedContentMeta, AriaSnapshotResult, AriaNode, RoleRefInfo, RoleRefs, BrowserTab, FormField, ClickOptions, TypeOptions, WaitOptions, ScreenshotOptions, ConsoleMessage, PageError, NetworkRequest, CookieData, StorageKind, ChromeKind, ChromeExecutable, DownloadResult, DialogOptions, ResponseBodyResult, TraceStartOptions, ColorScheme, GeolocationOptions, HttpCredentials, } from './types.js';

package/dist/browser/index.js

@@ -0,0 +1,3 @@
+export { BrowserClaw, CrawlPage } from './browser.js';
+export { setStealthEnabled } from './connection.js';
+export { InvalidBrowserNavigationUrlError, withBrowserNavigationPolicy, assertBrowserNavigationAllowed } from './security.js';

package/dist/browser/security.d.ts

@@ -0,0 +1,51 @@
+import { lookup } from 'node:dns/promises';
+import type { SsrfPolicy } from './types.js';
+export type LookupFn = typeof lookup;
+/**
+ * Thrown when a navigation URL is blocked by SSRF policy.
+ * Callers can catch this specifically to distinguish navigation blocks
+ * from other errors.
+ */
+export declare class InvalidBrowserNavigationUrlError extends Error {
+    constructor(message: string);
+}
+/** Options for browser navigation SSRF policy. */
+export type BrowserNavigationPolicyOptions = {
+    ssrfPolicy?: SsrfPolicy;
+};
+/** Build a BrowserNavigationPolicyOptions from an SsrfPolicy. */
+export declare function withBrowserNavigationPolicy(ssrfPolicy?: SsrfPolicy): BrowserNavigationPolicyOptions;
+/**
+ * Assert that a URL is allowed for browser navigation under the given SSRF policy.
+ * Throws `InvalidBrowserNavigationUrlError` if the URL is blocked.
+ */
+export declare function assertBrowserNavigationAllowed(opts: {
+    url: string;
+    lookupFn?: LookupFn;
+} & BrowserNavigationPolicyOptions): Promise<void>;
+/**
+ * Validate that an output file path is safe — no directory traversal or escape.
+ * Rejects paths containing `..` segments or relative paths that could escape
+ * the intended output directory.
+ *
+ * @param path - The output path to validate
+ * @param allowedRoots - Optional list of allowed root directories. If provided,
+ *   the resolved path must be within one of these roots.
+ * @throws If the path is unsafe
+ */
+export declare function assertSafeOutputPath(path: string, allowedRoots?: string[]): Promise<void>;
+/**
+ * Check whether a URL targets a loopback or private/internal network address.
+ * Synchronous hostname-based check. Used to prevent SSRF attacks.
+ */
+export declare function isInternalUrl(url: string): boolean;
+/**
+ * Validate upload file paths immediately before use — rejects symlinks,
+ * missing files, and non-regular files to prevent TOCTOU path-swap attacks.
+ */
+export declare function assertSafeUploadPaths(paths: string[]): Promise<void>;
+/**
+ * Async version that also resolves DNS to catch rebinding attacks
+ * where a public hostname resolves to an internal IP.
+ */
+export declare function isInternalUrlResolved(url: string, lookupFn?: LookupFn): Promise<boolean>;