@jitsusama/agentic-harness.core 0.1.0

package/dist/web/session/shaping.js

@@ -0,0 +1,113 @@
+/**
+ * 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 { resolveThrottle, ruleFor, } from "../environment/index.js";
+/** The rules and throttle a session's network answers to. */
+export class NetworkShaper {
+    wires;
+    /** Requests being mocked or blocked, first match winning. */
+    rules = [];
+    /** How slow the network is being made, if at all. */
+    throttle;
+    /** Whether the interceptor is currently attached. */
+    intercepting = false;
+    constructor(wires) {
+        this.wires = wires;
+    }
+    /** How the network is currently being bent. */
+    get current() {
+        return { rules: this.rules, throttle: this.throttle };
+    }
+    /**
+     * Mock a reply, block a request, slow it all down, or stop
+     * pretending.
+     */
+    async shape(change) {
+        await this.wires.ready();
+        if (change.clear) {
+            this.rules = [];
+            this.throttle = undefined;
+        }
+        else {
+            if (change.rules)
+                this.rules = [...this.rules, ...change.rules];
+            // Resolved here so a profile name is as good as the conditions
+            // it stands for. Passed a name, this used to read the fields
+            // it wanted off a string, find none, and shape nothing at all.
+            if (change.throttle)
+                this.throttle = resolveThrottle(change.throttle);
+        }
+        await this.wires.cdp().send("Network.emulateNetworkConditions", {
+            offline: this.throttle?.offline ?? false,
+            latency: this.throttle?.latency ?? 0,
+            // The protocol reads -1 as no limit, which is not the same
+            // as zero, and zero would mean nothing may pass at all.
+            downloadThroughput: this.throttle?.download || -1,
+            uploadThroughput: this.throttle?.upload || -1,
+        });
+        if (this.rules.length === 0) {
+            if (this.intercepting) {
+                await this.wires.cdp().send("Fetch.disable");
+                this.intercepting = false;
+            }
+        }
+        else if (!this.intercepting) {
+            this.wires.cdp().on("Fetch.requestPaused", (event) => {
+                void this.answerPaused(event);
+            });
+            await this.wires
+                .cdp()
+                .send("Fetch.enable", { patterns: [{ urlPattern: "*" }] });
+            this.intercepting = true;
+        }
+        return { rules: this.rules, throttle: this.throttle };
+    }
+    /**
+     * 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.
+     */
+    async answerPaused(event) {
+        const rule = ruleFor(this.rules, event.request.url);
+        try {
+            if (rule?.action === "block") {
+                await this.wires.cdp().send("Fetch.failRequest", {
+                    requestId: event.requestId,
+                    errorReason: (rule.reason ??
+                        "BlockedByClient"),
+                });
+                return;
+            }
+            if (rule?.action === "mock") {
+                await this.wires.cdp().send("Fetch.fulfillRequest", {
+                    requestId: event.requestId,
+                    responseCode: rule.status ?? 200,
+                    responseHeaders: [
+                        {
+                            name: "content-type",
+                            value: rule.contentType ?? "text/plain",
+                        },
+                    ],
+                    body: Buffer.from(rule.body ?? "").toString("base64"),
+                });
+                return;
+            }
+            await this.wires.cdp().send("Fetch.continueRequest", {
+                requestId: event.requestId,
+            });
+        }
+        catch {
+            // The request may already be resolved, or the page may have
+            // navigated out from under it. Either way there is nothing
+            // left to answer and nothing worth reporting.
+        }
+    }
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Which source map belongs to which file, and what that makes
+ * of a generated position.
+ *
+ * Chrome reports the map's URL and stops there. It does no
+ * resolving of its own, because in a browser that is the
+ * devtools front end's job, so a session that wants authored
+ * positions has to keep the note itself. The note is all that
+ * is kept eagerly: most sessions never throw, and fetching every
+ * map a page mentions would cost a request per bundle to answer
+ * a question nobody asked.
+ */
+import type { EvalFrame } from "../evaluate/index.js";
+import { type AuthoredPosition } from "../sourcemap/index.js";
+import type { SessionWires } from "./wires.js";
+/** The maps a page has declared, fetched only when asked after. */
+export declare class SourceMapStore {
+    private readonly wires;
+    /** Which map each script and stylesheet named, unresolved. */
+    private readonly mapUrls;
+    /** Maps already fetched. A null records one that will not come. */
+    private readonly maps;
+    /** Which URL each stylesheet id belongs to. */
+    private readonly sheetUrls;
+    constructor(wires: SessionWires);
+    /**
+     * Note which map belongs to which script and stylesheet, from
+     * here on.
+     */
+    listen(): Promise<void>;
+    /**
+     * Tell each frame of a stack where it was written.
+     *
+     * A frame with no map keeps its generated position rather than
+     * being dropped: half a stack is worse than a raw one.
+     */
+    resolveFrames(frames: readonly EvalFrame[]): Promise<readonly EvalFrame[]>;
+    /**
+     * Where a stylesheet position was authored, or nothing when no
+     * map covers it.
+     *
+     * The cascade names its stylesheet by protocol id, so the join
+     * from id to URL to map happens here, where all three notes
+     * live.
+     */
+    authoredForSheet(styleSheetId: string, position: {
+        readonly line: number;
+        readonly column: number;
+    }): Promise<AuthoredPosition | undefined>;
+    /**
+     * Fetch and decode the map for a file, once.
+     *
+     * The fetch goes through the page rather than through node,
+     * because the page is already on the right origin with the
+     * right cookies. A map behind a login is unreachable any
+     * other way.
+     *
+     * A failure is cached as firmly as a success. A map that 404s
+     * will still 404 on the next frame of the same stack, and
+     * asking again once per frame is how one bad path turns into
+     * a dozen requests.
+     */
+    private mapFor;
+}

package/dist/web/session/sourcemaps.js

@@ -0,0 +1,135 @@
+/**
+ * Which source map belongs to which file, and what that makes
+ * of a generated position.
+ *
+ * Chrome reports the map's URL and stops there. It does no
+ * resolving of its own, because in a browser that is the
+ * devtools front end's job, so a session that wants authored
+ * positions has to keep the note itself. The note is all that
+ * is kept eagerly: most sessions never throw, and fetching every
+ * map a page mentions would cost a request per bundle to answer
+ * a question nobody asked.
+ */
+import { authoredPosition, parseSourceMap, resolveMapUrl, } from "../sourcemap/index.js";
+/** The maps a page has declared, fetched only when asked after. */
+export class SourceMapStore {
+    wires;
+    /** Which map each script and stylesheet named, unresolved. */
+    mapUrls = new Map();
+    /** Maps already fetched. A null records one that will not come. */
+    maps = new Map();
+    /** Which URL each stylesheet id belongs to. */
+    sheetUrls = new Map();
+    constructor(wires) {
+        this.wires = wires;
+    }
+    /**
+     * Note which map belongs to which script and stylesheet, from
+     * here on.
+     */
+    async listen() {
+        this.wires.cdp().on("Debugger.scriptParsed", (event) => {
+            if (!event.sourceMapURL || !event.url)
+                return;
+            this.mapUrls.set(event.url, event.sourceMapURL);
+        });
+        this.wires.cdp().on("CSS.styleSheetAdded", (event) => {
+            const { sourceURL, sourceMapURL, styleSheetId } = event.header;
+            if (!sourceMapURL || !sourceURL)
+                return;
+            this.mapUrls.set(sourceURL, sourceMapURL);
+            // The cascade names a stylesheet by id, not by URL, so the
+            // two have to be joined here while both are in hand.
+            this.sheetUrls.set(styleSheetId, sourceURL);
+        });
+        await this.wires.cdp().send("Debugger.enable");
+    }
+    /**
+     * Tell each frame of a stack where it was written.
+     *
+     * A frame with no map keeps its generated position rather than
+     * being dropped: half a stack is worse than a raw one.
+     */
+    async resolveFrames(frames) {
+        return Promise.all(frames.map(async (frame) => {
+            if (!frame.url)
+                return frame;
+            const map = await this.mapFor(frame.url);
+            if (!map)
+                return frame;
+            const authored = authoredPosition(map, {
+                line: frame.lineNumber,
+                column: frame.columnNumber,
+            });
+            return authored === undefined ? frame : { ...frame, authored };
+        }));
+    }
+    /**
+     * Where a stylesheet position was authored, or nothing when no
+     * map covers it.
+     *
+     * The cascade names its stylesheet by protocol id, so the join
+     * from id to URL to map happens here, where all three notes
+     * live.
+     */
+    async authoredForSheet(styleSheetId, position) {
+        const url = this.sheetUrls.get(styleSheetId);
+        if (url === undefined)
+            return undefined;
+        const map = await this.mapFor(url);
+        if (!map)
+            return undefined;
+        return authoredPosition(map, position);
+    }
+    /**
+     * Fetch and decode the map for a file, once.
+     *
+     * The fetch goes through the page rather than through node,
+     * because the page is already on the right origin with the
+     * right cookies. A map behind a login is unreachable any
+     * other way.
+     *
+     * A failure is cached as firmly as a success. A map that 404s
+     * will still 404 on the next frame of the same stack, and
+     * asking again once per frame is how one bad path turns into
+     * a dozen requests.
+     */
+    async mapFor(fileUrl) {
+        const cached = this.maps.get(fileUrl);
+        if (cached !== undefined)
+            return cached ?? undefined;
+        const declared = this.mapUrls.get(fileUrl);
+        if (!declared)
+            return undefined;
+        const located = resolveMapUrl(fileUrl, declared);
+        if (!located) {
+            this.maps.set(fileUrl, null);
+            return undefined;
+        }
+        let json;
+        if (located.kind === "inline") {
+            json = located.json;
+        }
+        else {
+            try {
+                const response = await this.wires.cdp().send("Runtime.evaluate", {
+                    expression: `fetch(${JSON.stringify(located.url)})
+						.then((r) => (r.ok ? r.text() : null))
+						.catch(() => null)`,
+                    awaitPromise: true,
+                    returnByValue: true,
+                });
+                const body = response.result.value;
+                if (typeof body === "string")
+                    json = body;
+            }
+            catch {
+                // A page that navigated away mid-fetch is not a reason
+                // to lose the stack we were annotating.
+            }
+        }
+        const parsed = json === undefined ? undefined : parseSourceMap(json);
+        this.maps.set(fileUrl, parsed ?? null);
+        return parsed;
+    }
+}

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

@@ -0,0 +1,219 @@
+/**
+ * Everything a session overhears: console lines, exceptions,
+ * requests, dialogs, navigations, downloads and live-region
+ * announcements, each kept from the moment the tab opens.
+ *
+ * One keeper for all of it because the buffers share a life:
+ * they are installed together at open, reinstalled together
+ * after a crash, and recited together by status. The session
+ * decides when to listen; this decides what is heard and how it
+ * is kept.
+ */
+import { type Announcement } from "../a11y/index.js";
+import { type DialogEvent, type DialogPolicy, type DownloadRecord, type LifecycleEvent, type LogEntry, type NetworkRequest, type Recorded, type SocketRecord } from "../telemetry/index.js";
+import type { SessionWires } from "./wires.js";
+/** What the listeners need from the session beyond the browser. */
+interface TelemetryHooks {
+    /** Start replacing a crashed tab the moment it is announced. */
+    readonly onCrash: () => void;
+    /** Where downloads should land. */
+    readonly downloadDir: () => string;
+    /** Note a landed download in the session's ledger. */
+    readonly keep: (path: string) => void;
+}
+/** The buffers a session fills by listening, and their readers. */
+export declare class SessionTelemetry {
+    private readonly wires;
+    private readonly hooks;
+    /** What the page announced, oldest first, within its budget. */
+    private readonly announcements;
+    /**
+     * What the browser said about each nominated region, keyed by
+     * document epoch and registry index. Null means the browser
+     * ruled it not live.
+     */
+    private readonly livenessByRegion;
+    /** Everything the page has said since it opened. */
+    private readonly logBuffer;
+    /** Every request the page has made since it opened. */
+    private readonly requestLog;
+    /**
+     * Every websocket event, bounded like everything else here.
+     *
+     * A chatty socket can push frames faster than anything reads
+     * them, so this is the same ring buffer the logs use: the most
+     * recent within a budget, and a count of what it had to drop.
+     */
+    private readonly socketLog;
+    /** Every dialog the page has raised, and how it was answered. */
+    private readonly dialogLog;
+    /** Where the page has been, and whether it survived. */
+    private lifecycleLog?;
+    /** How dialogs get answered while nobody is watching. */
+    private dialogPolicy;
+    /** Files the page has handed back. */
+    private readonly downloadLog;
+    /**
+     * Wall seconds minus the protocol's monotonic seconds.
+     *
+     * The protocol's clock counts from when the browser started,
+     * so it reads around 586,000 while ours reads 1.78 billion.
+     * Comparing a recorded request against our own clock without
+     * this correction does not merely give a wrong answer, it
+     * gives a confidently idle one, because every request looks
+     * like it finished aeons ago.
+     */
+    private clockOffset?;
+    /**
+     * Announcements still being ruled on. Candidates resolve one
+     * at a time along this chain, so a slow lookup cannot overtake
+     * a fast one and record two out of the order they were said.
+     */
+    private pending;
+    constructor(wires: SessionWires, hooks: TelemetryHooks);
+    /**
+     * Listen for everything the page says, from the moment it
+     * opens.
+     *
+     * Three sources, because no one of them is complete. The
+     * console is what the page chose to say; exceptions are what
+     * it did not choose; and the browser's own log carries what
+     * the page never hears at all, a resource that failed to load
+     * or a request the browser refused.
+     */
+    listenForLogs(): Promise<void>;
+    /**
+     * Watch every request the page makes.
+     *
+     * The protocol reports one request as four separate events
+     * over its life, so the recorder does the reassembly and this
+     * only relabels the CDP names it consumes.
+     */
+    listenForRequests(): Promise<void>;
+    /**
+     * Answer dialogs, because an unanswered one stops the page.
+     *
+     * Until something replies, no script runs and no action lands,
+     * so there is no such thing as declining to have a policy.
+     * Every answer given is recorded, since a dismissed confirm
+     * changes what the page did next and the reader has to be able
+     * to see that it happened.
+     */
+    listenForDialogs(): Promise<void>;
+    /** Decide how dialogs will be answered from here on. */
+    setDialogPolicy(policy: DialogPolicy): void;
+    /** How dialogs are currently answered. */
+    get dialogs(): {
+        readonly policy: DialogPolicy;
+        readonly seen: readonly DialogEvent[];
+    };
+    /** Every request the page has made. */
+    requests(): readonly NetworkRequest[];
+    /**
+     * The body of one recorded reply, fetched on demand.
+     *
+     * Bodies are not captured as they stream past: most are never
+     * asked for, and holding every one would cost far more memory
+     * than the rest of the session put together. Chrome keeps them
+     * for the current document, so this asks only when asked.
+     */
+    bodyOf(requestId: string): Promise<{
+        body: string;
+        base64Encoded: boolean;
+    } | undefined>;
+    /**
+     * What the page has said, from a cursor onward.
+     *
+     * The buffer survives navigation on purpose: a message logged
+     * just before a redirect is often the one that explains it.
+     */
+    logs(since?: number): {
+        readonly entries: readonly Recorded<LogEntry>[];
+        readonly dropped: number;
+        readonly cursor: number;
+    };
+    /**
+     * Watch where the page goes, and notice if it dies.
+     *
+     * The crash half is not optional. After the tab crashes every
+     * call against it hangs rather than failing, measured against
+     * a deliberately crashed tab, so a session that waited to find
+     * out lazily would simply stop responding. Recovery therefore
+     * happens the moment the crash is announced.
+     */
+    listenForLifecycle(): Promise<void>;
+    /**
+     * Point the lifecycle handlers at a replacement tab.
+     *
+     * A new tab is a new main frame, and a recorder still watching
+     * the old id would ignore every navigation from here on while
+     * looking perfectly healthy.
+     */
+    readoptLifecycle(frameId: string): void;
+    /** Point the lifecycle handlers at the current protocol channel. */
+    private attachLifecycle;
+    /**
+     * Catch files the page hands back.
+     *
+     * The behaviour has to be set against this session's browser
+     * context, not merely the connection. Set without the context
+     * id, Chrome cancels every download in a non-default context
+     * and writes nothing, which looks exactly like a page that
+     * never offered a file.
+     */
+    listenForDownloads(): Promise<void>;
+    /** Files the page has handed back. */
+    downloads(): readonly DownloadRecord[];
+    /** Every websocket conversation, folded from its events. */
+    sockets(): readonly SocketRecord[];
+    /** Socket events dropped to stay within the buffer's budget. */
+    get socketFramesDropped(): number;
+    /** Where the page has been. */
+    get history(): readonly LifecycleEvent[];
+    /**
+     * Now, on the protocol's clock, so it can be compared with
+     * what requests carry.
+     *
+     * Before any request has been seen there is no offset to
+     * apply, but there are also no requests to compare against,
+     * so the figure cannot mislead anyone.
+     */
+    protocolNow(): number;
+    /**
+     * Start hearing what the page says. The binding is installed
+     * once and survives navigation; the observer is registered
+     * for every document, so announcements made during load are
+     * caught too.
+     *
+     * Candidates arrive faster than they can be ruled on, so they
+     * are resolved one at a time along a chain. Resolving them
+     * concurrently would let a slow lookup overtake a fast one and
+     * record two announcements out of the order they were said.
+     */
+    listenForAnnouncements(): Promise<void>;
+    /**
+     * What the page has announced since a cursor, with the cursor
+     * to read from next time and how many were dropped.
+     */
+    heard(since?: number): Promise<{
+        entries: readonly Recorded<Announcement>[];
+        cursor: number;
+        dropped: number;
+    }>;
+    /**
+     * Record a nominated change only if the browser calls its
+     * region live, at the politeness the browser computed.
+     */
+    private recordIfLive;
+    /**
+     * Ask the browser what it computed for a nominated region.
+     *
+     * The answer is cached per document: liveness is a property of
+     * the markup, and a navigation starts a new registry with a
+     * new epoch, so a stale entry can never be read back.
+     */
+    private politenessOf;
+    /** Read a region's computed live politeness from the AX tree. */
+    private readLiveness;
+}
+export {};