@jitsusama/agentic-harness.core 0.1.0

package/dist/web/perf/trace.js

@@ -0,0 +1,429 @@
+/**
+ * What the page was doing, and what caused what.
+ *
+ * A profile says which functions the time went into. It cannot say
+ * that a click installed a timer, that the timer fired forty
+ * milliseconds late, or that two fetches were in flight together
+ * and the second answered first. Those are questions about order
+ * and causation rather than cost, and the only place the browser
+ * answers them is its own trace stream.
+ *
+ * A trace is a recording rather than a recorder. Chrome hands
+ * nothing over while it runs and delivers everything in a burst
+ * when it stops, which is measured and is why this module folds a
+ * finished capture rather than following a live one.
+ *
+ * Two things about the stream shape are worth knowing before
+ * reading the code. Timestamps and durations are microseconds.
+ * And only some events say which frame they belong to: resource
+ * events carry a request id instead, and frame-pipeline events
+ * carry a layer tree, so placing those takes a join and a
+ * process, not a lookup.
+ */
+import { count } from "../../ui/count.js";
+/**
+ * The categories each profile turns on.
+ *
+ * Naming no categories is never right: measured, the default set
+ * costs about five megabytes a second and is almost entirely
+ * Chrome talking to itself about mojo messages and task queues.
+ * The sets below are the page's own story, at about sixty
+ * kilobytes a second for async and three hundred and forty with
+ * frames.
+ */
+export const TRACE_CATEGORIES = {
+    async: ["devtools.timeline", "v8.execute", "latencyInfo"],
+    frames: ["devtools.timeline", "disabled-by-default-devtools.timeline.frame"],
+};
+/** The categories to ask for, with nothing repeated. */
+export function categoriesFor(profiles) {
+    const wanted = new Set();
+    for (const profile of profiles) {
+        for (const category of TRACE_CATEGORIES[profile])
+            wanted.add(category);
+    }
+    return [...wanted];
+}
+/** Sixteen milliseconds is the budget for sixty frames a second. */
+const FRAME_BUDGET_MS = 1000 / 60;
+/** How many kinds of work to name before it is a data dump. */
+const TOP_TASKS = 12;
+const US_PER_MS = 1000;
+/** Microseconds to milliseconds, rounded to whole milliseconds. */
+const ms = (microseconds) => Math.round(microseconds / US_PER_MS);
+/** The payload most devtools.timeline events hang their fields on. */
+function dataOf(event) {
+    const data = event.args?.data;
+    return typeof data === "object" && data !== null
+        ? data
+        : undefined;
+}
+function stringField(data, key) {
+    const value = data?.[key];
+    return typeof value === "string" ? value : undefined;
+}
+function numberField(data, key) {
+    const value = data?.[key];
+    return typeof value === "number" ? value : undefined;
+}
+/** Which frame an event names, when it names one at all. */
+function frameOf(event) {
+    return stringField(dataOf(event), "frame");
+}
+/**
+ * Fold a finished recording into what it says.
+ *
+ * Attribution runs in two passes because the first pass is what
+ * makes the second possible: events that name one of our frames
+ * reveal which renderer process we are in, and that process is
+ * the only handle on the frame-pipeline events, which name no
+ * frame at all. Anything left is counted rather than guessed,
+ * because a report that quietly adopts another page's work is
+ * worse than one that admits a gap.
+ */
+export function foldTrace(events, options) {
+    const wantsFrames = options.profiles.includes("frames");
+    const myPids = new Set();
+    for (const event of events) {
+        const frame = frameOf(event);
+        if (frame !== undefined && options.frames.has(frame))
+            myPids.add(event.pid);
+    }
+    // Resource events name a request rather than a frame, so the
+    // send is what places the whole span and the rest follow it.
+    const requestFrames = new Map();
+    for (const event of events) {
+        if (event.name !== "ResourceSendRequest")
+            continue;
+        const data = dataOf(event);
+        const id = stringField(data, "requestId");
+        const frame = stringField(data, "frame");
+        if (id !== undefined && frame !== undefined)
+            requestFrames.set(id, frame);
+    }
+    const isMine = (event) => {
+        const frame = frameOf(event);
+        if (frame !== undefined)
+            return options.frames.has(frame);
+        const requestId = stringField(dataOf(event), "requestId");
+        if (requestId !== undefined) {
+            const owner = requestFrames.get(requestId);
+            if (owner !== undefined)
+                return options.frames.has(owner);
+            return undefined;
+        }
+        if (myPids.has(event.pid))
+            return true;
+        return undefined;
+    };
+    let mine = 0;
+    let unattributed = 0;
+    let firstUs = Number.POSITIVE_INFINITY;
+    let lastUs = Number.NEGATIVE_INFINITY;
+    const ours = [];
+    for (const event of events) {
+        if (event.ph === "M")
+            continue;
+        const verdict = isMine(event);
+        if (verdict === undefined)
+            unattributed += 1;
+        else if (verdict) {
+            mine += 1;
+            ours.push(event);
+            firstUs = Math.min(firstUs, event.ts);
+            lastUs = Math.max(lastUs, event.ts + (event.dur ?? 0));
+        }
+    }
+    const startUs = Number.isFinite(firstUs) ? firstUs : 0;
+    const at = (microseconds) => ms(microseconds - startUs);
+    return {
+        profiles: options.profiles,
+        spanMs: Number.isFinite(firstUs) ? ms(lastUs - firstUs) : 0,
+        events: events.length,
+        mine,
+        unattributed,
+        tasks: foldTasks(ours),
+        timers: foldTimers(ours, at),
+        ...foldRequests(ours, at),
+        frames: wantsFrames ? foldFrames(ours) : undefined,
+    };
+}
+/** Total the complete events by kind, dearest first. */
+function foldTasks(events) {
+    const totals = new Map();
+    for (const event of events) {
+        if (event.ph !== "X" || event.dur === undefined)
+            continue;
+        const seen = totals.get(event.name) ?? { count: 0, total: 0, max: 0 };
+        seen.count += 1;
+        seen.total += event.dur;
+        seen.max = Math.max(seen.max, event.dur);
+        totals.set(event.name, seen);
+    }
+    return [...totals.entries()]
+        .map(([name, seen]) => ({
+        name,
+        count: seen.count,
+        totalMs: ms(seen.total),
+        longestMs: ms(seen.max),
+    }))
+        .sort((one, other) => other.totalMs - one.totalMs)
+        .slice(0, TOP_TASKS);
+}
+/**
+ * Pair each install with the fire that belongs to it.
+ *
+ * Chrome recycles timer ids within a frame, so an id is not an
+ * identity. Pairing keeps only the most recent live install for
+ * an id and drops it on removal, because keyed naively a recycled
+ * id blames a fire on a long-dead install and reports a lateness
+ * of several seconds that never happened.
+ */
+function foldTimers(events, at) {
+    /** Where each live timer's story sits, so a fire can revise it. */
+    const live = new Map();
+    const stories = [];
+    const key = (frame, id) => `${frame ?? "?"}#${id}`;
+    for (const event of events) {
+        const data = dataOf(event);
+        const id = numberField(data, "timerId");
+        if (id === undefined)
+            continue;
+        const frame = stringField(data, "frame");
+        if (event.name === "TimerInstall") {
+            const story = {
+                timerId: id,
+                timeoutMs: numberField(data, "timeout") ?? 0,
+                singleShot: data?.singleShot === true,
+                installedAtMs: at(event.ts),
+                firedCount: 0,
+            };
+            live.set(key(frame, id), stories.length);
+            stories.push(story);
+            continue;
+        }
+        if (event.name === "TimerRemove") {
+            live.delete(key(frame, id));
+            continue;
+        }
+        if (event.name !== "TimerFire")
+            continue;
+        const slot = live.get(key(frame, id));
+        if (slot === undefined)
+            continue;
+        const install = stories[slot];
+        const firedAtMs = at(event.ts);
+        // A repeating timer keeps an interval, so what it promised is
+        // about the gap since it last ran. Measured from the install
+        // instead, a punctual interval looks later on every fire.
+        const since = install.firedAtMs ?? install.installedAtMs;
+        const lateBy = Math.max(0, firedAtMs - since - install.timeoutMs);
+        stories[slot] = {
+            ...install,
+            firedAtMs,
+            firedCount: install.firedCount + 1,
+            ranForMs: event.dur === undefined ? undefined : ms(event.dur),
+            lateByMs: Math.max(install.lateByMs ?? 0, lateBy),
+        };
+        if (install.singleShot)
+            live.delete(key(frame, id));
+    }
+    return stories;
+}
+/** Join request events by id, and say what the overlap was. */
+function foldRequests(events, at) {
+    const spans = new Map();
+    for (const event of events) {
+        const data = dataOf(event);
+        const id = stringField(data, "requestId");
+        if (id === undefined)
+            continue;
+        if (event.name === "ResourceSendRequest") {
+            spans.set(id, {
+                requestId: id,
+                url: stringField(data, "url"),
+                method: stringField(data, "requestMethod"),
+                resourceType: stringField(data, "resourceType"),
+                sentAtMs: at(event.ts),
+            });
+            continue;
+        }
+        const span = spans.get(id);
+        if (span === undefined)
+            continue;
+        if (event.name === "ResourceReceiveResponse") {
+            spans.set(id, {
+                ...span,
+                status: numberField(data, "statusCode"),
+                respondedAtMs: at(event.ts),
+            });
+        }
+        else if (event.name === "ResourceFinish") {
+            spans.set(id, {
+                ...span,
+                finishedAtMs: at(event.ts),
+                failed: data?.didFail === true,
+            });
+        }
+    }
+    const requests = [...spans.values()].sort((one, other) => one.sentAtMs - other.sentAtMs);
+    // A sweep over starts and ends gives the most in flight at once.
+    const edges = [];
+    for (const request of requests) {
+        edges.push({ atMs: request.sentAtMs, delta: 1 });
+        edges.push({
+            atMs: request.finishedAtMs ?? Number.POSITIVE_INFINITY,
+            delta: -1,
+        });
+    }
+    edges.sort((one, other) => one.atMs - other.atMs || one.delta - other.delta);
+    let inFlight = 0;
+    let overlapping = 0;
+    for (const edge of edges) {
+        inFlight += edge.delta;
+        overlapping = Math.max(overlapping, inFlight);
+    }
+    // Sent first but settled last is the fact that explains a
+    // waterfall nobody expected.
+    let resolvedOutOfOrder = false;
+    const settled = requests.filter((one) => one.finishedAtMs !== undefined);
+    for (let index = 1; index < settled.length; index += 1) {
+        const previous = settled[index - 1].finishedAtMs ?? 0;
+        if ((settled[index].finishedAtMs ?? 0) < previous) {
+            resolvedOutOfOrder = true;
+            break;
+        }
+    }
+    return { requests, overlapping, resolvedOutOfOrder };
+}
+/** Which layer tree host a pipeline event names, if any. */
+function layerTreeHostOf(event) {
+    const reporter = event.args?.frame_reporter;
+    if (typeof reporter !== "object" || reporter === null)
+        return undefined;
+    const host = reporter.layer_tree_host_id;
+    return typeof host === "number" ? host : undefined;
+}
+/**
+ * Time each frame from its paired begin and end.
+ *
+ * Only the begin event carries the layer tree host, the end event
+ * having empty args, so the host is banked on the way in and read
+ * back when the pair closes. Measured across 414 pairs, a begin is
+ * always closed by the next end for its id, so no pair is lost to
+ * an id being reused for a different tree.
+ */
+function foldFrames(events) {
+    const opened = new Map();
+    const durations = [];
+    const hosts = new Set();
+    for (const event of events) {
+        if (event.name !== "PipelineReporter")
+            continue;
+        const id = event.id2?.local;
+        if (id === undefined)
+            continue;
+        if (event.ph === "b") {
+            const host = layerTreeHostOf(event);
+            opened.set(id, { at: event.ts, ...(host === undefined ? {} : { host }) });
+        }
+        else if (event.ph === "e") {
+            const began = opened.get(id);
+            if (began === undefined)
+                continue;
+            opened.delete(id);
+            durations.push(ms(event.ts - began.at));
+            // Counted only for a frame that closed, so the tally covers
+            // exactly the frames the figures are built from.
+            if (began.host !== undefined)
+                hosts.add(began.host);
+        }
+    }
+    return {
+        counted: durations.length,
+        longestMs: durations.length === 0 ? 0 : Math.max(...durations),
+        slowMs: durations.filter((each) => each > FRAME_BUDGET_MS),
+        layerTrees: hosts.size,
+    };
+}
+/**
+ * Whose frames these are, said as precisely as the trace allows.
+ *
+ * A trace cannot tie a layer tree to a frame, so this cannot always
+ * be narrowed to one page. What it can do is stop hedging when
+ * there is nothing to hedge about: a single contributing layer tree
+ * means nothing else was in the numbers.
+ */
+function whoseFrames(frames) {
+    if (frames.layerTrees === 1) {
+        return [
+            "  One compositor layer tree produced all of them, so these are",
+            "  this page's frames.",
+        ];
+    }
+    if (frames.layerTrees > 1) {
+        return [
+            `  ${frames.layerTrees} compositor layer trees produced them, so`,
+            "  another page or tree in this renderer process is counted here",
+            "  too. Nothing in a trace ties a layer tree to a frame, so they",
+            "  cannot be told apart.",
+        ];
+    }
+    return [
+        "  The pipeline events named no layer tree, so whether another",
+        "  page in this renderer process is counted here is unknown.",
+    ];
+}
+/** Say what the recording found, in the order a reader needs it. */
+export function renderTrace(capture) {
+    if (capture.mine === 0) {
+        return "Nothing was recorded for this page.";
+    }
+    const lines = [
+        `Recorded ${capture.spanMs}ms across ${capture.mine} events ` +
+            `(${capture.profiles.join(" and ")}).`,
+    ];
+    if (capture.tasks.length > 0) {
+        lines.push("", "Where the time went:");
+        for (const task of capture.tasks) {
+            lines.push(`  ${task.name}: ${task.totalMs}ms over ${task.count}, ` +
+                `longest ${task.longestMs}ms`);
+        }
+    }
+    const late = capture.timers.filter((each) => (each.lateByMs ?? 0) > 0);
+    if (late.length > 0) {
+        lines.push("", "Timers that did not run when they were asked to:");
+        for (const timer of late) {
+            lines.push(`  asked for ${timer.timeoutMs}ms, fired ${timer.lateByMs}ms late`);
+        }
+    }
+    const pending = capture.timers.filter((each) => each.firedAtMs === undefined);
+    if (pending.length > 0) {
+        lines.push("", `${count(pending.length, "timer")} ` +
+            "installed but still waiting when the recording stopped.");
+    }
+    if (capture.requests.length > 0) {
+        lines.push("", `${count(capture.requests.length, "request")}, ` +
+            `at most ${capture.overlapping} in flight at once:`);
+        for (const request of capture.requests) {
+            const settled = request.finishedAtMs === undefined
+                ? "never settled"
+                : `settled ${request.finishedAtMs}ms`;
+            lines.push(`  ${request.sentAtMs}ms ${request.method ?? "?"} ` +
+                `${request.url ?? request.requestId} -> ` +
+                `${request.status ?? (request.failed ? "failed" : "?")}, ${settled}`);
+        }
+        if (capture.resolvedOutOfOrder) {
+            lines.push("  One of these settled before a request sent earlier, so the", "  order they answered in is not the order they were made.");
+        }
+    }
+    if (capture.frames !== undefined && capture.frames.counted > 0) {
+        const frames = capture.frames;
+        lines.push("", `${frames.counted} frames, longest ${frames.longestMs}ms, ` +
+            `${frames.slowMs.length} over the 16ms budget.`, ...whoseFrames(frames));
+    }
+    if (capture.unattributed > 0) {
+        lines.push("", `${capture.unattributed} events named neither our frames nor our`, "process and were left out rather than guessed at.");
+    }
+    return lines.join("\n");
+}

package/dist/web/perf/view.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reporting what the page cost.
+ */
+import { type Measure, type Vitals } from "./vitals.js";
+/** Say what the page cost, and what to look at first. */
+export declare function renderVitals(vitals: Vitals, measures: readonly Measure[]): string;

package/dist/web/perf/view.js

@@ -0,0 +1,86 @@
+/**
+ * Reporting what the page cost.
+ */
+import { renderVerdict } from "../audit/verdict.js";
+import { worstShiftSources, } from "./vitals.js";
+const MARK = {
+    good: "good",
+    "needs-improvement": "near",
+    poor: "POOR",
+};
+/** Mildest to worst, for ordering what to look at first. */
+const SEVERITY = ["good", "needs-improvement", "poor"];
+/** The worst rating decides the verdict. */
+function overall(measures) {
+    if (measures.some((one) => one.rating === "poor"))
+        return "fail";
+    return measures.some((one) => one.rating === "needs-improvement")
+        ? "warn"
+        : "pass";
+}
+function say(value, unit) {
+    return unit === "ms" ? `${Math.round(value)} ms` : value.toFixed(3);
+}
+/** Say what the page cost, and what to look at first. */
+export function renderVitals(vitals, measures) {
+    if (vitals.error) {
+        return renderVerdict({
+            standing: "warn",
+            headline: "The performance observers could not be installed.",
+            measured: vitals.error,
+        }, "");
+    }
+    if (measures.length === 0) {
+        return renderVerdict({
+            standing: "warn",
+            headline: "Nothing was measured.",
+            measured: "Observers are installed when a page opens, so a session " +
+                "that has not navigated since has nothing to report.",
+        }, "");
+    }
+    // Some measures arrived and some observers did not install. Say
+    // both, rather than throwing away what was collected: one
+    // unsupported entry type used to cost the whole report.
+    const missing = vitals.unavailable ?? [];
+    // Naming the one that is never taken, rather than leaving a
+    // count to imply the set. Interaction to next paint needs a
+    // person to interact: nothing here observes event timing, so a
+    // reader told only that four were measured has no way to know
+    // responsiveness was never among them, and assumes it passed.
+    const caveat = ` Interaction to next paint is not among them: it needs an ` +
+        `interaction, and this measures a load.` +
+        (missing.length === 0 ? "" : ` Not observed: ${missing.join("; ")}.`);
+    const width = Math.max(...measures.map((one) => one.name.length));
+    const lines = measures.map((one) => `  ${one.name.padEnd(width)}  ${MARK[one.rating].padEnd(4)}  ` +
+        `${say(one.value, one.unit).padStart(9)}` +
+        `${one.detail ? `  ${one.detail}` : ""}`);
+    const blame = worstShiftSources(vitals.shifts);
+    if (blame.length > 0) {
+        lines.push("", "What moved the page:");
+        for (const source of blame) {
+            lines.push(`  ${source.node}  ${source.moved.toFixed(3)}`);
+        }
+    }
+    // Worst first, so naming failing[0] names the worst thing.
+    // Sorting the other way put a near-miss ahead of a failure and
+    // the headline pointed at the milder of the two.
+    const failing = measures
+        .filter((one) => one.rating !== "good")
+        .sort((a, b) => SEVERITY.indexOf(b.rating) - SEVERITY.indexOf(a.rating));
+    return renderVerdict({
+        // A partial capture cannot pass: an observer that never
+        // installed reports nothing, which reads the same as a page
+        // with nothing wrong.
+        standing: missing.length > 0 && overall(measures) === "pass"
+            ? "warn"
+            : overall(measures),
+        headline: failing.length === 0
+            ? missing.length === 0
+                ? "Every measure is within its threshold."
+                : "Every measure taken is within its threshold, but " +
+                    `${missing.length} could not be observed.`
+            : `${failing.length} of ${measures.length} measures are outside ` +
+                `their threshold, worst is ${failing[0]?.name}.`,
+        measured: `Measured ${measures.length} of the published web vitals.${caveat}`,
+    }, lines.join("\n"));
+}

package/dist/web/perf/vitals.d.ts

@@ -0,0 +1,141 @@
+/**
+ * What the page cost the person waiting for it.
+ *
+ * The numbers come from the browser's own performance observers,
+ * which is the only place they can honestly come from: largest
+ * contentful paint and layout shift are defined by what the
+ * renderer did, not by anything measurable from outside.
+ *
+ * What this module adds is the arithmetic the observers leave to
+ * the caller, and one piece of it matters more than the rest.
+ * Cumulative layout shift is not the sum of every shift, though
+ * summing is the obvious reading of the name. It is the largest
+ * sum within a session window, so a page that shifts a little
+ * every few seconds over a long visit is not punished as though
+ * it had shifted once, enormously.
+ */
+/** Where a metric falls against the published thresholds. */
+export type Rating = "good" | "needs-improvement" | "poor";
+/** One layout shift the browser recorded. */
+export interface Shift {
+    readonly value: number;
+    readonly time: number;
+    readonly sources: readonly {
+        readonly node: string | null;
+        readonly from: readonly [number, number] | null;
+        readonly to: readonly [number, number] | null;
+    }[];
+}
+/** A stretch where the main thread could not respond. */
+export interface LongTask {
+    readonly time: number;
+    readonly duration: number;
+}
+/** Everything the observers gathered. */
+export interface Vitals {
+    readonly lcp?: {
+        readonly time: number;
+        readonly size: number;
+        readonly element: string | null;
+        readonly url: string | null;
+    };
+    readonly shifts: readonly Shift[];
+    readonly longTasks: readonly LongTask[];
+    readonly paints: Readonly<Record<string, number>>;
+    readonly nav?: {
+        readonly domContentLoaded: number;
+        readonly load: number;
+        readonly responseStart: number;
+        readonly transferSize: number;
+    };
+    /** Set when the bootstrap itself could not run at all. */
+    readonly error?: string;
+    /** Entry types that are being observed. */
+    readonly installed?: readonly string[];
+    /** Entry types that could not be observed, and why. */
+    readonly unavailable?: readonly string[];
+}
+/**
+ * Whether an entry type was actually being watched.
+ *
+ * An observer that never installed reports nothing, which looks
+ * exactly like a page with nothing to report. Cumulative layout
+ * shift is the one that matters: it was pushed unconditionally,
+ * so a capture where no observer ran still answered 0.000 and
+ * PASS, and the renderer's "Nothing was measured" branch could
+ * never be reached.
+ */
+export declare function watching(vitals: Vitals, type: string): boolean;
+/** A shift more than this far after the last one starts a new window. */
+export declare const SESSION_GAP_MS = 1000;
+/** No session window runs longer than this. */
+export declare const SESSION_CAP_MS = 5000;
+/**
+ * The published good and poor boundaries, in order.
+ *
+ * `longTask` is the per-task pair: a task over 50ms is long, and
+ * the deduction that turns a set of long tasks into total
+ * blocking time is taken against that 50. `tbt` is the separate
+ * pair for the aggregate. Reusing the per-task numbers to rate
+ * the sum called 210ms of total blocking time poor, when the
+ * published boundary for poor is 600, and because perf sits in
+ * the health digest an ordinary page dragged the whole digest
+ * to FAIL.
+ */
+export declare const THRESHOLDS: {
+    readonly lcp: {
+        readonly good: 2500;
+        readonly poor: 4000;
+    };
+    readonly cls: {
+        readonly good: 0.1;
+        readonly poor: 0.25;
+    };
+    readonly fcp: {
+        readonly good: 1800;
+        readonly poor: 3000;
+    };
+    readonly ttfb: {
+        readonly good: 800;
+        readonly poor: 1800;
+    };
+    readonly longTask: {
+        readonly good: 50;
+        readonly poor: 200;
+    };
+    readonly tbt: {
+        readonly good: 200;
+        readonly poor: 600;
+    };
+};
+/** Rate a measurement against its thresholds. */
+export declare function rate(value: number, bounds: {
+    readonly good: number;
+    readonly poor: number;
+}): Rating;
+/**
+ * Cumulative layout shift, as the metric is actually defined.
+ *
+ * Shifts are grouped into windows: a gap of a second starts a
+ * new one, and no window runs past five seconds. The score is
+ * the largest window, not the total. Summing everything would
+ * report a page that nudges once a minute as worse than one
+ * that jumps once on load, which is backwards.
+ */
+export declare function cumulativeShift(shifts: readonly Shift[]): number;
+/** What most moved the page, and how much. */
+export declare function worstShiftSources(shifts: readonly Shift[], limit?: number): readonly {
+    readonly node: string;
+    readonly moved: number;
+}[];
+/** One metric, rated. */
+export interface Measure {
+    readonly name: string;
+    readonly value: number;
+    readonly unit: "ms" | "score";
+    readonly rating: Rating;
+    /** What the value points at, when the browser said. */
+    readonly detail?: string;
+}
+/** Read the vitals into rated measures. */
+export declare function measure(vitals: Vitals): readonly Measure[];