@jitsusama/agentic-harness.core 0.1.0

package/dist/web/telemetry/sockets.js

@@ -0,0 +1,101 @@
+/**
+ * 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.
+ */
+/**
+ * The url of a socket nobody saw open.
+ *
+ * The recorder can attach part-way through a conversation, and a
+ * frame with no opening is still evidence. Dropping it would
+ * report a socket that was talking as no socket at all.
+ */
+const UNSEEN = "(socket already open when recording started)";
+/** Gather loose events into one record per socket, in order. */
+export function foldSockets(events) {
+    // Insertion order is the order sockets were first heard from,
+    // which is the order a reader expects to find them in.
+    const building = new Map();
+    const find = (id) => {
+        const existing = building.get(id);
+        if (existing !== undefined)
+            return existing;
+        const fresh = { id, url: UNSEEN, frames: [] };
+        building.set(id, fresh);
+        return fresh;
+    };
+    for (const event of events) {
+        const socket = find(event.id);
+        if (event.kind === "opened") {
+            socket.url = event.url;
+            socket.openedAt = event.at;
+        }
+        else if (event.kind === "closed") {
+            socket.closedAt = event.at;
+        }
+        else if (event.kind === "failed") {
+            socket.error = event.error;
+        }
+        else {
+            socket.frames.push({
+                direction: event.kind,
+                at: event.at,
+                payload: event.payload,
+            });
+        }
+    }
+    return [...building.values()].map((socket) => ({
+        id: socket.id,
+        url: socket.url,
+        ...(socket.openedAt === undefined ? {} : { openedAt: socket.openedAt }),
+        ...(socket.closedAt === undefined ? {} : { closedAt: socket.closedAt }),
+        ...(socket.error === undefined ? {} : { error: socket.error }),
+        frames: socket.frames,
+    }));
+}
+/** How much of one frame to show before it stops being a summary. */
+const MAX_PAYLOAD = 200;
+/** One frame, arrow first so the direction reads down the column. */
+function line(frame, openedAt) {
+    const arrow = frame.direction === "sent" ? "->" : "<-";
+    // Time since the socket opened, which is what a reader is
+    // actually asking when they look at a timestamp here.
+    const when = openedAt === undefined ? "" : `+${Math.round(frame.at - openedAt)}ms `;
+    const payload = frame.payload.length > MAX_PAYLOAD
+        ? `${frame.payload.slice(0, MAX_PAYLOAD)}... (${frame.payload.length} chars)`
+        : frame.payload;
+    return `    ${arrow} ${when}${payload}`;
+}
+/** Say what was said over each socket. */
+export function renderSockets(sockets) {
+    if (sockets.length === 0) {
+        // Worth saying plainly. A socket that opened and said nothing
+        // and a recorder that was not listening look identical in an
+        // empty report, and they mean opposite things.
+        return "No websocket traffic. The page opened no sockets while this session was recording.";
+    }
+    const blocks = sockets.map((socket) => {
+        const standing = socket.error !== undefined
+            ? `failed: ${socket.error}`
+            : socket.closedAt !== undefined
+                ? "closed"
+                : "open";
+        const head = `${socket.url} (${standing}, ${socket.frames.length} ${socket.frames.length === 1 ? "frame" : "frames"})`;
+        if (socket.frames.length === 0)
+            return `  ${head}`;
+        return [
+            `  ${head}`,
+            ...socket.frames.map((frame) => line(frame, socket.openedAt)),
+        ].join("\n");
+    });
+    return [
+        `${sockets.length} ${sockets.length === 1 ? "socket" : "sockets"}:`,
+        ...blocks,
+    ].join("\n");
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Reading a captured run back.
+ *
+ * Presentation, and only presentation: nothing here decides
+ * what was captured, only how much of it is worth putting in
+ * front of a reader at once.
+ */
+import type { Recorded } from "./buffer.js";
+import type { LogEntry } from "./console.js";
+/** A window onto a buffer, with what the buffer lost. */
+export interface Captured<T> {
+    readonly entries: readonly Recorded<T>[];
+    readonly dropped: number;
+    readonly cursor: number;
+}
+export declare function renderLogs(captured: Captured<LogEntry>): string;

package/dist/web/telemetry/view.js

@@ -0,0 +1,125 @@
+/**
+ * Reading a captured run back.
+ *
+ * Presentation, and only presentation: nothing here decides
+ * what was captured, only how much of it is worth putting in
+ * front of a reader at once.
+ */
+/** Levels worst first, so the tally reads in the order that matters. */
+const LEVEL_ORDER = [
+    "error",
+    "warning",
+    "assert",
+    "info",
+    "log",
+    "debug",
+    "verbose",
+    "trace",
+];
+/** How wide the level column is before the text starts. */
+const LEVEL_WIDTH = 8;
+export function renderLogs(captured) {
+    if (captured.entries.length === 0 && captured.dropped === 0) {
+        return "The page has not logged anything.";
+    }
+    const base = sharedBase(captured.entries);
+    const lines = [tally(captured.entries)];
+    if (base)
+        lines.push(`Paths below are under ${base}`);
+    lines.push("");
+    for (const { seq, item } of captured.entries) {
+        const source = item.source === "console" || item.source === "exception"
+            ? ""
+            : ` (${item.source})`;
+        lines.push(`${String(seq).padStart(4)}  ` +
+            `${item.level.padEnd(LEVEL_WIDTH)} ${item.text}${source}`);
+        if (item.origin) {
+            lines.push(`${" ".repeat(8)}${shorten(item.origin, base)}`);
+        }
+        const stack = usefulStack(item.stack, item.origin);
+        if (stack)
+            lines.push(shorten(stack, base));
+    }
+    if (captured.dropped > 0) {
+        lines.push("", `${captured.dropped} earlier entries were dropped to keep the ` +
+            "buffer bounded.");
+    }
+    lines.push("", `To read only what comes next, ask again with since: ${captured.cursor}.`);
+    return lines.join("\n");
+}
+/**
+ * A stack worth printing.
+ *
+ * A one-frame stack under an origin that already names that
+ * frame says the same thing twice, which is the one thing a
+ * reader scanning for the second location cannot afford.
+ */
+function usefulStack(stack, origin) {
+    if (!stack)
+        return undefined;
+    const frames = stack.split("\n").filter((line) => line.trim());
+    if (frames.length === 1 && origin && frames[0]?.includes(origin)) {
+        return undefined;
+    }
+    return stack;
+}
+/**
+ * The directory most origins share.
+ *
+ * A page's messages nearly all come from the same document, and
+ * repeating its full url on every line spends the budget saying
+ * what the reader learned on the first line. Deliberately the
+ * most common directory rather than the one they all share: a
+ * single failed image at the site root would otherwise drag the
+ * shared prefix down to the scheme and every other line would
+ * pay for it. Origins outside the hoist keep their full path,
+ * because a name relative to a base they do not sit under
+ * would point at nothing.
+ */
+function sharedBase(entries) {
+    const directories = entries
+        .map(({ item }) => item.origin)
+        .filter((origin) => Boolean(origin))
+        .map((origin) => origin.slice(0, origin.lastIndexOf("/") + 1))
+        // A bare scheme is not a path worth hoisting.
+        .filter((directory) => directory.length > "https://".length);
+    const counts = new Map();
+    for (const directory of directories) {
+        counts.set(directory, (counts.get(directory) ?? 0) + 1);
+    }
+    let best;
+    let bestCount = 1;
+    for (const [directory, count] of counts) {
+        if (count > bestCount) {
+            best = directory;
+            bestCount = count;
+        }
+    }
+    return best;
+}
+/** An origin with the shared base taken off the front. */
+function shorten(text, base) {
+    return base ? text.split(base).join("") : text;
+}
+/** How many of each level, worst first. */
+function tally(entries) {
+    const counts = new Map();
+    for (const { item } of entries) {
+        counts.set(item.level, (counts.get(item.level) ?? 0) + 1);
+    }
+    const ranked = [...counts.entries()].sort((left, right) => {
+        const leftRank = LEVEL_ORDER.indexOf(left[0]);
+        const rightRank = LEVEL_ORDER.indexOf(right[0]);
+        return ((leftRank < 0 ? LEVEL_ORDER.length : leftRank) -
+            (rightRank < 0 ? LEVEL_ORDER.length : rightRank));
+    });
+    if (ranked.length === 0)
+        return "Nothing in this window.";
+    return `${ranked
+        .map(([level, count]) => `${count} ${count === 1 ? level : plural(level)}`)
+        .join(", ")}.`;
+}
+/** The plural of a level name. */
+function plural(level) {
+    return level.endsWith("s") ? level : `${level}s`;
+}

package/dist/web/wait/conditions.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Waiting, and admitting what happened.
+ *
+ * A wait that times out is not a failure to be swallowed. It is
+ * the most informative moment in a session: the page did not
+ * reach a state something expected it to reach. So an outcome
+ * always says which condition it was, how long it waited, and
+ * what it saw instead, rather than returning a bare false that
+ * the caller has to guess at.
+ */
+import type { NetworkRequest } from "../telemetry/network.js";
+/** What a caller can wait for. */
+export type WaitCondition = {
+    readonly kind: "selector";
+    readonly selector: string;
+} | {
+    readonly kind: "gone";
+    readonly selector: string;
+} | {
+    readonly kind: "text";
+    readonly text: string;
+} | {
+    readonly kind: "idle";
+    readonly quietMs: number;
+} | {
+    readonly kind: "request";
+    readonly pattern: string;
+    /**
+     * The status that counts as arrival.
+     *
+     * Without it a request that answered 500 ends the wait as
+     * happily as one that answered 200, so a test for a save
+     * that worked passes on a save that failed.
+     */
+    readonly status?: number;
+} | {
+    readonly kind: "attribute";
+    readonly selector: string;
+    readonly attribute: string;
+    /** The value to wait for; omit to wait for the attribute to go. */
+    readonly value?: string;
+} | {
+    readonly kind: "count";
+    readonly selector: string;
+    readonly count: number;
+} | {
+    readonly kind: "animations";
+} | {
+    readonly kind: "duration";
+    readonly ms: number;
+};
+/** How a wait ended. */
+export interface WaitOutcome {
+    readonly met: boolean;
+    readonly waitedMs: number;
+    readonly condition: WaitCondition;
+    /** What was true instead, when the condition was not met. */
+    readonly saw?: string;
+    /** Anything the condition itself produced, such as a status. */
+    readonly detail?: string;
+}
+/**
+ * How long the network must be quiet to count as idle.
+ *
+ * Half a second is the interval a page's own deferred work
+ * tends to fall inside: a font fetch kicked off by layout, or
+ * an image requested once its container has a size. Calling
+ * idle any sooner catches the gap between two requests rather
+ * than the end of them.
+ */
+export declare const DEFAULT_QUIET_MS = 500;
+/** Requests that have not finished one way or the other. */
+export declare function inFlight(requests: readonly NetworkRequest[]): readonly NetworkRequest[];
+/**
+ * Whether the network has been quiet long enough.
+ *
+ * Quiet means two things at once: nothing is outstanding, and
+ * nothing has finished recently either. A page that completes
+ * one request and immediately starts another is busy, even
+ * though there is an instant between them when nothing is in
+ * flight.
+ */
+export declare function isIdle(requests: readonly NetworkRequest[], quietMs: number, 
+/** The protocol's monotonic clock, in seconds, as requests carry it. */
+nowSeconds: number): boolean;
+/** Say what happened, in a sentence a caller can act on. */
+export declare function renderWait(outcome: WaitOutcome): string;

package/dist/web/wait/conditions.js

@@ -0,0 +1,100 @@
+/**
+ * Waiting, and admitting what happened.
+ *
+ * A wait that times out is not a failure to be swallowed. It is
+ * the most informative moment in a session: the page did not
+ * reach a state something expected it to reach. So an outcome
+ * always says which condition it was, how long it waited, and
+ * what it saw instead, rather than returning a bare false that
+ * the caller has to guess at.
+ */
+/**
+ * How long the network must be quiet to count as idle.
+ *
+ * Half a second is the interval a page's own deferred work
+ * tends to fall inside: a font fetch kicked off by layout, or
+ * an image requested once its container has a size. Calling
+ * idle any sooner catches the gap between two requests rather
+ * than the end of them.
+ */
+export const DEFAULT_QUIET_MS = 500;
+/** Requests that have not finished one way or the other. */
+export function inFlight(requests) {
+    return requests.filter((request) => request.state === "pending");
+}
+/**
+ * Whether the network has been quiet long enough.
+ *
+ * Quiet means two things at once: nothing is outstanding, and
+ * nothing has finished recently either. A page that completes
+ * one request and immediately starts another is busy, even
+ * though there is an instant between them when nothing is in
+ * flight.
+ */
+export function isIdle(requests, quietMs, 
+/** The protocol's monotonic clock, in seconds, as requests carry it. */
+nowSeconds) {
+    if (inFlight(requests).length > 0)
+        return false;
+    const lastActivity = requests.reduce((latest, request) => Math.max(latest, endOf(request)), Number.NEGATIVE_INFINITY);
+    // A session that has seen no requests at all is idle, not
+    // infinitely busy.
+    if (!Number.isFinite(lastActivity))
+        return true;
+    return (nowSeconds - lastActivity) * MS_PER_SECOND >= quietMs;
+}
+/** Milliseconds in a second, since two clocks meet here. */
+const MS_PER_SECOND = 1000;
+/**
+ * When a request stopped occupying the network, on the
+ * protocol's monotonic clock in seconds.
+ *
+ * The two figures a request carries are in different units:
+ * startedAt is the protocol's seconds and durationMs is our
+ * rounded milliseconds, so one has to be converted rather than
+ * added straight on.
+ */
+function endOf(request) {
+    return request.startedAt + (request.durationMs ?? 0) / MS_PER_SECOND;
+}
+/** Say what happened, in a sentence a caller can act on. */
+export function renderWait(outcome) {
+    const took = `${Math.round(outcome.waitedMs)}ms`;
+    const what = describe(outcome.condition);
+    if (outcome.met) {
+        return outcome.detail
+            ? `Waited ${took} for ${what}. ${outcome.detail}`
+            : `Waited ${took} for ${what}.`;
+    }
+    // The thing that did not happen is the headline, and what was
+    // true instead is the reason it is worth reading.
+    const instead = outcome.saw ? ` ${outcome.saw}` : "";
+    return `Gave up after ${took}. Still waiting for ${what}.${instead}`;
+}
+/** Name a condition the way it would be asked for. */
+function describe(condition) {
+    switch (condition.kind) {
+        case "selector":
+            return `'${condition.selector}' to appear`;
+        case "gone":
+            return `'${condition.selector}' to go away`;
+        case "text":
+            return `the text '${condition.text}' to appear`;
+        case "idle":
+            return `the network to go quiet for ${condition.quietMs}ms`;
+        case "request":
+            return condition.status === undefined
+                ? `a request matching '${condition.pattern}' to finish`
+                : `a request matching '${condition.pattern}' to answer ${condition.status}`;
+        case "attribute":
+            return condition.value === undefined
+                ? `'${condition.selector}' to lose its ${condition.attribute}`
+                : `'${condition.selector}' to have ${condition.attribute}="${condition.value}"`;
+        case "count":
+            return `${condition.count} of '${condition.selector}' to be there`;
+        case "animations":
+            return "animations to settle";
+        case "duration":
+            return `${condition.ms}ms to pass`;
+    }
+}

package/dist/web/wait/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Waiting for the page to reach a state, and admitting it when
+ * it does not.
+ */
+export { DEFAULT_QUIET_MS, inFlight, isIdle, renderWait, type WaitCondition, type WaitOutcome, } from "./conditions.js";
+export { SETTLE_BUDGET_MS, SETTLE_QUIET_MS, type Settled, settleSource, } from "./settle.js";

package/dist/web/wait/index.js

@@ -0,0 +1,6 @@
+/**
+ * Waiting for the page to reach a state, and admitting it when
+ * it does not.
+ */
+export { DEFAULT_QUIET_MS, inFlight, isIdle, renderWait, } from "./conditions.js";
+export { SETTLE_BUDGET_MS, SETTLE_QUIET_MS, settleSource, } from "./settle.js";

package/dist/web/wait/settle.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Waiting for a page to stop changing before reading it.
+ *
+ * Every tool that acts on the page answers with a fresh outline,
+ * and that promise was quietly broken for any app that renders on
+ * the client. Navigating to a real application returned an outline
+ * whose only content was a live region saying "Loading page", and
+ * pressing Enter on a search box returned the page as it was
+ * before the result arrived. Both looked like the tool reporting a
+ * page with nothing on it, rather than a tool that read too early,
+ * which is the worse of the two failures: the caller reasons
+ * confidently about a page that no longer exists.
+ *
+ * Waiting on the network is not enough on its own. Chrome's own
+ * idle heuristics were already in use and had already declared
+ * this page idle, because the app fetches its content after the
+ * document settles. What actually indicates a rendered page is the
+ * DOM going quiet, so that is what this watches, with the network
+ * as a second signal rather than the only one.
+ *
+ * This ships as a page-side source string, like the other probes
+ * that declare helpers of their own.
+ */
+/** How long the DOM must be still before the page counts as settled. */
+export declare const SETTLE_QUIET_MS = 150;
+/**
+ * The longest we wait for stillness.
+ *
+ * A page that animates for ever, polls on a timer, or streams
+ * updates never goes quiet, and waiting on it would hang the one
+ * call a caller makes most. When the budget runs out the page is
+ * read anyway and the answer says it was still changing, because a
+ * reading of a moving page is worth having as long as nobody is
+ * told it was final.
+ */
+export declare const SETTLE_BUDGET_MS = 2000;
+/** What a settle attempt found. */
+export interface Settled {
+    /** Whether the page went quiet within its budget. */
+    readonly quiet: boolean;
+    /** How long it took, or the budget when it never settled. */
+    readonly waitedMs: number;
+    /** DOM mutations seen while waiting, for a page that never stopped. */
+    readonly mutations: number;
+}
+/**
+ * Page-side source: resolve once the DOM has been still for
+ * `quietMs`, or when `budgetMs` runs out.
+ *
+ * Counting mutations rather than merely noticing them lets the
+ * answer distinguish a page that is busy from one that never
+ * started, which are told apart nowhere else.
+ */
+export declare function settleSource(quietMs?: number, budgetMs?: number): string;

package/dist/web/wait/settle.js

@@ -0,0 +1,84 @@
+/**
+ * Waiting for a page to stop changing before reading it.
+ *
+ * Every tool that acts on the page answers with a fresh outline,
+ * and that promise was quietly broken for any app that renders on
+ * the client. Navigating to a real application returned an outline
+ * whose only content was a live region saying "Loading page", and
+ * pressing Enter on a search box returned the page as it was
+ * before the result arrived. Both looked like the tool reporting a
+ * page with nothing on it, rather than a tool that read too early,
+ * which is the worse of the two failures: the caller reasons
+ * confidently about a page that no longer exists.
+ *
+ * Waiting on the network is not enough on its own. Chrome's own
+ * idle heuristics were already in use and had already declared
+ * this page idle, because the app fetches its content after the
+ * document settles. What actually indicates a rendered page is the
+ * DOM going quiet, so that is what this watches, with the network
+ * as a second signal rather than the only one.
+ *
+ * This ships as a page-side source string, like the other probes
+ * that declare helpers of their own.
+ */
+/** How long the DOM must be still before the page counts as settled. */
+export const SETTLE_QUIET_MS = 150;
+/**
+ * The longest we wait for stillness.
+ *
+ * A page that animates for ever, polls on a timer, or streams
+ * updates never goes quiet, and waiting on it would hang the one
+ * call a caller makes most. When the budget runs out the page is
+ * read anyway and the answer says it was still changing, because a
+ * reading of a moving page is worth having as long as nobody is
+ * told it was final.
+ */
+export const SETTLE_BUDGET_MS = 2000;
+/**
+ * Page-side source: resolve once the DOM has been still for
+ * `quietMs`, or when `budgetMs` runs out.
+ *
+ * Counting mutations rather than merely noticing them lets the
+ * answer distinguish a page that is busy from one that never
+ * started, which are told apart nowhere else.
+ */
+export function settleSource(quietMs = SETTLE_QUIET_MS, budgetMs = SETTLE_BUDGET_MS) {
+    return `(() => new Promise((resolve) => {
+	const started = Date.now();
+	let mutations = 0;
+	let quietTimer;
+	let observer;
+
+	const finish = (quiet) => {
+		clearTimeout(quietTimer);
+		clearTimeout(deadline);
+		if (observer) observer.disconnect();
+		resolve({ quiet, waitedMs: Date.now() - started, mutations });
+	};
+
+	const deadline = setTimeout(() => finish(false), ${budgetMs});
+
+	const armQuiet = () => {
+		clearTimeout(quietTimer);
+		quietTimer = setTimeout(() => finish(true), ${quietMs});
+	};
+
+	try {
+		observer = new MutationObserver((records) => {
+			mutations += records.length;
+			armQuiet();
+		});
+		observer.observe(document, {
+			childList: true,
+			subtree: true,
+			attributes: true,
+			characterData: true,
+		});
+	} catch (error) {
+		// No observer available: fall back to the quiet timer alone,
+		// which still gives the page a moment to paint.
+	}
+
+	armQuiet();
+}))()`;
+}

package/dist/work/ask.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Turning a loose ask into a tree request, or a sentence saying
+ * why not.
+ *
+ * The broker takes a `TreeRequest` whose two shapes need
+ * different fields, and a tool surface takes whatever the caller
+ * sent. Somewhere in between, a caller who sent a commit where a
+ * branch belonged has to be told that specifically, rather than
+ * being handed a generic complaint or, worse, having the provider
+ * fail somewhere further from the cause.
+ *
+ * This is where. It is pure, so the refusals can be read as a set
+ * rather than discovered one live call at a time.
+ */
+import type { TreeRequest } from "./tree.js";
+/**
+ * A repo, as loosely as a caller may name one.
+ *
+ * Nothing here reads the last two. They are carried through to the
+ * provider, which is the only thing that knows whether it needs a
+ * checkout, a remote or neither, and they are declared here because
+ * this is the shape a caller fills in.
+ */
+export interface AskedRepo {
+    key: string;
+    remoteUrl?: string;
+    localPath?: string;
+}
+/** What a caller asked for, before it is known to be coherent. */
+export interface TreeAsk {
+    intent: "worktree" | "snapshot";
+    repo: AskedRepo;
+    purpose: string;
+    branch?: string;
+    commit?: string;
+    paths?: readonly string[];
+}
+/** Either a request the broker will accept, or why it will not. */
+export type TreeRequestOutcome = {
+    request: TreeRequest;
+} | {
+    refusal: string;
+};
+/** Build a tree request, or refuse with the missing part named. */
+export declare function treeRequestFrom(ask: TreeAsk): TreeRequestOutcome;