browxai 0.7.0

package/dist/tools/forms-plan-tools.d.ts

@@ -0,0 +1,7 @@
+import type { RegisterHost, GateHost, SessionHost, ActionHost, EgressHost, ConfigHost, ServerServicesHost } from "./host.js";
+/**
+ * Plan / execute tools: separate intent capture (`plan`) from dispatch
+ * (`execute`). Split out of `forms-recording-tools` (RFC 0004 P3 / D3 SRP);
+ * registered through the shared `ToolHost` seam in the same source order.
+ */
+export declare function registerFormsPlanTools(host: RegisterHost & GateHost & SessionHost & ActionHost & EgressHost & ConfigHost & ServerServicesHost): void;

package/dist/tools/forms-plan-tools.js

@@ -0,0 +1,159 @@
+import { withDeadline } from "../util/deadline.js";
+import { plan as planAction, execute as executeAction, PLAN_VERBS } from "../page/plan.js";
+import { ACTION_OPTS, SESSION_ARG } from "./schemas.js";
+import { confirmByobAction } from "../policy/confirm.js";
+/**
+ * Plan / execute tools: separate intent capture (`plan`) from dispatch
+ * (`execute`). Split out of `forms-recording-tools` (RFC 0004 P3 / D3 SRP);
+ * registered through the shared `ToolHost` seam in the same source order.
+ */
+export function registerFormsPlanTools(host) {
+    const { z, register, gateCheck, entryFor, confirmCtxFor, denyContent, actionTimeout, ctxFor, hintFromTarget, egressFor, config, caps, cfgActionTimeout, } = host;
+    // ---------- plan / execute (separate intent capture from dispatch) ----------
+    register("plan", {
+        capability: "read",
+        batchable: true,
+        description: "Resolve a natural-language `query` for a single element + a target action `verb` into a serialisable `ActionDescriptor` — no dispatch happens. The descriptor binds the picked ref (same `eN` namespace as snapshot/find/name_ref — NOT a parallel id system), the verb's args, evidence (selectorHint, stability, score, top alternatives + any low-confidence warnings), and an `expiresAt` deadline. Hand it back verbatim to `execute` to dispatch; cache it for replay / self-healing; or inspect `evidence` and refuse to dispatch when the stability is too low. NOT a mock dispatch — the value is captured intent, not suppressed effects.",
+        inputSchema: {
+            query: z
+                .string()
+                .describe("Natural-language description of the element to act on, e.g. 'the Save button'."),
+            verb: z.enum(PLAN_VERBS).describe(`Action verb to bind: ${PLAN_VERBS.join(" / ")}.`),
+            verbArgs: z
+                .object({
+                value: z.string().optional().describe("`fill` value."),
+                values: z.array(z.string()).optional().describe("`select` option labels/values."),
+                key: z.string().optional().describe("`press` key (Playwright key syntax)."),
+                button: z
+                    .enum(["left", "right", "middle"])
+                    .optional()
+                    .describe("`click` mouse button (default left)."),
+            })
+                .optional()
+                .describe("Verb-specific args. Required: `value` for fill, `key` for press, `values` for select. click/hover take none."),
+            contextRef: z
+                .string()
+                .optional()
+                .describe("Limit ranking to descendants of this ref (same semantics as find())."),
+            confidenceFloor: z
+                .number()
+                .nonnegative()
+                .optional()
+                .describe("Returns ok:false when no candidate scored above this floor."),
+            ttlMs: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Descriptor lifetime in ms (default 60000; clamped to [1000, 1800000])."),
+            ...SESSION_ARG,
+        },
+    }, async (args) => {
+        const g = gateCheck("plan");
+        if (g)
+            return g;
+        const e = await entryFor(args.session);
+        let outcome;
+        try {
+            outcome = await withDeadline(planAction(e.session.page(), e.snapshotSubstrate, e.refs, {
+                query: args.query,
+                verb: args.verb,
+                verbArgs: args.verbArgs,
+                contextRef: args.contextRef,
+                confidenceFloor: args.confidenceFloor,
+                ttlMs: args.ttlMs,
+                testAttributes: config.testAttributes,
+                fallbackHints: {
+                    coords: caps.enabled.has("action"),
+                    evalJs: caps.enabled.has("eval"),
+                },
+            }, e.session.cdp ? e.session.cdp() : undefined), cfgActionTimeout(), "plan");
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) }, null, 2),
+                    },
+                ],
+            };
+        }
+        // Egress sink — `plan().evidence` mirrors `find().evidence` (selectorHint
+        // / role / name) which IS masked. Match the find-handler's pattern so
+        // a planned descriptor's evidence doesn't leak a registered real-value
+        // that find() would have masked. Routes through the injected chokepoint
+        // (RFC 0004 P3 / D4): `egressFor(e).maskDeep(outcome)` is byte-identical
+        // to `caps.enabled.has("secrets") ? e.secrets.applyMaskDeep(outcome) : outcome`.
+        const maskedPlan = egressFor(e).maskDeep(outcome);
+        return { content: [{ type: "text", text: JSON.stringify(maskedPlan, null, 2) }] };
+    });
+    register("execute", {
+        capability: "action",
+        batchable: true,
+        description: 'Dispatch a previously-planned `ActionDescriptor` (from `plan`). Re-resolves the bound ref via the same stable-key scheme snapshot/find use; refuses with structured `reason:"expired"` past `expiresAt`, or `reason:"ref-gone"` when the ref is no longer in the session\'s registry — in both cases NO action runs, re-plan against the current snapshot. The underlying action verb\'s capability is enforced (a descriptor with verb:"click" still requires the `action` capability); a successful dispatch returns the same `ActionResult` shape as calling the verb\'s tool directly.',
+        inputSchema: {
+            descriptor: z
+                .object({
+                id: z.string(),
+                ref: z.string(),
+                verb: z.enum(PLAN_VERBS),
+                args: z.record(z.unknown()).optional(),
+                evidence: z.record(z.unknown()).optional(),
+                expiresAt: z.number(),
+            })
+                .passthrough()
+                .describe("The `ActionDescriptor` returned by `plan` — pass it back verbatim."),
+            ...ACTION_OPTS,
+        },
+    }, async (args) => {
+        const g = gateCheck("execute");
+        if (g)
+            return g;
+        // Surface the *underlying* verb's capability — a descriptor with
+        // verb:"click" denied for `action` should report `click` denied, not
+        // a generic "execute denied". The verb is parsed off the descriptor
+        // before the gate to keep the error attribution clean.
+        const verb = args.descriptor.verb;
+        if (verb) {
+            const vg = gateCheck(verb);
+            if (vg)
+                return vg;
+        }
+        const e = await entryFor(args.session);
+        // The descriptor's verb is also subject to the same confirm-hook
+        // policy as a direct call to that verb — a `byob_action` policy that
+        // blocks `click` also blocks an `execute` of a click descriptor.
+        if (verb) {
+            const c = await confirmByobAction(verb, confirmCtxFor(e));
+            if (!c.ok)
+                return denyContent(`execute(${verb})`, c);
+        }
+        const td = actionTimeout(args);
+        // Compute the recordingHint off the descriptor's bound ref (same
+        // shape `click` / `fill` build it).
+        const ref = args.descriptor.ref;
+        const recordingHint = ref ? hintFromTarget(e, { ref }) : undefined;
+        let outcome;
+        try {
+            outcome = await executeAction(ctxFor(e), args.descriptor, {
+                mode: args.mode,
+                maxResultTokens: args.maxResultTokens,
+                deadlineMs: td.ms,
+                deadlineWarning: td.warning,
+                recordingHint,
+            });
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, error: err instanceof Error ? err.message : String(err) }, null, 2),
+                    },
+                ],
+            };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(outcome, null, 2) }] };
+    });
+}

package/dist/tools/forms-recording-mode-tools.d.ts

@@ -0,0 +1,8 @@
+import type { RegisterHost, GateHost, SessionHost, ServerServicesHost } from "./host.js";
+/**
+ * Recording-mode tools: `start_recording` / `end_recording` / `record_annotate`.
+ * Capture subsequent action tool calls as a draft flow-file. Split out of
+ * `forms-recording-tools` (RFC 0004 P3 / D3 SRP); registered through the shared
+ * `ToolHost` seam in the same source order.
+ */
+export declare function registerFormsRecordingModeTools(host: RegisterHost & GateHost & SessionHost & ServerServicesHost): void;

package/dist/tools/forms-recording-mode-tools.js

@@ -0,0 +1,71 @@
+import { SESSION_ARG } from "./schemas.js";
+/**
+ * Recording-mode tools: `start_recording` / `end_recording` / `record_annotate`.
+ * Capture subsequent action tool calls as a draft flow-file. Split out of
+ * `forms-recording-tools` (RFC 0004 P3 / D3 SRP); registered through the shared
+ * `ToolHost` seam in the same source order.
+ */
+export function registerFormsRecordingModeTools(host) {
+    const { z, register, gateCheck, entryFor } = host;
+    // ---------- recording mode () ----------
+    register("start_recording", {
+        capability: "human",
+        description: "Begin recording subsequent action tool calls as a draft flow-file. Every successful navigate/click/fill/press/hover/select/wait_for adds a step (with the resolved selectorHint when a target was given). Call `end_recording` to emit a YAML draft. `record_annotate` attaches annotations to the most-recent step. Calibration-walk → flow-file scaffolding.",
+        inputSchema: {
+            flowName: z.string().describe('Name of the flow being recorded, e.g. "login-and-search"'),
+            ...SESSION_ARG,
+        },
+    }, async ({ flowName, session }) => {
+        const g = gateCheck("start_recording");
+        if (g)
+            return g;
+        const r = (await entryFor(session)).recorder.start(flowName);
+        return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+    });
+    register("end_recording", {
+        capability: "human",
+        description: "Stop the current recording and emit the draft flow-file YAML. Returns `{ name, yaml, stepCount }`. Review the locators block (entries flagged `stability: medium|low` deserve a second look) and add prerequisites/assertions before committing the flow into a site-docs workspace.",
+        inputSchema: { ...SESSION_ARG },
+    }, async ({ session }) => {
+        const g = gateCheck("end_recording");
+        if (g)
+            return g;
+        try {
+            const r = (await entryFor(session)).recorder.end();
+            return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+        }
+        catch (e) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, error: e instanceof Error ? e.message : String(e) }, null, 2),
+                    },
+                ],
+            };
+        }
+    });
+    register("record_annotate", {
+        capability: "human",
+        description: "Attach a doc annotation (copy + optional arrow position + optional target ref) to the most-recent recorded step, or to a specific `stepId`. No-op if no recording is active.",
+        inputSchema: {
+            copy: z.string().describe("Annotation copy"),
+            arrow: z
+                .string()
+                .optional()
+                .describe("Arrow position hint (top|top-left|left|bottom-right|...)"),
+            target: z
+                .string()
+                .optional()
+                .describe("Ref to anchor the annotation to (overrides the step's default)"),
+            stepId: z.string().optional().describe("Annotate a specific step; default = most-recent"),
+            ...SESSION_ARG,
+        },
+    }, async ({ copy, arrow, target, stepId, session }) => {
+        const g = gateCheck("record_annotate");
+        if (g)
+            return g;
+        const r = (await entryFor(session)).recorder.annotate({ stepId, copy, arrow, target });
+        return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+    });
+}

package/dist/tools/forms-recording-tools.d.ts

@@ -0,0 +1,14 @@
+import type { ToolHost } from "./host.js";
+/**
+ * Form-fill, plan/execute, recording, named-ref, and find-feedback tools:
+ * fill_form / plan / execute / start_recording / end_recording /
+ * record_annotate / name_ref / list_named_refs / find_feedback.
+ *
+ * RFC 0004 P3 / D3 (SRP): the registrations were split by cohesive family into
+ * four sibling modules (fill / plan-execute / recording-mode / refs). 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, confirm,
+ * ports); the family modules own the registrations.
+ */
+export declare function registerFormsRecordingTools(host: ToolHost): void;

package/dist/tools/forms-recording-tools.js

@@ -0,0 +1,22 @@
+import { registerFormsFillTools } from "./forms-fill-tools.js";
+import { registerFormsPlanTools } from "./forms-plan-tools.js";
+import { registerFormsRecordingModeTools } from "./forms-recording-mode-tools.js";
+import { registerFormsRefsTools } from "./forms-refs-tools.js";
+/**
+ * Form-fill, plan/execute, recording, named-ref, and find-feedback tools:
+ * fill_form / plan / execute / start_recording / end_recording /
+ * record_annotate / name_ref / list_named_refs / find_feedback.
+ *
+ * RFC 0004 P3 / D3 (SRP): the registrations were split by cohesive family into
+ * four sibling modules (fill / plan-execute / recording-mode / refs). 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, confirm,
+ * ports); the family modules own the registrations.
+ */
+export function registerFormsRecordingTools(host) {
+    registerFormsFillTools(host);
+    registerFormsPlanTools(host);
+    registerFormsRecordingModeTools(host);
+    registerFormsRefsTools(host);
+}

package/dist/tools/forms-refs-tools.d.ts

@@ -0,0 +1,8 @@
+import type { RegisterHost, GateHost, SessionHost, ServerServicesHost } from "./host.js";
+/**
+ * Named-ref + learned-find-ranking tools: `name_ref` / `list_named_refs` /
+ * `find_feedback`. Bind mnemonics to refs and feed the per-session find() ranker.
+ * Split out of `forms-recording-tools` (RFC 0004 P3 / D3 SRP); registered through
+ * the shared `ToolHost` seam in the same source order.
+ */
+export declare function registerFormsRefsTools(host: RegisterHost & GateHost & SessionHost & ServerServicesHost): void;

package/dist/tools/forms-refs-tools.js

@@ -0,0 +1,90 @@
+import { SESSION_ARG } from "./schemas.js";
+/**
+ * Named-ref + learned-find-ranking tools: `name_ref` / `list_named_refs` /
+ * `find_feedback`. Bind mnemonics to refs and feed the per-session find() ranker.
+ * Split out of `forms-recording-tools` (RFC 0004 P3 / D3 SRP); registered through
+ * the shared `ToolHost` seam in the same source order.
+ */
+export function registerFormsRefsTools(host) {
+    const { z, register, gateCheck, entryFor } = host;
+    // ---------- named refs () ----------
+    register("name_ref", {
+        capability: "human",
+        batchable: true,
+        description: 'Bind a mnemonic name to a ref. Subsequent action tools accept `named: "<name>"` in place of `ref` / `selector`. Refs are stable across snapshots (by element-key), so the binding survives navigation as long as the element persists. Carry session-wide anchor sets without remembering the bare `eN`s.',
+        inputSchema: {
+            name: z.string().describe('Mnemonic (e.g. "main_tab", "library_tab")'),
+            ref: z.string().describe("The ref to bind to this name"),
+            ...SESSION_ARG,
+        },
+    }, async ({ name, ref, session }) => {
+        const g = gateCheck("name_ref");
+        if (g)
+            return g;
+        (await entryFor(session)).refs.nameRef(name, ref);
+        return {
+            content: [{ type: "text", text: JSON.stringify({ ok: true, name, ref }, null, 2) }],
+        };
+    });
+    register("list_named_refs", {
+        capability: "read",
+        batchable: true,
+        description: "List all current name → ref bindings created via name_ref.",
+        inputSchema: { ...SESSION_ARG },
+    }, async ({ session }) => {
+        const g = gateCheck("list_named_refs");
+        if (g)
+            return g;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify((await entryFor(session)).refs.listNames(), null, 2),
+                },
+            ],
+        };
+    });
+    // ---------- learned find() ranking ----------
+    register("find_feedback", {
+        capability: "human",
+        batchable: true,
+        description: "Tell browxai which candidate was the right answer to a prior `find(query)`. Subsequent finds whose query overlaps the token set will boost candidates matching this winner's identity (testId, or role+name). Session-scoped, in-memory, capped at 100 entries with LRU eviction. The learning is intentionally simple — a 'don't re-do that mistake' signal, not an ML model.",
+        inputSchema: {
+            query: z
+                .string()
+                .describe("The query you previously passed to find() (or a paraphrase — token overlap is what matters)"),
+            ref: z.string().describe("The ref the agent ended up acting on (the right candidate)"),
+            ...SESSION_ARG,
+        },
+    }, async ({ query, ref, session }) => {
+        const g = gateCheck("find_feedback");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const inputs = e.refs.locatorOf(ref);
+        if (!inputs) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ok: false, error: `ref "${ref}" not in the registry` }, null, 2),
+                    },
+                ],
+            };
+        }
+        e.feedback.record(query, {
+            testId: inputs.testId,
+            testIdAttr: inputs.testIdAttr,
+            role: inputs.role,
+            name: inputs.name,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ ok: true, recorded: { query, identity: inputs }, memorySize: e.feedback.size() }, null, 2),
+                },
+            ],
+        };
+    });
+}

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

@@ -0,0 +1,8 @@
+import type { RegisterHost, GateHost, SessionHost, ActionHost, ServerServicesHost } from "./host.js";
+/**
+ * Coordinate-space gesture tools: mouse_wheel / gesture_pinch / gesture_swipe.
+ * CDP-deep touch/wheel primitives dispatched at viewport coords. 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 registerGestureCoordTools(host: RegisterHost & GateHost & SessionHost & ActionHost & ServerServicesHost): void;

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

@@ -0,0 +1,168 @@
+import { withDeadline } from "../util/deadline.js";
+import { estimateTokens } from "../util/tokens.js";
+import { mouseWheel, gesturePinch, gestureSwipe } from "../page/gestures.js";
+import { requireCdp } from "../engine/session-cdp.js";
+import { SESSION_ARG } from "./schemas.js";
+/**
+ * Coordinate-space gesture tools: mouse_wheel / gesture_pinch / gesture_swipe.
+ * CDP-deep touch/wheel primitives dispatched at viewport coords. 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 registerGestureCoordTools(host) {
+    const { z, register, gateCheck, engineGate, entryFor, cfgActionTimeout } = host;
+    register("mouse_wheel", {
+        capability: "action",
+        deep: true,
+        description: "Coordinate-space wheel event — dispatched via CDP at `coords` (viewport CSS px) regardless of the current pointer position. For canvas, virtualised lists, and map tiles that listen for `wheel` and ignore element-level scroll. `deltaX`/`deltaY` are CSS px (DOM `WheelEvent` convention: positive `deltaY` scrolls content up); at least one must be non-zero.",
+        inputSchema: {
+            coords: z
+                .object({ x: z.number(), y: z.number() })
+                .describe("Viewport CSS px — where the wheel event fires."),
+            deltaX: z.number().optional().describe("Horizontal wheel delta in CSS px (default 0)."),
+            deltaY: z.number().optional().describe("Vertical wheel delta in CSS px (default 0)."),
+            ...SESSION_ARG,
+        },
+    }, async ({ coords, deltaX, deltaY, session }) => {
+        const g = gateCheck("mouse_wheel");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("mouse_wheel", e);
+        if (eg)
+            return eg;
+        try {
+            const r = await withDeadline(mouseWheel(requireCdp(e.session), { coords, deltaX, deltaY }), cfgActionTimeout(), "mouse_wheel");
+            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),
+                    },
+                ],
+            };
+        }
+    });
+    register("gesture_pinch", {
+        capability: "action",
+        deep: true,
+        description: "Two-finger pinch in/out centred on `coords`. Two touch points start at `coords ± startOffset` (default 40 CSS px) and converge or diverge linearly so the final separation = `startOffset × scale`. `scale < 1` is pinch-in (zoom out); `scale > 1` is pinch-out (zoom in). Linear interpolation across `steps` (default 12, clamped 1–100) — pinch handlers read inter-frame deltas; a velocity-detecting curve can misfire fling heuristics, linear is the safe default. Dispatches via CDP touch pipeline; touch does not fire mouse events automatically.",
+        inputSchema: {
+            coords: z
+                .object({ x: z.number(), y: z.number() })
+                .describe("Pinch centre, viewport CSS px."),
+            scale: z
+                .number()
+                .positive()
+                .describe("Final separation / initial separation. <1 = pinch-in (zoom out); >1 = pinch-out (zoom in)."),
+            steps: z
+                .number()
+                .int()
+                .positive()
+                .max(100)
+                .optional()
+                .describe("Intermediate touchMove dispatches (default 12)."),
+            startOffset: z
+                .number()
+                .positive()
+                .optional()
+                .describe("Initial half-separation in CSS px (default 40)."),
+            ...SESSION_ARG,
+        },
+    }, async ({ coords, scale, steps, startOffset, session }) => {
+        const g = gateCheck("gesture_pinch");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("gesture_pinch", e);
+        if (eg)
+            return eg;
+        try {
+            const r = await withDeadline(gesturePinch(requireCdp(e.session), { coords, scale, steps, startOffset }), cfgActionTimeout(), "gesture_pinch");
+            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),
+                    },
+                ],
+            };
+        }
+    });
+    register("gesture_swipe", {
+        capability: "action",
+        deep: true,
+        description: "Single-finger swipe from `from` to `to` via the touch pipeline. Distinct from `drag` (mouse pipeline) — mobile carousels, pull-to-refresh, swipeable list items wire touch handlers that ignore mouse events. `durationMs` (default 200 — fast flick; 500+ reads as deliberate scroll) is split across `steps` (default 16, clamped 1–200) touchMove dispatches. Smoothed via an ease-out curve (`1 - (1 - t)²`) — matches the natural deceleration most fling-detect heuristics are tuned for (Hammer.js, native scroll inertia, react-spring physics).",
+        inputSchema: {
+            from: z.object({ x: z.number(), y: z.number() }).describe("Swipe start, viewport CSS px."),
+            to: z.object({ x: z.number(), y: z.number() }).describe("Swipe end, viewport CSS px."),
+            durationMs: z
+                .number()
+                .int()
+                .nonnegative()
+                .max(60_000)
+                .optional()
+                .describe("Total swipe duration in ms (default 200)."),
+            steps: z
+                .number()
+                .int()
+                .positive()
+                .max(200)
+                .optional()
+                .describe("Intermediate touchMove dispatches (default 16)."),
+            identifier: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Touch identifier (default 1)."),
+            ...SESSION_ARG,
+        },
+    }, async ({ from, to, durationMs, steps, identifier, session }) => {
+        const g = gateCheck("gesture_swipe");
+        if (g)
+            return g;
+        const e = await entryFor(session);
+        const eg = engineGate("gesture_swipe", e);
+        if (eg)
+            return eg;
+        try {
+            const r = await withDeadline(gestureSwipe(requireCdp(e.session), { from, to, durationMs, steps, identifier }), cfgActionTimeout(), "gesture_swipe");
+            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),
+                    },
+                ],
+            };
+        }
+    });
+}

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

@@ -0,0 +1,8 @@
+import type { RegisterHost, GateHost, SessionHost, ActionHost, ServerServicesHost } from "./host.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 declare function registerGestureEmulationTools(host: RegisterHost & GateHost & SessionHost & ActionHost & ServerServicesHost): void;