@jitsusama/agentic-harness.core 0.1.0

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

@@ -0,0 +1,26 @@
+/**
+ * Installing the performance observers, and reading them back.
+ *
+ * The bootstrap has to run before anything on the page does.
+ * Largest contentful paint and layout shift are events, not
+ * state, and an observer registered after the fact sees only
+ * what happens next. Chrome's buffered flag recovers some of it,
+ * but not the element that painted or the nodes that moved,
+ * which is the part worth having.
+ *
+ * So it goes in through addScriptToEvaluateOnNewDocument, which
+ * fires ahead of every navigation, and the whole thing is
+ * wrapped in a try: an observer type the browser does not
+ * support must cost the other observers nothing.
+ */
+/**
+ * The script installed before every navigation.
+ *
+ * Nodes are named the way a person would look for them rather
+ * than held as references. A retained node keeps a detached
+ * subtree alive, and measuring a page should not change what it
+ * costs.
+ */
+export declare function observerBootstrap(): string;
+/** The expression that reads the observers back. */
+export declare function readVitalsSource(): string;

package/dist/web/perf/probe.js

@@ -0,0 +1,123 @@
+/**
+ * Installing the performance observers, and reading them back.
+ *
+ * The bootstrap has to run before anything on the page does.
+ * Largest contentful paint and layout shift are events, not
+ * state, and an observer registered after the fact sees only
+ * what happens next. Chrome's buffered flag recovers some of it,
+ * but not the element that painted or the nodes that moved,
+ * which is the part worth having.
+ *
+ * So it goes in through addScriptToEvaluateOnNewDocument, which
+ * fires ahead of every navigation, and the whole thing is
+ * wrapped in a try: an observer type the browser does not
+ * support must cost the other observers nothing.
+ */
+/**
+ * The script installed before every navigation.
+ *
+ * Nodes are named the way a person would look for them rather
+ * than held as references. A retained node keeps a detached
+ * subtree alive, and measuring a page should not change what it
+ * costs.
+ */
+export function observerBootstrap() {
+    return `(() => {
+	const named = (node) => {
+		if (!node) return null;
+		if (node.id) return "#" + node.id;
+		if (!node.tagName) return null;
+		const tag = node.tagName.toLowerCase();
+		const first = node.classList && node.classList[0];
+		return first ? tag + "." + first : tag;
+	};
+
+	const vitals = {
+		lcp: null, shifts: [], longTasks: [], paints: {},
+		// Which observers are actually running, so a measure is only
+		// reported when something was watching for it. A zero from an
+		// observer that never installed is not a zero.
+		installed: [], unavailable: [],
+	};
+	window.__piVitals = vitals;
+
+	const watch = (type, handle) => {
+		try {
+			new PerformanceObserver((list) => {
+				for (const entry of list.getEntries()) handle(entry);
+			}).observe({ type, buffered: true });
+			vitals.installed.push(type);
+		} catch (error) {
+			// One unsupported entry type must not cost the others. It
+			// used to write a single shared error field that the
+			// renderer treated as fatal, so losing longtask on a browser
+			// that does not support it threw away the paints and the
+			// layout shifts that had been collected perfectly well.
+			vitals.unavailable.push(type + ": " + String(error));
+		}
+	};
+
+	watch("largest-contentful-paint", (entry) => {
+		vitals.lcp = {
+			time: entry.startTime,
+			size: entry.size,
+			element: named(entry.element),
+			url: entry.url || null,
+		};
+	});
+
+	watch("layout-shift", (entry) => {
+		// A shift the person caused by interacting is not a fault.
+		if (entry.hadRecentInput) return;
+		vitals.shifts.push({
+			value: entry.value,
+			time: entry.startTime,
+			sources: (entry.sources || []).map((source) => ({
+				node: named(source.node),
+				from: source.previousRect
+					? [source.previousRect.x, source.previousRect.y]
+					: null,
+				to: source.currentRect
+					? [source.currentRect.x, source.currentRect.y]
+					: null,
+			})),
+		});
+	});
+
+	watch("longtask", (entry) => {
+		vitals.longTasks.push({ time: entry.startTime, duration: entry.duration });
+	});
+
+	watch("paint", (entry) => {
+		vitals.paints[entry.name] = entry.startTime;
+	});
+})()`;
+}
+/** The expression that reads the observers back. */
+export function readVitalsSource() {
+    return `(() => {
+	const vitals = window.__piVitals;
+	if (!vitals) {
+		return {
+			shifts: [],
+			longTasks: [],
+			paints: {},
+			error:
+				"No observers are installed on this document. They are added " +
+				"before a navigation, so a page opened another way has none.",
+		};
+	}
+	const nav = performance.getEntriesByType("navigation")[0];
+	return {
+		...vitals,
+		nav: nav
+			? {
+					domContentLoaded: nav.domContentLoadedEventEnd,
+					load: nav.loadEventEnd,
+					responseStart: nav.responseStart,
+					transferSize: nav.transferSize,
+				}
+			: undefined,
+	};
+})()`;
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Where a slow stretch of page activity actually went.
+ *
+ * A long task tells you three seconds disappeared. It does not
+ * tell you whether that was a JSON parse of ten megabytes, a
+ * regular expression over the whole document, or a hundred awaits
+ * in a row, and those have nothing in common except the symptom.
+ *
+ * A sampling profile answers it. The engine interrupts itself
+ * every so often and writes down which function it was in, so
+ * counting samples per function is counting time per function.
+ * That is an estimate by construction: a function that never
+ * happens to be running at a sample is invisible, which is why
+ * the sampled total is reported alongside the shares rather than
+ * left for a reader to assume it covers everything.
+ */
+/** One function in a sampling profile, as the protocol sends it. */
+export interface RawProfileNode {
+    readonly id: number;
+    readonly callFrame: {
+        readonly functionName: string;
+        readonly url: string;
+        readonly lineNumber: number;
+    };
+    readonly children?: readonly number[];
+}
+/** A sampling profile as the protocol sends it. */
+export interface RawProfile {
+    readonly nodes: readonly RawProfileNode[];
+    readonly startTime: number;
+    readonly endTime: number;
+    readonly samples?: readonly number[];
+    readonly timeDeltas?: readonly number[];
+}
+/** One function and the time that landed in it. */
+export interface Hotspot {
+    readonly function: string;
+    readonly url: string;
+    readonly line: number;
+    /** Milliseconds sampled inside this function itself. */
+    readonly selfMs: number;
+    /** Its share of the sampled time, from zero to one. */
+    readonly share: number;
+}
+/** What the profile says about where the time went. */
+export interface Hotspots {
+    readonly hotspots: readonly Hotspot[];
+    readonly sampledMs: number;
+}
+/** Attribute the sampled time to the functions it landed in. */
+export declare function foldProfile(profile: RawProfile): Hotspots;
+/** Say where the time went. */
+export declare function renderHotspots(folded: Hotspots): string;

package/dist/web/perf/profile.js

@@ -0,0 +1,97 @@
+/**
+ * Where a slow stretch of page activity actually went.
+ *
+ * A long task tells you three seconds disappeared. It does not
+ * tell you whether that was a JSON parse of ten megabytes, a
+ * regular expression over the whole document, or a hundred awaits
+ * in a row, and those have nothing in common except the symptom.
+ *
+ * A sampling profile answers it. The engine interrupts itself
+ * every so often and writes down which function it was in, so
+ * counting samples per function is counting time per function.
+ * That is an estimate by construction: a function that never
+ * happens to be running at a sample is invisible, which is why
+ * the sampled total is reported alongside the shares rather than
+ * left for a reader to assume it covers everything.
+ */
+/** How many functions are worth naming before it is a data dump. */
+const TOP = 20;
+/**
+ * A name for a function that has none.
+ *
+ * The url and line still identify it exactly, so the name only
+ * has to be something a reader can recognise as "not missing,
+ * genuinely anonymous".
+ */
+const ANONYMOUS = "(anonymous)";
+/** Attribute the sampled time to the functions it landed in. */
+export function foldProfile(profile) {
+    const samples = profile.samples ?? [];
+    const deltas = profile.timeDeltas ?? [];
+    const byId = new Map(profile.nodes.map((node) => [node.id, node]));
+    // Microseconds, summed per node, then converted once at the end
+    // so the rounding happens in one place.
+    const spent = new Map();
+    let total = 0;
+    for (let at = 0; at < samples.length; at += 1) {
+        const id = samples[at];
+        if (id === undefined)
+            continue;
+        // Each delta is the gap before its sample, and is charged to
+        // that sample. Charging it to the previous one instead is the
+        // other defensible reading, and over a run of samples the two
+        // differ by a single interval; what is not defensible is
+        // dropping the first, which loses real time and inflates every
+        // share computed from the remainder.
+        const micros = deltas[at] ?? 0;
+        spent.set(id, (spent.get(id) ?? 0) + micros);
+        total += micros;
+    }
+    const hotspots = [];
+    for (const [id, micros] of spent) {
+        const node = byId.get(id);
+        if (node === undefined)
+            continue;
+        const named = node.callFrame.functionName;
+        hotspots.push({
+            function: named === "" ? ANONYMOUS : named,
+            url: node.callFrame.url,
+            line: node.callFrame.lineNumber,
+            selfMs: micros / 1000,
+            share: total === 0 ? 0 : micros / total,
+        });
+    }
+    hotspots.sort((one, other) => other.selfMs - one.selfMs);
+    return { hotspots: hotspots.slice(0, TOP), sampledMs: total / 1000 };
+}
+/** Say where the time went. */
+export function renderHotspots(folded) {
+    if (folded.hotspots.length === 0 || folded.sampledMs === 0) {
+        // An idle page profiles to nothing, and that is an answer.
+        // Reporting it as an empty list would read as a failure to
+        // measure rather than as nothing to measure.
+        return ("No JavaScript ran while the profiler was on. Either nothing " +
+            "was happening, or whatever you meant to profile finished " +
+            "before it started.");
+    }
+    const lines = folded.hotspots.map((spot) => {
+        const share = `${Math.round(spot.share * 100)}%`;
+        const where = spot.url === "" ? "the engine" : `${spot.url}:${spot.line + 1}`;
+        return `  ${spot.selfMs.toFixed(1)}ms (${share})  ${spot.function}  ${where}`;
+    });
+    return [
+        // Not "of JavaScript": the engine reports idle time as a
+        // function of its own, and a window that was mostly idle would
+        // otherwise be announced as that many milliseconds of work.
+        // Idle is left in rather than filtered, because knowing the
+        // page was doing nothing for most of the window is the answer
+        // when you profiled the wrong moment.
+        `${folded.sampledMs.toFixed(0)}ms sampled, by function:`,
+        ...lines,
+        "",
+        // Saying what the numbers are worth, because a sampled figure
+        // read as an exact one sends people optimising noise.
+        "Sampled, so these are estimates: a function that was never " +
+            "running at a sample does not appear at all.",
+    ].join("\n");
+}

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

@@ -0,0 +1,152 @@
+/**
+ * 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.
+ */
+/** One event as the tracing protocol sends it. */
+export interface RawTraceEvent {
+    readonly name: string;
+    readonly cat?: string;
+    /** Phase: X complete, I instant, b and e async pairs, M metadata. */
+    readonly ph: string;
+    /** Microseconds on the trace clock. */
+    readonly ts: number;
+    /** Microseconds, on complete events only. */
+    readonly dur?: number;
+    readonly pid: number;
+    readonly tid: number;
+    readonly id2?: {
+        readonly local?: string;
+    };
+    readonly args?: Record<string, unknown>;
+}
+/** Which story a recording is being asked to tell. */
+export type TraceProfile = "async" | "frames";
+/**
+ * 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 declare const TRACE_CATEGORIES: Record<TraceProfile, readonly string[]>;
+/** The categories to ask for, with nothing repeated. */
+export declare function categoriesFor(profiles: readonly TraceProfile[]): readonly string[];
+/** One kind of work and the time that landed in it. */
+export interface TaskCost {
+    readonly name: string;
+    readonly count: number;
+    readonly totalMs: number;
+    readonly longestMs: number;
+}
+/** A timer, from the moment it was asked for to the moment it ran. */
+export interface TimerStory {
+    readonly timerId: number;
+    readonly timeoutMs: number;
+    readonly singleShot: boolean;
+    /** Milliseconds from the start of the recording. */
+    readonly installedAtMs: number;
+    readonly firedAtMs?: number;
+    /** How long the callback itself took. */
+    readonly ranForMs?: number;
+    /**
+     * How much later than asked it fired, never below zero. For a
+     * repeating timer this is the worst delay between consecutive
+     * fires, since an interval is a promise about the gap.
+     */
+    readonly lateByMs?: number;
+    /** How many times it fired inside the recording. */
+    readonly firedCount: number;
+}
+/** A request, from the moment it left to the moment it settled. */
+export interface RequestSpan {
+    readonly requestId: string;
+    readonly url?: string;
+    readonly method?: string;
+    readonly resourceType?: string;
+    readonly status?: number;
+    readonly sentAtMs: number;
+    readonly respondedAtMs?: number;
+    readonly finishedAtMs?: number;
+    readonly failed?: boolean;
+}
+/**
+ * What the compositor did.
+ *
+ * These figures belong to a renderer process rather than to one
+ * page, and that cannot be narrowed from a trace. The frame
+ * pipeline names a layer tree host, never a frame, and measured
+ * against this Chrome no event carries both: `SetLayerTreeId`, which
+ * used to join them, is gone, and a search across a two page
+ * capture found nothing else linking the two.
+ *
+ * So instead of repeating a blanket disclaimer, `layerTrees` says
+ * how many hosts actually contributed. One means the figures came
+ * from a single layer tree and are this page's for any practical
+ * purpose; more than one means another page or another tree in the
+ * same process is in the numbers. Zero means the begin events
+ * carried no host id, so the question went unanswered, which is not
+ * the same as the answer being one.
+ */
+export interface FrameStory {
+    readonly counted: number;
+    readonly longestMs: number;
+    /** Every frame that missed the sixty-a-second budget. */
+    readonly slowMs: readonly number[];
+    /** Distinct compositor layer tree hosts behind these figures. */
+    readonly layerTrees: number;
+}
+/** What a finished recording says. */
+export interface TraceCapture {
+    readonly profiles: readonly TraceProfile[];
+    readonly spanMs: number;
+    /** Events received, before any attribution. */
+    readonly events: number;
+    /** Events placed with this session. */
+    readonly mine: number;
+    /** Events that named neither our frames nor our process. */
+    readonly unattributed: number;
+    readonly tasks: readonly TaskCost[];
+    readonly timers: readonly TimerStory[];
+    readonly requests: readonly RequestSpan[];
+    readonly overlapping: number;
+    readonly resolvedOutOfOrder: boolean;
+    readonly frames?: FrameStory;
+}
+/**
+ * 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 declare function foldTrace(events: readonly RawTraceEvent[], options: {
+    readonly frames: ReadonlySet<string>;
+    readonly profiles: readonly TraceProfile[];
+}): TraceCapture;
+/** Say what the recording found, in the order a reader needs it. */
+export declare function renderTrace(capture: TraceCapture): string;