browxai 0.7.0

package/dist/tools/gesture-emulation-tools.js

@@ -0,0 +1,135 @@
+import { estimateTokens } from "../util/tokens.js";
+import { requireCdp } from "../engine/session-cdp.js";
+import { SESSION_ARG } from "./schemas.js";
+/**
+ * Live network/CPU emulation tools: network_emulate / cpu_emulate — CDP-deep
+ * throttle/offline + CPU slowdown for low-end-device repros. Split out of
+ * `gesture-network-tools` by cohesive family (RFC 0004 P3 / D3 SRP); registered
+ * through the shared `ToolHost` seam in the same source order.
+ */
+export function registerGestureEmulationTools(host) {
+    const { z, register, gateCheck, engineGate, entryFor } = host;
+    register("network_emulate", {
+        capability: "action",
+        batchable: true,
+        deep: true,
+        description: "Throttle the session's network conditions (or simulate offline) via CDP `Network.emulateNetworkConditions`. For flaky-mobile / offline / slow-link repros on a real backend; **composes** with `route_queue` — each route's `delayMs` stacks ON TOP of the emulated `latencyMs`. Per-session; persists across navigation (re-applied on main-frame nav in case CDP drops it on a renderer swap). Empty input (or `{offline:false}` with no other fields) resets to no throttle. **BYOB:** the override applies to the attached Chrome and stays in effect even after browxai detaches, until the human resets DevTools or closes the page (a `warning` field surfaces this).",
+        inputSchema: {
+            offline: z
+                .boolean()
+                .optional()
+                .describe("If true, all network traffic from the page fails as offline. Wins over latency / bps."),
+            latencyMs: z
+                .number()
+                .int()
+                .nonnegative()
+                .max(600_000)
+                .optional()
+                .describe("One-way latency in ms. CDP doubles it for round-trip; route_queue delayMs stacks on top."),
+            downloadBps: z
+                .number()
+                .nonnegative()
+                .max(10_000_000_000)
+                .optional()
+                .describe("Max download throughput, bytes/sec. 0 / unset = unthrottled."),
+            uploadBps: z
+                .number()
+                .nonnegative()
+                .max(10_000_000_000)
+                .optional()
+                .describe("Max upload throughput, bytes/sec. 0 / unset = unthrottled."),
+            packetLoss: z
+                .number()
+                .min(0)
+                .max(1)
+                .optional()
+                .describe("Hint, 0..1. Most Chromium builds ignore it; pass for documentation."),
+            ...SESSION_ARG,
+        },
+    }, async ({ offline, latencyMs, downloadBps, uploadBps, packetLoss, session }) => {
+        const g = gateCheck("network_emulate");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("network_emulate", e);
+        if (eg)
+            return eg;
+        try {
+            const { state, reset } = await e.emulation.applyNetwork(requireCdp(e.session), e.session.page(), {
+                offline,
+                latencyMs,
+                downloadBps,
+                uploadBps,
+                packetLoss,
+            });
+            const body = { ok: true, applied: state, reset };
+            if (e.mode === "attached") {
+                body.warning =
+                    "BYOB / attached Chrome: this network override stays in effect on the attached browser even after browxai detaches — reset it (call again with empty args) or close the page when you're done.";
+            }
+            const tokensEstimate = estimateTokens(JSON.stringify(body));
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ ...body, tokensEstimate }, null, 2) },
+                ],
+            };
+        }
+        catch (err) {
+            const body = { ok: false, error: err instanceof Error ? err.message : String(err) };
+            const tokensEstimate = estimateTokens(JSON.stringify(body));
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ ...body, tokensEstimate }, null, 2) },
+                ],
+            };
+        }
+    });
+    register("cpu_emulate", {
+        capability: "action",
+        batchable: true,
+        deep: true,
+        description: "Slow the renderer to simulate a low-end device via CDP `Emulation.setCPUThrottlingRate`. `throttleRate: 1` = no throttle (and is the reset path); `2` = 2× slowdown; `4`–`6` = mid-to-low-end mobile. Per-session; persists across navigation (re-applied on main-frame nav in case CDP drops it). Empty input resets to `1`. Independent of `network_emulate` — apply both for a full low-end-device repro. **BYOB:** the throttle stays in effect on the attached Chrome until reset or page close (`warning` surfaces this).",
+        inputSchema: {
+            throttleRate: z
+                .number()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe("CPU slowdown multiplier. 1 = none (reset). 2 = 2×. 4–6 = low-end mobile."),
+            ...SESSION_ARG,
+        },
+    }, async ({ throttleRate, session }) => {
+        const g = gateCheck("cpu_emulate");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("cpu_emulate", e);
+        if (eg)
+            return eg;
+        try {
+            const { state, reset } = await e.emulation.applyCpu(requireCdp(e.session), e.session.page(), {
+                throttleRate,
+            });
+            const body = { ok: true, applied: state, reset };
+            if (e.mode === "attached") {
+                body.warning =
+                    "BYOB / attached Chrome: this CPU throttle stays in effect on the attached browser even after browxai detaches — reset it (call again with no args / throttleRate:1) or close the page when you're done.";
+            }
+            const tokensEstimate = estimateTokens(JSON.stringify(body));
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ ...body, tokensEstimate }, null, 2) },
+                ],
+            };
+        }
+        catch (err) {
+            const body = { ok: false, error: err instanceof Error ? err.message : String(err) };
+            const tokensEstimate = estimateTokens(JSON.stringify(body));
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ ...body, tokensEstimate }, null, 2) },
+                ],
+            };
+        }
+    });
+}

package/dist/tools/gesture-network-tools.d.ts

@@ -0,0 +1,17 @@
+import type { ToolHost } from "./host.js";
+/**
+ * Coordinate-space gestures (mouse_wheel / gesture_pinch / gesture_swipe),
+ * route mocking (route / route_queue / unroute), interactive WebSocket
+ * primitives (ws_send / ws_intercept / ws_unintercept), worker visibility
+ * (workers_list / worker_message_send / worker_messages_read /
+ * sw_intercept_fetch / sw_unintercept_fetch), and live network/CPU emulation
+ * (network_emulate / cpu_emulate).
+ *
+ * RFC 0004 P3 / D3 (SRP): the registrations were split by cohesive family into
+ * five sibling modules (coord / route / websocket / worker / emulation). This
+ * module stays the single entry point `server.ts` + `tool-metadata.ts` call, and
+ * invokes each family in the EXACT prior source order so the registered-name set
+ * + the derived maps stay byte-identical. The host owns the closures (gate,
+ * engine-gate, entry); the family modules own the registrations.
+ */
+export declare function registerGestureNetworkTools(host: ToolHost): void;

package/dist/tools/gesture-network-tools.js

@@ -0,0 +1,27 @@
+import { registerGestureCoordTools } from "./gesture-coord-tools.js";
+import { registerGestureRouteTools } from "./gesture-route-tools.js";
+import { registerGestureWebsocketTools } from "./gesture-websocket-tools.js";
+import { registerGestureWorkerTools } from "./gesture-worker-tools.js";
+import { registerGestureEmulationTools } from "./gesture-emulation-tools.js";
+/**
+ * Coordinate-space gestures (mouse_wheel / gesture_pinch / gesture_swipe),
+ * route mocking (route / route_queue / unroute), interactive WebSocket
+ * primitives (ws_send / ws_intercept / ws_unintercept), worker visibility
+ * (workers_list / worker_message_send / worker_messages_read /
+ * sw_intercept_fetch / sw_unintercept_fetch), and live network/CPU emulation
+ * (network_emulate / cpu_emulate).
+ *
+ * RFC 0004 P3 / D3 (SRP): the registrations were split by cohesive family into
+ * five sibling modules (coord / route / websocket / worker / emulation). This
+ * module stays the single entry point `server.ts` + `tool-metadata.ts` call, and
+ * invokes each family in the EXACT prior source order so the registered-name set
+ * + the derived maps stay byte-identical. The host owns the closures (gate,
+ * engine-gate, entry); the family modules own the registrations.
+ */
+export function registerGestureNetworkTools(host) {
+    registerGestureCoordTools(host);
+    registerGestureRouteTools(host);
+    registerGestureWebsocketTools(host);
+    registerGestureWorkerTools(host);
+    registerGestureEmulationTools(host);
+}

package/dist/tools/gesture-route-tools.d.ts

@@ -0,0 +1,8 @@
+import type { RegisterHost, GateHost, SessionHost, ServerServicesHost } from "./host.js";
+/**
+ * Request route-mocking tools: route / route_queue / unroute. Per-session canned
+ * responses for backend substitution + out-of-order arrival QA. Split out of
+ * `gesture-network-tools` by cohesive family (RFC 0004 P3 / D3 SRP); registered
+ * through the shared `ToolHost` seam in the same source order.
+ */
+export declare function registerGestureRouteTools(host: RegisterHost & GateHost & SessionHost & ServerServicesHost): void;

package/dist/tools/gesture-route-tools.js

@@ -0,0 +1,142 @@
+import { SESSION_ARG } from "./schemas.js";
+/**
+ * Request route-mocking tools: route / route_queue / unroute. Per-session canned
+ * responses for backend substitution + out-of-order arrival QA. Split out of
+ * `gesture-network-tools` by cohesive family (RFC 0004 P3 / D3 SRP); registered
+ * through the shared `ToolHost` seam in the same source order.
+ */
+export function registerGestureRouteTools(host) {
+    const { z, register, gateCheck, entryFor } = host;
+    const ROUTE_RESPONSE = {
+        status: z.number().int().optional().describe("HTTP status (default 200)."),
+        body: z.string().optional().describe("Response body (default empty)."),
+        contentType: z.string().optional().describe("Content-Type (default application/json)."),
+        delayMs: z
+            .number()
+            .int()
+            .nonnegative()
+            .max(60_000)
+            .optional()
+            .describe("Delay before fulfilling (ms). Use to control arrival order."),
+    };
+    register("route", {
+        capability: "action",
+        description: "Intercept requests matching `urlPattern` (Playwright glob) and fulfil every match with one canned response. For substituting a backend response in QA. Per-session; discarded with the session or via `unroute`.",
+        inputSchema: {
+            urlPattern: z.string().describe("Playwright URL glob, e.g. `**/api/records*`."),
+            method: z
+                .string()
+                .optional()
+                .describe("Restrict to this HTTP method; other methods fall through to the real network."),
+            ...ROUTE_RESPONSE,
+            ...SESSION_ARG,
+        },
+    }, async ({ urlPattern, method, status, body, contentType, delayMs, session }) => {
+        const g = gateCheck("route");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        try {
+            const r = await e.routes.add(e.session.page(), {
+                urlPattern,
+                method,
+                status,
+                body,
+                contentType,
+                delayMs,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: true, ...r, active: e.routes.list() }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) }, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+    register("route_queue", {
+        capability: "action",
+        description: "Intercept `urlPattern` and fulfil *successive* matches from `responses[]` (one per request, in order); once exhausted, matches fall through to the real network. Each response carries its own `delayMs` — give response #1 a long delay and #2 a short one to make backend responses **arrive out of request order** (the race-condition QA case). Per-session.",
+        inputSchema: {
+            urlPattern: z.string().describe("Playwright URL glob."),
+            method: z.string().optional(),
+            responses: z
+                .array(z.object(ROUTE_RESPONSE))
+                .min(1)
+                .describe("Consumed one per matching request, in order."),
+            ...SESSION_ARG,
+        },
+    }, async ({ urlPattern, method, responses, session }) => {
+        const g = gateCheck("route_queue");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        try {
+            const r = await e.routes.addQueue(e.session.page(), { urlPattern, method, responses });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: true, ...r, active: e.routes.list() }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) }, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+    register("unroute", {
+        capability: "action",
+        description: "Remove a route registered by `route`/`route_queue` (by `urlPattern`[+`method`]), or — with no `urlPattern` — every route this session registered.",
+        inputSchema: {
+            urlPattern: z.string().optional().describe("Omit to clear ALL of this session's routes."),
+            method: z.string().optional(),
+            ...SESSION_ARG,
+        },
+    }, async ({ urlPattern, method, session }) => {
+        const g = gateCheck("unroute");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        try {
+            const removed = await e.routes.remove(e.session.page(), { urlPattern, method });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: true, removed, active: e.routes.list() }, 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/gesture-websocket-tools.d.ts

@@ -0,0 +1,8 @@
+import type { RegisterHost, GateHost, SessionHost, ServerServicesHost } from "./host.js";
+/**
+ * Interactive WebSocket primitives: ws_send / ws_intercept / ws_unintercept — the
+ * mutation half of the WS surface (the read-only view is `ws_read`). Split out of
+ * `gesture-network-tools` by cohesive family (RFC 0004 P3 / D3 SRP); registered
+ * through the shared `ToolHost` seam in the same source order.
+ */
+export declare function registerGestureWebsocketTools(host: RegisterHost & GateHost & SessionHost & ServerServicesHost): void;

package/dist/tools/gesture-websocket-tools.js

@@ -0,0 +1,122 @@
+import { estimateTokens } from "../util/tokens.js";
+import { SESSION_ARG } from "./schemas.js";
+/**
+ * Interactive WebSocket primitives: ws_send / ws_intercept / ws_unintercept — the
+ * mutation half of the WS surface (the read-only view is `ws_read`). Split out of
+ * `gesture-network-tools` by cohesive family (RFC 0004 P3 / D3 SRP); registered
+ * through the shared `ToolHost` seam in the same source order.
+ */
+export function registerGestureWebsocketTools(host) {
+    const { z, register, gateCheck, entryFor } = host;
+    // ---- Interactive WebSocket primitives (capability `action`) ----------------
+    // The read-only WS view is `ws_read` / `ActionResult.network.wsFrames`; this
+    // family is the mutation half — `ws_send` pushes a frame on a live page-side
+    // socket, `ws_intercept` rewrites/drops inbound frames before app handlers
+    // see them. Both engage by lazily installing a page-side `WebSocket` wrapper
+    // on first call (`addInitScript` for future docs + `evaluate` for the live
+    // doc). Active interceptors mirror onto a per-session registry; `unintercept`
+    // can target one pattern or clear them all. See src/page/ws-interactive.ts.
+    register("ws_send", {
+        capability: "action",
+        description: "Send a payload on a live page-side WebSocket. `wsId` is the id surfaced by the page-side `__browxWs.list()` registry (the wrapper assigns `ws-1`, `ws-2`, … as the page opens sockets) — call `ws_read` first to identify the endpoint URL, then `eval_js` `JSON.stringify(window.__browxWs.list())` to map URL → wsId, OR drive a deterministic test where the order of socket creation is known. Calls the real (unwrapped) `WebSocket.prototype.send`, so app-level message listeners do NOT observe a fake event — only the server sees the outbound frame. Returns `{ok:true, wsId, url, bytes}` on success, or `{ok:false, error}` if the id is unknown or the socket isn't OPEN. Capability: `action`.",
+        inputSchema: {
+            wsId: z.string().describe("Page-side socket id, e.g. `ws-1`. See `__browxWs.list()`."),
+            message: z
+                .string()
+                .describe("Payload to send. Binary frames are not supported in MVP — send as text."),
+            ...SESSION_ARG,
+        },
+    }, async ({ wsId, message, session }) => {
+        const g = gateCheck("ws_send");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        try {
+            const r = await e.wsInteractive.send(e.session.page(), { wsId, message });
+            const body = { ...r, tokensEstimate: 0 };
+            body.tokensEstimate = estimateTokens(JSON.stringify(body));
+            return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+        }
+        catch (err) {
+            const body = {
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+                tokensEstimate: 0,
+            };
+            body.tokensEstimate = estimateTokens(JSON.stringify(body));
+            return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+        }
+    });
+    register("ws_intercept", {
+        capability: "action",
+        description: 'Install a route-style interceptor for INBOUND WebSocket frames. `pattern` is a glob matched against `socket.url` (the route family\'s intent: `*` = single segment, `**` = any). `response` controls what the page sees: `"drop"` — silently discard the frame (app handlers don\'t run); `"echo"` — mirror the inbound payload back to the server (the app still receives it locally); `{data:"<string>"}` — replace the inbound payload with `data` (app handlers see the replacement). The interceptor evaluates on every matching frame until removed via `ws_unintercept`; re-adding the same pattern replaces the prior entry. Per-session; lost on session close or session rebuild. Capability: `action`.',
+        inputSchema: {
+            pattern: z
+                .string()
+                .describe("Glob matched against `socket.url`, e.g. `wss://chat.example/**`."),
+            response: z
+                .union([
+                z.literal("drop"),
+                z.literal("echo"),
+                z.object({
+                    data: z
+                        .string()
+                        .describe("Replacement payload delivered to app handlers in place of the original."),
+                }),
+            ])
+                .describe('`drop`, `echo`, or `{data: "…"}`.'),
+            ...SESSION_ARG,
+        },
+    }, async ({ pattern, response, session }) => {
+        const g = gateCheck("ws_intercept");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        try {
+            const r = await e.wsInteractive.addInterceptor(e.session.page(), { pattern, response });
+            const body = { ok: true, ...r, tokensEstimate: 0 };
+            body.tokensEstimate = estimateTokens(JSON.stringify(body));
+            return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+        }
+        catch (err) {
+            const body = {
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+                tokensEstimate: 0,
+            };
+            body.tokensEstimate = estimateTokens(JSON.stringify(body));
+            return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+        }
+    });
+    register("ws_unintercept", {
+        capability: "action",
+        description: "Remove a `ws_intercept` interceptor (by exact `pattern`), or — with no `pattern` — every interceptor this session installed. Capability: `action`.",
+        inputSchema: {
+            pattern: z
+                .string()
+                .optional()
+                .describe("Omit to clear ALL of this session's WS interceptors."),
+            ...SESSION_ARG,
+        },
+    }, async ({ pattern, session }) => {
+        const g = gateCheck("ws_unintercept");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        try {
+            const r = await e.wsInteractive.removeInterceptor(e.session.page(), pattern !== undefined ? { pattern } : {});
+            const body = { ok: true, ...r, tokensEstimate: 0 };
+            body.tokensEstimate = estimateTokens(JSON.stringify(body));
+            return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+        }
+        catch (err) {
+            const body = {
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+                tokensEstimate: 0,
+            };
+            body.tokensEstimate = estimateTokens(JSON.stringify(body));
+            return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+        }
+    });
+}

package/dist/tools/gesture-worker-tools.d.ts

@@ -0,0 +1,9 @@
+import type { RegisterHost, GateHost, SessionHost, ActionHost, ServerServicesHost } from "./host.js";
+/**
+ * Worker-visibility tools: workers_list / worker_message_send /
+ * worker_messages_read / sw_intercept_fetch / sw_unintercept_fetch — make Web +
+ * Service Workers (otherwise off-grid) observable and drivable. Split out of
+ * `gesture-network-tools` by cohesive family (RFC 0004 P3 / D3 SRP); registered
+ * through the shared `ToolHost` seam in the same source order.
+ */
+export declare function registerGestureWorkerTools(host: RegisterHost & GateHost & SessionHost & ActionHost & ServerServicesHost): void;