@jitsusama/agentic-harness.core 0.1.0

package/dist/web/element/view.js

@@ -0,0 +1,117 @@
+/**
+ * Laying out what was found about one element.
+ *
+ * Kept apart from the judging so the two have separate reasons
+ * to change: what is true about an element and how it reads are
+ * different questions.
+ */
+/** Round a measurement to something a person would say. */
+function round(value) {
+    return String(Math.round(value * 100) / 100);
+}
+/** The verdict, as a sentence. */
+export function renderVisibility(verdict) {
+    return `${verdict.state}: ${verdict.because}`;
+}
+/**
+ * The boxes, innermost outwards, with the offsets between them
+ * stated only where they exist. Four zeroes for the margin of
+ * an element with no margin is noise.
+ *
+ * The position says which space it is measured in. These numbers
+ * come from the box model, which measures from the viewport, while
+ * a page query reports the same element measured down the document.
+ * On a scrolled page the two differ by however far it has moved,
+ * and an unlabelled pair of numbers invites reading one as the
+ * other: that confusion hid a real defect for hours, because every
+ * reading was true in its own frame and none were comparable.
+ */
+export function renderBox(box) {
+    const lines = [
+        `content ${round(box.content.width)} by ${round(box.content.height)}` +
+            ` at (${round(box.content.x)}, ${round(box.content.y)})` +
+            " in the viewport",
+    ];
+    const padding = insetsBetween(box.content, box.padding);
+    if (padding)
+        lines.push(`padding ${padding}`);
+    const border = insetsBetween(box.padding, box.border);
+    if (border)
+        lines.push(`border ${border}`);
+    const margin = insetsBetween(box.border, box.margin);
+    if (margin)
+        lines.push(`margin ${margin}`);
+    return lines.join("\n");
+}
+/** The gap on each side between an inner and an outer box. */
+function insetsBetween(inner, outer) {
+    const top = inner.y - outer.y;
+    const left = inner.x - outer.x;
+    const right = outer.x + outer.width - (inner.x + inner.width);
+    const bottom = outer.y + outer.height - (inner.y + inner.height);
+    if ([top, right, bottom, left].every((side) => side === 0))
+        return undefined;
+    if (top === right && right === bottom && bottom === left) {
+        return round(top);
+    }
+    if (top === bottom && left === right)
+        return `${round(top)} ${round(right)}`;
+    return `${round(top)} ${round(right)} ${round(bottom)} ${round(left)}`;
+}
+/** Curated styles, grouped as they were curated. */
+export function renderStyles(groups) {
+    if (groups.length === 0)
+        return "Nothing was set beyond the defaults.";
+    return groups
+        .map((group) => `${group.name}\n` +
+        group.entries
+            .map((entry) => `  ${entry.property}: ${entry.value}`)
+            .join("\n"))
+        .join("\n");
+}
+/** One declaration, said the way a person would read it. */
+function renderDeclaration(declaration, won) {
+    const mark = won ? "wins " : "     ";
+    const value = declaration.important
+        ? `${declaration.value} !important`
+        : declaration.value;
+    const where = declaration.origin === "inline"
+        ? "inline style"
+        : (declaration.selector ?? declaration.origin);
+    const parts = [`${mark} ${declaration.property}: ${value}`, `from ${where}`];
+    if (declaration.media)
+        parts.push(`@media ${declaration.media.join(", ")}`);
+    if (declaration.origin === "user-agent")
+        parts.push("(browser default)");
+    if (declaration.origin === "inherited")
+        parts.push("(inherited)");
+    if (declaration.via)
+        parts.push(`via ${declaration.via}`);
+    const authored = declaration.source?.authored;
+    if (authored) {
+        // The authored position is the one worth reading, but the
+        // generated line stays beside it: a stale map is a real
+        // thing, and hiding the disagreement hides the bug.
+        parts.push(`${authored.source}:${authored.line + 1}`);
+        if (declaration.source?.line !== undefined) {
+            parts.push(`(built line ${declaration.source.line + 1})`);
+        }
+    }
+    else if (declaration.source?.line !== undefined) {
+        parts.push(`line ${declaration.source.line + 1}`);
+    }
+    return parts.join("  ");
+}
+/** Everything that had a say in one property, strongest first. */
+export function renderTrace(trace) {
+    if (trace.declarations.length === 0) {
+        return `Nothing declared ${trace.property}.`;
+    }
+    const heading = trace.computed === undefined
+        ? trace.property
+        : `${trace.property} computed to ${trace.computed}`;
+    return [
+        heading,
+        ...trace.declarations.map((declaration) => renderDeclaration(declaration, declaration === trace.winner)),
+    ].join("\n");
+}

package/dist/web/element/visibility.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Whether a person could actually see and click this.
+ *
+ * "Is it there" has several answers that look alike from the
+ * outside and need entirely different fixes: not rendered at
+ * all, rendered with no size, rendered off screen, rendered
+ * under something else, rendered invisibly. A caller whose
+ * click went nowhere needs to be told which.
+ */
+import type { Rect } from "./box.js";
+/** What a person would find when they looked. */
+export type Visible = "visible" | "not rendered" | "zero size" | "off screen" | "covered" | "transparent";
+/** The area a person can currently see. */
+export interface Viewport {
+    readonly width: number;
+    readonly height: number;
+}
+/** What is known about an element's presence. */
+export interface VisibilityFacts {
+    /** Whether the capture could measure a box at all. */
+    readonly rendered: boolean;
+    readonly border?: Rect;
+    readonly viewport?: Viewport;
+    /** What the hit test found instead, described for a person. */
+    readonly coveredBy?: string;
+    readonly opacity?: number;
+    readonly visibility?: string;
+}
+/** One plain answer, with the reason it was reached. */
+export interface VisibilityVerdict {
+    readonly state: Visible;
+    readonly because: string;
+}
+/**
+ * Judge an element's presence.
+ *
+ * The order matters. An element that is not rendered cannot
+ * usefully also be called covered, and saying so would send
+ * someone hunting an overlay that is not the cause. So the most
+ * fundamental problem is the one reported.
+ */
+export declare function judgeVisibility(facts: VisibilityFacts): VisibilityVerdict;

package/dist/web/element/visibility.js

@@ -0,0 +1,67 @@
+/**
+ * Whether a person could actually see and click this.
+ *
+ * "Is it there" has several answers that look alike from the
+ * outside and need entirely different fixes: not rendered at
+ * all, rendered with no size, rendered off screen, rendered
+ * under something else, rendered invisibly. A caller whose
+ * click went nowhere needs to be told which.
+ */
+/**
+ * Judge an element's presence.
+ *
+ * The order matters. An element that is not rendered cannot
+ * usefully also be called covered, and saying so would send
+ * someone hunting an overlay that is not the cause. So the most
+ * fundamental problem is the one reported.
+ */
+export function judgeVisibility(facts) {
+    if (!facts.rendered || !facts.border) {
+        return {
+            state: "not rendered",
+            because: "it has no box, so display is none or it is not in the page",
+        };
+    }
+    if (facts.visibility === "hidden" || facts.visibility === "collapse") {
+        return {
+            state: "not rendered",
+            because: `its visibility is ${facts.visibility}`,
+        };
+    }
+    const { width, height } = facts.border;
+    if (width === 0 || height === 0) {
+        return { state: "zero size", because: `it measures ${width} by ${height}` };
+    }
+    if (facts.opacity === 0) {
+        return { state: "transparent", because: "its opacity is 0" };
+    }
+    const viewport = facts.viewport;
+    if (viewport && !overlaps(facts.border, viewport)) {
+        return {
+            state: "off screen",
+            because: `it sits outside the ${viewport.width} by ${viewport.height} ` +
+                "viewport and needs scrolling to",
+        };
+    }
+    if (facts.coveredBy) {
+        return {
+            state: "covered",
+            because: `${facts.coveredBy} is painted over its centre`,
+        };
+    }
+    return {
+        state: "visible",
+        because: "it is on screen and receives its own centre",
+    };
+}
+/**
+ * Whether any part of the box is on screen. Half a control is
+ * still usable, and calling it off screen would send a caller
+ * scrolling for no reason.
+ */
+function overlaps(border, viewport) {
+    return (border.x < viewport.width &&
+        border.y < viewport.height &&
+        border.x + border.width > 0 &&
+        border.y + border.height > 0);
+}

package/dist/web/envelope/artifacts.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Divert-to-disk: the uncapped form of any capped answer.
+ *
+ * A response has a byte budget; a file does not. Anything the
+ * budget cannot carry inline goes to the session's bundle
+ * directory whole, and the answer carries the path, so no
+ * result is ever unobtainable, only relocated.
+ */
+import type { Paged } from "./paged.js";
+import type { BundleSink } from "./sink.js";
+/** How the whole list should read on disk. */
+export interface ArtifactOptions<T> {
+    /** File name to write under, before uniquing. */
+    readonly name: string;
+    /** How to render the artifact; JSON when the caller has no opinion. */
+    readonly render?: (all: readonly T[]) => string;
+}
+/**
+ * Write the whole list to the sink and return the same page
+ * carrying the path, so the caller keeps its summary and its
+ * window alongside the complete answer.
+ */
+export declare function withArtifact<T>(page: Paged<T>, all: readonly T[], sink: BundleSink, options: ArtifactOptions<T>): Paged<T>;

package/dist/web/envelope/artifacts.js

@@ -0,0 +1,45 @@
+/**
+ * Divert-to-disk: the uncapped form of any capped answer.
+ *
+ * A response has a byte budget; a file does not. Anything the
+ * budget cannot carry inline goes to the session's bundle
+ * directory whole, and the answer carries the path, so no
+ * result is ever unobtainable, only relocated.
+ */
+/**
+ * Names already written to each sink, so no divert clobbers
+ * another. Keyed by the sink so the tally dies with the
+ * session's bundle directory rather than growing for the life
+ * of the process.
+ */
+const used = new WeakMap();
+/**
+ * Write the whole list to the sink and return the same page
+ * carrying the path, so the caller keeps its summary and its
+ * window alongside the complete answer.
+ */
+export function withArtifact(page, all, sink, options) {
+    const render = options.render ?? defaultRender;
+    const artifactPath = sink.writeText(unique(sink, options.name), render(all));
+    return { ...page, artifactPath };
+}
+/** A name no earlier divert to this sink has taken. */
+function unique(sink, name) {
+    let taken = used.get(sink);
+    if (!taken) {
+        taken = new Map();
+        used.set(sink, taken);
+    }
+    const seen = taken.get(name) ?? 0;
+    taken.set(name, seen + 1);
+    if (seen === 0)
+        return name;
+    const dot = name.lastIndexOf(".");
+    return dot <= 0
+        ? `${name}-${seen + 1}`
+        : `${name.slice(0, dot)}-${seen + 1}${name.slice(dot)}`;
+}
+/** The artifact when the caller names no format. */
+function defaultRender(all) {
+    return JSON.stringify(all, null, 2);
+}

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

@@ -0,0 +1,9 @@
+/**
+ * The shared envelope: how every list-shaped answer is
+ * windowed, budgeted and, when it outgrows a response,
+ * diverted to disk.
+ */
+export { type ArtifactOptions, withArtifact } from "./artifacts.js";
+export { pathComponent } from "./naming.js";
+export { DEFAULT_BUDGET_BYTES, DEFAULT_LIMIT, type ListArgs, type Paged, type PageShape, paginate, } from "./paged.js";
+export { BUNDLE_ROOT, type BundleSink, DIR_MODE, diskSink, FILE_MODE, LEGACY_BUNDLE_ROOTS, sessionDir, } from "./sink.js";

package/dist/web/envelope/index.js

@@ -0,0 +1,9 @@
+/**
+ * The shared envelope: how every list-shaped answer is
+ * windowed, budgeted and, when it outgrows a response,
+ * diverted to disk.
+ */
+export { withArtifact } from "./artifacts.js";
+export { pathComponent } from "./naming.js";
+export { DEFAULT_BUDGET_BYTES, DEFAULT_LIMIT, paginate, } from "./paged.js";
+export { BUNDLE_ROOT, DIR_MODE, diskSink, FILE_MODE, LEGACY_BUNDLE_ROOTS, sessionDir, } from "./sink.js";

package/dist/web/envelope/naming.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Turning caller-chosen words into one safe path component.
+ *
+ * Session names and baseline labels are chosen by whoever is
+ * driving, which in practice means a language model, and both end
+ * up joined onto a directory. A name of "../../../../tmp/evil"
+ * put a baseline write at /Users/tmp/evil rather than under the
+ * extension's data directory, because only the label was being
+ * cleaned and the session name went through untouched.
+ *
+ * The rule is stated once here and used by both, so the next
+ * caller-chosen word that becomes a path gets it for free rather
+ * than repeating the omission.
+ */
+/**
+ * One path component, safe to join onto a directory.
+ *
+ * Refuses nothing and always returns something joinable. A name
+ * made entirely of separators becomes the fallback rather than an
+ * error, because the caller asked to look at a page, not to be
+ * lectured about their session name.
+ */
+export declare function pathComponent(value: string): string;

package/dist/web/envelope/naming.js

@@ -0,0 +1,43 @@
+/**
+ * Turning caller-chosen words into one safe path component.
+ *
+ * Session names and baseline labels are chosen by whoever is
+ * driving, which in practice means a language model, and both end
+ * up joined onto a directory. A name of "../../../../tmp/evil"
+ * put a baseline write at /Users/tmp/evil rather than under the
+ * extension's data directory, because only the label was being
+ * cleaned and the session name went through untouched.
+ *
+ * The rule is stated once here and used by both, so the next
+ * caller-chosen word that becomes a path gets it for free rather
+ * than repeating the omission.
+ */
+/** What is allowed to survive into a path component. */
+const UNSAFE = /[^a-zA-Z0-9._-]+/g;
+/**
+ * A name to fall back on when nothing usable is left.
+ *
+ * Something has to be written somewhere, and an empty component
+ * makes path.join silently return the parent directory, which is
+ * how a file lands one level up from where it was meant to.
+ */
+const FALLBACK = "unnamed";
+/**
+ * One path component, safe to join onto a directory.
+ *
+ * Refuses nothing and always returns something joinable. A name
+ * made entirely of separators becomes the fallback rather than an
+ * error, because the caller asked to look at a page, not to be
+ * lectured about their session name.
+ */
+export function pathComponent(value) {
+    // "." and ".." survive the character filter untouched, and both
+    // mean a directory rather than a name. Stripping the leading dots
+    // handles those and the merely-hidden ".secret" in one move, but
+    // it can empty the name outright, which is why the fallback is
+    // applied after it rather than before: "..." cleaned first and
+    // checked second came back as the empty string, and path.join of
+    // an empty component returns the parent directory.
+    const cleaned = value.replace(UNSAFE, "-").replace(/^\.+/, "");
+    return cleaned === "" ? FALLBACK : cleaned;
+}

package/dist/web/envelope/paged.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The envelope every list-shaped answer arrives in.
+ *
+ * The context window is the screen these answers render to, so
+ * the shape is summary first: what the whole list looks like,
+ * then as much of it as the window and the byte budget allow,
+ * then how to get the rest. Limits here are presentation
+ * defaults, never ceilings: every one can be raised per call,
+ * and anything cut says so and says how to retrieve it.
+ */
+/** What a caller may ask of any list. */
+export interface ListArgs {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly ids?: readonly number[];
+    readonly toDisk?: boolean;
+    readonly budget?: number;
+}
+/** A window onto a list, with the whole list's shape around it. */
+export interface Paged<T> {
+    readonly total: number;
+    readonly groups?: Record<string, number>;
+    readonly items: readonly T[];
+    readonly nextCursor?: string;
+    readonly dropped?: number;
+    readonly elided?: string;
+    readonly artifactPath?: string;
+}
+/** What paging needs to know about the items it is windowing. */
+export interface PageShape<T> {
+    readonly idOf: (item: T) => number;
+    readonly groupOf?: (item: T) => string;
+    readonly sizeOf?: (item: T) => number;
+    readonly more?: string;
+    readonly dropped?: number;
+}
+/** How many items a window holds when the caller says nothing. */
+export declare const DEFAULT_LIMIT = 20;
+/** How many bytes a response spends on items when nothing says otherwise. */
+export declare const DEFAULT_BUDGET_BYTES = 8192;
+/** Window a list into the shared envelope. */
+export declare function paginate<T>(all: readonly T[], args: ListArgs, shape: PageShape<T>): Paged<T>;

package/dist/web/envelope/paged.js

@@ -0,0 +1,99 @@
+/**
+ * The envelope every list-shaped answer arrives in.
+ *
+ * The context window is the screen these answers render to, so
+ * the shape is summary first: what the whole list looks like,
+ * then as much of it as the window and the byte budget allow,
+ * then how to get the rest. Limits here are presentation
+ * defaults, never ceilings: every one can be raised per call,
+ * and anything cut says so and says how to retrieve it.
+ */
+/** How many items a window holds when the caller says nothing. */
+export const DEFAULT_LIMIT = 20;
+/** How many bytes a response spends on items when nothing says otherwise. */
+export const DEFAULT_BUDGET_BYTES = 8192;
+/** Window a list into the shared envelope. */
+export function paginate(all, args, shape) {
+    const summary = {
+        total: all.length,
+        ...(shape.groupOf ? { groups: countByGroup(all, shape.groupOf) } : {}),
+        ...(shape.dropped ? { dropped: shape.dropped } : {}),
+    };
+    // Naming ids is a detail fetch, not a walk: the window and
+    // the cursor have nothing to say about it.
+    if (args.ids) {
+        const wanted = new Set(args.ids);
+        return {
+            ...summary,
+            items: all.filter((one) => wanted.has(shape.idOf(one))),
+        };
+    }
+    const start = resumePoint(all, args.cursor, shape.idOf);
+    const limit = args.limit ?? DEFAULT_LIMIT;
+    const budget = args.budget ?? DEFAULT_BUDGET_BYTES;
+    const candidates = all.slice(start, start + limit);
+    const items = withinBudget(candidates, budget, shape.sizeOf ?? measure);
+    const consumed = start + items.length;
+    const remaining = all.length - consumed;
+    const cut = candidates.length - items.length;
+    return {
+        ...summary,
+        items,
+        // A cursor needs something to point at. With a limit of zero
+        // there are no items and this read index -1, so asking for an
+        // empty window of a non-empty list threw a TypeError instead
+        // of answering with nothing.
+        ...(remaining > 0 && items.length > 0
+            ? { nextCursor: String(shape.idOf(items[items.length - 1])) }
+            : {}),
+        ...(cut > 0 ? { elided: elision(cut, budget, shape.more) } : {}),
+    };
+}
+/** Where a cursor says to carry on from. */
+function resumePoint(all, cursor, idOf) {
+    if (cursor === undefined)
+        return 0;
+    const last = Number(cursor);
+    const at = all.findIndex((one) => idOf(one) === last);
+    // A cursor whose item is gone (evicted, re-run) starts over
+    // rather than silently skipping into the middle of the list.
+    return at === -1 ? 0 : at + 1;
+}
+/** As many items as the byte budget affords, and never none. */
+function withinBudget(candidates, budget, sizeOf) {
+    const kept = [];
+    let spent = 0;
+    for (const one of candidates) {
+        const cost = sizeOf(one);
+        // One item always goes through: a record too big for the
+        // budget must still be reachable, not invisible.
+        if (kept.length > 0 && spent + cost > budget)
+            break;
+        kept.push(one);
+        spent += cost;
+    }
+    return kept;
+}
+/** Say what the budget cut, and how the caller gets it anyway. */
+function elision(cut, budget, more) {
+    const ways = [
+        "raise budget",
+        ...(more ? [more] : []),
+        "or pass toDisk for the whole set",
+    ];
+    return (`${cut} more ${cut === 1 ? "item" : "items"} in this window did not ` +
+        `fit the ${budget} byte budget: ${ways.join(", ")}.`);
+}
+/** How many bytes an item costs when the caller has no opinion. */
+function measure(item) {
+    return JSON.stringify(item)?.length ?? 0;
+}
+/** How many items fall in each group across the whole list. */
+function countByGroup(all, groupOf) {
+    const counts = {};
+    for (const one of all) {
+        const group = groupOf(one);
+        counts[group] = (counts[group] ?? 0) + 1;
+    }
+    return counts;
+}

package/dist/web/envelope/sink.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Where anything too large to return goes.
+ *
+ * A response has a byte budget and an image has none, so
+ * captures are written to a private per-session directory and
+ * the answer carries the path. This lives beside the paging and
+ * artifact rules rather than with the page reader, because
+ * everything that outgrows a response needs it: screenshots,
+ * traces, network archives, whole DOMs.
+ */
+/** Where every session's bundle directory is rooted. */
+export declare const BUNDLE_ROOT: string;
+/**
+ * Where bundles used to be written, still swept so nothing is
+ * orphaned.
+ *
+ * The directory was named after web_read because that was the only
+ * thing writing to it. It now holds screenshots, HAR archives, DOM
+ * captures and visual baselines from four browser tools, and a
+ * person looking at their temp directory to find out what wrote
+ * two hundred megabytes there was told the wrong answer.
+ *
+ * Two of them: the original was hard-coded under /tmp, and the
+ * next version moved it under the real temp directory without
+ * renaming it.
+ */
+export declare const LEGACY_BUNDLE_ROOTS: readonly string[];
+/** Bundle directories are private to the user who made them. */
+export declare const DIR_MODE = 448;
+/** Artifacts are readable only by their owner. */
+export declare const FILE_MODE = 384;
+/** Somewhere to put what a response cannot carry. */
+export interface BundleSink {
+    dir: string;
+    /** Write a text artifact and return its path. */
+    writeText(name: string, content: string): string;
+    /** Write a binary artifact from base64 and return its path. */
+    writeBinary(name: string, base64: string): string;
+}
+/** This process's private bundle directory. */
+export declare function sessionDir(): string;
+/** A filesystem sink that creates a private bundle dir. */
+export declare function diskSink(root?: string): BundleSink;

package/dist/web/envelope/sink.js

@@ -0,0 +1,67 @@
+/**
+ * Where anything too large to return goes.
+ *
+ * A response has a byte budget and an image has none, so
+ * captures are written to a private per-session directory and
+ * the answer carries the path. This lives beside the paging and
+ * artifact rules rather than with the page reader, because
+ * everything that outgrows a response needs it: screenshots,
+ * traces, network archives, whole DOMs.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/** Where every session's bundle directory is rooted. */
+export const BUNDLE_ROOT = path.join(os.tmpdir(), "pi-web");
+/**
+ * Where bundles used to be written, still swept so nothing is
+ * orphaned.
+ *
+ * The directory was named after web_read because that was the only
+ * thing writing to it. It now holds screenshots, HAR archives, DOM
+ * captures and visual baselines from four browser tools, and a
+ * person looking at their temp directory to find out what wrote
+ * two hundred megabytes there was told the wrong answer.
+ *
+ * Two of them: the original was hard-coded under /tmp, and the
+ * next version moved it under the real temp directory without
+ * renaming it.
+ */
+export const LEGACY_BUNDLE_ROOTS = [
+    "/tmp/pi-web-read",
+    path.join(os.tmpdir(), "pi-web-read"),
+];
+/** Bundle directories are private to the user who made them. */
+export const DIR_MODE = 0o700;
+/** Artifacts are readable only by their owner. */
+export const FILE_MODE = 0o600;
+/** This process's private bundle directory. */
+export function sessionDir() {
+    return path.join(BUNDLE_ROOT, String(process.pid));
+}
+/** A filesystem sink that creates a private bundle dir. */
+export function diskSink(root = sessionDir()) {
+    fs.mkdirSync(root, { recursive: true, mode: DIR_MODE });
+    // The "r-" prefix keeps the temp dir inside root, where the
+    // reaper looks, rather than creating a sibling of it.
+    const dir = fs.mkdtempSync(path.join(root, "r-"));
+    fs.chmodSync(dir, DIR_MODE);
+    return {
+        dir,
+        writeText(name, content) {
+            const filePath = path.join(dir, name);
+            fs.writeFileSync(filePath, content, {
+                encoding: "utf-8",
+                mode: FILE_MODE,
+            });
+            return filePath;
+        },
+        writeBinary(name, base64) {
+            const filePath = path.join(dir, name);
+            fs.writeFileSync(filePath, Buffer.from(base64, "base64"), {
+                mode: FILE_MODE,
+            });
+            return filePath;
+        },
+    };
+}