@jitsusama/agentic-harness.core 0.1.0

package/dist/web/session/emulation.js

@@ -0,0 +1,307 @@
+/**
+ * What a session pretends to be, and how the pretence is kept.
+ *
+ * The intent is held whole and re-applied in full, because
+ * Chrome's media emulation forgets anything a call omits, and a
+ * cross-process navigation swaps the renderer the flags live in.
+ * Applying, observing and diverging all live here so the one
+ * piece of state has one keeper.
+ */
+import { KnownDevices } from "puppeteer-core";
+import { deviceEmulation, noSuchDevice } from "../environment/devices.js";
+import { divergences, ENVIRONMENT_PROBE, mediaFeaturesOf, mergeEmulation, refusedFeature, unsupportedFields, withoutFeature, } from "../environment/index.js";
+/**
+ * Touch points a touch device is given, matching a common phone.
+ *
+ * Layered over the driver's own request, which asks only for touch
+ * to exist. If a navigation ever costs us this command again, the
+ * driver restores touch with one point rather than none, so the
+ * page stays a touch device and only the count degrades.
+ */
+const TOUCH_POINTS = 5;
+/** Metres of accuracy claimed for an overridden position. */
+const GEOLOCATION_ACCURACY = 10;
+/** The standing pretence, applied, observed and diverged. */
+export class EmulationController {
+    wires;
+    hooks;
+    /** What this session is pretending to be. */
+    state = {};
+    /**
+     * Media features this browser turned down.
+     *
+     * Kept so the refusal can be reported once, rather than lost
+     * silently or, worse, left in the intent to fail again on every
+     * navigation that replays it.
+     */
+    refused = [];
+    constructor(wires, hooks) {
+        this.wires = wires;
+        this.hooks = hooks;
+    }
+    /** What this session has asked the browser to pretend. */
+    get asked() {
+        return this.state;
+    }
+    /** Whether the page believes it is being touched. */
+    get touch() {
+        return this.state.touch === true;
+    }
+    /**
+     * Put the emulation back exactly as it was.
+     *
+     * change merges, which is right for a caller adding one
+     * condition and wrong for anything that has to undo itself: a
+     * merge cannot clear a field, so a sweep that widened the
+     * viewport could never restore a session that had none. This
+     * replaces the state wholesale.
+     */
+    async restore(state) {
+        await this.wires.ready();
+        this.state = state;
+        await this.apply();
+    }
+    /**
+     * Pretend to be a different visitor, then report what the page
+     * actually experiences.
+     *
+     * The intent is kept whole and re-applied in full, because
+     * Chrome's media emulation forgets anything a call omits, so
+     * asking for reduced motion after asking for dark mode would
+     * otherwise turn the dark mode back off.
+     */
+    async change(change = {}, 
+    /** Overrides to take off, which an absent key cannot express. */
+    clear = []) {
+        await this.wires.ready();
+        // Anything this cannot emulate is named before it is dropped.
+        // Silently ignoring a field meant a call asking for a 1024px
+        // viewport did nothing, said nothing, and reported no gaps.
+        const ignored = unsupportedFields(change);
+        this.state = mergeEmulation(this.state, change, clear);
+        // A device this catalogue has never heard of is reported the
+        // same way as a field with nothing behind it, rather than
+        // echoed back as though it had been honoured.
+        const device = this.state.device;
+        const unknown = device !== undefined && !deviceEmulation(device, KnownDevices)
+            ? [
+                {
+                    what: "device",
+                    asked: device,
+                    observed: "ignored, no device by that name",
+                    note: noSuchDevice(device, KnownDevices),
+                },
+            ]
+            : [];
+        await this.apply();
+        // A feature the browser turned down is reported beside the
+        // fields this build never had, since to the caller they are the
+        // same disappointment.
+        const turnedDown = this.refused.map((feature) => ({
+            what: feature,
+            asked: "emulated",
+            observed: "refused by this browser",
+            note: `this Chrome does not know ${feature}, so it has been ` +
+                "dropped rather than retried on every navigation",
+        }));
+        // A viewport change reflows the page and a real application
+        // re-renders for it, so the same wait a navigation gets applies
+        // here: without it the next read describes the old layout.
+        await this.hooks.settle();
+        const observed = await this.observe();
+        // Emulating before navigating is the order this tool asks for,
+        // and it used to be punished for it. There is nothing laid out
+        // on a blank page, so the width comes back as the desktop
+        // default and ontouchstart has no document to be installed on:
+        // two alarming gaps that both come right the moment a real page
+        // loads. Reporting them as divergences sent me measuring the
+        // wrong thing twice. What the page cannot answer yet is not a
+        // discrepancy, so it is held back and said plainly instead.
+        const blank = this.wires.page().url() === "about:blank";
+        const measured = blank
+            ? [
+                {
+                    what: "the page",
+                    asked: "nothing loaded yet",
+                    observed: "about:blank",
+                    note: "layout and touch cannot be checked until a document " +
+                        "is loaded; navigate, then read status to confirm",
+                },
+            ]
+            : divergences(this.effective, observed);
+        return {
+            asked: this.state,
+            observed,
+            // Compared against the effective state, since a device is
+            // the reason a viewport is what it is.
+            gaps: [...ignored, ...unknown, ...turnedDown, ...measured],
+        };
+    }
+    /**
+     * Put the standing intent to the browser again, after arriving.
+     *
+     * Kept, though the driver now carries emulation across a
+     * navigation itself, because this same path restores a session
+     * after a crash and because it costs nothing when nothing is
+     * being emulated.
+     *
+     * What is gone is what used to sit under here: a second
+     * application on the document-arrival event, and a loop that
+     * asked the page whether the first two had worked. Both were
+     * workarounds for sending emulation on a protocol session of our
+     * own, and neither made it certain. Removing the cause removed
+     * the need for either, measured twelve times out of twelve
+     * through the shape that used to fail one time in three.
+     */
+    async reassert() {
+        if (Object.keys(this.state).length === 0)
+            return;
+        await this.apply();
+    }
+    /**
+     * How the pretence and the page disagree right now.
+     *
+     * Checked rather than recited. What is being emulated is what
+     * the session asked for, and a navigation can quietly drop part
+     * of it, so the page is asked whether it agrees before status
+     * says it is pretending to be a phone. A blank page has nothing
+     * laid out to check, so it reports no gaps rather than fake ones.
+     */
+    async currentGaps() {
+        const blank = this.wires.page().url() === "about:blank";
+        if (blank || Object.keys(this.state).length === 0)
+            return [];
+        return divergences(this.effective, await this.observe());
+    }
+    /**
+     * The standing intent with any named device resolved.
+     *
+     * A device is shorthand for a viewport and a touch screen, and
+     * anything the caller said explicitly outranks it: asking for a
+     * phone and a width means the phone with that width.
+     */
+    get effective() {
+        const asked = this.state;
+        if (asked.device === undefined)
+            return asked;
+        const fromDevice = deviceEmulation(asked.device, KnownDevices);
+        if (!fromDevice)
+            return asked;
+        return { ...fromDevice, ...asked };
+    }
+    /**
+     * Put the media features to the browser, dropping any it refuses.
+     *
+     * The set goes over in one call and Chrome rejects the whole set on
+     * the first feature it does not recognise, so a feature this build
+     * of Chrome has never heard of would otherwise take every working
+     * feature with it. Worse, the intent is replayed on navigation, so
+     * a single refusal became an error on later calls that asked for
+     * nothing at all: one real session failed a plain navigate with
+     * "Unsupported media feature: prefers-contrast" long after the
+     * emulate call that set it.
+     *
+     * Dropping is per feature and one at a time, because the message
+     * names only the first offender.
+     */
+    async applyMediaFeatures(page, state) {
+        let wanted = state;
+        for (;;) {
+            try {
+                await page.emulateMediaFeatures([...mediaFeaturesOf(wanted)]);
+                return;
+            }
+            catch (failure) {
+                const feature = refusedFeature(failure instanceof Error ? failure.message : String(failure));
+                const left = feature ? withoutFeature(wanted, feature) : wanted;
+                // Nothing to drop means the failure was not a refusal, or
+                // names something this cannot map, and retrying would spin.
+                if (!feature || left === wanted)
+                    throw failure;
+                if (!this.refused.includes(feature))
+                    this.refused.push(feature);
+                // The intent itself gives the feature up, so no later
+                // navigation replays it.
+                this.state = withoutFeature(this.state, feature);
+                wanted = left;
+            }
+        }
+    }
+    /** Put the whole standing intent to the browser. */
+    async apply() {
+        const state = this.effective;
+        const page = this.wires.page();
+        // Every one of these goes through the driver rather than the
+        // protocol, and that is the whole fix for emulation not
+        // surviving a navigation.
+        //
+        // A cross-process navigation swaps the target's protocol
+        // session. The driver listens for that swap and puts its whole
+        // emulation state to the new session; commands sent on a session
+        // of our own just went to the renderer being replaced. Device
+        // metrics are held browser-side and came through regardless,
+        // which is why this looked like a touch-only fault: touch is a
+        // flag in the renderer, so the page quietly stopped being a
+        // phone while the report still said it was one.
+        await page.emulateMediaType(state.media);
+        await this.applyMediaFeatures(page, state);
+        await page.emulateVisionDeficiency(state.vision ?? "none");
+        // Screen, touch and user agent go through the driver rather
+        // than the protocol, which is the whole reason they now survive
+        // a navigation.
+        await page.setViewport(state.viewport
+            ? {
+                width: state.viewport.width,
+                height: state.viewport.height,
+                deviceScaleFactor: state.viewport.deviceScaleFactor ?? 1,
+                isMobile: state.viewport.mobile ?? false,
+                hasTouch: state.touch ?? false,
+            }
+            : // Null is how the driver spells "stop overriding", and
+                // touch has to be asked for separately when there is no
+                // viewport to carry it.
+                null);
+        // The driver asks for a touch screen without saying how many
+        // fingers, which Chrome reads as one; a real phone reports five,
+        // so that is asked for on top.
+        //
+        // Sent every time, including to turn it off. Sending it only
+        // when touch was wanted left a phone that could not stop being
+        // one: this override rides on our own protocol session, the
+        // driver's disable rides on its own, and one session cannot
+        // clear the other's. So the viewport and the user agent went
+        // back to the desktop while the touch screen stayed.
+        await this.wires.cdp().send("Emulation.setTouchEmulationEnabled", {
+            enabled: state.touch ?? false,
+            ...(state.touch ? { maxTouchPoints: TOUCH_POINTS } : {}),
+        });
+        // An empty string is how this one is taken off again.
+        await page.setUserAgent(state.userAgent ?? "");
+        await page.emulateCPUThrottling(state.cpuThrottle ?? null);
+        // Passed undefined rather than skipped, because an override
+        // with no arguments is how one gets taken off again. Guarding
+        // these on being defined meant nothing could ever be cleared: a
+        // session that emulated Tokyo once stayed in Tokyo for its life,
+        // quietly recolouring every later reading.
+        await page.emulateTimezone(state.timezone);
+        await page.emulateLocale(state.locale);
+        if (state.geolocation === undefined) {
+            await this.wires.cdp().send("Emulation.clearGeolocationOverride");
+        }
+        else {
+            await this.wires.cdp().send("Emulation.setGeolocationOverride", {
+                latitude: state.geolocation.latitude,
+                longitude: state.geolocation.longitude,
+                accuracy: state.geolocation.accuracy ?? GEOLOCATION_ACCURACY,
+            });
+        }
+    }
+    /** What the page says it is experiencing. */
+    async observe() {
+        const { result } = await this.wires.cdp().send("Runtime.evaluate", {
+            expression: ENVIRONMENT_PROBE,
+            returnByValue: true,
+        });
+        return result.value;
+    }
+}

package/dist/web/session/recording.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Who is tracing, and the fact that only one of us can be.
+ *
+ * Tracing is a browser-wide facility rather than a per-page one.
+ * Measured: a second Tracing.start is refused with "Tracing has
+ * already been started (possibly in another tab)", and a recording
+ * begun for one session contains another session's work. So the
+ * limit is real, and it is shared.
+ *
+ * That makes two things this module's job. It hands out the single
+ * permit, so a second session is told no rather than crashing into
+ * a protocol error. And it remembers who holds it, because every
+ * page in the browser is paying for a recording while it runs and
+ * a reader wondering why should be able to find out.
+ */
+import type { TraceProfile } from "../perf/trace.js";
+/** A recording in progress, and who asked for it. */
+export interface Recording {
+    /** The session that started it. */
+    readonly session: string;
+    readonly profiles: readonly TraceProfile[];
+    readonly startedAt: Date;
+}
+/** Why a recording could not be started. */
+export interface RecordingRefused {
+    readonly refusal: string;
+    /** The recording already running. */
+    readonly held: Recording;
+}
+/**
+ * Claim the single recording permit.
+ *
+ * Refuses rather than waiting. A traced action that silently
+ * queued behind another session's recording would report a
+ * duration that included the wait, which is a worse answer than
+ * being told the facility is busy.
+ */
+export declare function claimRecording(session: string, profiles: readonly TraceProfile[]): Recording | RecordingRefused;
+/** Release the permit. Safe to call when nothing is held. */
+export declare function releaseRecording(): void;
+/** The recording in progress, for any session that wants to report it. */
+export declare function recordingInProgress(): Recording | undefined;
+/**
+ * How a session's status should mention a live recording.
+ *
+ * Every session says this, not just the one that started it,
+ * because every page in the browser is being instrumented while
+ * it runs. A reader looking at an unexpectedly slow page should
+ * find the reason in front of them.
+ */
+export declare function describeRecording(recording: Recording | undefined, viewer: string): string | undefined;

package/dist/web/session/recording.js

@@ -0,0 +1,64 @@
+/**
+ * Who is tracing, and the fact that only one of us can be.
+ *
+ * Tracing is a browser-wide facility rather than a per-page one.
+ * Measured: a second Tracing.start is refused with "Tracing has
+ * already been started (possibly in another tab)", and a recording
+ * begun for one session contains another session's work. So the
+ * limit is real, and it is shared.
+ *
+ * That makes two things this module's job. It hands out the single
+ * permit, so a second session is told no rather than crashing into
+ * a protocol error. And it remembers who holds it, because every
+ * page in the browser is paying for a recording while it runs and
+ * a reader wondering why should be able to find out.
+ */
+let current;
+/**
+ * Claim the single recording permit.
+ *
+ * Refuses rather than waiting. A traced action that silently
+ * queued behind another session's recording would report a
+ * duration that included the wait, which is a worse answer than
+ * being told the facility is busy.
+ */
+export function claimRecording(session, profiles) {
+    if (current !== undefined) {
+        const since = current.startedAt.toISOString().slice(11, 19);
+        return {
+            refusal: `Session ${current.session} has been recording a trace since ` +
+                `${since}. The browser allows one at a time, so this one ` +
+                "cannot start until that finishes.",
+            held: current,
+        };
+    }
+    current = { session, profiles, startedAt: new Date() };
+    return current;
+}
+/** Release the permit. Safe to call when nothing is held. */
+export function releaseRecording() {
+    current = undefined;
+}
+/** The recording in progress, for any session that wants to report it. */
+export function recordingInProgress() {
+    return current;
+}
+/**
+ * How a session's status should mention a live recording.
+ *
+ * Every session says this, not just the one that started it,
+ * because every page in the browser is being instrumented while
+ * it runs. A reader looking at an unexpectedly slow page should
+ * find the reason in front of them.
+ */
+export function describeRecording(recording, viewer) {
+    if (recording === undefined)
+        return undefined;
+    const whose = recording.session === viewer
+        ? "this session"
+        : `session ${recording.session}`;
+    return (`Tracing is on, started by ${whose} at ` +
+        `${recording.startedAt.toISOString().slice(11, 19)} ` +
+        `(${recording.profiles.join(" and ")}). Every page in the browser ` +
+        "is being instrumented while it runs.");
+}

package/dist/web/session/settling.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Waiting for a page to stop changing, so a read that follows
+ * describes where the page ended up rather than where it was.
+ *
+ * The DOM and the network each miss a case the other catches,
+ * so both have to hold at once, and since satisfying one can
+ * disturb the other they are rechecked together until they
+ * agree or the budget runs out.
+ */
+import type { NetworkRequest } from "../telemetry/index.js";
+import { type Settled } from "../wait/index.js";
+import type { SessionWires } from "./wires.js";
+/** The wait between a change and an honest reading of it. */
+export declare class PageSettler {
+    private readonly wires;
+    /** The request log, for what may yet rewrite the page. */
+    private readonly requests;
+    /** What the last settle saw, so a reader can qualify its answer. */
+    private last;
+    constructor(wires: SessionWires, 
+    /** The request log, for what may yet rewrite the page. */
+    requests: () => readonly NetworkRequest[]);
+    /** What the last settle saw, for a reader that wants to say so. */
+    get lastSeen(): Settled | undefined;
+    /**
+     * Wait for the page to stop changing.
+     *
+     * Returns what it found instead of throwing on a page that never
+     * settles: something that animates or polls for ever is still
+     * worth reading, as long as the answer does not pretend it was
+     * final.
+     *
+     * The budget is a parameter rather than only a constant because
+     * what it has to exceed is the quiet interval, and both stretch
+     * on a machine under load. A caller that needs "this page is
+     * quiet" to be answered reliably has to be able to say how long
+     * it is willing to wait for that, rather than inheriting a number
+     * chosen for an interactive read. Two browser tests asserting
+     * exactly that property failed intermittently for want of this.
+     */
+    settle(budgetMs?: number): Promise<Settled>;
+}

package/dist/web/session/settling.js

@@ -0,0 +1,104 @@
+/**
+ * Waiting for a page to stop changing, so a read that follows
+ * describes where the page ended up rather than where it was.
+ *
+ * The DOM and the network each miss a case the other catches,
+ * so both have to hold at once, and since satisfying one can
+ * disturb the other they are rechecked together until they
+ * agree or the budget runs out.
+ */
+import { inFlight, SETTLE_BUDGET_MS, SETTLE_QUIET_MS, settleSource, } from "../wait/index.js";
+/**
+ * Whether the settle probe came back with what it promised.
+ *
+ * Page-side results arrive as unknown, and a navigation landing
+ * mid-evaluate resolves with nothing at all, so this is narrowed
+ * rather than asserted.
+ */
+function isSettled(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.quiet === "boolean" &&
+        typeof candidate.waitedMs === "number" &&
+        typeof candidate.mutations === "number");
+}
+/** The wait between a change and an honest reading of it. */
+export class PageSettler {
+    wires;
+    requests;
+    /** What the last settle saw, so a reader can qualify its answer. */
+    last;
+    constructor(wires, 
+    /** The request log, for what may yet rewrite the page. */
+    requests) {
+        this.wires = wires;
+        this.requests = requests;
+    }
+    /** What the last settle saw, for a reader that wants to say so. */
+    get lastSeen() {
+        return this.last;
+    }
+    /**
+     * Wait for the page to stop changing.
+     *
+     * Returns what it found instead of throwing on a page that never
+     * settles: something that animates or polls for ever is still
+     * worth reading, as long as the answer does not pretend it was
+     * final.
+     *
+     * The budget is a parameter rather than only a constant because
+     * what it has to exceed is the quiet interval, and both stretch
+     * on a machine under load. A caller that needs "this page is
+     * quiet" to be answered reliably has to be able to say how long
+     * it is willing to wait for that, rather than inheriting a number
+     * chosen for an interactive read. Two browser tests asserting
+     * exactly that property failed intermittently for want of this.
+     */
+    async settle(budgetMs = SETTLE_BUDGET_MS) {
+        const started = Date.now();
+        let mutations = 0;
+        let quiet = false;
+        // The DOM and the network each miss a case the other catches.
+        //
+        // A client-side navigation waiting on a fetch touches nothing
+        // for as long as the request takes, so the DOM goes quiet and
+        // the page then changes completely a moment later: pressing
+        // Enter on a search box answered with the pre-search page for
+        // exactly this reason. Meanwhile Chrome's network idle fires
+        // before an app that already has its data has rendered any of
+        // it.
+        //
+        // So both have to hold at once, and since satisfying one can
+        // disturb the other, they are rechecked together until they
+        // agree or the budget runs out.
+        while (Date.now() - started < budgetMs) {
+            const left = budgetMs - (Date.now() - started);
+            const outcome = await this.wires
+                .page()
+                .evaluate(settleSource(SETTLE_QUIET_MS, left))
+                .catch(() => undefined);
+            if (isSettled(outcome)) {
+                mutations += outcome.mutations;
+                quiet = outcome.quiet;
+            }
+            else {
+                // A navigation landed mid-evaluate, which is itself the
+                // change we are waiting out. Go round again.
+                quiet = false;
+            }
+            if (!quiet)
+                continue;
+            if (inFlight(this.requests()).length === 0)
+                break;
+            // Something is outstanding that may yet rewrite the page.
+            quiet = false;
+        }
+        this.last = {
+            quiet,
+            waitedMs: Date.now() - started,
+            mutations,
+        };
+        return this.last;
+    }
+}

package/dist/web/session/shaping.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Bending the network a session sees: mocked replies, blocked
+ * requests and throttled throughput.
+ *
+ * Interception is only attached while there is a rule to apply.
+ * Every paused request has to be answered or the page waits on
+ * it forever, so an interceptor with nothing to say is a
+ * liability rather than a neutral bystander.
+ */
+import { type NetworkRule, type ThrottleConditions } from "../environment/index.js";
+import type { SessionWires } from "./wires.js";
+/** The rules and throttle a session's network answers to. */
+export declare class NetworkShaper {
+    private readonly wires;
+    /** Requests being mocked or blocked, first match winning. */
+    private rules;
+    /** How slow the network is being made, if at all. */
+    private throttle?;
+    /** Whether the interceptor is currently attached. */
+    private intercepting;
+    constructor(wires: SessionWires);
+    /** How the network is currently being bent. */
+    get current(): {
+        rules: readonly NetworkRule[];
+        throttle: ThrottleConditions | undefined;
+    };
+    /**
+     * Mock a reply, block a request, slow it all down, or stop
+     * pretending.
+     */
+    shape(change: {
+        rules?: readonly NetworkRule[];
+        /** Conditions, or the name of a profile such as slow-3g. */
+        throttle?: ThrottleConditions | string;
+        clear?: boolean;
+    }): Promise<{
+        rules: readonly NetworkRule[];
+        throttle: ThrottleConditions | undefined;
+    }>;
+    /**
+     * Decide what a paused request gets.
+     *
+     * Whatever happens, it is answered. A handler that throws and
+     * says nothing leaves the page waiting forever on a request
+     * the browser has already stopped for us.
+     */
+    private answerPaused;
+}