@poolzin/pool-bot 2026.3.22 → 2026.3.24

package/dist/browser/chrome-mcp.js

@@ -0,0 +1,421 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { BrowserProfileUnavailableError, BrowserTabNotFoundError } from "./errors.js";
+const DEFAULT_CHROME_MCP_COMMAND = "npx";
+const DEFAULT_CHROME_MCP_ARGS = [
+    "-y",
+    "chrome-devtools-mcp@latest",
+    "--autoConnect",
+    // Direct chrome-devtools-mcp launches do not enable structuredContent by default.
+    "--experimentalStructuredContent",
+    "--experimental-page-id-routing",
+];
+const sessions = new Map();
+const pendingSessions = new Map();
+let sessionFactory = null;
+const browserProfiles = new Map();
+/**
+ * Register a browser profile for isolated sessions
+ */
+export function registerBrowserProfile(config) {
+    browserProfiles.set(config.name, config);
+}
+/**
+ * Get registered browser profile
+ */
+export function getBrowserProfile(name) {
+    return browserProfiles.get(name);
+}
+/**
+ * List all registered browser profiles
+ */
+export function listBrowserProfiles() {
+    return Array.from(browserProfiles.values());
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asPages(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const out = [];
+    for (const entry of value) {
+        const record = asRecord(entry);
+        if (!record || typeof record.id !== "number") {
+            continue;
+        }
+        out.push({
+            id: record.id,
+            url: typeof record.url === "string" ? record.url : undefined,
+            selected: record.selected === true,
+        });
+    }
+    return out;
+}
+function parsePageId(targetId) {
+    const parsed = Number.parseInt(targetId.trim(), 10);
+    if (!Number.isFinite(parsed)) {
+        throw new BrowserTabNotFoundError();
+    }
+    return parsed;
+}
+function toBrowserTabs(pages) {
+    return pages.map((page) => ({
+        targetId: String(page.id),
+        title: "",
+        url: page.url ?? "",
+        type: "page",
+    }));
+}
+function extractStructuredContent(result) {
+    return asRecord(result.structuredContent) ?? {};
+}
+function extractTextContent(result) {
+    const content = Array.isArray(result.content) ? result.content : [];
+    return content
+        .map((entry) => {
+        const record = asRecord(entry);
+        return record && typeof record.text === "string" ? record.text : "";
+    })
+        .filter(Boolean);
+}
+function extractTextPages(result) {
+    const pages = [];
+    for (const block of extractTextContent(result)) {
+        for (const line of block.split(/\r?\n/)) {
+            const match = line.match(/^\s*(\d+):\s+(.+?)(?:\s+\[(selected)\])?\s*$/i);
+            if (!match) {
+                continue;
+            }
+            pages.push({
+                id: Number.parseInt(match[1] ?? "", 10),
+                url: match[2]?.trim() || undefined,
+                selected: Boolean(match[3]),
+            });
+        }
+    }
+    return pages;
+}
+function extractStructuredPages(result) {
+    const structured = asPages(extractStructuredContent(result).pages);
+    return structured.length > 0 ? structured : extractTextPages(result);
+}
+function extractSnapshot(result) {
+    const structured = extractStructuredContent(result);
+    const snapshot = asRecord(structured.snapshot);
+    if (!snapshot) {
+        throw new Error("Chrome MCP snapshot response was missing structured snapshot data.");
+    }
+    return snapshot;
+}
+function extractJsonBlock(text) {
+    const match = text.match(/```json\s*([\s\S]*?)\s*```/i);
+    const raw = match?.[1]?.trim() || text.trim();
+    return raw ? JSON.parse(raw) : null;
+}
+function extractMessageText(result) {
+    const message = extractStructuredContent(result).message;
+    if (typeof message === "string" && message.trim()) {
+        return message;
+    }
+    const blocks = extractTextContent(result);
+    return blocks.find((block) => block.trim()) ?? "";
+}
+function extractToolErrorMessage(result, name) {
+    const message = extractMessageText(result).trim();
+    return message || `Chrome MCP tool "${name}" failed.`;
+}
+function extractJsonMessage(result) {
+    const candidates = [extractMessageText(result), ...extractTextContent(result)].filter((text) => text.trim());
+    let lastError;
+    for (const candidate of candidates) {
+        try {
+            return extractJsonBlock(candidate);
+        }
+        catch (err) {
+            lastError = err;
+        }
+    }
+    if (lastError) {
+        throw lastError;
+    }
+    return null;
+}
+async function createRealSession(profileName) {
+    const transport = new StdioClientTransport({
+        command: DEFAULT_CHROME_MCP_COMMAND,
+        args: DEFAULT_CHROME_MCP_ARGS,
+        stderr: "pipe",
+    });
+    const client = new Client({
+        name: "openclaw-browser",
+        version: "0.0.0",
+    }, {});
+    const ready = (async () => {
+        try {
+            await client.connect(transport);
+            const tools = await client.listTools();
+            if (!tools.tools.some((tool) => tool.name === "list_pages")) {
+                throw new Error("Chrome MCP server did not expose the expected navigation tools.");
+            }
+        }
+        catch (err) {
+            await client.close().catch(() => { });
+            throw new BrowserProfileUnavailableError(`Chrome MCP existing-session attach failed for profile "${profileName}". ` +
+                `Make sure Chrome (v146+) is running. ` +
+                `Details: ${String(err)}`);
+        }
+    })();
+    return {
+        client,
+        transport,
+        ready,
+    };
+}
+async function getSession(profileName) {
+    let session = sessions.get(profileName);
+    if (session && session.transport.pid === null) {
+        sessions.delete(profileName);
+        session = undefined;
+    }
+    if (!session) {
+        let pending = pendingSessions.get(profileName);
+        if (!pending) {
+            pending = (async () => {
+                const created = await (sessionFactory ?? createRealSession)(profileName);
+                sessions.set(profileName, created);
+                return created;
+            })();
+            pendingSessions.set(profileName, pending);
+        }
+        try {
+            session = await pending;
+        }
+        finally {
+            if (pendingSessions.get(profileName) === pending) {
+                pendingSessions.delete(profileName);
+            }
+        }
+    }
+    try {
+        await session.ready;
+        return session;
+    }
+    catch (err) {
+        const current = sessions.get(profileName);
+        if (current?.transport === session.transport) {
+            sessions.delete(profileName);
+        }
+        throw err;
+    }
+}
+async function callTool(profileName, name, args = {}) {
+    const session = await getSession(profileName);
+    let result;
+    try {
+        result = (await session.client.callTool({
+            name,
+            arguments: args,
+        }));
+    }
+    catch (err) {
+        // Transport/connection error — tear down session so it reconnects on next call
+        sessions.delete(profileName);
+        await session.client.close().catch(() => { });
+        throw err;
+    }
+    // Tool-level errors (element not found, script error, etc.) don't indicate a
+    // broken connection — don't tear down the session for these.
+    if (result.isError) {
+        throw new Error(extractToolErrorMessage(result, name));
+    }
+    return result;
+}
+async function withTempFile(fn) {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-chrome-mcp-"));
+    const filePath = path.join(dir, randomUUID());
+    try {
+        return await fn(filePath);
+    }
+    finally {
+        await fs.rm(dir, { recursive: true, force: true }).catch(() => { });
+    }
+}
+async function findPageById(profileName, pageId) {
+    const pages = await listChromeMcpPages(profileName);
+    const page = pages.find((entry) => entry.id === pageId);
+    if (!page) {
+        throw new BrowserTabNotFoundError();
+    }
+    return page;
+}
+export async function ensureChromeMcpAvailable(profileName) {
+    await getSession(profileName);
+}
+export function getChromeMcpPid(profileName) {
+    return sessions.get(profileName)?.transport.pid ?? null;
+}
+export async function closeChromeMcpSession(profileName) {
+    pendingSessions.delete(profileName);
+    const session = sessions.get(profileName);
+    if (!session) {
+        return false;
+    }
+    sessions.delete(profileName);
+    await session.client.close().catch(() => { });
+    return true;
+}
+export async function stopAllChromeMcpSessions() {
+    const names = [...sessions.keys()];
+    for (const name of names) {
+        await closeChromeMcpSession(name).catch(() => { });
+    }
+}
+export async function listChromeMcpPages(profileName) {
+    const result = await callTool(profileName, "list_pages");
+    return extractStructuredPages(result);
+}
+export async function listChromeMcpTabs(profileName) {
+    return toBrowserTabs(await listChromeMcpPages(profileName));
+}
+export async function openChromeMcpTab(profileName, url) {
+    const result = await callTool(profileName, "new_page", { url });
+    const pages = extractStructuredPages(result);
+    const chosen = pages.find((page) => page.selected) ?? pages.at(-1);
+    if (!chosen) {
+        throw new Error("Chrome MCP did not return the created page.");
+    }
+    return {
+        targetId: String(chosen.id),
+        title: "",
+        url: chosen.url ?? url,
+        type: "page",
+    };
+}
+export async function focusChromeMcpTab(profileName, targetId) {
+    await callTool(profileName, "select_page", {
+        pageId: parsePageId(targetId),
+        bringToFront: true,
+    });
+}
+export async function closeChromeMcpTab(profileName, targetId) {
+    await callTool(profileName, "close_page", { pageId: parsePageId(targetId) });
+}
+export async function navigateChromeMcpPage(params) {
+    await callTool(params.profileName, "navigate_page", {
+        pageId: parsePageId(params.targetId),
+        type: "url",
+        url: params.url,
+        ...(typeof params.timeoutMs === "number" ? { timeout: params.timeoutMs } : {}),
+    });
+    const page = await findPageById(params.profileName, parsePageId(params.targetId));
+    return { url: page.url ?? params.url };
+}
+export async function takeChromeMcpSnapshot(params) {
+    const result = await callTool(params.profileName, "take_snapshot", {
+        pageId: parsePageId(params.targetId),
+    });
+    return extractSnapshot(result);
+}
+export async function takeChromeMcpScreenshot(params) {
+    return await withTempFile(async (filePath) => {
+        await callTool(params.profileName, "take_screenshot", {
+            pageId: parsePageId(params.targetId),
+            filePath,
+            format: params.format ?? "png",
+            ...(params.uid ? { uid: params.uid } : {}),
+            ...(params.fullPage ? { fullPage: true } : {}),
+        });
+        return await fs.readFile(filePath);
+    });
+}
+export async function clickChromeMcpElement(params) {
+    await callTool(params.profileName, "click", {
+        pageId: parsePageId(params.targetId),
+        uid: params.uid,
+        ...(params.doubleClick ? { dblClick: true } : {}),
+    });
+}
+export async function fillChromeMcpElement(params) {
+    await callTool(params.profileName, "fill", {
+        pageId: parsePageId(params.targetId),
+        uid: params.uid,
+        value: params.value,
+    });
+}
+export async function fillChromeMcpForm(params) {
+    await callTool(params.profileName, "fill_form", {
+        pageId: parsePageId(params.targetId),
+        elements: params.elements,
+    });
+}
+export async function hoverChromeMcpElement(params) {
+    await callTool(params.profileName, "hover", {
+        pageId: parsePageId(params.targetId),
+        uid: params.uid,
+    });
+}
+export async function dragChromeMcpElement(params) {
+    await callTool(params.profileName, "drag", {
+        pageId: parsePageId(params.targetId),
+        from_uid: params.fromUid,
+        to_uid: params.toUid,
+    });
+}
+export async function uploadChromeMcpFile(params) {
+    await callTool(params.profileName, "upload_file", {
+        pageId: parsePageId(params.targetId),
+        uid: params.uid,
+        filePath: params.filePath,
+    });
+}
+export async function pressChromeMcpKey(params) {
+    await callTool(params.profileName, "press_key", {
+        pageId: parsePageId(params.targetId),
+        key: params.key,
+    });
+}
+export async function resizeChromeMcpPage(params) {
+    await callTool(params.profileName, "resize_page", {
+        pageId: parsePageId(params.targetId),
+        width: params.width,
+        height: params.height,
+    });
+}
+export async function handleChromeMcpDialog(params) {
+    await callTool(params.profileName, "handle_dialog", {
+        pageId: parsePageId(params.targetId),
+        action: params.action,
+        ...(params.promptText ? { promptText: params.promptText } : {}),
+    });
+}
+export async function evaluateChromeMcpScript(params) {
+    const result = await callTool(params.profileName, "evaluate_script", {
+        pageId: parsePageId(params.targetId),
+        function: params.fn,
+        ...(params.args?.length ? { args: params.args } : {}),
+    });
+    return extractJsonMessage(result);
+}
+export async function waitForChromeMcpText(params) {
+    await callTool(params.profileName, "wait_for", {
+        pageId: parsePageId(params.targetId),
+        text: params.text,
+        ...(typeof params.timeoutMs === "number" ? { timeout: params.timeoutMs } : {}),
+    });
+}
+export function setChromeMcpSessionFactoryForTest(factory) {
+    sessionFactory = factory;
+}
+export async function resetChromeMcpSessionsForTest() {
+    sessionFactory = null;
+    pendingSessions.clear();
+    await stopAllChromeMcpSessions();
+}

package/dist/browser/chrome-mcp.snapshot.js

@@ -0,0 +1,133 @@
+import { getRoleSnapshotStats, } from "./pw-role-snapshot.js";
+import { CONTENT_ROLES, INTERACTIVE_ROLES, STRUCTURAL_ROLES } from "./snapshot-roles.js";
+function normalizeRole(node) {
+    const role = typeof node.role === "string" ? node.role.trim().toLowerCase() : "";
+    return role || "generic";
+}
+function normalizeString(value) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed || undefined;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return undefined;
+}
+function escapeQuoted(value) {
+    return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}
+function shouldIncludeNode(params) {
+    if (params.options?.interactive && !INTERACTIVE_ROLES.has(params.role)) {
+        return false;
+    }
+    if (params.options?.compact && STRUCTURAL_ROLES.has(params.role) && !params.name) {
+        return false;
+    }
+    return true;
+}
+function shouldCreateRef(role, name) {
+    return INTERACTIVE_ROLES.has(role) || (CONTENT_ROLES.has(role) && Boolean(name));
+}
+function createDuplicateTracker() {
+    return {
+        counts: new Map(),
+        keysByRef: new Map(),
+        duplicates: new Set(),
+    };
+}
+function registerRef(tracker, ref, role, name) {
+    const key = `${role}:${name ?? ""}`;
+    const count = tracker.counts.get(key) ?? 0;
+    tracker.counts.set(key, count + 1);
+    tracker.keysByRef.set(ref, key);
+    if (count > 0) {
+        tracker.duplicates.add(key);
+        return count;
+    }
+    return undefined;
+}
+export function flattenChromeMcpSnapshotToAriaNodes(root, limit = 500) {
+    const boundedLimit = Math.max(1, Math.min(2000, Math.floor(limit)));
+    const out = [];
+    const visit = (node, depth) => {
+        if (out.length >= boundedLimit) {
+            return;
+        }
+        const ref = normalizeString(node.id);
+        if (ref) {
+            out.push({
+                ref,
+                role: normalizeRole(node),
+                name: normalizeString(node.name) ?? "",
+                value: normalizeString(node.value),
+                description: normalizeString(node.description),
+                depth,
+            });
+        }
+        for (const child of node.children ?? []) {
+            visit(child, depth + 1);
+            if (out.length >= boundedLimit) {
+                return;
+            }
+        }
+    };
+    visit(root, 0);
+    return out;
+}
+export function buildAiSnapshotFromChromeMcpSnapshot(params) {
+    const refs = {};
+    const tracker = createDuplicateTracker();
+    const lines = [];
+    const visit = (node, depth) => {
+        const role = normalizeRole(node);
+        const name = normalizeString(node.name);
+        const value = normalizeString(node.value);
+        const description = normalizeString(node.description);
+        const maxDepth = params.options?.maxDepth;
+        if (maxDepth !== undefined && depth > maxDepth) {
+            return;
+        }
+        const includeNode = shouldIncludeNode({ role, name, options: params.options });
+        if (includeNode) {
+            let line = `${"  ".repeat(depth)}- ${role}`;
+            if (name) {
+                line += ` "${escapeQuoted(name)}"`;
+            }
+            const ref = normalizeString(node.id);
+            if (ref && shouldCreateRef(role, name)) {
+                const nth = registerRef(tracker, ref, role, name);
+                refs[ref] = nth === undefined ? { role, name } : { role, name, nth };
+                line += ` [ref=${ref}]`;
+            }
+            if (value) {
+                line += ` value="${escapeQuoted(value)}"`;
+            }
+            if (description) {
+                line += ` description="${escapeQuoted(description)}"`;
+            }
+            lines.push(line);
+        }
+        for (const child of node.children ?? []) {
+            visit(child, depth + 1);
+        }
+    };
+    visit(params.root, 0);
+    for (const [ref, data] of Object.entries(refs)) {
+        const key = tracker.keysByRef.get(ref);
+        if (key && !tracker.duplicates.has(key)) {
+            delete data.nth;
+        }
+    }
+    let snapshot = lines.join("\n");
+    let truncated = false;
+    const maxChars = typeof params.maxChars === "number" && Number.isFinite(params.maxChars) && params.maxChars > 0
+        ? Math.floor(params.maxChars)
+        : undefined;
+    if (maxChars && snapshot.length > maxChars) {
+        snapshot = `${snapshot.slice(0, maxChars)}\n\n[...TRUNCATED - page too large]`;
+        truncated = true;
+    }
+    const stats = getRoleSnapshotStats(snapshot, refs);
+    return truncated ? { snapshot, truncated, refs, stats } : { snapshot, refs, stats };
+}

package/dist/browser/errors.js

@@ -0,0 +1,67 @@
+import { SsrFBlockedError } from "../infra/net/ssrf.js";
+import { InvalidBrowserNavigationUrlError } from "./navigation-guard.js";
+export class BrowserError extends Error {
+    status;
+    constructor(message, status = 500, options) {
+        super(message, options);
+        this.name = new.target.name;
+        this.status = status;
+    }
+}
+export class BrowserValidationError extends BrowserError {
+    constructor(message, options) {
+        super(message, 400, options);
+    }
+}
+export class BrowserConfigurationError extends BrowserError {
+    constructor(message, options) {
+        super(message, 400, options);
+    }
+}
+export class BrowserTargetAmbiguousError extends BrowserError {
+    constructor(message = "ambiguous target id prefix", options) {
+        super(message, 409, options);
+    }
+}
+export class BrowserTabNotFoundError extends BrowserError {
+    constructor(message = "tab not found", options) {
+        super(message, 404, options);
+    }
+}
+export class BrowserProfileNotFoundError extends BrowserError {
+    constructor(message, options) {
+        super(message, 404, options);
+    }
+}
+export class BrowserConflictError extends BrowserError {
+    constructor(message, options) {
+        super(message, 409, options);
+    }
+}
+export class BrowserResetUnsupportedError extends BrowserError {
+    constructor(message, options) {
+        super(message, 400, options);
+    }
+}
+export class BrowserProfileUnavailableError extends BrowserError {
+    constructor(message, options) {
+        super(message, 409, options);
+    }
+}
+export class BrowserResourceExhaustedError extends BrowserError {
+    constructor(message, options) {
+        super(message, 507, options);
+    }
+}
+export function toBrowserErrorResponse(err) {
+    if (err instanceof BrowserError) {
+        return { status: err.status, message: err.message };
+    }
+    if (err instanceof SsrFBlockedError) {
+        return { status: 400, message: err.message };
+    }
+    if (err instanceof InvalidBrowserNavigationUrlError) {
+        return { status: 400, message: err.message };
+    }
+    return null;
+}

package/dist/browser/form-fields.js

@@ -0,0 +1,22 @@
+export const DEFAULT_FILL_FIELD_TYPE = "text";
+export function normalizeBrowserFormFieldRef(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+export function normalizeBrowserFormFieldType(value) {
+    const type = typeof value === "string" ? value.trim() : "";
+    return type || DEFAULT_FILL_FIELD_TYPE;
+}
+export function normalizeBrowserFormFieldValue(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean"
+        ? value
+        : undefined;
+}
+export function normalizeBrowserFormField(record) {
+    const ref = normalizeBrowserFormFieldRef(record.ref);
+    if (!ref) {
+        return null;
+    }
+    const type = normalizeBrowserFormFieldType(record.type);
+    const value = normalizeBrowserFormFieldValue(record.value);
+    return value === undefined ? { ref, type } : { ref, type, value };
+}

package/dist/browser/output-atomic.js

@@ -0,0 +1,44 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeFileFromPathWithinRoot } from "../infra/fs-safe.js";
+import { sanitizeUntrustedFileName } from "./safe-filename.js";
+function buildSiblingTempPath(targetPath) {
+    const id = crypto.randomUUID();
+    const safeTail = sanitizeUntrustedFileName(path.basename(targetPath), "output.bin");
+    return path.join(path.dirname(targetPath), `.poolbot-output-${id}-${safeTail}.part`);
+}
+export async function writeViaSiblingTempPath(params) {
+    const rootDir = await fs
+        .realpath(path.resolve(params.rootDir))
+        .catch(() => path.resolve(params.rootDir));
+    const requestedTargetPath = path.resolve(params.targetPath);
+    const targetPath = await fs
+        .realpath(path.dirname(requestedTargetPath))
+        .then((realDir) => path.join(realDir, path.basename(requestedTargetPath)))
+        .catch(() => requestedTargetPath);
+    const relativeTargetPath = path.relative(rootDir, targetPath);
+    if (!relativeTargetPath ||
+        relativeTargetPath === ".." ||
+        relativeTargetPath.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativeTargetPath)) {
+        throw new Error("Target path is outside the allowed root");
+    }
+    const tempPath = buildSiblingTempPath(targetPath);
+    let renameSucceeded = false;
+    try {
+        await params.writeTemp(tempPath);
+        await writeFileFromPathWithinRoot({
+            rootDir,
+            relativePath: relativeTargetPath,
+            sourcePath: tempPath,
+            mkdir: false,
+        });
+        renameSucceeded = true;
+    }
+    finally {
+        if (!renameSucceeded) {
+            await fs.rm(tempPath, { force: true }).catch(() => { });
+        }
+    }
+}