@jitsusama/agentic-harness.core 0.1.0

package/dist/web/telemetry/lifecycle.js

@@ -0,0 +1,120 @@
+/**
+ * Where the page went, and whether it survived the trip.
+ *
+ * A session's readings are only meaningful against the document
+ * they were taken from, so a navigation is a fact worth keeping
+ * beside them. A crash is worth keeping for a stronger reason:
+ * everything recorded after one belongs to a different tab.
+ */
+/**
+ * Whether the session is sitting on the tab that replaced a crash.
+ *
+ * A crash is not the end of a session: the tab is replaced and
+ * everything goes on working. What is not restored is where the
+ * session was, because the replacement starts blank and nothing
+ * sends it back. So every read after a crash describes a blank
+ * page, and describing a blank page accurately is the problem:
+ * an empty outline reads as a page with nothing on it rather
+ * than a page that is gone.
+ *
+ * Asked of the history rather than of the url, because the
+ * question is whether anything has been loaded since, and a
+ * session deliberately sitting on about:blank is not stranded.
+ */
+export function strandedByCrash(history) {
+    // Walking back from the end rather than filtering forward:
+    // the first of these two kinds to turn up is the answer, and
+    // findLastIndex is not available on a readonly array here.
+    for (let at = history.length - 1; at >= 0; at -= 1) {
+        const kind = history[at]?.kind;
+        if (kind === "navigated" || kind === "routeChanged")
+            return false;
+        if (kind === "crashed")
+            return true;
+    }
+    return false;
+}
+export function createLifecycleRecorder(mainFrameId) {
+    const events = [];
+    let main = mainFrameId;
+    // Chrome announces why it is about to navigate in a separate
+    // event just before the navigation itself, so the reason is
+    // held until the navigation it belongs to arrives.
+    let pendingReason;
+    return {
+        adoptFrame(frameId) {
+            main = frameId;
+        },
+        apply(input) {
+            if (input.kind === "crashed") {
+                events.push({ kind: "crashed" });
+                return;
+            }
+            if (input.kind === "recovered") {
+                events.push({
+                    kind: "recovered",
+                    ...(input.url === undefined ? {} : { url: input.url }),
+                });
+                return;
+            }
+            // A subframe navigating is the page's business, not the
+            // session's: the session is looking at the main document,
+            // and an advertisement reloading itself is not news.
+            if (input.frameId !== main)
+                return;
+            if (input.kind === "requested") {
+                pendingReason = input.reason;
+                return;
+            }
+            if (input.kind === "navigated") {
+                events.push({
+                    kind: "navigated",
+                    url: input.url,
+                    ...(pendingReason === undefined ? {} : { reason: pendingReason }),
+                });
+                pendingReason = undefined;
+                return;
+            }
+            // A framework that announces its route on startup says the
+            // page it is already on, so a plain arrival was recorded
+            // twice: once as the navigation and once as the app noticing
+            // it. That made the trail longer than the number of pages
+            // visited, which is misleading when the trail is what you are
+            // counting history depth from. A route change to where we
+            // already are is not a move.
+            const last = events[events.length - 1];
+            if (last && "url" in last && last.url === input.url)
+                return;
+            events.push({
+                kind: "routeChanged",
+                url: input.url,
+                ...(input.navigationType === undefined
+                    ? {}
+                    : { via: input.navigationType }),
+            });
+        },
+        all() {
+            return events;
+        },
+    };
+}
+/** Where the page has been, in order. */
+export function renderLifecycle(events) {
+    if (events.length === 0)
+        return "The page has not navigated.";
+    return events
+        .map((event) => {
+        if (event.kind === "crashed") {
+            return ("crashed: the tab died, and nothing read before it " +
+                "belongs to the tab reading now");
+        }
+        if (event.kind === "recovered") {
+            return `recovered: a fresh tab${event.url ? `, back at ${event.url}` : ""}`;
+        }
+        if (event.kind === "routeChanged") {
+            return `route changed to ${event.url}${event.via ? ` (${event.via})` : ""}`;
+        }
+        return `navigated to ${event.url}${event.reason ? ` (${event.reason})` : ""}`;
+    })
+        .join("\n");
+}

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

@@ -0,0 +1,152 @@
+/**
+ * What the page asked the network for, and what it got back.
+ *
+ * The protocol reports one request as a scatter of events over
+ * time: sent, replied to, finished or failed, and sometimes
+ * sent again when it redirects. Nothing here judges any of it;
+ * this only reassembles the pieces into the record the events
+ * were always describing.
+ */
+/**
+ * The phase timings Chrome reports for a reply.
+ *
+ * Every field but requestTime is an offset in milliseconds from
+ * it, and a phase that did not happen is reported as -1 rather
+ * than left out. Named rather than treated as a bag of numbers,
+ * so the shape matches what the protocol actually sends.
+ */
+export interface ResourceTiming {
+    readonly requestTime: number;
+    readonly proxyStart?: number;
+    readonly proxyEnd?: number;
+    readonly dnsStart?: number;
+    readonly dnsEnd?: number;
+    readonly connectStart?: number;
+    readonly connectEnd?: number;
+    readonly sslStart?: number;
+    readonly sslEnd?: number;
+    readonly workerStart?: number;
+    readonly workerReady?: number;
+    readonly workerFetchStart?: number;
+    readonly workerRespondWithSettled?: number;
+    readonly sendStart?: number;
+    readonly sendEnd?: number;
+    readonly pushStart?: number;
+    readonly pushEnd?: number;
+    readonly receiveHeadersStart?: number;
+    readonly receiveHeadersEnd?: number;
+}
+/** One hop a request took before arriving. */
+export interface RedirectHop {
+    readonly url: string;
+    readonly status: number;
+    readonly location?: string;
+}
+/** Where a request got to. */
+export type RequestState = "pending" | "complete" | "failed" | "cancelled";
+/** One request, whole. */
+export interface NetworkRequest {
+    readonly id: string;
+    readonly url: string;
+    readonly method: string;
+    readonly resourceType: string;
+    /** The protocol's monotonic clock, good for measuring spans. */
+    readonly startedAt: number;
+    /**
+     * Wall clock seconds since the epoch, good for saying when.
+     * Kept apart from startedAt because the monotonic clock has no
+     * relationship to any calendar.
+     */
+    readonly wallTimeSeconds?: number;
+    readonly state: RequestState;
+    readonly requestHeaders: Readonly<Record<string, string>>;
+    readonly redirects: readonly RedirectHop[];
+    readonly postData?: string;
+    readonly status?: number;
+    readonly statusText?: string;
+    readonly mimeType?: string;
+    readonly responseHeaders?: Readonly<Record<string, string>>;
+    readonly remoteAddress?: string;
+    readonly fromCache?: boolean;
+    readonly durationMs?: number;
+    readonly transferredBytes?: number;
+    readonly failure?: string;
+    readonly initiator?: string;
+    readonly timing?: ResourceTiming;
+}
+/** Network.requestWillBeSent, as the protocol sends it. */
+export interface RequestSent {
+    readonly requestId: string;
+    readonly timestamp: number;
+    readonly wallTime?: number;
+    readonly type?: string;
+    readonly request: {
+        readonly url: string;
+        readonly method: string;
+        readonly headers: Readonly<Record<string, string>>;
+        readonly postData?: string;
+        readonly hasPostData?: boolean;
+    };
+    readonly initiator?: {
+        readonly type: string;
+    };
+    readonly redirectResponse?: {
+        readonly url: string;
+        readonly status: number;
+        readonly statusText?: string;
+        readonly headers?: Readonly<Record<string, string>>;
+    };
+}
+/** Network.responseReceived, as the protocol sends it. */
+export interface ResponseReceived {
+    readonly requestId: string;
+    readonly timestamp: number;
+    readonly type?: string;
+    readonly response: {
+        readonly url: string;
+        readonly status: number;
+        readonly statusText?: string;
+        readonly headers: Readonly<Record<string, string>>;
+        readonly mimeType?: string;
+        readonly remoteIPAddress?: string;
+        readonly remotePort?: number;
+        readonly fromDiskCache?: boolean;
+        readonly encodedDataLength?: number;
+        readonly protocol?: string;
+        readonly timing?: ResourceTiming;
+    };
+}
+/** Network.loadingFinished, as the protocol sends it. */
+export interface LoadingFinished {
+    readonly requestId: string;
+    readonly timestamp: number;
+    readonly encodedDataLength?: number;
+}
+/** Network.loadingFailed, as the protocol sends it. */
+export interface LoadingFailed {
+    readonly requestId: string;
+    readonly timestamp: number;
+    readonly errorText: string;
+    readonly canceled?: boolean;
+    readonly blockedReason?: string;
+}
+/** Any of the four events, tagged so the fold can tell them apart. */
+export type NetworkEvent = {
+    readonly kind: "sent";
+    readonly event: RequestSent;
+} | {
+    readonly kind: "received";
+    readonly event: ResponseReceived;
+} | {
+    readonly kind: "finished";
+    readonly event: LoadingFinished;
+} | {
+    readonly kind: "failed";
+    readonly event: LoadingFailed;
+};
+/** A running record of every request, in the order they started. */
+export interface NetworkRecorder {
+    apply(event: NetworkEvent): void;
+    all(): readonly NetworkRequest[];
+}
+export declare function createNetworkRecorder(): NetworkRecorder;

package/dist/web/telemetry/network.js

@@ -0,0 +1,130 @@
+/**
+ * What the page asked the network for, and what it got back.
+ *
+ * The protocol reports one request as a scatter of events over
+ * time: sent, replied to, finished or failed, and sometimes
+ * sent again when it redirects. Nothing here judges any of it;
+ * this only reassembles the pieces into the record the events
+ * were always describing.
+ */
+/** Seconds, as the protocol counts, to milliseconds. */
+const MS_PER_SECOND = 1000;
+export function createNetworkRecorder() {
+    // Insertion-ordered, so requests read in the order the page
+    // asked for them without a sort that could tie.
+    const byId = new Map();
+    return {
+        apply(entry) {
+            if (entry.kind === "sent")
+                return applySent(byId, entry.event);
+            const existing = byId.get(entry.event.requestId);
+            // A reply to a request that started before capture was
+            // on says nothing on its own, and inventing a record for
+            // it would report a request with no url or method.
+            if (!existing)
+                return;
+            byId.set(entry.event.requestId, entry.kind === "received"
+                ? withResponse(existing, entry.event)
+                : entry.kind === "finished"
+                    ? withCompletion(existing, entry.event)
+                    : withFailure(existing, entry.event));
+        },
+        all() {
+            return [...byId.values()];
+        },
+    };
+}
+/**
+ * A request starting, or the next hop of one that redirected.
+ *
+ * A redirect reuses the request id and arrives as another sent
+ * event carrying the reply that redirected it. Overwriting
+ * would lose the hop, which is often the thing being
+ * investigated.
+ */
+function applySent(byId, event) {
+    const previous = byId.get(event.requestId);
+    const hop = event.redirectResponse;
+    const redirects = previous && hop
+        ? [
+            ...previous.redirects,
+            {
+                url: hop.url,
+                status: hop.status,
+                ...(hop.headers?.location === undefined
+                    ? {}
+                    : { location: hop.headers.location }),
+            },
+        ]
+        : (previous?.redirects ?? []);
+    byId.set(event.requestId, {
+        id: event.requestId,
+        url: event.request.url,
+        method: event.request.method,
+        resourceType: event.type ?? "Other",
+        startedAt: previous?.startedAt ?? event.timestamp,
+        ...((previous?.wallTimeSeconds ?? event.wallTime) === undefined
+            ? {}
+            : { wallTimeSeconds: previous?.wallTimeSeconds ?? event.wallTime }),
+        state: "pending",
+        requestHeaders: event.request.headers,
+        redirects,
+        ...(event.request.postData === undefined
+            ? {}
+            : { postData: event.request.postData }),
+        ...(event.initiator?.type === undefined
+            ? {}
+            : { initiator: event.initiator.type }),
+    });
+}
+/** The reply, folded onto the request that asked for it. */
+function withResponse(request, event) {
+    const response = event.response;
+    return {
+        ...request,
+        status: response.status,
+        ...(response.statusText === undefined
+            ? {}
+            : { statusText: response.statusText }),
+        ...(response.mimeType === undefined ? {} : { mimeType: response.mimeType }),
+        responseHeaders: response.headers,
+        ...(response.remoteIPAddress === undefined
+            ? {}
+            : {
+                remoteAddress: response.remotePort === undefined
+                    ? response.remoteIPAddress
+                    : `${response.remoteIPAddress}:${response.remotePort}`,
+            }),
+        ...(response.fromDiskCache === undefined
+            ? {}
+            : { fromCache: response.fromDiskCache }),
+        ...(response.timing === undefined ? {} : { timing: response.timing }),
+    };
+}
+/** The request finished, however its status reads. */
+function withCompletion(request, event) {
+    return {
+        ...request,
+        // A 404 is a completed transaction. Whether the answer was
+        // the wanted one is the reader's judgment, not the
+        // protocol's, and not this module's either.
+        state: "complete",
+        durationMs: Math.round((event.timestamp - request.startedAt) * MS_PER_SECOND),
+        ...(event.encodedDataLength === undefined
+            ? {}
+            : { transferredBytes: event.encodedDataLength }),
+    };
+}
+/** The request did not finish, and why. */
+function withFailure(request, event) {
+    return {
+        ...request,
+        // A cancellation is usually the page changing its mind,
+        // which is not the same news as a request that broke.
+        state: event.canceled ? "cancelled" : "failed",
+        failure: event.blockedReason
+            ? `${event.errorText} (blocked: ${event.blockedReason})`
+            : event.errorText,
+        durationMs: Math.round((event.timestamp - request.startedAt) * MS_PER_SECOND),
+    };
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Reading a run of requests back.
+ *
+ * Presentation only. The one editorial choice is ordering the
+ * summary by what usually matters: a list of forty successful
+ * requests buries the one that failed, so the failures are
+ * counted before the list rather than found in it.
+ */
+import type { NetworkRequest } from "./network.js";
+/**
+ * What the caller asked for, so an empty answer can say which
+ * kind of empty it is.
+ */
+export interface RequestQuery {
+    /** The filter applied, when one was. */
+    readonly filter?: string;
+    /** How many were recorded before filtering. */
+    readonly recorded?: number;
+}
+export declare function renderRequests(requests: readonly NetworkRequest[], query?: RequestQuery): string;
+/** Whether the listing had to take the middle out of any url. */
+export declare function anyUrlShortened(requests: readonly NetworkRequest[]): boolean;
+/**
+ * The status, or the reason there is not one.
+ *
+ * A cancelled request often carries no failure text, and a
+ * request still in flight has no status, so every reader of
+ * either field needs this rule; printing the raw field puts the
+ * word undefined in front of someone debugging a network fault.
+ */
+export declare function requestStatus(request: NetworkRequest): string;

package/dist/web/telemetry/requests.js

@@ -0,0 +1,119 @@
+/**
+ * Reading a run of requests back.
+ *
+ * Presentation only. The one editorial choice is ordering the
+ * summary by what usually matters: a list of forty successful
+ * requests buries the one that failed, so the failures are
+ * counted before the list rather than found in it.
+ */
+import { count } from "../../ui/count.js";
+/** Where a status stops being a success. */
+const FIRST_ERROR_STATUS = 400;
+/** Bytes in a kilobyte, as a browser's network panel counts them. */
+const BYTES_PER_KB = 1024;
+/** Width of the method column, the longest common verb plus room. */
+const METHOD_WIDTH = 6;
+/** Width of the status column. */
+const STATUS_WIDTH = 8;
+export function renderRequests(requests, query = {}) {
+    if (requests.length === 0) {
+        // An empty filtered list is not a silent page, and saying so
+        // was actively misleading: asked for failures on a page that
+        // had made eighty requests and had none, the answer was "the
+        // page has not requested anything", which reads as the
+        // telemetry being broken rather than as good news.
+        if (query.filter !== undefined && (query.recorded ?? 0) > 0) {
+            return (`Nothing matched '${query.filter}', out of ` +
+                `${query.recorded} requests recorded.`);
+        }
+        return "The page has not requested anything.";
+    }
+    const lines = [summarize(requests), ""];
+    for (const [index, request] of requests.entries()) {
+        // An ordinal rather than the protocol's hex id: the reader
+        // has to be able to type it back to ask for a body.
+        lines.push(`${`#${index + 1}`.padStart(4)}  ` +
+            `${request.method.padEnd(METHOD_WIDTH)}` +
+            `${requestStatus(request).padEnd(STATUS_WIDTH)}` +
+            `${timingOf(request).padStart(7)}  ${scannable(request.url)}`);
+        for (const hop of request.redirects) {
+            lines.push(`          ${hop.status} from ${scannable(hop.url)}`);
+        }
+    }
+    return lines.join("\n");
+}
+/** Past this, a url is a payload rather than a label. */
+const MAX_URL = 160;
+/** How much of an over-long url still identifies it. */
+const URL_TAIL = 24;
+/**
+ * A url short enough to scan, with the middle taken out.
+ *
+ * One bundler request on a real page was twelve hundred
+ * characters, nearly all of it a module list. Three of those
+ * filled an eighth of the answer's budget each, and the budget
+ * pays for them by dropping whole requests, so a reader lost
+ * entire rows to preserve query strings nobody reads in a
+ * listing. The stored records keep every url whole, which is
+ * where a caller who wants the module list should be reading it.
+ *
+ * The front is kept because that is the origin and path, and the
+ * tail because that is where a cache key or a version usually
+ * sits, and those are the two ends that tell requests apart.
+ */
+function scannable(url) {
+    if (url.length <= MAX_URL)
+        return url;
+    const cut = url.length - (MAX_URL - URL_TAIL) - URL_TAIL;
+    return (`${url.slice(0, MAX_URL - URL_TAIL)}` +
+        `[...${cut} chars]${url.slice(-URL_TAIL)}`);
+}
+/** Whether the listing had to take the middle out of any url. */
+export function anyUrlShortened(requests) {
+    return requests.some((request) => request.url.length > MAX_URL ||
+        request.redirects.some((hop) => hop.url.length > MAX_URL));
+}
+/** What happened, before the detail of what each one was. */
+function summarize(requests) {
+    const failed = requests.filter((request) => request.state === "failed").length;
+    const cancelled = requests.filter((request) => request.state === "cancelled").length;
+    const pending = requests.filter((request) => request.state === "pending").length;
+    const errored = requests.filter((request) => request.status !== undefined && request.status >= FIRST_ERROR_STATUS).length;
+    const bytes = requests.reduce((total, request) => total + (request.transferredBytes ?? 0), 0);
+    const notes = [
+        count(requests.length, "request"),
+        `${(bytes / BYTES_PER_KB).toFixed(1)} KB transferred`,
+    ];
+    if (failed > 0)
+        notes.push(`${failed} failed`);
+    if (cancelled > 0)
+        notes.push(`${cancelled} cancelled`);
+    if (errored > 0) {
+        notes.push(`${errored} error status${errored === 1 ? "" : "es"}`);
+    }
+    if (pending > 0)
+        notes.push(`${pending} still in flight`);
+    return `${notes.join(", ")}.`;
+}
+/**
+ * The status, or the reason there is not one.
+ *
+ * A cancelled request often carries no failure text, and a
+ * request still in flight has no status, so every reader of
+ * either field needs this rule; printing the raw field puts the
+ * word undefined in front of someone debugging a network fault.
+ */
+export function requestStatus(request) {
+    if (request.state === "failed" || request.state === "cancelled") {
+        return request.failure ?? request.state;
+    }
+    if (request.status === undefined)
+        return "pending";
+    return String(request.status);
+}
+/** How long it took, and whether the network was involved at all. */
+function timingOf(request) {
+    if (request.fromCache)
+        return "cached";
+    return request.durationMs === undefined ? "" : `${request.durationMs}ms`;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * What a page said over its websockets.
+ *
+ * A request is a question with an answer attached, so the request
+ * record can hold both. A socket is a conversation that outlives
+ * any one message, and the whole point of a feature built on one
+ * is that messages arrive when nobody asked. None of that fits
+ * the request shape, so until this existed a live feature was
+ * invisible: the page did nothing observable and worked, or did
+ * nothing observable and did not.
+ */
+/** One thing that happened to a websocket. */
+export type SocketEvent = {
+    kind: "opened";
+    id: string;
+    at: number;
+    url: string;
+} | {
+    kind: "sent";
+    id: string;
+    at: number;
+    payload: string;
+} | {
+    kind: "received";
+    id: string;
+    at: number;
+    payload: string;
+} | {
+    kind: "closed";
+    id: string;
+    at: number;
+} | {
+    kind: "failed";
+    id: string;
+    at: number;
+    error: string;
+};
+/** One frame in a conversation. */
+export interface SocketFrame {
+    readonly direction: "sent" | "received";
+    readonly at: number;
+    readonly payload: string;
+}
+/** One socket and everything said over it. */
+export interface SocketRecord {
+    readonly id: string;
+    readonly url: string;
+    readonly openedAt?: number;
+    readonly closedAt?: number;
+    readonly error?: string;
+    readonly frames: readonly SocketFrame[];
+}
+/** Gather loose events into one record per socket, in order. */
+export declare function foldSockets(events: readonly SocketEvent[]): readonly SocketRecord[];
+/** Say what was said over each socket. */
+export declare function renderSockets(sockets: readonly SocketRecord[]): string;