browxai 0.7.0

package/dist/tools/deep-coverage-tools.js

@@ -0,0 +1,325 @@
+import { requireCdp } from "../engine/index.js";
+import { estimateTokens } from "../util/tokens.js";
+import { runLayoutThrashTrace } from "../page/layout-thrash.js";
+import { diffHeapSnapshots } from "../page/memory-diff.js";
+import { takeHeapSnapshot, defaultHeapSnapshotPath, writeHeapSnapshotFile, readHeapSnapshotFile, queryRetainers, } from "../page/heap.js";
+import { SESSION_ARG } from "./schemas.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 function registerDeepCoverageTools(host) {
+    const { z, register, gateCheck, engineGate, entryFor, workspace } = host;
+    register("coverage_start", {
+        capability: "action",
+        batchable: true,
+        deep: true,
+        description: "Arm precise JS + CSS coverage tracking on this session — wraps CDP `Profiler.startPreciseCoverage` (per-script byte-level use counts) + `CSS.startRuleUsageTracking` (per-stylesheet rule-level use counts) in lockstep. Use to identify dead JS + dead CSS that ships but boot never executes. Pairs with `coverage_stop` (returns the parsed report). Per-session; one lifecycle in flight at a time. **Idempotent restart:** calling `coverage_start` while a tracker is already running cleanly stops the in-flight one (results discarded) and starts fresh. Captures stylesheet metadata (URL + length) via the `CSS.styleSheetAdded` event stream during the tracking window. Capability `action` (mutates target state). The audit tool `perf_audit` calls this internally — only use the direct primitives when you want the raw report or want a longer window than the audit's default.",
+        inputSchema: {
+            ...SESSION_ARG,
+        },
+    }, async ({ session }) => {
+        const g = gateCheck("coverage_start");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("coverage_start", e);
+        if (eg)
+            return eg;
+        try {
+            const r = await e.coverage.start(requireCdp(e.session));
+            const body = {
+                ok: true,
+                running: true,
+                startedAt: r.startedAt,
+                restarted: r.restarted,
+                hint: "Drive your action(s), then call coverage_stop to get the {jsCoverage, cssCoverage} report.",
+            };
+            if (r.restarted) {
+                body.warning =
+                    "A prior coverage_start was still active — it has been cleanly stopped (results discarded) and a fresh tracker started.";
+            }
+            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("coverage_stop", {
+        capability: "read",
+        batchable: true,
+        deep: true,
+        description: "Stop precise JS + CSS coverage tracking and return the parsed report. Calls `Profiler.takePreciseCoverage` + `CSS.stopRuleUsageTracking` then aggregates the raw byte-range output into per-script + per-stylesheet entries. Returns `{ok, jsCoverage:[{url, totalBytes, usedBytes, usagePercent, deadRanges?}], cssCoverage:[{url, totalBytes, usedBytes, usedRules, totalRules, usagePercent, deadRules?}], durationMs}`. `usagePercent` is the agent's scan metric — `<30` indicates substantial dead code (the audit's `unused-code` analyser flags it). `deadRanges` / `deadRules` are top-50 byte ranges per file. **Safe to call any number of times:** if no tracker is running, returns `notRunning:true` rather than an error. Pure parsing + composition past the CDP fetches — no file written; the caller decides whether to persist the report. Capability `read`.",
+        inputSchema: {
+            ...SESSION_ARG,
+        },
+    }, async ({ session }) => {
+        const g = gateCheck("coverage_stop");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("coverage_stop", e);
+        if (eg)
+            return eg;
+        try {
+            const r = await e.coverage.stop(requireCdp(e.session));
+            if (r.notRunning) {
+                const body = {
+                    ok: true,
+                    notRunning: true,
+                    hint: "No coverage was active for this session — coverage_stop is idempotent; call coverage_start first.",
+                };
+                const tokensEstimate = estimateTokens(JSON.stringify(body));
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify({ ...body, tokensEstimate }, null, 2) },
+                    ],
+                };
+            }
+            const body = {
+                ok: true,
+                jsCoverage: r.jsCoverage,
+                cssCoverage: r.cssCoverage,
+                durationMs: r.durationMs,
+            };
+            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("layout_thrash_trace", {
+        capability: "read",
+        batchable: true,
+        deep: true,
+        description: 'Record a focused CDP trace for `durationMs` (default 5000, max 30000) that captures forced synchronous layouts + LayoutShift + Recalc Style events, then aggregate by originating call-stack so the agent sees `"this rAF loop fired 200 forced layouts"` at a glance instead of paging through a 100MB chromium trace. Returns `{ok, forcedLayoutsCount, layoutShiftsCount, eventsByOrigin:[{originatingStack, count, totalDurationMs}], tracePath, durationMs}`. `originatingStack` reads from the trace\'s `stackTrace` field on each event (chromium populates it when DevTools is attached) — `"<anonymous>"` when no stack was attached. `tracePath` is a workspace-rooted JSON file under `<workspace>/perf/<sessionId>-layout-thrash-<ts>.json` — loadable in DevTools\' Performance panel for the full visual. Capped at the top 50 origins, sorted by count desc. Capability `read`.',
+        inputSchema: {
+            durationMs: z
+                .number()
+                .int()
+                .positive()
+                .max(30_000)
+                .optional()
+                .describe("Trace recording window in ms. Default 5000, max 30000."),
+            ...SESSION_ARG,
+        },
+    }, async ({ durationMs, session }) => {
+        const g = gateCheck("layout_thrash_trace");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("layout_thrash_trace", e);
+        if (eg)
+            return eg;
+        try {
+            const r = await runLayoutThrashTrace(requireCdp(e.session), workspace.root, e.id, {
+                durationMs,
+            });
+            const body = {
+                ok: true,
+                forcedLayoutsCount: r.forcedLayoutsCount,
+                layoutShiftsCount: r.layoutShiftsCount,
+                eventsByOrigin: r.eventsByOrigin,
+                tracePath: r.tracePath,
+                durationMs: r.durationMs,
+            };
+            if (e.mode === "attached") {
+                body.warning =
+                    "BYOB / attached Chrome: trace buffer on the human's Chrome has been released. The JSON file remains under $BROWX_WORKSPACE.";
+            }
+            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("memory_diff", {
+        capability: "read",
+        batchable: true,
+        deep: true,
+        description: "Diff two V8 heap snapshots (paths to existing `.heapsnapshot` files from `heap_snapshot`) and report retainer growth per node-type group. Pure function — no browser interaction; no CDP touch; reads + parses two existing JSON-shaped V8 heap snapshots on disk and emits the structured diff. **Inputs:** `beforePath` + `afterPath`, both workspace-rooted (path-escape rejected). **Output:** `{ok, retainerGrowth:[{node, type, sizeBefore, sizeAfter, deltaBytes, deltaPercent}], summary:{totalGrowth, top3Growers}}`. `node` is the V8 `${type}:${name}` display (matches `heap_retainers`'s shape). Groups whose `|deltaBytes| < 1024` are dropped as noise. Sorted by `deltaBytes` desc, capped at 100 rows. Typical leak-detection flow: `heap_snapshot` (before suspect interaction) → drive the action → `heap_snapshot` (after) → `memory_diff({beforePath, afterPath})`. The audit's `leak-suspects` analyser consumes this shape directly. Capability `read`.",
+        inputSchema: {
+            beforePath: z
+                .string()
+                .describe("Workspace-rooted path to a `.heapsnapshot` file (the 'before' snapshot)."),
+            afterPath: z
+                .string()
+                .describe("Workspace-rooted path to a `.heapsnapshot` file (the 'after' snapshot)."),
+            ...SESSION_ARG,
+        },
+    }, async ({ beforePath, afterPath, session: _session }) => {
+        const g = gateCheck("memory_diff");
+        if (g)
+            return g;
+        // Pure file read + parse — no session touch required. SESSION_ARG
+        // honoured for surface consistency with the sibling `perf_insights`.
+        try {
+            const r = diffHeapSnapshots(workspace.root, beforePath, afterPath, "memory_diff");
+            const body = {
+                ok: true,
+                retainerGrowth: r.retainerGrowth,
+                summary: r.summary,
+            };
+            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) },
+                ],
+            };
+        }
+    });
+    // -------- V8 heap snapshots --------
+    register("heap_snapshot", {
+        capability: "action",
+        batchable: true,
+        deep: true,
+        description: "Take a V8 heap snapshot on this session's target — wraps CDP `HeapProfiler.takeHeapSnapshot`. The output file is the same `.heapsnapshot` JSON DevTools' Memory panel and `chrome://inspect` consume on drag-and-drop. Use to diagnose memory leaks: pair with `heap_retainers({snapshotPath, query})` to ask \"who's still pointing to objects named X / typed Y\" — the answer is invisible in `snapshot` / `find` because the leaked nodes are no longer in the DOM. Per-session; one-shot (a heap snapshot is a point-in-time capture, not a recording window). Default file path: `<workspace>/heap-snapshots/<sessionId>-<ts>.heapsnapshot` — explicit `path` is rejected if it escapes `$BROWX_WORKSPACE`. Snapshots are heavy (often tens to hundreds of MiB on a real page); don't take them in a tight loop.",
+        inputSchema: {
+            path: z
+                .string()
+                .optional()
+                .describe("Workspace-rooted output path for the .heapsnapshot file. Default: <workspace>/heap-snapshots/<sessionId>-<ts>.heapsnapshot. Rejected if it escapes $BROWX_WORKSPACE."),
+            ...SESSION_ARG,
+        },
+    }, async ({ path, session }) => {
+        const g = gateCheck("heap_snapshot");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("heap_snapshot", e);
+        if (eg)
+            return eg;
+        try {
+            const snapshotJson = await takeHeapSnapshot(requireCdp(e.session));
+            const targetPath = path ?? defaultHeapSnapshotPath(workspace.root, e.id);
+            const written = writeHeapSnapshotFile(workspace.root, targetPath, snapshotJson, "heap_snapshot");
+            const body = {
+                ok: true,
+                path: written.resolved,
+                bytes: written.bytes,
+                hint: "Call heap_retainers({snapshotPath, query:{name|type}}) to find what's holding suspect objects alive. Drag-and-drop this file onto chrome://inspect's Memory panel for the full interactive view.",
+            };
+            if (e.mode === "attached") {
+                body.warning =
+                    "BYOB / attached Chrome: the snapshot was captured against the human's Chrome. The .heapsnapshot file remains under $BROWX_WORKSPACE.";
+            }
+            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("heap_retainers", {
+        capability: "action",
+        batchable: true,
+        deep: true,
+        description: 'Run a retainer query against a written `.heapsnapshot` file. Returns the top retainers (sorted by retainer self-size desc, capped at 50) of nodes whose display name and/or V8 type matches the query — directly answers "who\'s holding these objects alive?" without paging through DevTools\' Memory panel. Pure file read + in-process parse, no CDP touch. `query.name` defaults to exact match against the node\'s string-table name (use `nameMatch:"substring"` for containment); `query.type` filters by V8 node-type (`"closure"`, `"object"`, `"hidden"`, …). At least one of `name` / `type` is required — a match-everything query is never the right answer. `snapshotPath` is workspace-rooted; rejected if it escapes `$BROWX_WORKSPACE`. Same JSON format `heap_snapshot` writes — bring-your-own snapshot (downloaded from DevTools, saved by a CI run) works too.',
+        inputSchema: {
+            snapshotPath: z
+                .string()
+                .describe("Workspace-rooted path to a .heapsnapshot file (the path returned by heap_snapshot)."),
+            query: z
+                .object({
+                name: z
+                    .string()
+                    .optional()
+                    .describe('Match against the V8 string-table name of a node (e.g. "Cache", "MyLeakyClass").'),
+                type: z
+                    .string()
+                    .optional()
+                    .describe('Match against V8 node-type (e.g. "closure", "object", "hidden").'),
+                nameMatch: z
+                    .enum(["exact", "substring"])
+                    .optional()
+                    .describe('Default "exact". Use "substring" for containment matching against `name`.'),
+            })
+                .describe("At least one of `name` or `type` is required."),
+            ...SESSION_ARG,
+        },
+    }, async ({ snapshotPath, query, session: _session }) => {
+        const g = gateCheck("heap_retainers");
+        if (g)
+            return g;
+        // Pure file read + parse — no session touch needed. We still honour
+        // SESSION_ARG for consistency with the sibling `perf_insights`.
+        try {
+            const { parsed, resolved } = readHeapSnapshotFile(workspace.root, snapshotPath, "heap_retainers");
+            const result = queryRetainers(parsed, query);
+            const body = {
+                ok: true,
+                snapshotPath: resolved,
+                ...result,
+            };
+            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/deep-determinism-tools.d.ts

@@ -0,0 +1,8 @@
+import type { ToolHost } from "./host.js";
+/**
+ * Deep tools — determinism injection & compound network waits. `clock` (virtual
+ * time), `seed_random` (deterministic Math.random), `act_and_wait_for_network`
+ * (one action then a settle-window), and `poll_eval`. Registered through the
+ * shared `ToolHost` seam.
+ */
+export declare function registerDeepDeterminismTools(host: ToolHost): void;

package/dist/tools/deep-determinism-tools.js

@@ -0,0 +1,276 @@
+import { requireCdp } from "../engine/index.js";
+import { withDeadline } from "../util/deadline.js";
+import { estimateTokens } from "../util/tokens.js";
+import { matchesResponse } from "../page/await_network.js";
+import { sanitizeUrl } from "../util/url-sanitizer.js";
+import { SESSION_ARG } from "./schemas.js";
+/** Wrap a JSON body as a tool text response — the shape the determinism handlers
+ *  return. */
+function determinismJson(body) {
+    return { content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+}
+/** A structured `{ok:false, error}` envelope. */
+function determinismJsonError(error) {
+    return determinismJson({ ok: false, error });
+}
+/**
+ * Deep tools — determinism injection & compound network waits. `clock` (virtual
+ * time), `seed_random` (deterministic Math.random), `act_and_wait_for_network`
+ * (one action then a settle-window), and `poll_eval`. Registered through the
+ * shared `ToolHost` seam.
+ */
+export function registerDeepDeterminismTools(host) {
+    const { z, register, gateCheck, engineGate, entryFor, batchAllowedTools: BATCH_ALLOWED_TOOLS, toolHandlers, } = host;
+    register("clock", {
+        capability: "action",
+        batchable: true,
+        deep: true,
+        description: 'Control the page\'s virtual clock via CDP `Emulation.setVirtualTimePolicy` — deterministic testing of date-sensitive flows (renewal dates, "today" filters, scheduling, expiry edges) without changing the OS clock. Three modes: `freeze` pauses virtual time at `atIso` (or wall-clock now if omitted); `advance` jumps the clock by `byMs` or to an absolute `atIso`, then re-pins; `release` resumes real time. Per-session; persists across navigation (re-applied on main-frame nav in case CDP drops it). Independent of `network_emulate` / `cpu_emulate` — compose freely. **BYOB:** the policy stays in effect on the attached Chrome until released, reloaded, or closed; a `warning` field surfaces this in `attached` mode.',
+        inputSchema: {
+            mode: z
+                .enum(["freeze", "advance", "release"])
+                .describe("freeze: pause virtual time at `atIso` (or now). advance: jump by `byMs` or to `atIso`. release: resume real time."),
+            atIso: z
+                .string()
+                .optional()
+                .describe("ISO-8601 instant. freeze → pin time here; advance → jump to this absolute instant. Mutually exclusive with `byMs` on advance."),
+            byMs: z
+                .number()
+                .int()
+                .positive()
+                .max(365 * 24 * 60 * 60 * 1000)
+                .optional()
+                .describe("Advance only — relative jump in ms (max 1 year). Mutually exclusive with `atIso`."),
+            ...SESSION_ARG,
+        },
+    }, async ({ mode, atIso, byMs, session }) => {
+        const g = gateCheck("clock");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("clock", e);
+        if (eg)
+            return eg;
+        try {
+            const { state, mode: appliedMode, appliedAtIso, } = await e.clock.apply(requireCdp(e.session), e.session.page(), { mode, atIso, byMs });
+            const body = {
+                ok: true,
+                applied: {
+                    mode: appliedMode,
+                    nowIso: appliedAtIso,
+                    paused: state?.paused ?? false,
+                },
+            };
+            if (e.mode === "attached") {
+                body.warning =
+                    'BYOB / attached Chrome: this virtual-clock policy stays in effect on the attached browser even after browxai detaches — release it (mode:"release"), reload, or close the page when you\'re done. A page with a frozen wall clock is a debugging trap.';
+            }
+            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("seed_random", {
+        capability: "action",
+        batchable: true,
+        description: "Override the page's `Math.random` with a deterministic Mulberry32 PRNG seeded from `seed`. For flake-repros where unseeded randomness drives id generation, dice / card / A-B picks, or jittered retry timing. Injected via Playwright `addInitScript`, so every new document in the session — including subsequent navigations — bootstraps the same override; the current page's main realm is re-seeded immediately so the effect is visible without navigating. Per-session; persists across navigation (re-applied on main-frame `framenavigated` for symmetry with `network_emulate` / `clock`). **MVP scope:** only `Math.random` is overridden — `crypto.randomUUID` / `crypto.getRandomValues` are NOT touched (web-crypto is a much bigger deterministic-stub surface; revisit later). Workers are out of scope (the init script runs in document realms, not worker realms). **BYOB:** the override is installed on the attached Chrome's context for as long as the context lives; surfaced as a `warning` in `attached` session mode.",
+        inputSchema: {
+            seed: z
+                .number()
+                .int()
+                .min(0)
+                .max(0xffffffff)
+                .describe("Non-negative integer in [0, 2^32 - 1]. The Mulberry32 state domain — 0 is valid."),
+            ...SESSION_ARG,
+        },
+    }, async ({ seed, session }) => {
+        const g = gateCheck("seed_random");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        try {
+            const { state } = await e.seededRandom.apply(e.session.page().context(), e.session.page(), {
+                seed,
+            });
+            const body = { ok: true, applied: state };
+            if (e.mode === "attached") {
+                body.warning =
+                    "BYOB / attached Chrome: this Math.random override is installed on the attached browser's context and stays in effect for as long as the context lives — close the tab / context when you're done to drop it.";
+            }
+            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("act_and_wait_for_network", {
+        capability: "read",
+        description: "Run ONE action and wait for a specific network response to complete — async SPAs fire follow-up requests after the action-result window, so `ActionResult.network` misses them. The waiter is armed BEFORE the action dispatches (no race). `action` is `{tool,args}` from the batch whitelist. `match` selects the response: `urlPattern` (case-insensitive substring), `method`, `status` — at least one required. Returns `{ action: <inner result>, network: { matched, method?, url?, status? } }` (url redacted, same as `network_read`). `timeoutMs` is the max wait (default 10000).",
+        inputSchema: {
+            action: z.object({
+                tool: z.string().describe("Inner tool name (batch whitelist)."),
+                args: z.record(z.unknown()).optional(),
+            }),
+            match: z
+                .object({
+                urlPattern: z
+                    .string()
+                    .optional()
+                    .describe("Case-insensitive substring of the request URL."),
+                method: z.string().optional(),
+                status: z.number().int().optional(),
+            })
+                .describe("At least one field required."),
+            timeoutMs: z
+                .number()
+                .int()
+                .positive()
+                .max(120_000)
+                .optional()
+                .describe("Max wait for the matching response (default 10000)."),
+            ...SESSION_ARG,
+        },
+    }, async (args) => {
+        const g = gateCheck("act_and_wait_for_network");
+        if (g)
+            return g;
+        const innerTool = args.action.tool;
+        if (!BATCH_ALLOWED_TOOLS.has(innerTool) || innerTool === "act_and_wait_for_network") {
+            return determinismJsonError(`act_and_wait_for_network: inner tool "${innerTool}" not allowed (batch whitelist; no batch / await_human / recording / self)`);
+        }
+        const ig = gateCheck(innerTool);
+        if (ig)
+            return ig;
+        if (args.match.urlPattern === undefined &&
+            args.match.method === undefined &&
+            args.match.status === undefined) {
+            return determinismJsonError("act_and_wait_for_network: `match` needs at least one of urlPattern / method / status");
+        }
+        const e = await entryFor(args.session);
+        const timeout = args.timeoutMs ?? 10_000;
+        const parseInner = (resp) => {
+            const first = resp.content[0];
+            if (!first || first.type !== "text" || first.text === undefined)
+                return first ?? null;
+            try {
+                return JSON.parse(first.text);
+            }
+            catch {
+                return first.text;
+            }
+        };
+        // arm the waiter BEFORE dispatching the action so a fast response can't slip past.
+        const waitP = e.session
+            .page()
+            .waitForResponse((r) => matchesResponse({ url: r.url(), method: r.request().method(), status: r.status() }, args.match), { timeout })
+            .then((r) => ({
+            matched: true,
+            method: r.request().method(),
+            url: sanitizeUrl(r.url()),
+            status: r.status(),
+        }), () => ({ matched: false }));
+        const innerArgs = { ...(args.action.args ?? {}), session: args.session };
+        const [aRes, network] = await Promise.all([toolHandlers[innerTool](innerArgs), waitP]);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ action: parseInner(aRes), network }, null, 2),
+                },
+            ],
+        };
+    });
+    register("poll_eval", {
+        capability: "eval",
+        description: "Repeatedly evaluate a JS expression in the page until it returns a truthy value or `timeoutMs` elapses — for waiting on async job completion / store updates without ad-hoc in-page loops (a long in-page promise would trip the anti-wedge deadline). The value is page-controlled — treat it as untrusted, like `eval_js`. Capability: `eval`. Returns `{ ok, truthy, value, polls, elapsedMs, timedOut }`.",
+        inputSchema: {
+            expr: z
+                .string()
+                .describe("JS expression; must be JSON-serializable. Wrap statements in `(() => { … })()`."),
+            intervalMs: z
+                .number()
+                .int()
+                .min(50)
+                .max(10_000)
+                .optional()
+                .describe("Poll interval (default 250, min 50)."),
+            timeoutMs: z
+                .number()
+                .int()
+                .positive()
+                .max(120_000)
+                .optional()
+                .describe("Total budget (default 5000)."),
+            ...SESSION_ARG,
+        },
+    }, async ({ expr, intervalMs, timeoutMs, session }) => {
+        const g = gateCheck("poll_eval");
+        if (g)
+            return g;
+        const s = (await entryFor(session)).session;
+        const interval = intervalMs ?? 250;
+        const budget = timeoutMs ?? 5000;
+        const perPoll = Math.min(budget, 5000);
+        const start = Date.now();
+        let polls = 0;
+        let value;
+        while (Date.now() - start < budget) {
+            polls++;
+            try {
+                value = await withDeadline(s.page().evaluate(expr), perPoll, "poll_eval");
+            }
+            catch (err) {
+                return determinismJson({
+                    ok: false,
+                    error: err instanceof Error ? err.message : String(err),
+                    polls,
+                    elapsedMs: Date.now() - start,
+                });
+            }
+            if (value) {
+                return determinismJson({
+                    ok: true,
+                    truthy: true,
+                    value,
+                    polls,
+                    elapsedMs: Date.now() - start,
+                    timedOut: false,
+                });
+            }
+            if (Date.now() - start + interval >= budget)
+                break;
+            await new Promise((r) => setTimeout(r, interval));
+        }
+        return determinismJson({
+            ok: true,
+            truthy: false,
+            value,
+            polls,
+            elapsedMs: Date.now() - start,
+            timedOut: true,
+        });
+    });
+}

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

@@ -0,0 +1,19 @@
+import type { ToolHost } from "./host.js";
+/**
+ * Deep-diagnostics tools — the heavyweight observation surface an agent reaches
+ * for when a flow is slow, leaky, or non-deterministic: performance tracing
+ * (perf_start / perf_stop / perf_insights), the orchestrated perf_audit, JS+CSS
+ * coverage, layout-thrash tracing, V8 heap snapshots + retainer / memory-diff
+ * queries, the virtual clock + seeded RNG determinism knobs, and the
+ * network-aware act_and_wait_for_network / poll_eval waiters. Every block is
+ * registered through the shared `ToolHost` seam; the host owns the closures
+ * (gate, engine-gate, session, workspace, batch dispatch), this module owns the
+ * registrations.
+ */
+/**
+ * Deep tools — performance tracing & audit. `perf_start` / `perf_stop` (Chromium
+ * trace capture), `perf_insights` (post-hoc trace analysis), and `perf_audit`
+ * (the category-driven optimisation pass). All CDP-deep (refused off Chromium).
+ * Registered through the shared `ToolHost` seam.
+ */
+export declare function registerDeepPerfTools(host: ToolHost): void;