browxai 0.7.0

package/dist/tools/capture-report-upload-tools.js

@@ -0,0 +1,277 @@
+import { confirmByobAction } from "../policy/confirm.js";
+import { withDeadline } from "../util/deadline.js";
+import { estimateTokens } from "../util/tokens.js";
+import { uploadFile } from "../page/upload.js";
+import { dropFiles } from "../page/drop-files.js";
+import { readCapturedBytes } from "../page/downloads.js";
+import { REF_OR_SELECTOR, SESSION_ARG } from "./schemas.js";
+/**
+ * Capture + report — file ingress & download egress. `upload_file` / `drop_files`
+ * (file ingress into the page), `downloads_capture` / `download_get` (capture and
+ * read browser-initiated downloads under the workspace root). Registered through
+ * the shared `ToolHost` seam.
+ */
+export function registerCaptureReportUploadTools(host) {
+    const { z, register, gateCheck, entryFor, confirmCtxFor, denyContent, asTarget, cfgActionTimeout, workspace, } = host;
+    register("upload_file", {
+        capability: "file-io",
+        description: "Set a file on a file `<input>` (works on hidden inputs) via Playwright `setInputFiles` — the first-class alternative to injecting `File`/`DataTransfer` through `eval_js`. Target the input by `ref`/`selector`. File source is exactly one of: `content` (base64 inline — no filesystem read; pass `name`/`mimeType`) OR `path` (resolved **inside `$BROWX_WORKSPACE` only** — a path escaping the workspace is rejected; stage the file there). Gated by the off-by-default **`file-io`** capability.",
+        inputSchema: {
+            ...REF_OR_SELECTOR,
+            name: z
+                .string()
+                .optional()
+                .describe('Filename presented to the page (content-mode; default "upload").'),
+            mimeType: z
+                .string()
+                .optional()
+                .describe("MIME type (content-mode; default application/octet-stream)."),
+            content: z
+                .string()
+                .optional()
+                .describe("base64 file content. Mutually exclusive with `path`."),
+            path: z
+                .string()
+                .optional()
+                .describe("Workspace-rooted file path. Mutually exclusive with `content`."),
+            ...SESSION_ARG,
+        },
+    }, async (args) => {
+        const g = gateCheck("upload_file");
+        if (g)
+            return g;
+        const e = await entryFor(args.session);
+        const c = await confirmByobAction("upload_file", confirmCtxFor(e));
+        if (!c.ok)
+            return denyContent("upload_file", c);
+        try {
+            const target = asTarget(args, "upload_file", e.refs);
+            if ("coords" in target) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                ok: false,
+                                error: "upload_file: target must be a ref/selector for the file input, not coords",
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            const r = await withDeadline(uploadFile(e.session.page(), e.refs, workspace.root, {
+                target,
+                name: args.name,
+                mimeType: args.mimeType,
+                content: args.content,
+                path: args.path,
+            }), cfgActionTimeout(), "upload_file");
+            return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) }, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+    // `drop_files` — sibling to `upload_file` for drop-zone uploaders. Modern
+    // SaaS file pickers listen for `dragenter`/`dragover`/`drop` with a
+    // populated `DataTransfer.files` and never expose an `<input type=file>` —
+    // `setInputFiles` can't drive them. drop_files synthesizes the standard
+    // HTML5 drop sequence with `File` objects built in-page from the bytes the
+    // caller supplies (`path` mode reads from $BROWX_WORKSPACE; `contents`
+    // mode is inline base64). Same `file-io` capability as upload_file.
+    register("drop_files", {
+        capability: "file-io",
+        description: "Synthesize an HTML5 file drag-drop on a page element — the first-class alternative to driving DataTransfer through `eval_js` for drop-zone uploaders that don't expose an `<input type=file>` (modern SaaS file pickers). Target via the standard target shapes (`ref`/`selector`/`named`/`coords`). `files[]` carries one or more file entries; each entry is exactly one of: `{path, name?, mimeType?}` (workspace-rooted file — escape-rejected, same posture as `upload_file`'s `path`) OR `{contents, name, mimeType?}` (base64 inline — no filesystem read). Builds an in-page `DataTransfer` populated with `File` objects and dispatches `dragenter` → `dragover` → `drop` on the target with realistic `clientX`/`clientY` (element box centre for ref/selector; literal coords). Drops every file in a single sequence — passing multiple entries simulates the multi-file drop most uploaders support natively. → `{ ok, target, files: [{name, mode, bytes, mimeType}], totalBytes, fileCount, eventsFired, dropDispatched, tokensEstimate }`. Gated by the off-by-default **`file-io`** capability.",
+        inputSchema: {
+            ...REF_OR_SELECTOR,
+            files: z
+                .array(z.object({
+                path: z
+                    .string()
+                    .optional()
+                    .describe("Workspace-rooted file path. Mutually exclusive with `contents`."),
+                contents: z
+                    .string()
+                    .optional()
+                    .describe("base64 file content. Mutually exclusive with `path`."),
+                name: z
+                    .string()
+                    .optional()
+                    .describe("Filename presented to the page. Required in `contents`-mode; defaults to the basename of `path` in `path`-mode."),
+                mimeType: z
+                    .string()
+                    .optional()
+                    .describe('MIME type. Default "application/octet-stream".'),
+            }))
+                .min(1)
+                .describe("Files to drop. Each entry is exactly one of `{path}` or `{contents}` (plus optional `name`/`mimeType`)."),
+            ...SESSION_ARG,
+        },
+    }, async (args) => {
+        const g = gateCheck("drop_files");
+        if (g)
+            return g;
+        const e = await entryFor(args.session);
+        const c = await confirmByobAction("drop_files", confirmCtxFor(e));
+        if (!c.ok)
+            return denyContent("drop_files", c);
+        try {
+            const target = asTarget(args, "drop_files", e.refs);
+            const r = await withDeadline(dropFiles(e.session.page(), e.refs, workspace.root, {
+                target,
+                files: args.files,
+            }), cfgActionTimeout(), "drop_files");
+            const json = JSON.stringify(r);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ...r, tokensEstimate: estimateTokens(json) }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const body = { ok: false, error: err instanceof Error ? err.message : String(err) };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ...body, tokensEstimate: estimateTokens(JSON.stringify(body)) }, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+    // Download capture — the reverse of `upload_file`. Off by default per
+    // session; toggled by `downloads_capture`. When on, any download fired
+    // during a subsequent action lands on `ActionResult.downloads[]` and can
+    // be read back via `download_get`. Workspace-rooted paths only.
+    register("downloads_capture", {
+        capability: "file-io",
+        description: "Per-session download capture — toggle interception of Playwright `download` events. When `on:true`, every download fired during a subsequent action is persisted to `$BROWX_WORKSPACE/.downloads/<sessionId>/<prefix>-<sanitised-name>` and surfaced on `ActionResult.downloads[{id, suggestedFilename, mimeType, sizeBytes, path}]`. When `on:false` (the default) the artifact is silently discarded so a session that never opted in leaves no on-disk trace. The page-supplied filename is sanitised (no path separators / NULs / leading dots / control bytes; length-capped) before composing the on-disk name — workspace-escape rejected. Read captured bytes with `download_get({id})`. Gated by the off-by-default **`file-io`** capability — same posture as `upload_file`. → `{ ok, captureOn, storageDir, captured: [{id, suggestedFilename, sizeBytes, path, mimeType?}], tokensEstimate }`. Pass `clear:true` alongside `on:false` to ALSO delete every captured file on disk.",
+        inputSchema: {
+            on: z.boolean().describe("Turn capture on (true) or off (false). Off by default."),
+            clear: z
+                .boolean()
+                .optional()
+                .describe("When toggling off, also delete every previously-captured file from disk. No-op when `on:true`."),
+            ...SESSION_ARG,
+        },
+    }, async (args) => {
+        const g = gateCheck("downloads_capture");
+        if (g)
+            return g;
+        const e = await entryFor(args.session);
+        try {
+            e.downloads.captureOn = !!args.on;
+            if (!args.on && args.clear) {
+                // best-effort cleanup of previously-captured files. Every entry's
+                // `path` is rooted under BROWX_WORKSPACE/.downloads/<sessionId>/
+                // by construction (see SessionEntry factory + page/downloads.ts).
+                const { unlinkSync } = await import("node:fs");
+                for (const d of e.downloads.list()) {
+                    try {
+                        unlinkSync(d.path);
+                    }
+                    catch {
+                        /* best-effort */
+                    }
+                }
+            }
+            const captured = e.downloads.list().map((d) => {
+                const out = {
+                    id: d.id,
+                    suggestedFilename: d.suggestedFilename,
+                    sizeBytes: d.sizeBytes,
+                    path: d.path,
+                };
+                if (d.mimeType !== undefined)
+                    out.mimeType = d.mimeType;
+                return out;
+            });
+            const body = {
+                ok: true,
+                captureOn: e.downloads.captureOn,
+                storageDir: e.downloads.storageDir,
+                captured,
+            };
+            const json = JSON.stringify(body);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ...body, tokensEstimate: estimateTokens(json) }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) }, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+    register("download_get", {
+        capability: "file-io",
+        description: "Return the bytes (base64) of a previously-captured download. Pass the `id` from `ActionResult.downloads[]` (or `downloads_capture({on:true}).captured[]`). Set `pathOnly:true` to skip the base64 payload and return just the workspace-rooted path metadata (useful for very large artifacts an agent only needs to forward to another tool by path). → `{ ok, id, suggestedFilename, mimeType?, sizeBytes, path, content?: base64, tokensEstimate }`. Gated by the off-by-default **`file-io`** capability.",
+        inputSchema: {
+            id: z.string().describe("Download id from ActionResult.downloads[].id."),
+            pathOnly: z
+                .boolean()
+                .optional()
+                .describe("When true, omit the base64 `content` field and return only path/metadata."),
+            ...SESSION_ARG,
+        },
+    }, async (args) => {
+        const g = gateCheck("download_get");
+        if (g)
+            return g;
+        const e = await entryFor(args.session);
+        try {
+            const r = readCapturedBytes(e.downloads, args.id);
+            const body = {
+                ok: true,
+                id: args.id,
+                suggestedFilename: r.suggestedFilename,
+                sizeBytes: r.bytes,
+                path: r.path,
+            };
+            if (r.mimeType !== undefined)
+                body.mimeType = r.mimeType;
+            if (!args.pathOnly)
+                body.content = r.base64;
+            const json = JSON.stringify(body);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ...body, tokensEstimate: estimateTokens(json) }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) }, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+}

package/dist/tools/config-approval-tools.d.ts

@@ -0,0 +1,8 @@
+import type { ToolHost } from "./host.js";
+/**
+ * Config-store + pre-approval tools — the browxai-managed layered config store
+ * (`get_config` / `set_config` / `reset_config`) and the session-independent
+ * pre-approval grants (`approve_actions` / `list_approvals`). Registered through
+ * the shared `ToolHost` seam.
+ */
+export declare function registerConfigApprovalTools(host: ToolHost): void;

package/dist/tools/config-approval-tools.js

@@ -0,0 +1,166 @@
+/**
+ * Config-store + pre-approval tools — the browxai-managed layered config store
+ * (`get_config` / `set_config` / `reset_config`) and the session-independent
+ * pre-approval grants (`approve_actions` / `list_approvals`). Registered through
+ * the shared `ToolHost` seam.
+ */
+export function registerConfigApprovalTools(host) {
+    // NOTE: `pluginRecords` is NOT destructured here — `host.pluginRecords` is a
+    // LIVE getter (host-build.ts) populated AFTER this tool is registered (the
+    // plugin runtime starts later). Destructuring would snapshot the empty
+    // pre-load array, so get_config would always report `plugins: []`. Read it
+    // live inside the handler instead.
+    const { z, register, caps, configStore, approvals } = host;
+    // ---------- config store ----------
+    const CONFIG_PATCH_SCHEMA = {
+        testAttributes: z.array(z.string()).optional(),
+        capabilities: z.array(z.string()).optional(),
+        confirmRequired: z.array(z.string()).optional(),
+        allowedOrigins: z.array(z.string()).optional(),
+        blockedOrigins: z.array(z.string()).optional(),
+        headless: z.boolean().optional(),
+        actionTimeoutMs: z.number().int().positive().max(3_600_000).optional(),
+        disableWebSecurity: z.boolean().optional(),
+        defaultDevice: z.string().optional(),
+        defaultViewport: z
+            .object({ width: z.number().int().positive(), height: z.number().int().positive() })
+            .optional(),
+        hideOverlaySelectors: z.array(z.string()).optional(),
+        plugins: z.array(z.string()).optional(),
+        unstable: z.record(z.unknown()).optional(),
+    };
+    register("get_config", {
+        batchable: true,
+        description: "Inspect browxai configuration. Default returns the fully *resolved* view (precedence: built-in defaults < env [legacy BROWX_*] < user < project < session). Pass `scope` to see one raw pre-merge layer. Config is browxai-managed — change it with `set_config`, never by hand-editing files or env.",
+        inputSchema: {
+            scope: z
+                .enum(["defaults", "env", "user", "project", "session", "resolved"])
+                .optional()
+                .describe("Which layer to show. Omit or 'resolved' for the merged view."),
+        },
+    }, async ({ scope }) => {
+        let body;
+        if (!scope || scope === "resolved") {
+            const resolved = configStore.resolve();
+            // `capabilities` in the resolved view is the LIVE enforced set — what
+            // tool gating actually uses — not the freshly re-resolved config.
+            // Those diverge after a `set_config({capabilities})` until a restart;
+            // reporting the re-resolved value here would lie to the agent.
+            const live = [...caps.enabled].sort();
+            const persisted = [...resolved.capabilities].sort();
+            // the LIVE enabled plugin set is whatever the runtime
+            // loaded at server start (status === "loaded"). Persisted plugins
+            // come from the resolved config layer. They diverge after a
+            // `set_config({plugins})` until a restart — same posture as
+            // capabilities.
+            const livePlugins = host.pluginRecords
+                .filter((p) => p.status === "loaded")
+                .map((p) => p.manifest.name)
+                .sort();
+            const persistedPlugins = [...resolved.plugins].sort();
+            body = {
+                scope: "resolved",
+                config: { ...resolved, capabilities: live, plugins: livePlugins },
+            };
+            if (live.join(",") !== persisted.join(",")) {
+                body.capabilitiesPendingRestart = {
+                    active: live,
+                    persisted,
+                    note: "`capabilities` was changed via set_config (or env) but is resolved ONCE at server start — the difference takes effect only after a browxai server RESTART. Tool gating enforces `active`.",
+                };
+            }
+            if (livePlugins.join(",") !== persistedPlugins.join(",")) {
+                body.pluginsPendingRestart = {
+                    active: livePlugins,
+                    persisted: persistedPlugins,
+                    note: "`plugins` was changed via set_config but is resolved ONCE at server start — the difference takes effect only after a browxai server RESTART. Plugin tool registration enforces `active`.",
+                };
+            }
+        }
+        else {
+            body = { scope, config: configStore.getLayer(scope) };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+    });
+    register("set_config", {
+        description: "Persist a config patch into the `user` or `project` layer of the browxai-managed config store (`<workspace>/config.json`). This is the ONLY supported way to set persistent config — no env vars, no hand-edited files. Arrays replace; `unstable.*` shallow-merges. Takes effect for sessions opened after this call (the default session re-resolves lazily). Refuses defaults/env/session scopes.",
+        inputSchema: {
+            scope: z.enum(["user", "project"]).describe("Which persistent layer to write."),
+            patch: z
+                .object(CONFIG_PATCH_SCHEMA)
+                .describe("Partial config — only the keys you want to override."),
+        },
+    }, async ({ scope, patch }) => {
+        configStore.setLayer(scope, patch);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ ok: true, scope, written: Object.keys(patch), resolved: configStore.resolve() }, null, 2),
+                },
+            ],
+        };
+    });
+    register("reset_config", {
+        description: "Clear a persistent config layer (`user` or `project`) entirely. The built-in defaults + env layer remain.",
+        inputSchema: { scope: z.enum(["user", "project"]).describe("Persistent layer to clear.") },
+    }, async ({ scope }) => {
+        configStore.resetLayer(scope);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ ok: true, cleared: scope, resolved: configStore.resolve() }, null, 2),
+                },
+            ],
+        };
+    });
+    // ---------- session pre-approvals ----------
+    register("approve_actions", {
+        batchable: true,
+        description: 'session-scoped pre-approval for one or more confirm-required scopes. Lets a non-Claude MCP client run without a human at DevTools to issue page-side `__browx.confirm(true)`. The client calls this once at session start with the scopes to pre-approve (e.g. `["byob_action"]`) and an optional TTL; confirm hooks for those scopes auto-approve within the window. Each grant + consume is logged for audit. Falls back to page-side confirm when no grant covers the scope. Pre-approval is **not** a security boundary — it\'s an unblock for headless flows; tighten by capping `ttlSeconds` per-session.',
+        inputSchema: {
+            scopes: z
+                .array(z.enum(["navigate_off_allowlist", "byob_action", "file_download", "file_upload"]))
+                .min(1)
+                .describe("Confirm scope names to grant. Same vocabulary as BROWX_CONFIRM_REQUIRED."),
+            ttlSeconds: z
+                .number()
+                .int()
+                .positive()
+                .max(24 * 60 * 60)
+                .optional()
+                .describe("Lifetime of the grant in seconds. Default 3600 (1 hour). Hard cap 86400 (24h)."),
+        },
+    }, async ({ scopes, ttlSeconds }) => {
+        const ttl = ttlSeconds ?? 3600;
+        for (const scope of scopes)
+            approvals.grant(scope, ttl);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ok: true,
+                        granted: scopes,
+                        ttlSeconds: ttl,
+                        expiresAt: new Date(Date.now() + ttl * 1000).toISOString(),
+                        note: "Each call into a granted scope is logged. Subsequent approve_actions calls for the same scope reset the TTL.",
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    register("list_approvals", {
+        batchable: true,
+        description: "List live pre-approvals from `approve_actions` — scope, grantedAt, expiresAt, uses, remainingMs. Audit helper.",
+        inputSchema: {},
+    }, async () => ({
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ approvals: approvals.list() }, null, 2),
+            },
+        ],
+    }));
+}

package/dist/tools/deep-coverage-tools.d.ts

@@ -0,0 +1,8 @@
+import type { ToolHost } from "./host.js";
+/**
+ * Deep tools — coverage, layout-thrash, and V8 heap. `coverage_start` /
+ * `coverage_stop`, `layout_thrash_trace`, `memory_diff`, `heap_snapshot`, and
+ * `heap_retainers`. All CDP-deep (refused off Chromium). Registered through the
+ * shared `ToolHost` seam.
+ */
+export declare function registerDeepCoverageTools(host: ToolHost): void;