@monoes/monomindcli 2.13.0 → 2.14.1

package/dist/src/mcp-tools/browser-profile-tools.js

@@ -0,0 +1,324 @@
+/**
+ * Browser performance tools: web vitals, CPU/heap profiling, device emulation.
+ *
+ * Profiles and heap snapshots are megabytes of JSON, so these tools write the
+ * artifact to a file under `.monomind/` and return the path plus a summary an
+ * agent can actually act on — never the raw dump.
+ *
+ * Registered from `browser-tools.ts`; shared plumbing lives in
+ * `browser-session.ts`, console/network capture in
+ * `browser-instrument-tools.ts`, and the grading/summarising in
+ * `browser-metrics.ts`.
+ */
+import { collectRequests } from './browser-instrument-tools.js';
+import { gradeVitals, summarizeCpuProfile } from './browser-metrics.js';
+import { fail, getConnection, ok, rejectFlagLike, resolveArtifactPath, safeFileSlug, touchSession, validateSessionId, } from './browser-session.js';
+/** Most devices allowed in one emulation matrix run — each is a full screenshot. */
+const MAX_MATRIX_DEVICES = 8;
+/** Refuse to parse a .cpuprofile larger than this; the file is still written. */
+const MAX_PROFILE_PARSE_BYTES = 64 * 1024 * 1024;
+/** Settle time after applying a device profile before screenshotting. */
+const EMULATION_SETTLE_MS = 300;
+// ---------------------------------------------------------------------------
+// Tools
+// ---------------------------------------------------------------------------
+export const browserProfileTools = [
+    {
+        name: 'browser_vitals',
+        description: 'Measure Core Web Vitals for the loaded page — LCP, CLS, INP, TTFB, FCP — graded against the standard budgets, with the metrics that miss them listed worst-first. Returns numbers to act on plus the human-readable report. Reach for this when asked whether a page is fast, or after a change that could affect load performance. Run browser_network with action:"start" and reload beforehand to also get the heaviest resources.',
+        category: 'browser',
+        tags: ['performance', 'vitals'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                waitMs: {
+                    type: 'number',
+                    description: 'How long to observe before reporting (default 2000, max 10000)',
+                },
+                session: { type: 'string', description: 'Session ID' },
+            },
+        },
+        handler: async (input) => {
+            const raw = input;
+            let sessionId;
+            try {
+                sessionId = validateSessionId(raw.session);
+            }
+            catch (e) {
+                return fail(e.message);
+            }
+            const waitMs = Math.min(Math.max(Number(raw.waitMs ?? 2000), 0), 10_000);
+            try {
+                const { collectVitals, formatVitals } = await import('@monoes/monobrowse');
+                const conn = await getConnection(sessionId);
+                const vitals = await collectVitals(conn.client, conn.cdpSessionId, waitMs);
+                const { assessment, worst } = gradeVitals(vitals);
+                const heaviest = (await collectRequests(conn.cdpSessionId))
+                    .filter((r) => r.sizeBytes !== undefined)
+                    .sort((a, b) => (b.sizeBytes ?? 0) - (a.sizeBytes ?? 0))
+                    .slice(0, 5)
+                    .map((r) => ({
+                    url: r.url,
+                    type: r.type,
+                    sizeBytes: r.sizeBytes,
+                    durationMs: r.durationMs,
+                }));
+                touchSession(sessionId);
+                return ok({
+                    session: sessionId,
+                    vitals,
+                    formatted: formatVitals(vitals),
+                    assessment,
+                    worst,
+                    heaviestResources: heaviest.length > 0 ? heaviest : undefined,
+                    note: heaviest.length > 0
+                        ? undefined
+                        : 'No resource sizes available — run browser_network with action:"start" and reload the page to attribute page weight to specific requests.',
+                });
+            }
+            catch (e) {
+                return fail(e.message);
+            }
+        },
+    },
+    {
+        name: 'browser_profile',
+        description: 'CPU profile or heap snapshot of the page. action:"start" then interact then action:"stop" writes a .cpuprofile and returns the functions burning the most self time — enough to answer "what is slow" without reading the file. action:"heap" writes a .heapsnapshot for leak hunting. Reach for this when a page is janky or memory-hungry and browser_vitals only told you that it is.',
+        category: 'browser',
+        tags: ['performance', 'profiling', 'memory'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['start', 'stop', 'heap'],
+                    description: 'start/stop a CPU profile, or heap for a one-shot heap snapshot',
+                },
+                topFunctions: {
+                    type: 'number',
+                    description: 'How many hot functions to summarise on stop (default 10, max 50)',
+                },
+                samplingInterval: {
+                    type: 'number',
+                    description: 'CPU sampling interval in microseconds (default: Chrome’s 1000)',
+                },
+                path: {
+                    type: 'string',
+                    description: 'Output file, relative to .monomind/profiles/ (default: timestamped)',
+                },
+                session: { type: 'string', description: 'Session ID' },
+            },
+            required: ['action'],
+        },
+        handler: async (input) => {
+            const raw = input;
+            let sessionId;
+            try {
+                sessionId = validateSessionId(raw.session);
+            }
+            catch (e) {
+                return fail(e.message);
+            }
+            const action = raw.action;
+            if (action !== 'start' && action !== 'stop' && action !== 'heap')
+                return fail('action: must be one of start|stop|heap');
+            const top = Math.min(Math.max(Number(raw.topFunctions ?? 10), 1), 50);
+            try {
+                const { startCpuProfile, stopCpuProfile, startHeapSnapshot } = await import('@monoes/monobrowse');
+                const conn = await getConnection(sessionId);
+                touchSession(sessionId);
+                if (action === 'start') {
+                    const interval = raw.samplingInterval !== undefined ? Number(raw.samplingInterval) : undefined;
+                    if (interval !== undefined && (!Number.isFinite(interval) || interval <= 0))
+                        return fail('samplingInterval: must be a positive number of microseconds');
+                    await startCpuProfile(conn.client, conn.cdpSessionId, { samplingInterval: interval });
+                    return ok({
+                        session: sessionId,
+                        profiling: true,
+                        note: 'CPU profiler running. Drive the page, then call browser_profile with action:"stop".',
+                    });
+                }
+                const fs = await import('node:fs/promises');
+                if (action === 'heap') {
+                    const outPath = await resolveArtifactPath('profiles', raw.path, `heap-${Date.now()}.heapsnapshot`);
+                    // A snapshot that captured no chunks throws inside startHeapSnapshot
+                    // rather than returning a path, so a path here always has data and
+                    // an empty one surfaces as fail() through the catch below.
+                    const written = await startHeapSnapshot(conn.client, conn.cdpSessionId, outPath);
+                    const { size } = await fs.stat(written);
+                    return ok({
+                        session: sessionId,
+                        path: written,
+                        sizeBytes: size,
+                        note: 'Heap snapshot written. Open it in Chrome DevTools → Memory → Load to compare retainers.',
+                    });
+                }
+                // action === 'stop'
+                const outPath = await resolveArtifactPath('profiles', raw.path, `cpu-${Date.now()}.cpuprofile`);
+                const written = await stopCpuProfile(conn.client, conn.cdpSessionId, outPath);
+                const { size } = await fs.stat(written);
+                if (size > MAX_PROFILE_PARSE_BYTES) {
+                    return ok({
+                        session: sessionId,
+                        path: written,
+                        sizeBytes: size,
+                        note: `Profile is ${Math.round(size / 1024 / 1024)}MB — too large to summarise here. Open it in Chrome DevTools → Performance.`,
+                    });
+                }
+                let summary;
+                try {
+                    summary = summarizeCpuProfile(JSON.parse(await fs.readFile(written, 'utf8')), top);
+                }
+                catch (e) {
+                    return ok({
+                        session: sessionId,
+                        path: written,
+                        sizeBytes: size,
+                        note: `Profile written but could not be summarised (${e.message}). Open it in Chrome DevTools → Performance.`,
+                    });
+                }
+                return ok({
+                    session: sessionId,
+                    path: written,
+                    sizeBytes: size,
+                    durationMs: summary.durationMs,
+                    totalSamples: summary.totalSamples,
+                    topFunctions: summary.topFunctions,
+                    note: summary.totalSamples === 0
+                        ? 'No samples recorded — the page was idle for the whole profile.'
+                        : 'selfMs is time sampled inside the function itself, not its callees.',
+                });
+            }
+            catch (e) {
+                return fail(e.message);
+            }
+        },
+    },
+    {
+        name: 'browser_emulate',
+        description: 'Apply a device profile (viewport, DPR, touch, user agent) to the session, or pass devices:[…] to screenshot the current URL across a matrix of them and get the file paths back. Call with no arguments to list the available devices. Reach for this to check responsive layout or to reproduce a mobile-only bug. Emulation persists until reset:true, so clear it before other work.',
+        category: 'browser',
+        tags: ['emulation', 'responsive', 'screenshot'],
+        inputSchema: {
+            type: 'object',
+            properties: {
+                device: {
+                    type: 'string',
+                    description: 'Device profile name to apply (see the no-arg listing)',
+                },
+                devices: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: `Matrix mode: screenshot the current URL on each device (max ${MAX_MATRIX_DEVICES})`,
+                },
+                fullPage: { type: 'boolean', description: 'Matrix mode: capture the full scrollable page' },
+                reload: {
+                    type: 'boolean',
+                    description: 'Matrix mode: reload on each device instead of only reflowing',
+                },
+                reset: {
+                    type: 'boolean',
+                    description: 'Clear emulation overrides and restore the defaults',
+                },
+                session: { type: 'string', description: 'Session ID' },
+            },
+        },
+        handler: async (input) => {
+            const raw = input;
+            let sessionId;
+            try {
+                sessionId = validateSessionId(raw.session);
+            }
+            catch (e) {
+                return fail(e.message);
+            }
+            const matrix = raw.devices;
+            if (matrix !== undefined) {
+                if (!Array.isArray(matrix) || matrix.some((d) => typeof d !== 'string'))
+                    return fail('devices: must be an array of device names');
+                if (matrix.length === 0)
+                    return fail('devices: must not be empty');
+                if (matrix.length > MAX_MATRIX_DEVICES)
+                    return fail(`devices: too many (max ${MAX_MATRIX_DEVICES} per run)`);
+            }
+            try {
+                const { emulateDevice, listDevices, captureScreenshot, getCurrentUrl, waitForLoad } = await import('@monoes/monobrowse');
+                if (raw.device === undefined && matrix === undefined && raw.reset !== true) {
+                    return ok({
+                        devices: listDevices(),
+                        note: 'Pass device:"<name>" to emulate one, or devices:["…","…"] to screenshot a matrix.',
+                    });
+                }
+                const conn = await getConnection(sessionId);
+                touchSession(sessionId);
+                if (raw.reset === true && matrix === undefined && raw.device === undefined) {
+                    await clearEmulation(conn);
+                    return ok({ session: sessionId, reset: true });
+                }
+                if (matrix === undefined) {
+                    const device = rejectFlagLike(raw.device, 'device');
+                    await emulateDevice(conn.client, conn.cdpSessionId, device);
+                    return ok({
+                        session: sessionId,
+                        device,
+                        note: 'Emulation stays active for this session — call browser_emulate with reset:true when done.',
+                    });
+                }
+                // Matrix mode: one screenshot per device, then put the session back.
+                const url = await getCurrentUrl(conn.client, conn.cdpSessionId);
+                const stamp = Date.now();
+                const screenshots = [];
+                for (const device of matrix) {
+                    try {
+                        await emulateDevice(conn.client, conn.cdpSessionId, device);
+                        if (raw.reload === true) {
+                            await conn.client.send('Page.reload', {}, conn.cdpSessionId);
+                            await waitForLoad(conn.client, conn.cdpSessionId, 'load', 30_000);
+                        }
+                        else {
+                            await new Promise((r) => setTimeout(r, EMULATION_SETTLE_MS));
+                        }
+                        const outPath = await resolveArtifactPath('screenshots', undefined, `emulate-${stamp}-${safeFileSlug(device)}.png`);
+                        const shot = await captureScreenshot(conn.client, conn.cdpSessionId, {
+                            path: outPath,
+                            fullPage: raw.fullPage === true,
+                            format: 'png',
+                        });
+                        screenshots.push({ device, path: shot.path ?? outPath });
+                    }
+                    catch (e) {
+                        screenshots.push({ device, error: e.message });
+                    }
+                }
+                await clearEmulation(conn);
+                const failed = screenshots.filter((s) => s.error !== undefined).length;
+                return ok({
+                    session: sessionId,
+                    url,
+                    screenshots,
+                    failed,
+                    note: 'Emulation overrides were cleared after the matrix run.',
+                });
+            }
+            catch (e) {
+                return fail(e.message);
+            }
+        },
+    },
+];
+/** Drop every emulation override so later tool calls see a normal browser. */
+async function clearEmulation(conn) {
+    const send = async (method, params = {}) => {
+        try {
+            await conn.client.send(method, params, conn.cdpSessionId);
+        }
+        catch {
+            /* best-effort: a cleared override that was never set is not an error */
+        }
+    };
+    await send('Emulation.clearDeviceMetricsOverride');
+    await send('Emulation.setTouchEmulationEnabled', { enabled: false });
+    await send('Emulation.setUserAgentOverride', { userAgent: '' });
+}
+export default browserProfileTools;
+//# sourceMappingURL=browser-profile-tools.js.map

package/dist/src/mcp-tools/browser-profile-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-profile-tools.js","sourceRoot":"","sources":["../../../src/mcp-tools/browser-profile-tools.ts"],"names":[],"mappings":"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"}

package/dist/src/mcp-tools/browser-session.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared plumbing for the browser MCP tools.
+ *
+ * Session registry, CDP connection cache, input validation and result
+ * formatting — used by both `browser-tools.ts` (navigation / interaction)
+ * and the instrument tools (`browser-instrument-tools.ts`,
+ * `browser-profile-tools.ts`). Lives in its own module so the tool files
+ * stay readable and neither has to import the other.
+ */
+import type { MCPToolResult } from './types.js';
+export declare const MAX_BROWSER_SESSIONS = 5;
+export declare const SESSION_TTL_MS: number;
+/** Tracking metadata for a single browser session. */
+export interface BrowserSessionInfo {
+    sessionId: string;
+    createdAt: string;
+    lastActivity: string;
+}
+export interface BrowserConnection {
+    client: import('@monoes/monobrowse').CdpClient;
+    cdpSessionId: string;
+    refs: Map<string, import('@monoes/monobrowse').ElementRef>;
+    /**
+     * When this CDP connection was established. Console/network capture buffers
+     * are armed at connect time and keyed by `cdpSessionId`, so this is the
+     * start of the window those buffers cover — the instrument tools report it
+     * so an agent knows what it is and isn't seeing.
+     */
+    openedAt: string;
+}
+export declare const browserSessions: Map<string, BrowserSessionInfo>;
+export declare const connectionCache: Map<string, BrowserConnection>;
+export declare function pruneExpiredSessions(): Promise<void>;
+export declare function touchSession(sessionId: string): void;
+export declare function getConnection(sessionId: string): Promise<BrowserConnection>;
+export declare function releaseConnection(sessionId: string): Promise<void>;
+export declare function closeTarget(conn: BrowserConnection, port: number): Promise<void>;
+export declare function ok(data?: Record<string, unknown>): MCPToolResult;
+export declare function fail(message: string): MCPToolResult;
+/** Validate a session ID against a strict allowlist. */
+export declare function validateSessionId(value: unknown): string;
+/** Validate a URL against a scheme allowlist. */
+export declare const ALLOWED_URL_SCHEMES: Set<string>;
+export declare function validateUrl(value: unknown): string;
+/**
+ * Validate a screenshot path. Resolved path must be within
+ * `<projectRoot>/.monomind/screenshots` and must not already exist.
+ */
+export declare function validateScreenshotPath(value: unknown): Promise<string>;
+/**
+ * Resolve the output path for a generated artifact (HAR, CPU profile, heap
+ * snapshot, device screenshot) under `<projectRoot>/.monomind/<subdir>/`.
+ * A caller-supplied path is taken relative to that directory, must stay
+ * inside it, and must not already exist. With no path, `fallbackName` is
+ * used. Creates the directory when missing.
+ */
+export declare function resolveArtifactPath(subdir: string, value: unknown, fallbackName: string): Promise<string>;
+/** Reduce an arbitrary label to something safe to use as a file name. */
+export declare function safeFileSlug(value: string): string;
+/** Reject strings starting with '-' (flag-injection defense). */
+export declare function rejectFlagLike(value: unknown, field: string): string;
+/**
+ * Resolve an element target using monobrowse finders.
+ * target: CSS selector string (e.g. "#id", ".class", "button")
+ * locator: "selector" (default) | "role" | "text" | "label" | "placeholder"
+ */
+export declare function findElement(conn: BrowserConnection, target: string, locator?: string): Promise<import('@monoes/monobrowse').ElementRef>;
+//# sourceMappingURL=browser-session.d.ts.map

package/dist/src/mcp-tools/browser-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-session.d.ts","sourceRoot":"","sources":["../../../src/mcp-tools/browser-session.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,eAAO,MAAM,cAAc,QAAiB,CAAC;AAE7C,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,OAAO,oBAAoB,EAAE,SAAS,CAAC;IAC/C,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,oBAAoB,EAAE,UAAU,CAAC,CAAC;IAC3D;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAGD,eAAO,MAAM,eAAe,iCAAwC,CAAC;AACrE,eAAO,MAAM,eAAe,gCAAuC,CAAC;AAEpE,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAW1D;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAGpD;AAED,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA4BjF;AAED,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYxE;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBtF;AAED,wBAAgB,EAAE,CAAC,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,aAAa,CAEpE;AAED,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CAKnD;AAED,wDAAwD;AACxD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMxD;AAED,iDAAiD;AACjD,eAAO,MAAM,mBAAmB,aAAyC,CAAC;AAE1E,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAalD;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAe5E;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,CAajB;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQlD;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKpE;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,MAAM,EACd,OAAO,SAAa,GACnB,OAAO,CAAC,OAAO,oBAAoB,EAAE,UAAU,CAAC,CA2BlD"}

package/dist/src/mcp-tools/browser-session.js

@@ -0,0 +1,224 @@
+/**
+ * Shared plumbing for the browser MCP tools.
+ *
+ * Session registry, CDP connection cache, input validation and result
+ * formatting — used by both `browser-tools.ts` (navigation / interaction)
+ * and the instrument tools (`browser-instrument-tools.ts`,
+ * `browser-profile-tools.ts`). Lives in its own module so the tool files
+ * stay readable and neither has to import the other.
+ */
+export const MAX_BROWSER_SESSIONS = 5;
+export const SESSION_TTL_MS = 10 * 60 * 1000; // 10 minutes
+// Session registry for multi-session support (sessionId → connection)
+export const browserSessions = new Map();
+export const connectionCache = new Map();
+export async function pruneExpiredSessions() {
+    const cutoff = Date.now() - SESSION_TTL_MS;
+    const port = Number(process.env.MONOBROWSE_CDP_PORT ?? 9222);
+    for (const [id, info] of browserSessions) {
+        if (new Date(info.lastActivity).getTime() < cutoff) {
+            browserSessions.delete(id);
+            const conn = connectionCache.get(id);
+            connectionCache.delete(id);
+            if (conn)
+                await closeTarget(conn, port);
+        }
+    }
+}
+export function touchSession(sessionId) {
+    const info = browserSessions.get(sessionId);
+    if (info)
+        info.lastActivity = new Date().toISOString();
+}
+export async function getConnection(sessionId) {
+    if (connectionCache.has(sessionId)) {
+        const conn = connectionCache.get(sessionId);
+        try {
+            // Liveness check — evict stale CDP connections
+            await conn.client.send('Runtime.evaluate', { expression: '1', returnByValue: true }, conn.cdpSessionId);
+            return conn;
+        }
+        catch {
+            const port = Number(process.env.MONOBROWSE_CDP_PORT ?? 9222);
+            connectionCache.delete(sessionId);
+            await closeTarget(conn, port);
+        }
+    }
+    const port = Number(process.env.MONOBROWSE_CDP_PORT ?? 9222);
+    const { connectToTarget } = await import('@monoes/monobrowse');
+    const { client, sessionId: cdpSessionId } = await connectToTarget(port);
+    const conn = {
+        client,
+        cdpSessionId,
+        refs: new Map(),
+        openedAt: new Date().toISOString(),
+    };
+    connectionCache.set(sessionId, conn);
+    return conn;
+}
+export async function releaseConnection(sessionId) {
+    const conn = connectionCache.get(sessionId);
+    connectionCache.delete(sessionId);
+    browserSessions.delete(sessionId);
+    if (conn) {
+        const port = Number(process.env.MONOBROWSE_CDP_PORT ?? 9222);
+        // Close the actual Chrome tab — just closing the WebSocket leaves the
+        // renderer process alive and consuming ~250MB+ RAM each. Awaited (not
+        // fire-and-forget) so a burst of session churn can't pile up concurrent
+        // in-flight closes and leak renderers when one fails silently.
+        await closeTarget(conn, port);
+    }
+}
+export async function closeTarget(conn, port) {
+    try {
+        // Get the target ID for this session so we can close the tab
+        const result = await conn.client.send('Target.getTargetInfo', {}, conn.cdpSessionId);
+        const targetId = result?.targetInfo?.targetId;
+        if (targetId) {
+            // Close via HTTP endpoint — works even if the CDP session is stale
+            await fetch(`http://127.0.0.1:${port}/json/close/${encodeURIComponent(targetId)}`, {
+                method: 'GET',
+            });
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+    try {
+        conn.client.close();
+    }
+    catch {
+        /* ignore */
+    }
+}
+export function ok(data = {}) {
+    return { content: [{ type: 'text', text: JSON.stringify({ success: true, ...data }, null, 2) }] };
+}
+export function fail(message) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify({ success: false, error: message }) }],
+        isError: true,
+    };
+}
+/** Validate a session ID against a strict allowlist. */
+export function validateSessionId(value) {
+    if (value === undefined || value === null || value === '')
+        return 'default';
+    if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,64}$/.test(value)) {
+        throw new Error('session: must match ^[A-Za-z0-9_-]{1,64}$');
+    }
+    return value;
+}
+/** Validate a URL against a scheme allowlist. */
+export const ALLOWED_URL_SCHEMES = new Set(['http:', 'https:', 'about:']);
+export function validateUrl(value) {
+    if (typeof value !== 'string')
+        throw new Error('url: must be a string');
+    if (value.length > 4096)
+        throw new Error('url: too long (max 4096)');
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new Error(`url: not a valid URL: ${value}`);
+    }
+    if (!ALLOWED_URL_SCHEMES.has(parsed.protocol)) {
+        throw new Error(`url: scheme "${parsed.protocol}" not allowed (only http/https/about)`);
+    }
+    return value;
+}
+/**
+ * Validate a screenshot path. Resolved path must be within
+ * `<projectRoot>/.monomind/screenshots` and must not already exist.
+ */
+export async function validateScreenshotPath(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        throw new Error('path: must be a non-empty string');
+    if (value.startsWith('-'))
+        throw new Error('path: must not start with "-"');
+    const path = await import('node:path');
+    const fs = await import('node:fs');
+    const root = path.resolve(process.cwd(), '.monomind', 'screenshots');
+    await fs.promises.mkdir(root, { recursive: true });
+    const resolved = path.resolve(value);
+    if (!resolved.startsWith(root + path.sep) && resolved !== root) {
+        throw new Error(`path: must be within ${root}`);
+    }
+    if (fs.existsSync(resolved))
+        throw new Error(`path: refuses to overwrite existing file at ${resolved}`);
+    return resolved;
+}
+/**
+ * Resolve the output path for a generated artifact (HAR, CPU profile, heap
+ * snapshot, device screenshot) under `<projectRoot>/.monomind/<subdir>/`.
+ * A caller-supplied path is taken relative to that directory, must stay
+ * inside it, and must not already exist. With no path, `fallbackName` is
+ * used. Creates the directory when missing.
+ */
+export async function resolveArtifactPath(subdir, value, fallbackName) {
+    const path = await import('node:path');
+    const fs = await import('node:fs');
+    const root = path.resolve(process.cwd(), '.monomind', subdir);
+    await fs.promises.mkdir(root, { recursive: true });
+    if (value === undefined || value === null || value === '')
+        return path.join(root, fallbackName);
+    if (typeof value !== 'string')
+        throw new Error('path: must be a string');
+    if (value.startsWith('-'))
+        throw new Error('path: must not start with "-"');
+    const resolved = path.resolve(root, value);
+    if (!resolved.startsWith(root + path.sep))
+        throw new Error(`path: must be within ${root}`);
+    if (fs.existsSync(resolved))
+        throw new Error(`path: refuses to overwrite existing file at ${resolved}`);
+    return resolved;
+}
+/** Reduce an arbitrary label to something safe to use as a file name. */
+export function safeFileSlug(value) {
+    return (value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 40) || 'item');
+}
+/** Reject strings starting with '-' (flag-injection defense). */
+export function rejectFlagLike(value, field) {
+    if (typeof value !== 'string')
+        throw new Error(`${field}: must be a string`);
+    if (value.startsWith('-'))
+        throw new Error(`${field}: must not start with '-' (flag-injection defense)`);
+    return value;
+}
+/**
+ * Resolve an element target using monobrowse finders.
+ * target: CSS selector string (e.g. "#id", ".class", "button")
+ * locator: "selector" (default) | "role" | "text" | "label" | "placeholder"
+ */
+export async function findElement(conn, target, locator = 'selector') {
+    const { findBySelector, findByRole, findByText, findByLabel, findByPlaceholder } = await import('@monoes/monobrowse');
+    let ref = null;
+    switch (locator) {
+        case 'selector':
+            ref = await findBySelector(conn.client, conn.cdpSessionId, conn.refs, target);
+            break;
+        case 'role':
+            ref = await findByRole(conn.client, conn.cdpSessionId, conn.refs, target);
+            break;
+        case 'text':
+            ref = await findByText(conn.client, conn.cdpSessionId, conn.refs, target);
+            break;
+        case 'label':
+            ref = await findByLabel(conn.client, conn.cdpSessionId, conn.refs, target);
+            break;
+        case 'placeholder':
+            ref = await findByPlaceholder(conn.client, conn.cdpSessionId, conn.refs, target);
+            break;
+        default:
+            throw new Error(`Unknown locator "${locator}". Use: selector|role|text|label|placeholder`);
+    }
+    if (!ref)
+        throw new Error(`Element not found: ${locator}="${target}"`);
+    return ref;
+}
+//# sourceMappingURL=browser-session.js.map

package/dist/src/mcp-tools/browser-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-session.js","sourceRoot":"","sources":["../../../src/mcp-tools/browser-session.ts"],"names":[],"mappings":"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"}