@wordbricks/playwright-mcp 0.1.25 → 0.1.26

package/lib/response.js

@@ -0,0 +1,192 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { renderModalStates } from "./tab.js";
+import { formatTruncationLine, truncateStringTo } from "./utils/truncate.js";
+const MAX_RESULT_CHARS = 25000;
+export class Response {
+    _result = [];
+    _events = [];
+    _code = [];
+    _images = [];
+    _context;
+    _includeSnapshot = false;
+    _includeTabs = false;
+    _includeCode = false;
+    _tabSnapshot;
+    toolName;
+    toolArgs;
+    _isError;
+    constructor(context, toolName, toolArgs) {
+        this._context = context;
+        this.toolName = toolName;
+        this.toolArgs = toolArgs;
+    }
+    addResult(result) {
+        this._result.push(result);
+    }
+    addEvent(event) {
+        this._events.push(event);
+    }
+    addError(error) {
+        this._result.push(error);
+        this._isError = true;
+    }
+    isError() {
+        return this._isError;
+    }
+    result() {
+        return this._result.join("\n");
+    }
+    addCode(code) {
+        this._code.push(code);
+    }
+    code() {
+        return this._code.join("\n");
+    }
+    addImage(image) {
+        this._images.push(image);
+    }
+    images() {
+        return this._images;
+    }
+    // NOTE Wordbricks Disabled: Page state logging not needed
+    setIncludeSnapshot(full) {
+        // this._includeSnapshot = full ?? 'incremental';
+    }
+    setIncludeTabs() {
+        this._includeTabs = true;
+    }
+    async finish() {
+        // All the async snapshotting post-action is happening here.
+        // Everything below should race against modal states.
+        if (this._includeSnapshot && this._context.currentTab())
+            this._tabSnapshot = await this._context
+                .currentTabOrDie()
+                .captureSnapshot();
+        for (const tab of this._context.tabs())
+            await tab.updateTitle();
+    }
+    tabSnapshot() {
+        return this._tabSnapshot;
+    }
+    serialize() {
+        const response = [];
+        // Start with command result.
+        if (this._result.length) {
+            const resultText = this._result.join("\n");
+            const { text: clipped, truncated } = truncateStringTo(resultText, MAX_RESULT_CHARS);
+            response.push("### Result");
+            response.push(clipped);
+            if (truncated) {
+                const total = resultText.length;
+                const shown = clipped.length;
+                response.push(formatTruncationLine(shown, total, { units: "chars" }));
+            }
+            response.push("");
+        }
+        // Then show events
+        if (this._events.length) {
+            response.push("### Events");
+            response.push(this._events.join("\n"));
+            response.push("");
+        }
+        // Add code if it exists.
+        if (this._includeCode && this._code.length) {
+            response.push(`### Ran Playwright code
+\`\`\`js
+${this._code.join("\n")}
+\`\`\``);
+            response.push("");
+        }
+        // List browser tabs.
+        if (this._includeSnapshot || this._includeTabs)
+            response.push(...renderTabsMarkdown(this._context.tabs(), this._includeTabs));
+        // Add snapshot if provided.
+        if (this._tabSnapshot?.modalStates.length) {
+            response.push(...renderModalStates(this._context, this._tabSnapshot.modalStates));
+            response.push("");
+        }
+        else if (this._tabSnapshot) {
+            response.push(renderTabSnapshot(this._tabSnapshot));
+            response.push("");
+        }
+        // Main response part
+        const content = [
+            { type: "text", text: response.join("\n") },
+        ];
+        // Image attachments.
+        if (this._context.config.imageResponses !== "omit") {
+            for (const image of this._images)
+                content.push({
+                    type: "image",
+                    data: image.data.toString("base64"),
+                    mimeType: image.contentType,
+                });
+        }
+        return { content, isError: this._isError };
+    }
+}
+function renderTabSnapshot(tabSnapshot) {
+    const lines = [];
+    if (tabSnapshot.consoleMessages.length) {
+        lines.push(`### New console messages`);
+        for (const message of tabSnapshot.consoleMessages)
+            lines.push(`- ${trim(message.toString(), 100)}`);
+        lines.push("");
+    }
+    if (tabSnapshot.downloads.length) {
+        lines.push(`### Downloads`);
+        for (const entry of tabSnapshot.downloads) {
+            if (entry.finished)
+                lines.push(`- Downloaded file ${entry.download.suggestedFilename()} to ${entry.outputFile}`);
+            else
+                lines.push(`- Downloading file ${entry.download.suggestedFilename()} ...`);
+        }
+        lines.push("");
+    }
+    lines.push(`### Page state`);
+    lines.push(`- Page URL: ${tabSnapshot.url}`);
+    lines.push(`- Page Title: ${tabSnapshot.title}`);
+    lines.push(`- Page Snapshot:`);
+    lines.push("```yaml");
+    lines.push(tabSnapshot.ariaSnapshot);
+    lines.push("```");
+    return lines.join("\n");
+}
+function renderTabsMarkdown(tabs, force = false) {
+    if (tabs.length === 1 && !force)
+        return [];
+    if (!tabs.length) {
+        return [
+            "### Open tabs",
+            'No open tabs. Use the "browser_navigate" tool to navigate to a page first.',
+            "",
+        ];
+    }
+    const lines = ["### Open tabs"];
+    for (let i = 0; i < tabs.length; i++) {
+        const tab = tabs[i];
+        const current = tab.isCurrentTab() ? " (current)" : "";
+        lines.push(`- ${i}:${current} [${tab.lastTitle()}] (${tab.page.url()})`);
+    }
+    lines.push("");
+    return lines;
+}
+function trim(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    return text.slice(0, maxLength) + "...";
+}

package/lib/sessionLog.js

@@ -0,0 +1,123 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import fs from "fs";
+import path from "path";
+import { outputFile } from "./config.js";
+import { logUnhandledError } from "./utils/log.js";
+export class SessionLog {
+    _folder;
+    _file;
+    _ordinal = 0;
+    _pendingEntries = [];
+    _sessionFileQueue = Promise.resolve();
+    _flushEntriesTimeout;
+    constructor(sessionFolder) {
+        this._folder = sessionFolder;
+        this._file = path.join(this._folder, "session.md");
+    }
+    static async create(config, rootPath) {
+        const sessionFolder = await outputFile(config, rootPath, `session-${Date.now()}`);
+        await fs.promises.mkdir(sessionFolder, { recursive: true });
+        // eslint-disable-next-line no-console
+        console.error(`Session: ${sessionFolder}`);
+        return new SessionLog(sessionFolder);
+    }
+    logResponse(response) {
+        const entry = {
+            timestamp: performance.now(),
+            toolCall: {
+                toolName: response.toolName,
+                toolArgs: response.toolArgs,
+                result: response.result(),
+                isError: response.isError(),
+            },
+            code: response.code(),
+            tabSnapshot: response.tabSnapshot(),
+        };
+        this._appendEntry(entry);
+    }
+    logUserAction(action, tab, code, isUpdate) {
+        code = code.trim();
+        if (isUpdate) {
+            const lastEntry = this._pendingEntries[this._pendingEntries.length - 1];
+            if (lastEntry.userAction?.name === action.name) {
+                lastEntry.userAction = action;
+                lastEntry.code = code;
+                return;
+            }
+        }
+        if (action.name === "navigate") {
+            // Already logged at this location.
+            const lastEntry = this._pendingEntries[this._pendingEntries.length - 1];
+            if (lastEntry?.tabSnapshot?.url === action.url)
+                return;
+        }
+        const entry = {
+            timestamp: performance.now(),
+            userAction: action,
+            code,
+            tabSnapshot: {
+                url: tab.page.url(),
+                title: "",
+                ariaSnapshot: action.ariaSnapshot || "",
+                modalStates: [],
+                consoleMessages: [],
+                downloads: [],
+            },
+        };
+        this._appendEntry(entry);
+    }
+    _appendEntry(entry) {
+        this._pendingEntries.push(entry);
+        if (this._flushEntriesTimeout)
+            clearTimeout(this._flushEntriesTimeout);
+        this._flushEntriesTimeout = setTimeout(() => this._flushEntries(), 1000);
+    }
+    async _flushEntries() {
+        clearTimeout(this._flushEntriesTimeout);
+        const entries = this._pendingEntries;
+        this._pendingEntries = [];
+        const lines = [""];
+        for (const entry of entries) {
+            const ordinal = (++this._ordinal).toString().padStart(3, "0");
+            if (entry.toolCall) {
+                lines.push(`### Tool call: ${entry.toolCall.toolName}`, `- Args`, "```json", JSON.stringify(entry.toolCall.toolArgs, null, 2), "```");
+                if (entry.toolCall.result) {
+                    lines.push(entry.toolCall.isError ? `- Error` : `- Result`, "```", entry.toolCall.result, "```");
+                }
+            }
+            if (entry.userAction) {
+                const actionData = { ...entry.userAction };
+                delete actionData.ariaSnapshot;
+                delete actionData.selector;
+                delete actionData.signals;
+                lines.push(`### User action: ${entry.userAction.name}`, `- Args`, "```json", JSON.stringify(actionData, null, 2), "```");
+            }
+            if (entry.code) {
+                lines.push(`- Code`, "```js", entry.code, "```");
+            }
+            if (entry.tabSnapshot) {
+                const fileName = `${ordinal}.snapshot.yml`;
+                fs.promises
+                    .writeFile(path.join(this._folder, fileName), entry.tabSnapshot.ariaSnapshot)
+                    .catch(logUnhandledError);
+                lines.push(`- Snapshot: ${fileName}`);
+            }
+            lines.push("", "");
+        }
+        this._sessionFileQueue = this._sessionFileQueue.then(() => fs.promises.appendFile(this._file, lines.join("\n")));
+    }
+}

package/lib/tab.js

@@ -0,0 +1,251 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { EventEmitter } from "events";
+import { callOnPageNoTrace, waitForCompletion } from "./tools/utils.js";
+import { logUnhandledError } from "./utils/log.js";
+import { ManualPromise } from "./utils/manualPromise.js";
+export const TabEvents = {
+    modalState: "modalState",
+};
+export class Tab extends EventEmitter {
+    context;
+    page;
+    _lastTitle = "about:blank";
+    _consoleMessages = [];
+    _recentConsoleMessages = [];
+    _requests = new Map();
+    _onPageClose;
+    _modalStates = [];
+    _downloads = [];
+    constructor(context, page, onPageClose) {
+        super();
+        this.context = context;
+        this.page = page;
+        this._onPageClose = onPageClose;
+        page.on("console", (event) => this._handleConsoleMessage(messageToConsoleMessage(event)));
+        page.on("pageerror", (error) => this._handleConsoleMessage(pageErrorToConsoleMessage(error)));
+        page.on("request", (request) => this._requests.set(request, null));
+        page.on("response", (response) => this._requests.set(response.request(), response));
+        page.on("close", () => this._onClose());
+        page.on("filechooser", (chooser) => {
+            this.setModalState({
+                type: "fileChooser",
+                description: "File chooser",
+                fileChooser: chooser,
+            });
+        });
+        page.on("dialog", (dialog) => this._dialogShown(dialog));
+        // page.on('download', download => {
+        //   void this._downloadStarted(download);
+        // });
+        page.setDefaultNavigationTimeout(60000);
+        page.setDefaultTimeout(5000);
+        page[tabSymbol] = this;
+    }
+    static forPage(page) {
+        return page[tabSymbol];
+    }
+    modalStates() {
+        return this._modalStates;
+    }
+    setModalState(modalState) {
+        this._modalStates.push(modalState);
+        this.emit(TabEvents.modalState, modalState);
+    }
+    clearModalState(modalState) {
+        this._modalStates = this._modalStates.filter((state) => state !== modalState);
+    }
+    modalStatesMarkdown() {
+        return renderModalStates(this.context, this.modalStates());
+    }
+    _dialogShown(dialog) {
+        this.setModalState({
+            type: "dialog",
+            description: `"${dialog.type()}" dialog with message "${dialog.message()}"`,
+            dialog,
+        });
+    }
+    async _downloadStarted(download) {
+        const entry = {
+            download,
+            finished: false,
+            outputFile: await this.context.outputFile(download.suggestedFilename()),
+        };
+        this._downloads.push(entry);
+        await download.saveAs(entry.outputFile);
+        entry.finished = true;
+    }
+    _clearCollectedArtifacts() {
+        this._consoleMessages.length = 0;
+        this._recentConsoleMessages.length = 0;
+        this._requests.clear();
+    }
+    _handleConsoleMessage(message) {
+        this._consoleMessages.push(message);
+        this._recentConsoleMessages.push(message);
+    }
+    _onClose() {
+        this._clearCollectedArtifacts();
+        this._onPageClose(this);
+    }
+    async updateTitle() {
+        await this._raceAgainstModalStates(async () => {
+            this._lastTitle = await callOnPageNoTrace(this.page, (page) => page.title());
+        });
+    }
+    lastTitle() {
+        return this._lastTitle;
+    }
+    isCurrentTab() {
+        return this === this.context.currentTab();
+    }
+    async waitForLoadState(state, options) {
+        await callOnPageNoTrace(this.page, (page) => page.waitForLoadState(state, options).catch(logUnhandledError));
+    }
+    async navigate(url) {
+        this._clearCollectedArtifacts();
+        // const downloadEvent = callOnPageNoTrace(this.page, page => page.waitForEvent('download').catch(logUnhandledError));
+        const downloadEvent = Promise.resolve(undefined);
+        try {
+            await this.page.goto(url, { waitUntil: "domcontentloaded" });
+        }
+        catch (_e) {
+            const e = _e;
+            const mightBeDownload = e.message.includes("net::ERR_ABORTED") || // chromium
+                e.message.includes("Download is starting"); // firefox + webkit
+            if (!mightBeDownload)
+                throw e;
+            // on chromium, the download event is fired *after* page.goto rejects, so we wait a lil bit
+            const download = await Promise.race([
+                downloadEvent,
+                new Promise((resolve) => setTimeout(resolve, 3000)),
+            ]);
+            if (!download)
+                throw e;
+            // Make sure other "download" listeners are notified first.
+            await new Promise((resolve) => setTimeout(resolve, 500));
+            return;
+        }
+        // Cap load event to 5 seconds, the page is operational at this point.
+        await this.waitForLoadState("load", { timeout: 5000 });
+    }
+    consoleMessages() {
+        return this._consoleMessages;
+    }
+    requests() {
+        return this._requests;
+    }
+    async captureSnapshot() {
+        let tabSnapshot;
+        const modalStates = await this._raceAgainstModalStates(async () => {
+            const snapshot = await this.page._snapshotForAI();
+            tabSnapshot = {
+                url: this.page.url(),
+                title: await this.page.title(),
+                ariaSnapshot: snapshot,
+                modalStates: [],
+                consoleMessages: [],
+                downloads: this._downloads,
+            };
+        });
+        if (tabSnapshot) {
+            // Assign console message late so that we did not lose any to modal state.
+            tabSnapshot.consoleMessages = this._recentConsoleMessages;
+            this._recentConsoleMessages = [];
+        }
+        return (tabSnapshot ?? {
+            url: this.page.url(),
+            title: "",
+            ariaSnapshot: "",
+            modalStates,
+            consoleMessages: [],
+            downloads: [],
+        });
+    }
+    _javaScriptBlocked() {
+        return this._modalStates.some((state) => state.type === "dialog");
+    }
+    async _raceAgainstModalStates(action) {
+        if (this.modalStates().length)
+            return this.modalStates();
+        const promise = new ManualPromise();
+        const listener = (modalState) => promise.resolve([modalState]);
+        this.once(TabEvents.modalState, listener);
+        return await Promise.race([
+            action().then(() => {
+                this.off(TabEvents.modalState, listener);
+                return [];
+            }),
+            promise,
+        ]);
+    }
+    async waitForCompletion(callback) {
+        await this._raceAgainstModalStates(() => waitForCompletion(this, callback));
+    }
+    async refLocator(params) {
+        return (await this.refLocators([params]))[0];
+    }
+    async refLocators(params) {
+        // Ensure aria-ref mapping is present without validating refs against a fresh snapshot.
+        // This avoids invalidating refs obtained from browser_get_snapshot while still
+        // initializing the mapping when needed (e.g., after navigation).
+        await this.page._snapshotForAI();
+        return params.map((param) => this.page.locator(`aria-ref=${param.ref}`));
+    }
+    async waitForTimeout(time) {
+        if (this._javaScriptBlocked()) {
+            await new Promise((f) => setTimeout(f, time));
+            return;
+        }
+        await callOnPageNoTrace(this.page, (page) => {
+            return page.evaluate(() => new Promise((f) => setTimeout(f, 1000)));
+        });
+    }
+}
+function messageToConsoleMessage(message) {
+    return {
+        type: message.type(),
+        text: message.text(),
+        toString: () => `[${message.type().toUpperCase()}] ${message.text()} @ ${message.location().url}:${message.location().lineNumber}`,
+    };
+}
+function pageErrorToConsoleMessage(errorOrValue) {
+    if (errorOrValue instanceof Error) {
+        return {
+            type: undefined,
+            text: errorOrValue.message,
+            toString: () => errorOrValue.stack || errorOrValue.message,
+        };
+    }
+    return {
+        type: undefined,
+        text: String(errorOrValue),
+        toString: () => String(errorOrValue),
+    };
+}
+export function renderModalStates(context, modalStates) {
+    const result = ["### Modal state"];
+    if (modalStates.length === 0)
+        result.push("- There is no modal state present");
+    for (const state of modalStates) {
+        const tool = context.tools
+            .filter((tool) => "clearsModalState" in tool)
+            .find((tool) => tool.clearsModalState === state.type);
+        result.push(`- [${state.description}]: can be handled by the "${tool?.schema.name}" tool`);
+    }
+    return result;
+}
+const tabSymbol = Symbol("tabSymbol");

package/lib/tools/common.js

@@ -0,0 +1,55 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from "zod";
+import { defineTabTool, defineTool } from "./tool.js";
+const close = defineTool({
+    capability: "core",
+    schema: {
+        name: "browser_close",
+        title: "Close browser",
+        description: "Close the page",
+        inputSchema: z.object({}),
+        type: "readOnly",
+    },
+    handle: async (context, params, response) => {
+        await context.closeBrowserContext();
+        response.setIncludeTabs();
+        response.addCode(`await page.close()`);
+    },
+});
+const resize = defineTabTool({
+    capability: "core",
+    schema: {
+        name: "browser_resize",
+        title: "Resize browser window",
+        description: "Resize the browser window",
+        inputSchema: z.object({
+            width: z.number().describe("Width of the browser window"),
+            height: z.number().describe("Height of the browser window"),
+        }),
+        type: "readOnly",
+    },
+    handle: async (tab, params, response) => {
+        response.addCode(`await page.setViewportSize({ width: ${params.width}, height: ${params.height} });`);
+        await tab.waitForCompletion(async () => {
+            await tab.page.setViewportSize({
+                width: params.width,
+                height: params.height,
+            });
+        });
+    },
+});
+export default [close, resize];

package/lib/tools/console.js

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { z } from "zod";
+import { defineTabTool } from "./tool.js";
+const console = defineTabTool({
+    capability: "core",
+    schema: {
+        name: "browser_console_messages",
+        title: "Get console messages",
+        description: "Returns all console messages",
+        inputSchema: z.object({}),
+        type: "readOnly",
+    },
+    handle: async (tab, params, response) => {
+        tab
+            .consoleMessages()
+            .map((message) => response.addResult(message.toString()));
+    },
+});
+export default [console];