@poolzin/pool-bot 2026.2.23 → 2026.2.25

package/dist/browser/routes/agent.shared.js

@@ -11,14 +11,24 @@ export const SELECTOR_UNSUPPORTED_MESSAGE = [
 ].join("\n");
 export function readBody(req) {
     const body = req.body;
-    if (!body || typeof body !== "object" || Array.isArray(body))
+    if (!body || typeof body !== "object" || Array.isArray(body)) {
         return {};
+    }
     return body;
 }
+export function resolveTargetIdFromBody(body) {
+    const targetId = typeof body.targetId === "string" ? body.targetId.trim() : "";
+    return targetId || undefined;
+}
+export function resolveTargetIdFromQuery(query) {
+    const targetId = typeof query.targetId === "string" ? query.targetId.trim() : "";
+    return targetId || undefined;
+}
 export function handleRouteError(ctx, res, err) {
     const mapped = ctx.mapTabError(err);
-    if (mapped)
+    if (mapped) {
         return jsonError(res, mapped.status, mapped.message);
+    }
     jsonError(res, 500, String(err));
 }
 export function resolveProfileContext(req, res, ctx) {
@@ -34,8 +44,9 @@ export async function getPwAiModule() {
 }
 export async function requirePwAi(res, feature) {
     const mod = await getPwAiModule();
-    if (mod)
+    if (mod) {
         return mod;
+    }
     jsonError(res, 501, [
         `Playwright is not available in this gateway build; '${feature}' is unsupported.`,
         "Install the full Playwright package (not playwright-core) and restart the gateway, or reinstall with browser support.",
@@ -43,3 +54,36 @@ export async function requirePwAi(res, feature) {
     ].join("\n"));
     return null;
 }
+export async function withRouteTabContext(params) {
+    const profileCtx = resolveProfileContext(params.req, params.res, params.ctx);
+    if (!profileCtx) {
+        return undefined;
+    }
+    try {
+        const tab = await profileCtx.ensureTabAvailable(params.targetId);
+        return await params.run({
+            profileCtx,
+            tab,
+            cdpUrl: profileCtx.profile.cdpUrl,
+        });
+    }
+    catch (err) {
+        handleRouteError(params.ctx, params.res, err);
+        return undefined;
+    }
+}
+export async function withPlaywrightRouteContext(params) {
+    return await withRouteTabContext({
+        req: params.req,
+        res: params.res,
+        ctx: params.ctx,
+        targetId: params.targetId,
+        run: async ({ profileCtx, tab, cdpUrl }) => {
+            const pw = await requirePwAi(params.res, params.feature);
+            if (!pw) {
+                return undefined;
+            }
+            return await params.run({ profileCtx, tab, cdpUrl, pw });
+        },
+    });
+}

package/dist/browser/routes/agent.snapshot.js

@@ -2,67 +2,71 @@ import path from "node:path";
 import { ensureMediaDir, saveMediaBuffer } from "../../media/store.js";
 import { captureScreenshot, snapshotAria } from "../cdp.js";
 import { DEFAULT_AI_SNAPSHOT_EFFICIENT_DEPTH, DEFAULT_AI_SNAPSHOT_EFFICIENT_MAX_CHARS, DEFAULT_AI_SNAPSHOT_MAX_CHARS, } from "../constants.js";
+import { withBrowserNavigationPolicy } from "../navigation-guard.js";
 import { DEFAULT_BROWSER_SCREENSHOT_MAX_BYTES, DEFAULT_BROWSER_SCREENSHOT_MAX_SIDE, normalizeBrowserScreenshot, } from "../screenshot.js";
-import { getPwAiModule, handleRouteError, readBody, requirePwAi, resolveProfileContext, } from "./agent.shared.js";
+import { getPwAiModule, handleRouteError, readBody, requirePwAi, resolveProfileContext, withPlaywrightRouteContext, withRouteTabContext, } from "./agent.shared.js";
 import { jsonError, toBoolean, toNumber, toStringOrEmpty } from "./utils.js";
+async function saveBrowserMediaResponse(params) {
+    await ensureMediaDir();
+    const saved = await saveMediaBuffer(params.buffer, params.contentType, "browser", params.maxBytes);
+    params.res.json({
+        ok: true,
+        path: path.resolve(saved.path),
+        targetId: params.targetId,
+        url: params.url,
+    });
+}
 export function registerBrowserAgentSnapshotRoutes(app, ctx) {
     app.post("/navigate", async (req, res) => {
-        const profileCtx = resolveProfileContext(req, res, ctx);
-        if (!profileCtx)
-            return;
         const body = readBody(req);
         const url = toStringOrEmpty(body.url);
         const targetId = toStringOrEmpty(body.targetId) || undefined;
-        if (!url)
+        if (!url) {
             return jsonError(res, 400, "url is required");
-        try {
-            const tab = await profileCtx.ensureTabAvailable(targetId);
-            const pw = await requirePwAi(res, "navigate");
-            if (!pw)
-                return;
-            const result = await pw.navigateViaPlaywright({
-                cdpUrl: profileCtx.profile.cdpUrl,
-                targetId: tab.targetId,
-                url,
-            });
-            res.json({ ok: true, targetId: tab.targetId, ...result });
-        }
-        catch (err) {
-            handleRouteError(ctx, res, err);
         }
+        await withPlaywrightRouteContext({
+            req,
+            res,
+            ctx,
+            targetId,
+            feature: "navigate",
+            run: async ({ cdpUrl, tab, pw }) => {
+                const result = await pw.navigateViaPlaywright({
+                    cdpUrl,
+                    targetId: tab.targetId,
+                    url,
+                    ...withBrowserNavigationPolicy(ctx.state().resolved.ssrfPolicy),
+                });
+                res.json({ ok: true, targetId: tab.targetId, ...result });
+            },
+        });
     });
     app.post("/pdf", async (req, res) => {
-        const profileCtx = resolveProfileContext(req, res, ctx);
-        if (!profileCtx)
-            return;
         const body = readBody(req);
         const targetId = toStringOrEmpty(body.targetId) || undefined;
-        try {
-            const tab = await profileCtx.ensureTabAvailable(targetId);
-            const pw = await requirePwAi(res, "pdf");
-            if (!pw)
-                return;
-            const pdf = await pw.pdfViaPlaywright({
-                cdpUrl: profileCtx.profile.cdpUrl,
-                targetId: tab.targetId,
-            });
-            await ensureMediaDir();
-            const saved = await saveMediaBuffer(pdf.buffer, "application/pdf", "browser", pdf.buffer.byteLength);
-            res.json({
-                ok: true,
-                path: path.resolve(saved.path),
-                targetId: tab.targetId,
-                url: tab.url,
-            });
-        }
-        catch (err) {
-            handleRouteError(ctx, res, err);
-        }
+        await withPlaywrightRouteContext({
+            req,
+            res,
+            ctx,
+            targetId,
+            feature: "pdf",
+            run: async ({ cdpUrl, tab, pw }) => {
+                const pdf = await pw.pdfViaPlaywright({
+                    cdpUrl,
+                    targetId: tab.targetId,
+                });
+                await saveBrowserMediaResponse({
+                    res,
+                    buffer: pdf.buffer,
+                    contentType: "application/pdf",
+                    maxBytes: pdf.buffer.byteLength,
+                    targetId: tab.targetId,
+                    url: tab.url,
+                });
+            },
+        });
     });
     app.post("/screenshot", async (req, res) => {
-        const profileCtx = resolveProfileContext(req, res, ctx);
-        if (!profileCtx)
-            return;
         const body = readBody(req);
         const targetId = toStringOrEmpty(body.targetId) || undefined;
         const fullPage = toBoolean(body.fullPage) ?? false;
@@ -72,53 +76,60 @@ export function registerBrowserAgentSnapshotRoutes(app, ctx) {
         if (fullPage && (ref || element)) {
             return jsonError(res, 400, "fullPage is not supported for element screenshots");
         }
-        try {
-            const tab = await profileCtx.ensureTabAvailable(targetId);
-            let buffer;
-            const shouldUsePlaywright = profileCtx.profile.driver === "extension" || !tab.wsUrl || Boolean(ref) || Boolean(element);
-            if (shouldUsePlaywright) {
-                const pw = await requirePwAi(res, "screenshot");
-                if (!pw)
-                    return;
-                const snap = await pw.takeScreenshotViaPlaywright({
-                    cdpUrl: profileCtx.profile.cdpUrl,
-                    targetId: tab.targetId,
-                    ref,
-                    element,
-                    fullPage,
-                    type,
+        await withRouteTabContext({
+            req,
+            res,
+            ctx,
+            targetId,
+            run: async ({ profileCtx, tab, cdpUrl }) => {
+                let buffer;
+                const shouldUsePlaywright = profileCtx.profile.driver === "extension" ||
+                    !tab.wsUrl ||
+                    Boolean(ref) ||
+                    Boolean(element);
+                if (shouldUsePlaywright) {
+                    const pw = await requirePwAi(res, "screenshot");
+                    if (!pw) {
+                        return;
+                    }
+                    const snap = await pw.takeScreenshotViaPlaywright({
+                        cdpUrl,
+                        targetId: tab.targetId,
+                        ref,
+                        element,
+                        fullPage,
+                        type,
+                    });
+                    buffer = snap.buffer;
+                }
+                else {
+                    buffer = await captureScreenshot({
+                        wsUrl: tab.wsUrl ?? "",
+                        fullPage,
+                        format: type,
+                        quality: type === "jpeg" ? 85 : undefined,
+                    });
+                }
+                const normalized = await normalizeBrowserScreenshot(buffer, {
+                    maxSide: DEFAULT_BROWSER_SCREENSHOT_MAX_SIDE,
+                    maxBytes: DEFAULT_BROWSER_SCREENSHOT_MAX_BYTES,
                 });
-                buffer = snap.buffer;
-            }
-            else {
-                buffer = await captureScreenshot({
-                    wsUrl: tab.wsUrl ?? "",
-                    fullPage,
-                    format: type,
-                    quality: type === "jpeg" ? 85 : undefined,
+                await saveBrowserMediaResponse({
+                    res,
+                    buffer: normalized.buffer,
+                    contentType: normalized.contentType ?? `image/${type}`,
+                    maxBytes: DEFAULT_BROWSER_SCREENSHOT_MAX_BYTES,
+                    targetId: tab.targetId,
+                    url: tab.url,
                 });
-            }
-            const normalized = await normalizeBrowserScreenshot(buffer, {
-                maxSide: DEFAULT_BROWSER_SCREENSHOT_MAX_SIDE,
-                maxBytes: DEFAULT_BROWSER_SCREENSHOT_MAX_BYTES,
-            });
-            await ensureMediaDir();
-            const saved = await saveMediaBuffer(normalized.buffer, normalized.contentType ?? `image/${type}`, "browser", DEFAULT_BROWSER_SCREENSHOT_MAX_BYTES);
-            res.json({
-                ok: true,
-                path: path.resolve(saved.path),
-                targetId: tab.targetId,
-                url: tab.url,
-            });
-        }
-        catch (err) {
-            handleRouteError(ctx, res, err);
-        }
+            },
+        });
     });
     app.get("/snapshot", async (req, res) => {
         const profileCtx = resolveProfileContext(req, res, ctx);
-        if (!profileCtx)
+        if (!profileCtx) {
             return;
+        }
         const targetId = typeof req.query.targetId === "string" ? req.query.targetId.trim() : "";
         const mode = req.query.mode === "efficient" ? "efficient" : undefined;
         const labels = toBoolean(req.query.labels) ?? undefined;
@@ -148,6 +159,8 @@ export function registerBrowserAgentSnapshotRoutes(app, ctx) {
         const depth = depthRaw ?? (mode === "efficient" ? DEFAULT_AI_SNAPSHOT_EFFICIENT_DEPTH : undefined);
         const selector = toStringOrEmpty(req.query.selector);
         const frameSelector = toStringOrEmpty(req.query.frame);
+        const selectorValue = selector.trim() || undefined;
+        const frameSelectorValue = frameSelector.trim() || undefined;
         try {
             const tab = await profileCtx.ensureTabAvailable(targetId || undefined);
             if ((labels || mode === "efficient") && format === "aria") {
@@ -155,28 +168,30 @@ export function registerBrowserAgentSnapshotRoutes(app, ctx) {
             }
             if (format === "ai") {
                 const pw = await requirePwAi(res, "ai snapshot");
-                if (!pw)
+                if (!pw) {
                     return;
+                }
                 const wantsRoleSnapshot = labels === true ||
                     mode === "efficient" ||
                     interactive === true ||
                     compact === true ||
                     depth !== undefined ||
-                    Boolean(selector.trim()) ||
-                    Boolean(frameSelector.trim());
+                    Boolean(selectorValue) ||
+                    Boolean(frameSelectorValue);
+                const roleSnapshotArgs = {
+                    cdpUrl: profileCtx.profile.cdpUrl,
+                    targetId: tab.targetId,
+                    selector: selectorValue,
+                    frameSelector: frameSelectorValue,
+                    refsMode,
+                    options: {
+                        interactive: interactive ?? undefined,
+                        compact: compact ?? undefined,
+                        maxDepth: depth ?? undefined,
+                    },
+                };
                 const snap = wantsRoleSnapshot
-                    ? await pw.snapshotRoleViaPlaywright({
-                        cdpUrl: profileCtx.profile.cdpUrl,
-                        targetId: tab.targetId,
-                        selector: selector.trim() || undefined,
-                        frameSelector: frameSelector.trim() || undefined,
-                        refsMode,
-                        options: {
-                            interactive: interactive ?? undefined,
-                            compact: compact ?? undefined,
-                            maxDepth: depth ?? undefined,
-                        },
-                    })
+                    ? await pw.snapshotRoleViaPlaywright(roleSnapshotArgs)
                     : await pw
                         .snapshotAiViaPlaywright({
                         cdpUrl: profileCtx.profile.cdpUrl,
@@ -186,18 +201,7 @@ export function registerBrowserAgentSnapshotRoutes(app, ctx) {
                         .catch(async (err) => {
                         // Public-API fallback when Playwright's private _snapshotForAI is missing.
                         if (String(err).toLowerCase().includes("_snapshotforai")) {
-                            return await pw.snapshotRoleViaPlaywright({
-                                cdpUrl: profileCtx.profile.cdpUrl,
-                                targetId: tab.targetId,
-                                selector: selector.trim() || undefined,
-                                frameSelector: frameSelector.trim() || undefined,
-                                refsMode,
-                                options: {
-                                    interactive: interactive ?? undefined,
-                                    compact: compact ?? undefined,
-                                    maxDepth: depth ?? undefined,
-                                },
-                            });
+                            return await pw.snapshotRoleViaPlaywright(roleSnapshotArgs);
                         }
                         throw err;
                     });
@@ -241,8 +245,9 @@ export function registerBrowserAgentSnapshotRoutes(app, ctx) {
                     // Extension relay doesn't expose per-page WS URLs; run AX snapshot via Playwright CDP session.
                     // Also covers cases where wsUrl is missing/unusable.
                     return requirePwAi(res, "aria snapshot").then(async (pw) => {
-                        if (!pw)
+                        if (!pw) {
                             return null;
+                        }
                         return await pw.snapshotAriaViaPlaywright({
                             cdpUrl: profileCtx.profile.cdpUrl,
                             targetId: tab.targetId,
@@ -252,8 +257,9 @@ export function registerBrowserAgentSnapshotRoutes(app, ctx) {
                 })()
                 : snapshotAria({ wsUrl: tab.wsUrl ?? "", limit });
             const resolved = await Promise.resolve(snap);
-            if (!resolved)
+            if (!resolved) {
                 return;
+            }
             return res.json({
                 ok: true,
                 format,