@reticlehq/server 2.14.0 → 3.2.0

package/dist/portal/input/drive-url-stamp.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A drive's URL, marked so the page can tell Reticle opened it.
+ *
+ * Every page Reticle opens for itself should be able to say so, and only the lease pool could: the
+ * launched provider navigated to the bare URL, so its page was indistinguishable from a developer's
+ * own tab. That mattered the moment the first-run tour shipped — the page got the tour, and the
+ * tour's scrim takes `pointer-events: auto` deliberately, so it swallowed every native click and
+ * hover the drive made. The drive reported `dispatched: true` the whole time, because from the
+ * server's side the mouse HAD moved; it landed on the scrim.
+ *
+ * An unparseable URL is returned untouched. A navigation that happens without the stamp is a page
+ * showing a tour it should not; a navigation that does not happen at all is the feature gone.
+ */
+export declare function stampedDriveUrl(driveUrl: string): string;

package/dist/portal/input/drive-url-stamp.js

@@ -0,0 +1,33 @@
+import { RETICLE_URL_PARAM } from '@reticlehq/core';
+/**
+ * The value the stamp carries for a launched drive.
+ *
+ * The lease pool stamps a real lease id; a drive owns exactly one page and has no id to give, so
+ * the constant says what it is. Only its PRESENCE is read page-side.
+ */
+const OPENED_STAMP = '1';
+/**
+ * A drive's URL, marked so the page can tell Reticle opened it.
+ *
+ * Every page Reticle opens for itself should be able to say so, and only the lease pool could: the
+ * launched provider navigated to the bare URL, so its page was indistinguishable from a developer's
+ * own tab. That mattered the moment the first-run tour shipped — the page got the tour, and the
+ * tour's scrim takes `pointer-events: auto` deliberately, so it swallowed every native click and
+ * hover the drive made. The drive reported `dispatched: true` the whole time, because from the
+ * server's side the mouse HAD moved; it landed on the scrim.
+ *
+ * An unparseable URL is returned untouched. A navigation that happens without the stamp is a page
+ * showing a tour it should not; a navigation that does not happen at all is the feature gone.
+ */
+export function stampedDriveUrl(driveUrl) {
+    try {
+        const url = new URL(driveUrl);
+        // OPENED, never SESSION: the session param doubles as the session ID when the app names none,
+        // so stamping it here would rename every driven session to one constant and collide two drives.
+        url.searchParams.set(RETICLE_URL_PARAM.OPENED, OPENED_STAMP);
+        return url.toString();
+    }
+    catch {
+        return driveUrl;
+    }
+}

package/dist/portal/input/network-detail.d.ts

@@ -0,0 +1,97 @@
+import { URL_RAW, type RedactionPolicy } from '@reticlehq/core';
+/**
+ * CDP-authoritative network detail. Wherever the daemon has a CDP connection — whether it launched
+ * the browser or attached to one someone else started — `page.on('response')` sees the FULL response:
+ * status, mime type, and every response header, including the ones the in-page fetch/XHR wrapper
+ * structurally cannot read (CORS-opaque headers, redirects).
+ * Capturing it as a NET_DETAIL event and merging it onto the matching in-page NET_REQUEST means the
+ * driven view never loses fidelity to an outside-in tool. Pure builder + merge are unit-tested; the
+ * `page.on` attachment is thin Playwright glue (exercised e2e, like the pool launcher).
+ */
+export interface NetworkDetail {
+    /**
+     * The URL as the agent reads it, redacted by the same rule the in-page observer applies.
+     *
+     * It arrives raw from the driver, exactly like the headers and the request body below, and it
+     * carries credentials just as routinely: a presigned upload, an OAuth callback, a single-use reset
+     * link. Redacting the other two and not this one left the one field nobody had to parse to read.
+     */
+    url: string;
+    /**
+     * The URL before redaction, present only when redaction rewrote it.
+     *
+     * The grader-only match haystack, the same field and the same contract as on a NET_REQUEST: it is
+     * how `urlContains` still matches a public path segment the heuristic rewrote, and how the merge
+     * below pairs this detail with the request the SDK reported. `withoutUrlRaw` strips it before any
+     * event is rendered to an agent.
+     */
+    [URL_RAW]?: string;
+    method?: string;
+    status: number;
+    headers: Record<string, string>;
+    resourceType?: string;
+    /**
+     * The request body as the NETWORK STACK saw it — what actually left, not what the page handed to
+     * fetch. Redacted and bounded here because it arrives raw from the driver.
+     *
+     * This is the one thing in-page instrumentation structurally cannot get: Reticle reads `init.body`
+     * inside its own fetch wrapper, and whoever patches fetch last is outermost — app bootstrap
+     * decides that, not us. An interceptor initialised after connect(), or a service worker (no
+     * window.fetch frame at all), rewrites requests invisibly. Available on the DRIVE path only.
+     */
+    requestBody?: string;
+    /**
+     * Present, and only ever `true`, when the bound above cut the captured body short.
+     *
+     * The same field and the same contract the in-page observer already emits. A shortened body an
+     * agent cannot tell apart from a whole one is the false green this project exists to prevent: a
+     * `net` assertion over a payload that was cut reads as an absence of the thing that was cut off.
+     * Omitted when the whole body fits, so the caveat means something when it appears.
+     */
+    requestBodyTruncated?: boolean;
+    /**
+     * The document that ISSUED the request, which is what identifies the session it belongs to.
+     *
+     * Routing used to match the REQUEST's origin against the session's, falling back to the drive
+     * URL's. Both miss the ordinary case: an app on one origin calling an API on another produces a
+     * detail matching no session, so it was dropped silently — and on the CDP-attach path there is no
+     * drive URL, so the fallback matched nothing at all. Cross-origin API calls are most API calls.
+     */
+    pageUrl?: string;
+}
+/**
+ * Shape a raw authoritative response into a NET_DETAIL payload (lower-cased headers).
+ *
+ * `policy` defaults to the built-in rule so this stays a PURE builder — the driven-path union is
+ * resolved by `attachNetworkDetail`, at the glue layer, where reading process state is not a lie
+ * about the function's inputs.
+ */
+export declare function buildNetworkDetail(raw: {
+    url: string;
+    method?: string;
+    status: number;
+    headers: Record<string, string>;
+    resourceType?: string;
+    requestBody?: string;
+    pageUrl?: string;
+}, policy?: RedactionPolicy): NetworkDetail;
+/** The minimal Playwright surfaces this attachment reads — kept structural so it's fake-testable. */
+export interface ResponseLike {
+    url(): string;
+    status(): number;
+    headers(): Record<string, string> | Promise<Record<string, string>>;
+    request(): {
+        method(): string;
+        resourceType?(): string;
+        postData?(): string | null;
+    };
+}
+export interface PageLike {
+    url(): string;
+    on(event: 'response', handler: (response: ResponseLike) => void): void;
+}
+/**
+ * Attach a response listener to a driven page: every response becomes a NET_DETAIL via `emit`. Thin glue
+ * over Playwright's event surface — the daemon routes `emit` to the driven session's pushEvent.
+ */
+export declare function attachNetworkDetail(page: PageLike, emit: (detail: NetworkDetail) => void): void;

package/dist/portal/input/network-detail.js

@@ -0,0 +1,138 @@
+import { REDACTED_VALUE, URL_RAW, defaultIsSensitiveKey, netUrlFields, scrubKnownSecrets, } from '@reticlehq/core';
+import { drivenRedactionPolicy } from './driven-redaction.js';
+/** Bound on a captured wire body — matches the in-page capture so the two are comparable. */
+const MAX_WIRE_BODY_CHARS = 8192;
+/**
+ * The rule this module redacts by.
+ *
+ * `defaultIsSensitiveKey`, never the ambient `isSensitiveKey`: a daemon serves many sessions in one
+ * process, so an ambient policy here would let one app's config decide another app's redaction.
+ * Callers that have a session's declarations pass a policy explicitly; everything else gets the
+ * built-in floor, which is exactly what this module did before the rule became configurable.
+ */
+const DEFAULT_POLICY = { isSensitiveKey: defaultIsSensitiveKey };
+/**
+ * Redact a sensitive key's value whatever its TYPE — string, number, array, or a nested object.
+ *
+ * This is the one payload in the system that reaches the journal without having passed through the
+ * SDK's sanitizer (Playwright hands it over raw), so its redaction has to be as strong as the SDK's,
+ * which is key-based over a parsed object — not string-shaped.
+ */
+function redactByKey(value, policy) {
+    if (Array.isArray(value))
+        return value.map((v) => redactByKey(v, policy));
+    if (value !== null && 'object' === typeof value) {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = policy.isSensitiveKey(k) ? REDACTED_VALUE : redactByKey(v, policy);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Redact and bound a captured wire body, returning the value AND whether the bound was reached.
+ *
+ * The report is the point. This body is taken raw off the network stack, it is capped, and the cap is
+ * reached by ordinary payloads (a bulk save, a base64 attachment, a rich-text field). Returning the
+ * shortened string alone let a partial capture be read as a whole one, which is the shape the
+ * lossy-transform rule exists to forbid.
+ */
+function projectWireBody(raw, policy) {
+    const truncated = raw.length > MAX_WIRE_BODY_CHARS;
+    const bounded = truncated ? raw.slice(0, MAX_WIRE_BODY_CHARS) : raw;
+    const byShape = scrubKnownSecrets(bounded);
+    // Prefer a STRUCTURAL pass. A sensitive key must be redacted regardless of its value type — a
+    // numeric PIN (`"password": 1234`), a token array, a nested credential object — and the old
+    // string-only sweep matched exclusively `"key":"string"`, so every non-string secret leaked
+    // straight to the agent's context and the on-disk journal. Parsing and walking redacts them by key
+    // whatever the shape.
+    try {
+        return { body: JSON.stringify(redactByKey(JSON.parse(byShape), policy)), truncated };
+    }
+    catch {
+        // Not JSON (a truncated capture, or a form-encoded body — the shape a login form actually POSTs).
+        // Two best-effort sweeps, because a password lives in both: the `"key":"string"` JSON fragment a
+        // truncated body still contains, and the `key=value` pair of `application/x-www-form-urlencoded`,
+        // which neither the JSON path nor the old regex ever touched — so `password=hunter2` leaked.
+        const body = byShape
+            .replace(/"([^"]+)"\s*:\s*"([^"]*)"/g, (whole, key) => policy.isSensitiveKey(key) ? `"${key}":"${REDACTED_VALUE}"` : whole)
+            .replace(/([^&?=\s]+)=([^&\s]*)/g, (whole, key) => policy.isSensitiveKey(key) ? `${key}=${REDACTED_VALUE}` : whole);
+        return { body, truncated };
+    }
+}
+/**
+ * Header names are case-insensitive; normalize to lower-case so a merge/compare is stable — and
+ * REDACT while we do it. On the CDP/drive path `page.on('response')` sees the full response headers,
+ * including `set-cookie` (the session credential), and requests carry `cookie`/`authorization`. These
+ * were the one wire payload that reached the journal (cleartext, on disk) and the agent's context
+ * window unredacted — every other capture goes through the SDK sanitizer or projectWireBody. A
+ * credential HEADER is redacted whole by key; any other header value is still swept for known secret
+ * SHAPES (a JWT echoed in a custom header), matching how request bodies are handled.
+ */
+function projectHeaders(headers, policy) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers)) {
+        const key = k.toLowerCase();
+        out[key] = policy.isSensitiveKey(key) ? REDACTED_VALUE : scrubKnownSecrets(v);
+    }
+    return out;
+}
+/**
+ * Shape a raw authoritative response into a NET_DETAIL payload (lower-cased headers).
+ *
+ * `policy` defaults to the built-in rule so this stays a PURE builder — the driven-path union is
+ * resolved by `attachNetworkDetail`, at the glue layer, where reading process state is not a lie
+ * about the function's inputs.
+ */
+export function buildNetworkDetail(raw, policy = DEFAULT_POLICY) {
+    const wireBody = raw.requestBody === undefined || 0 === raw.requestBody.length
+        ? undefined
+        : projectWireBody(raw.requestBody, policy);
+    return {
+        ...netUrlFields(raw.url, policy.isSensitiveKey),
+        ...(raw.method === undefined ? {} : { method: raw.method }),
+        status: raw.status,
+        headers: projectHeaders(raw.headers, policy),
+        ...(raw.resourceType === undefined ? {} : { resourceType: raw.resourceType }),
+        ...(wireBody === undefined
+            ? {}
+            : {
+                requestBody: wireBody.body,
+                ...(wireBody.truncated ? { requestBodyTruncated: true } : {}),
+            }),
+        ...(raw.pageUrl === undefined || 0 === raw.pageUrl.length ? {} : { pageUrl: raw.pageUrl }),
+    };
+}
+/**
+ * Attach a response listener to a driven page: every response becomes a NET_DETAIL via `emit`. Thin glue
+ * over Playwright's event surface — the daemon routes `emit` to the driven session's pushEvent.
+ */
+export function attachNetworkDetail(page, emit) {
+    page.on('response', (response) => {
+        const detailPromise = Promise.resolve(response.headers()).then((headers) => {
+            const request = response.request();
+            const resourceType = request.resourceType?.();
+            // postData is null for GETs and for bodies the driver did not retain; both mean "nothing to say".
+            const postData = request.postData?.() ?? null;
+            emit(buildNetworkDetail({
+                url: response.url(),
+                method: request.method(),
+                status: response.status(),
+                headers,
+                ...(resourceType === undefined ? {} : { resourceType }),
+                ...(null === postData ? {} : { requestBody: postData }),
+                pageUrl: page.url(),
+            }, 
+            // Resolved per response, not per attachment: a session declaring extra keys can connect
+            // after the listener is attached, and capturing the policy once would leave every
+            // already-driven page redacting by the rule that was in force before the app said so.
+            drivenRedactionPolicy()));
+        });
+        // `response.headers()` REJECTS when the page/CDP session is closing — precisely when responses race
+        // teardown (navigation, tab close). Without this catch the rejection floats; on the daemon path a
+        // global unhandledRejection trap swallows it, but on the stdio `start()` path there is no trap, so
+        // one late response would crash the whole MCP server. A detail we can't read is simply dropped.
+        void detailPromise.catch(() => undefined);
+    });
+}

package/dist/portal/input/network-mock-tools.d.ts

@@ -0,0 +1,21 @@
+import type { MockRule } from './network-mock.js';
+import type { ToolDef } from '../../surface/tools/tool-kit.js';
+/**
+ * Narrow the validated tool args into MockRule[], omitting undefined keys (exactOptionalPropertyTypes).
+ *
+ * THROWS on a malformed rule rather than falling back to `[]`, because `[]` is not a neutral value
+ * here — it is the documented way to clear every active mock. A rule with a wrong field name used to
+ * produce exactly the call that turns mocking OFF, and the handler then reported `applied: true`
+ * with `count: 0`. For a tool whose entire job is forcing an error state, that means the agent
+ * checks the app's failure handling against the real backend, sees the happy path, and reports that
+ * the error state works.
+ *
+ * Same rule as the action arguments: an argument that could not be understood is refused by name,
+ * never reinterpreted into a destructive default. A valueless `fill` used to wipe the field and
+ * report ok; it throws now, for this reason.
+ *
+ * `undefined` and `[]` still mean "clear" — those are deliberate, documented requests, not failures
+ * to parse.
+ */
+export declare function toRules(value: unknown): MockRule[];
+export declare const NETWORK_MOCK_TOOLS: ToolDef[];

package/dist/portal/input/network-mock-tools.js

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+import { CDP_NO_PROVIDER_REASON, CDP_NO_PROVIDER_RECOMMENDATION } from '@reticlehq/core';
+import { ReticleTool } from '@reticlehq/core';
+import { sessionIdShape } from '../../surface/tools/tool-kit.js';
+import { delayMsSchema, httpStatusSchema } from '../../surface/tools/args/numeric-bounds.js';
+import { asString } from '@reticlehq/core';
+function mockProvider(deps) {
+    const p = deps.realInput;
+    return p !== undefined && 'function' === typeof p.setMocks ? p : undefined;
+}
+const ruleShape = z.object({
+    urlContains: z
+        .string()
+        .min(1)
+        .describe('Substring the request URL must contain, e.g. "/api/pay".'),
+    method: z.string().optional().describe('Optional method filter (GET/POST/…), case-insensitive.'),
+    status: httpStatusSchema.optional().describe('Fulfill with this HTTP status (default 200).'),
+    body: z.string().optional().describe('Response body to fulfill with.'),
+    contentType: z.string().optional().describe('Response content type (default application/json).'),
+    delayMs: delayMsSchema.optional().describe('Delay (ms) before fulfilling — simulate a slow API.'),
+    abort: z
+        .boolean()
+        .optional()
+        .describe('Simulate a network failure (offline) instead of a response.'),
+});
+/**
+ * Narrow the validated tool args into MockRule[], omitting undefined keys (exactOptionalPropertyTypes).
+ *
+ * THROWS on a malformed rule rather than falling back to `[]`, because `[]` is not a neutral value
+ * here — it is the documented way to clear every active mock. A rule with a wrong field name used to
+ * produce exactly the call that turns mocking OFF, and the handler then reported `applied: true`
+ * with `count: 0`. For a tool whose entire job is forcing an error state, that means the agent
+ * checks the app's failure handling against the real backend, sees the happy path, and reports that
+ * the error state works.
+ *
+ * Same rule as the action arguments: an argument that could not be understood is refused by name,
+ * never reinterpreted into a destructive default. A valueless `fill` used to wipe the field and
+ * report ok; it throws now, for this reason.
+ *
+ * `undefined` and `[]` still mean "clear" — those are deliberate, documented requests, not failures
+ * to parse.
+ */
+export function toRules(value) {
+    if (value === undefined)
+        return [];
+    const parsed = z.array(ruleShape).safeParse(value);
+    if (!parsed.success) {
+        const problem = parsed.error.issues
+            .map((i) => `${0 === i.path.length ? 'mocks' : `mocks.${i.path.join('.')}`}: ${i.message}`)
+            .join('; ');
+        throw new Error(`reticle_network_mock could not read \`mocks\` (${problem}). Nothing was applied and mocking ` +
+            'was left unchanged — an unreadable rule is NOT treated as a request to clear. A rule is ' +
+            '{ urlContains, method?, status?, body?, contentType?, delayMs?, abort? }; pass `clear: true` ' +
+            'or an empty array if you meant to turn mocking off.');
+    }
+    return parsed.data.map((r) => {
+        const rule = { urlContains: r.urlContains };
+        if (r.method !== undefined)
+            rule.method = r.method;
+        if (r.status !== undefined)
+            rule.status = r.status;
+        if (r.body !== undefined)
+            rule.body = r.body;
+        if (r.contentType !== undefined)
+            rule.contentType = r.contentType;
+        if (r.delayMs !== undefined)
+            rule.delayMs = r.delayMs;
+        if (r.abort !== undefined)
+            rule.abort = r.abort;
+        return rule;
+    });
+}
+export const NETWORK_MOCK_TOOLS = [
+    {
+        name: ReticleTool.NETWORK_MOCK,
+        description: 'Stub or intercept network requests on a driven page (`reticle drive` / RETICLE_CDP_URL) or a ' +
+            'leased Playwright tab (`reticle_lease acquire`): return a 500, force offline (abort), or delay ' +
+            'a response — so you can deterministically test error and edge states without touching the ' +
+            'backend ("verify the app handles a failed payment"). Pass `mocks` (first matching rule wins); ' +
+            'pass an empty array or `clear: true` to turn mocking off.',
+        inputSchema: {
+            // The rule fields each carry their own `.describe()` on `ruleShape`, but the params
+            // view reads only the top-level description of each entry, so those are flattened
+            // away before an agent sees them. Naming the shape here is what keeps the tool
+            // callable from its own description instead of by guessing and failing first.
+            mocks: z
+                .array(ruleShape)
+                .optional()
+                .describe('Interception rules, first match wins: { urlContains, method?, status?, body?, contentType?, delayMs?, abort? }. Omit or pass [] to clear.'),
+            clear: z.boolean().optional().describe('Clear all active mocks (same as mocks: []).'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            applied: z.boolean(),
+            count: z.number(),
+            ok: z.boolean().optional(),
+            reason: z.string().optional(),
+            recommendation: z.string().optional(),
+        },
+        handler: async (deps, args) => {
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const rules = true === args['clear'] ? [] : toRules(args['mocks']);
+            const provider = mockProvider(deps);
+            if (provider !== undefined) {
+                const applied = await provider.setMocks(session.url, rules);
+                if (applied)
+                    return { applied: true, count: rules.length };
+            }
+            // A lease is a Playwright-owned page — CDP intercept was always there, this tool just had no
+            // route to it. Tried after the driven provider: when both exist, drive is the page the caller
+            // means, and a lease is the fallback rather than a competitor.
+            const leased = await deps.pool?.setMocksLease(session.id, rules);
+            if (true === leased)
+                return { applied: true, count: rules.length };
+            return {
+                applied: false,
+                count: 0,
+                ok: false,
+                reason: CDP_NO_PROVIDER_REASON,
+                recommendation: CDP_NO_PROVIDER_RECOMMENDATION,
+            };
+        },
+    },
+];

package/dist/portal/input/network-mock.js

@@ -0,0 +1,83 @@
+const DEFAULT_STATUS = 200;
+const DEFAULT_CONTENT_TYPE = 'application/json';
+/**
+ * Decide the outcome for a request from the active rules. Pure: no IO, no clock. The first rule
+ * whose url-substring (and optional method) matches wins; no match → continue (let it hit the network).
+ */
+export function matchMock(rules, req) {
+    for (const rule of rules) {
+        if (!req.url.includes(rule.urlContains))
+            continue;
+        if (rule.method !== undefined && rule.method.toUpperCase() !== req.method.toUpperCase())
+            continue;
+        if (true === rule.abort)
+            return { kind: 'abort' };
+        /*
+         * A rule that says only WHEN says nothing about WHAT.
+         *
+         * `delayMs` on its own used to fulfill — status 200, `application/json`, body `''` — so asking
+         * for a slow endpoint handed the app an EMPTY payload it never requested, and everything
+         * observed afterwards described Reticle's substitute rather than the app under load. Now the
+         * request goes to the real server and the real answer comes back, later.
+         *
+         * This is what makes seeded perturbation honest. A race "found" by pushing empty bodies at an
+         * app is an artifact, not a race, and shipping one as a finding puts a fabricated defect in
+         * front of somebody at 3am.
+         */
+        if (rule.status === undefined &&
+            rule.body === undefined &&
+            rule.contentType === undefined &&
+            rule.delayMs !== undefined) {
+            return { kind: 'continue', delayMs: rule.delayMs };
+        }
+        const outcome = {
+            kind: 'fulfill',
+            status: rule.status ?? DEFAULT_STATUS,
+            contentType: rule.contentType ?? DEFAULT_CONTENT_TYPE,
+        };
+        if (rule.body !== undefined)
+            outcome.body = rule.body;
+        if (rule.delayMs !== undefined)
+            outcome.delayMs = rule.delayMs;
+        return outcome;
+    }
+    return { kind: 'continue' };
+}
+/** Apply a matched outcome to a Playwright Route. Exported so the route handler is testable in isolation. */
+export async function applyOutcome(route, outcome, sleep) {
+    if ('continue' === outcome.kind) {
+        // Sleep FIRST, then let it through: the delay is the whole perturbation, and the response that
+        // comes back is the server's own.
+        if (outcome.delayMs !== undefined && outcome.delayMs > 0)
+            await sleep(outcome.delayMs);
+        await route.continue();
+        return;
+    }
+    if ('abort' === outcome.kind) {
+        await route.abort('failed');
+        return;
+    }
+    if (outcome.delayMs !== undefined && outcome.delayMs > 0)
+        await sleep(outcome.delayMs);
+    await route.fulfill({
+        status: outcome.status ?? DEFAULT_STATUS,
+        contentType: outcome.contentType ?? DEFAULT_CONTENT_TYPE,
+        body: outcome.body ?? '',
+    });
+}
+const realSleep = (ms) => new Promise((res) => setTimeout(res, ms));
+/**
+ * Install (or replace) the network-mock handler on a driven page. Clears any prior Reticle route first,
+ * so calling with a new rule set is idempotent and calling with [] turns mocking off. The handler
+ * consults matchMock per request and fulfills/aborts/continues accordingly.
+ */
+export async function installNetworkMocks(page, rules, sleep = realSleep) {
+    await page.unroute('**/*').catch(() => undefined);
+    if (0 === rules.length)
+        return;
+    await page.route('**/*', (route) => {
+        const req = route.request();
+        const outcome = matchMock(rules, { url: req.url(), method: req.method() });
+        void applyOutcome(route, outcome, sleep);
+    });
+}

package/dist/portal/input/network-mutation.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Breaking a driven page on purpose, with machinery that already exists.
+ *
+ * A flow that would stay green if the feature broke is a false green with a maintenance cost, and
+ * the only way to find one is to break the thing it claims to watch. `setMocks` already fails a
+ * request on a driven page and clearing the rules already puts it back, which makes this a real
+ * mutation with a real reversal rather than a new capability nobody has proved.
+ *
+ * A failing request is the sharpest single mutation available here. A flow whose action fires a
+ * request that 500s and still passes is one that never asserted the consequence — precisely the
+ * shape the demotion grade exists to catch.
+ */
+import { type Reversal } from 'open-verification';
+import type { RealInputProvider } from './real-input.js';
+/**
+ * How a broken endpoint breaks: the request ABORTS. It leaves and never arrives.
+ *
+ * This used to fulfill with a fabricated 500 — a response the server never sent. Grading a flow
+ * against an invented payload grades it against Reticle's fiction, and the grade is a real
+ * accusation ("this is a click sequence, not a test") to make on made-up input. A verdict built on
+ * something nobody observed is the exact failure this product exists to catch.
+ *
+ * An abort is a real failure mode — server down, network partition, DNS gone — and nothing is
+ * claimed on the server's behalf. It is also the STRICTLY harder break to survive silently: an app
+ * can quietly read a 500 body as empty data and carry on looking fine, but no code path mistakes a
+ * request that never completed for a successful one. A flow that stays green through it is
+ * unambiguously not checking what it declared it depends on.
+ */
+/**
+ * What this hands back. Declared here rather than imported from the realm that consumes it: the
+ * realm owns the interface it depends on and this file owns a thing that provides one, and a
+ * provider that imported its consumer would be the inversion backwards.
+ */
+export interface NetworkMutationPort {
+    mutate(mutation: {
+        kind: string;
+        target?: string;
+    }): Promise<Reversal>;
+    revert(): Promise<void>;
+}
+/**
+ * A port for this session, or nothing.
+ *
+ * Nothing when the provider cannot install mocks, and nothing when it is not driving THIS page —
+ * breaking a page this provider does not drive would perturb somebody else's subject.
+ */
+export declare function mutationPortFor(provider: RealInputProvider, sessionUrl: string): Promise<NetworkMutationPort | undefined>;

package/dist/portal/input/network-mutation.js

@@ -0,0 +1,53 @@
+/**
+ * Breaking a driven page on purpose, with machinery that already exists.
+ *
+ * A flow that would stay green if the feature broke is a false green with a maintenance cost, and
+ * the only way to find one is to break the thing it claims to watch. `setMocks` already fails a
+ * request on a driven page and clearing the rules already puts it back, which makes this a real
+ * mutation with a real reversal rather than a new capability nobody has proved.
+ *
+ * A failing request is the sharpest single mutation available here. A flow whose action fires a
+ * request that 500s and still passes is one that never asserted the consequence — precisely the
+ * shape the demotion grade exists to catch.
+ */
+import { MutationKind } from 'open-verification';
+/**
+ * A port for this session, or nothing.
+ *
+ * Nothing when the provider cannot install mocks, and nothing when it is not driving THIS page —
+ * breaking a page this provider does not drive would perturb somebody else's subject.
+ */
+export async function mutationPortFor(provider, sessionUrl) {
+    if (provider.setMocks === undefined)
+        return undefined;
+    if (!(await provider.isAvailableFor(sessionUrl)))
+        return undefined;
+    const setMocks = (rules) => provider.setMocks?.(sessionUrl, rules) ?? Promise.resolve(false);
+    return {
+        async mutate(mutation) {
+            /*
+             * A kind this page cannot perform is REFUSED, never faked.
+             *
+             * The mutation set is allowed to be small — a realm perturbs what it has. What it may not do
+             * is report a perturbation it never applied, because a flow would then be demoted for
+             * surviving something that never happened to it. That is the mutation score lying in the
+             * direction that looks like rigour.
+             */
+            if (MutationKind.REQUEST_FAILS !== mutation.kind) {
+                throw new Error(`a driven web page cannot perform the mutation "${mutation.kind}" — it breaks requests, ` +
+                    `and nothing else. Refusing rather than reporting a break that did not happen: a flow ` +
+                    `that survived a mutation nobody applied would be demoted for somebody else's gap.`);
+            }
+            if (mutation.target === undefined || '' === mutation.target) {
+                throw new Error('a failing-request mutation needs a `target` — the URL fragment to break (e.g. ' +
+                    '"/api/orders"). Failing every request would not test a flow, it would unplug the app.');
+            }
+            await setMocks([{ urlContains: mutation.target, abort: true }]);
+            return { mutation: `${MutationKind.REQUEST_FAILS}:${mutation.target}` };
+        },
+        /** Clearing the rules is the undo. A break nobody reverses is damage the next run inherits. */
+        async revert() {
+            await setMocks([]);
+        },
+    };
+}