@jitsusama/agentic-harness.core 0.1.0

package/dist/web/target/target.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Semantic targeting: resolve the way the model addresses an
+ * element (role plus accessible name, disambiguated by
+ * container or a name-scoped ordinal) to the matched node's
+ * internal backend id. The id never reaches the model; the
+ * caller uses it to drive the real element, and falls back to
+ * text, selector or coordinates when the tree cannot name the
+ * element.
+ */
+import type { AxNode } from "../a11y/index.js";
+/** How the model addresses an element. */
+export interface Target {
+    readonly role: string;
+    /**
+     * The accessible name, when there is one. An icon button or a
+     * bare input has none, and the outline shows only its role, so
+     * a role on its own has to be a way of addressing it.
+     */
+    readonly name?: string;
+    /** Restrict to descendants of a container with this name (and optional role). */
+    readonly container?: {
+        readonly role?: string;
+        readonly name: string;
+    };
+    /** 1-based position among same-named matches ("the second X"). */
+    readonly ordinal?: number;
+}
+/** The outcome of resolving a target. */
+export type TargetResolution = {
+    kind: "resolved";
+    backendDomId: number;
+} | {
+    kind: "ambiguous";
+    count: number;
+} | {
+    kind: "notFound";
+};
+/**
+ * How this module compares a written role or name to the one
+ * in the tree: case and surrounding whitespace never decide a
+ * match. Shared with the refusal ladder so both agree on what
+ * counts as the same name.
+ */
+export declare function foldEquals(a: string | undefined, b: string | undefined): boolean;
+/**
+ * Resolve a semantic target to a backend id, or report that it
+ * matched nothing or more than one node.
+ */
+export declare function resolveTarget(root: AxNode, target: Target): TargetResolution;
+/**
+ * Read a target written the way the outline prints it.
+ *
+ * The role is the first word, since roles are single words and
+ * names routinely are not. Quotes around the name are allowed,
+ * because a caller copying from the outline will bring them.
+ * A bare role targets the unnamed element of that role, which
+ * is how landmarks usually appear.
+ */
+export declare function parseTarget(spec: string): Target | undefined;

package/dist/web/target/target.js

@@ -0,0 +1,94 @@
+/**
+ * Semantic targeting: resolve the way the model addresses an
+ * element (role plus accessible name, disambiguated by
+ * container or a name-scoped ordinal) to the matched node's
+ * internal backend id. The id never reaches the model; the
+ * caller uses it to drive the real element, and falls back to
+ * text, selector or coordinates when the tree cannot name the
+ * element.
+ */
+/**
+ * How this module compares a written role or name to the one
+ * in the tree: case and surrounding whitespace never decide a
+ * match. Shared with the refusal ladder so both agree on what
+ * counts as the same name.
+ */
+export function foldEquals(a, b) {
+    // A missing name and an empty one are the same thing here:
+    // parseTarget already yields "" for a bare role, and a node
+    // with nothing to call it normalizes the same way. Accepting
+    // undefined keeps a caller outside TypeScript from getting a
+    // TypeError three frames down instead of an answer.
+    return (a ?? "").trim().toLowerCase() === (b ?? "").trim().toLowerCase();
+}
+/** Every node under (and including) root, depth-first. */
+function flatten(node, into) {
+    into.push(node);
+    for (const child of node.children)
+        flatten(child, into);
+}
+/** The subtrees whose container matches, or the whole tree when none is asked for. */
+function scopes(root, container) {
+    if (!container)
+        return [root];
+    const all = [];
+    flatten(root, all);
+    return all.filter((node) => foldEquals(node.name, container.name) &&
+        (container.role === undefined || foldEquals(node.role, container.role)));
+}
+/**
+ * Resolve a semantic target to a backend id, or report that it
+ * matched nothing or more than one node.
+ */
+export function resolveTarget(root, target) {
+    const matches = [];
+    for (const scope of scopes(root, target.container)) {
+        const nodes = [];
+        flatten(scope, nodes);
+        for (const node of nodes) {
+            if (foldEquals(node.role, target.role) &&
+                foldEquals(node.name, target.name)) {
+                matches.push(node);
+            }
+        }
+    }
+    if (target.ordinal !== undefined) {
+        const picked = matches[target.ordinal - 1];
+        return picked?.backendDomId !== undefined
+            ? { kind: "resolved", backendDomId: picked.backendDomId }
+            : { kind: "notFound" };
+    }
+    if (matches.length === 0)
+        return { kind: "notFound" };
+    if (matches.length > 1)
+        return { kind: "ambiguous", count: matches.length };
+    const only = matches[0];
+    return only.backendDomId !== undefined
+        ? { kind: "resolved", backendDomId: only.backendDomId }
+        : { kind: "notFound" };
+}
+/**
+ * Read a target written the way the outline prints it.
+ *
+ * The role is the first word, since roles are single words and
+ * names routinely are not. Quotes around the name are allowed,
+ * because a caller copying from the outline will bring them.
+ * A bare role targets the unnamed element of that role, which
+ * is how landmarks usually appear.
+ */
+export function parseTarget(spec) {
+    const trimmed = spec.trim();
+    if (!trimmed)
+        return undefined;
+    const split = trimmed.indexOf(" ");
+    if (split < 0)
+        return { role: trimmed, name: "" };
+    return {
+        role: trimmed.slice(0, split),
+        name: unquote(trimmed.slice(split + 1).trim()),
+    };
+}
+/** Drop a matched pair of surrounding quotes. */
+function unquote(name) {
+    return name.replace(/^(["'])(.*)\1$/, "$2");
+}

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

@@ -0,0 +1,35 @@
+/**
+ * A bounded record of things that happened.
+ *
+ * A page can log thousands of lines and issue hundreds of
+ * requests. Keeping all of it risks the process; keeping a
+ * silent subset risks the reader's conclusions. This keeps the
+ * most recent within a budget and always says how much it had
+ * to drop, so a partial record is never mistaken for a whole
+ * one.
+ */
+/** An item as recorded, with its place in the sequence. */
+export interface Recorded<T> {
+    readonly seq: number;
+    readonly item: T;
+}
+/** How much a buffer is willing to hold. */
+export interface BufferLimits {
+    readonly maxEntries?: number;
+    readonly maxBytes?: number;
+}
+/** A bounded, cursor-readable record. */
+export interface RingBuffer<T> {
+    push(item: T): void;
+    all(): readonly Recorded<T>[];
+    since(cursor: number): readonly Recorded<T>[];
+    readonly dropped: number;
+    readonly size: number;
+    readonly cursor: number;
+}
+/** Entries a buffer holds before it starts evicting. */
+export declare const DEFAULT_MAX_ENTRIES = 2000;
+/** Bytes a buffer holds before it starts evicting. */
+export declare const DEFAULT_MAX_BYTES: number;
+/** Create a buffer that keeps the most recent entries. */
+export declare function createRingBuffer<T>(limits?: BufferLimits): RingBuffer<T>;

package/dist/web/telemetry/buffer.js

@@ -0,0 +1,72 @@
+/**
+ * A bounded record of things that happened.
+ *
+ * A page can log thousands of lines and issue hundreds of
+ * requests. Keeping all of it risks the process; keeping a
+ * silent subset risks the reader's conclusions. This keeps the
+ * most recent within a budget and always says how much it had
+ * to drop, so a partial record is never mistaken for a whole
+ * one.
+ */
+/** Entries a buffer holds before it starts evicting. */
+export const DEFAULT_MAX_ENTRIES = 2000;
+/** Bytes a buffer holds before it starts evicting. */
+export const DEFAULT_MAX_BYTES = 4 * 1024 * 1024;
+/** Create a buffer that keeps the most recent entries. */
+export function createRingBuffer(limits = {}) {
+    const maxEntries = limits.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    const maxBytes = limits.maxBytes ?? DEFAULT_MAX_BYTES;
+    const held = [];
+    let seen = 0;
+    let dropped = 0;
+    let weight = 0;
+    /**
+     * Drop the oldest until the buffer is inside its budget. The
+     * last entry always stays, even when it alone exceeds the
+     * budget: an oversized record should be expensive to read,
+     * not invisible.
+     */
+    const evict = () => {
+        while (held.length > 1 && (held.length > maxEntries || weight > maxBytes)) {
+            const oldest = held.shift();
+            if (!oldest)
+                break;
+            weight -= oldest.weight;
+            dropped += 1;
+        }
+    };
+    return {
+        push(item) {
+            seen += 1;
+            const cost = weigh(item);
+            held.push({ record: { seq: seen, item }, weight: cost });
+            weight += cost;
+            evict();
+        },
+        all: () => held.map((entry) => entry.record),
+        since: (cursor) => held.filter((entry) => entry.record.seq > cursor).map((e) => e.record),
+        get dropped() {
+            return dropped;
+        },
+        get size() {
+            return held.length;
+        },
+        get cursor() {
+            return seen;
+        },
+    };
+}
+/** Roughly what an entry costs to keep. */
+function weigh(item) {
+    if (typeof item === "string")
+        return item.length;
+    try {
+        return JSON.stringify(item)?.length ?? 0;
+    }
+    catch {
+        // A value that will not serialize (a cycle, a bigint) still
+        // occupies space; charge it a nominal amount rather than
+        // letting it weigh nothing and evade the budget.
+        return 256;
+    }
+}

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

@@ -0,0 +1,127 @@
+/**
+ * What the page said, and how to read it back.
+ *
+ * Chrome hands over console arguments as remote object
+ * descriptions rather than text: it never renders them, because
+ * rendering is the front end's job. Everything here is that
+ * front end, and is therefore presentation by definition. The
+ * facts, the types, the values and the previews, are the
+ * browser's; the shape they are read in is ours.
+ */
+/** A property inside a preview Chrome sends. */
+export interface RemotePreviewProperty {
+    readonly name: string;
+    readonly type: string;
+    readonly subtype?: string;
+    readonly value?: string;
+}
+/** Chrome's summary of an object it will not send whole. */
+export interface RemotePreview {
+    readonly type: string;
+    readonly subtype?: string;
+    readonly description?: string;
+    readonly overflow?: boolean;
+    readonly properties?: readonly RemotePreviewProperty[];
+}
+/** One console argument as the protocol describes it. */
+export interface RemoteArg {
+    readonly type: string;
+    readonly subtype?: string;
+    readonly className?: string;
+    readonly description?: string;
+    readonly value?: unknown;
+    readonly objectId?: string;
+    readonly preview?: RemotePreview;
+}
+/**
+ * One console argument, as the developer would have seen it.
+ *
+ * Strings read bare, because that is how a logged message
+ * reads; a string nested inside an object is quoted, because
+ * there the quoting is what distinguishes it from a name.
+ */
+export declare function renderArg(arg: RemoteArg): string;
+/** One line of what the page said. */
+export interface LogEntry {
+    readonly source: string;
+    readonly level: string;
+    readonly text: string;
+    readonly timestamp: number;
+    readonly origin?: string;
+    readonly stack?: string;
+    readonly requestId?: string;
+}
+/** One frame of a stack Chrome captured. */
+export interface CallFrame {
+    readonly functionName: string;
+    readonly url: string;
+    readonly lineNumber: number;
+    readonly columnNumber: number;
+}
+/** Runtime.consoleAPICalled, as the protocol sends it. */
+export interface ConsoleCalled {
+    readonly type: string;
+    readonly timestamp: number;
+    readonly args: readonly RemoteArg[];
+    readonly stackTrace?: {
+        readonly callFrames: readonly CallFrame[];
+    };
+}
+/**
+ * Runtime.exceptionThrown's details, as the protocol sends
+ * them. The timestamp is not in here: it belongs to the event
+ * that carried the details, and is passed alongside.
+ */
+export interface ExceptionThrown {
+    readonly text: string;
+    readonly url?: string;
+    readonly lineNumber?: number;
+    readonly columnNumber?: number;
+    readonly exception?: RemoteArg;
+    readonly stackTrace?: {
+        readonly callFrames: readonly CallFrame[];
+    };
+}
+/** Log.entryAdded's entry, as the protocol sends it. */
+export interface BrowserLogged {
+    readonly source: string;
+    readonly level: string;
+    readonly text: string;
+    readonly timestamp: number;
+    readonly url?: string;
+    readonly lineNumber?: number;
+    readonly networkRequestId?: string;
+    readonly stackTrace?: {
+        readonly callFrames: readonly CallFrame[];
+    };
+}
+/**
+ * The text of a console call, directives and all.
+ *
+ * Chrome sends the arguments exactly as they were passed and
+ * substitutes nothing, because substitution is the front end's
+ * job. Doing it here is what makes the line read the way the
+ * developer saw it in their own console rather than as a
+ * format string followed by loose values.
+ */
+export declare function consoleText(args: readonly RemoteArg[]): string;
+/** A console call, as a log entry. */
+export declare function consoleEntry(event: ConsoleCalled): LogEntry;
+/**
+ * A thrown exception, as a log entry.
+ *
+ * The protocol's own text is only "Uncaught", or "Uncaught (in
+ * promise)" when a rejection went unhandled. That prefix says
+ * how the throw escaped and is worth keeping, but the message
+ * itself lives on the thrown value.
+ */
+export declare function exceptionEntry(details: ExceptionThrown, timestamp: number): LogEntry;
+/**
+ * A browser-generated message, as a log entry.
+ *
+ * These are the ones the page's own console never sees: a
+ * resource that failed to load, a blocked mixed-content
+ * request, a deprecation. Missing them is how a broken image
+ * goes unnoticed.
+ */
+export declare function browserEntry(entry: BrowserLogged): LogEntry;

package/dist/web/telemetry/console.js

@@ -0,0 +1,217 @@
+/**
+ * What the page said, and how to read it back.
+ *
+ * Chrome hands over console arguments as remote object
+ * descriptions rather than text: it never renders them, because
+ * rendering is the front end's job. Everything here is that
+ * front end, and is therefore presentation by definition. The
+ * facts, the types, the values and the previews, are the
+ * browser's; the shape they are read in is ours.
+ */
+/** How many preview properties are worth showing before it stops helping. */
+const MAX_PREVIEW_PROPERTIES = 8;
+/**
+ * One console argument, as the developer would have seen it.
+ *
+ * Strings read bare, because that is how a logged message
+ * reads; a string nested inside an object is quoted, because
+ * there the quoting is what distinguishes it from a name.
+ */
+export function renderArg(arg) {
+    if (arg.type === "undefined")
+        return "undefined";
+    if (arg.subtype === "null")
+        return "null";
+    if (arg.type === "string")
+        return String(arg.value ?? arg.description ?? "");
+    if (arg.type === "bigint")
+        return arg.description ?? String(arg.value);
+    if (arg.type === "number" || arg.type === "boolean") {
+        return arg.value !== undefined
+            ? String(arg.value)
+            : (arg.description ?? "");
+    }
+    // An error's description carries the whole stack. The message
+    // is the first line; the rest belongs to the entry's own stack
+    // field, where it is not repeated for every argument.
+    if (arg.subtype === "error" && arg.description) {
+        return arg.description.split("\n")[0] ?? arg.description;
+    }
+    // A node prints as the selector-ish description Chrome gives,
+    // not as its property bag, which is all attributes and noise.
+    if (arg.subtype === "node")
+        return arg.description ?? "node";
+    const preview = arg.preview;
+    if (preview?.properties) {
+        const isArray = preview.subtype === "array" || arg.subtype === "array";
+        const shown = preview.properties.slice(0, MAX_PREVIEW_PROPERTIES);
+        const parts = shown.map((property) => isArray
+            ? previewValue(property)
+            : `${property.name}: ${previewValue(property)}`);
+        const cut = preview.overflow || shown.length < preview.properties.length;
+        if (cut)
+            parts.push("...");
+        return isArray ? `[${parts.join(", ")}]` : `{${parts.join(", ")}}`;
+    }
+    return arg.description ?? arg.className ?? arg.type;
+}
+/**
+ * The text of a console call, directives and all.
+ *
+ * Chrome sends the arguments exactly as they were passed and
+ * substitutes nothing, because substitution is the front end's
+ * job. Doing it here is what makes the line read the way the
+ * developer saw it in their own console rather than as a
+ * format string followed by loose values.
+ */
+export function consoleText(args) {
+    if (args.length === 0)
+        return "";
+    const [first, ...rest] = args;
+    if (first === undefined)
+        return "";
+    const pending = [...rest];
+    const formatted = first.type === "string"
+        ? substitute(String(first.value ?? ""), pending)
+        : renderArg(first);
+    return [formatted, ...pending.map(renderArg)].filter(Boolean).join(" ");
+}
+/**
+ * Fill a format string from the arguments, consuming as it
+ * goes, so whatever is left over can be appended.
+ */
+function substitute(format, pending) {
+    return format.replace(/%[sdifoOjc%]/g, (directive) => {
+        if (directive === "%%")
+            return "%";
+        // A directive with nothing left to fill it is not a
+        // directive; "100%s complete" is a sentence about percent.
+        if (pending.length === 0)
+            return directive;
+        const arg = pending.shift();
+        if (arg === undefined)
+            return directive;
+        // %c consumes its styling and shows nothing: this is text.
+        if (directive === "%c")
+            return "";
+        if (directive === "%d" || directive === "%i") {
+            const value = Number(arg.value ?? arg.description);
+            return Number.isFinite(value)
+                ? String(Math.trunc(value))
+                : renderArg(arg);
+        }
+        return renderArg(arg);
+    });
+}
+/** A console call, as a log entry. */
+export function consoleEntry(event) {
+    const origin = originOf(event.stackTrace?.callFrames);
+    return {
+        source: "console",
+        // Chrome's own vocabulary, kept as sent: it says "warning",
+        // not "warn", and renaming it would invent a third dialect.
+        level: event.type,
+        text: consoleText(event.args),
+        timestamp: event.timestamp,
+        ...(origin === undefined ? {} : { origin }),
+        ...stackOf(event.stackTrace?.callFrames),
+    };
+}
+/**
+ * A thrown exception, as a log entry.
+ *
+ * The protocol's own text is only "Uncaught", or "Uncaught (in
+ * promise)" when a rejection went unhandled. That prefix says
+ * how the throw escaped and is worth keeping, but the message
+ * itself lives on the thrown value.
+ */
+export function exceptionEntry(details, timestamp) {
+    const thrown = details.exception ? renderArg(details.exception) : "";
+    const description = details.exception?.description ?? "";
+    const stack = description.includes("\n")
+        ? description.slice(description.indexOf("\n") + 1)
+        : undefined;
+    const origin = locationOf(details.url, details.lineNumber, details.columnNumber);
+    return {
+        source: "exception",
+        level: "error",
+        text: [details.text, thrown].filter(Boolean).join(" "),
+        timestamp,
+        ...(origin === undefined ? {} : { origin }),
+        ...(stack === undefined ? {} : { stack }),
+    };
+}
+/**
+ * A browser-generated message, as a log entry.
+ *
+ * These are the ones the page's own console never sees: a
+ * resource that failed to load, a blocked mixed-content
+ * request, a deprecation. Missing them is how a broken image
+ * goes unnoticed.
+ */
+export function browserEntry(entry) {
+    const origin = locationOf(entry.url, entry.lineNumber);
+    return {
+        source: entry.source,
+        level: entry.level,
+        text: entry.text,
+        timestamp: entry.timestamp,
+        ...(origin === undefined ? {} : { origin }),
+        ...(entry.networkRequestId === undefined
+            ? {}
+            : { requestId: entry.networkRequestId }),
+        ...stackOf(entry.stackTrace?.callFrames),
+    };
+}
+/** Where a call came from: the innermost frame that has a url. */
+function originOf(frames) {
+    const frame = frames?.find((candidate) => candidate.url);
+    return frame
+        ? locationOf(frame.url, frame.lineNumber, frame.columnNumber)
+        : undefined;
+}
+/**
+ * The rest of the stack, when there is more than one frame.
+ *
+ * A frame is worth a line when it can say where it was or what
+ * it was called. Code the page ran through the debugger has
+ * neither, and those frames used to print as "at (anonymous)
+ * undefined": three lines of that under every console.error,
+ * saying less than nothing, since "undefined" reads as a value
+ * the page produced. A stack of nothing but those is no stack.
+ */
+function stackOf(frames) {
+    if (!frames || frames.length < 2)
+        return {};
+    const lines = frames
+        .map((frame) => {
+        const where = locationOf(frame.url, frame.lineNumber, frame.columnNumber);
+        if (!frame.functionName && !where)
+            return undefined;
+        if (!where)
+            return `    at ${frame.functionName}`;
+        return `    at ${frame.functionName || "(anonymous)"} ${where}`;
+    })
+        .filter((line) => line !== undefined);
+    return lines.length > 0 ? { stack: lines.join("\n") } : {};
+}
+/**
+ * A url with its position, counted from one.
+ *
+ * The protocol counts lines and columns from zero; every editor
+ * and every stack trace a developer reads counts from one.
+ */
+function locationOf(url, line, column) {
+    if (!url)
+        return undefined;
+    if (line === undefined)
+        return url;
+    const place = `${url}:${line + 1}`;
+    return column === undefined ? place : `${place}:${column + 1}`;
+}
+/** A preview property's value, quoted when a string. */
+function previewValue(property) {
+    if (property.type === "string")
+        return JSON.stringify(property.value ?? "");
+    return property.value ?? property.type;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * The dialogs a page put up, and what was said back.
+ *
+ * A dialog is not a passive event. Until something answers it,
+ * the page is stopped: no script runs, no action lands, and
+ * anything waiting on the page waits forever. So a session
+ * always has an answer ready, and records what it gave.
+ */
+/** What the page asked for. */
+export type DialogKind = "alert" | "confirm" | "prompt" | "beforeunload";
+/** How dialogs get answered while nobody is watching. */
+export interface DialogPolicy {
+    /** Accept, or dismiss. Dismissing is the cautious default. */
+    readonly accept: boolean;
+    /** What to type into a prompt when accepting one. */
+    readonly promptText?: string;
+}
+/** One dialog, and the answer it was given. */
+export interface DialogEvent {
+    readonly kind: DialogKind;
+    readonly message: string;
+    readonly defaultPrompt?: string;
+    readonly accepted: boolean;
+    readonly reply?: string;
+    readonly url?: string;
+}
+/**
+ * Dismiss unless told otherwise.
+ *
+ * Dismissing is the answer that changes least: a confirm that
+ * guards a deletion gets a no, and a prompt gets nothing rather
+ * than a value nobody chose. Accepting can be asked for.
+ */
+export declare const DEFAULT_DIALOG_POLICY: DialogPolicy;
+/** What the page asked, and what it was told. */
+export declare function renderDialogs(dialogs: readonly DialogEvent[]): string;
+/** How a dialog of this kind would be answered under this policy. */
+export declare function answerFor(kind: DialogKind, policy: DialogPolicy): {
+    accept: boolean;
+    promptText?: string;
+};

package/dist/web/telemetry/dialogs.js

@@ -0,0 +1,38 @@
+/**
+ * The dialogs a page put up, and what was said back.
+ *
+ * A dialog is not a passive event. Until something answers it,
+ * the page is stopped: no script runs, no action lands, and
+ * anything waiting on the page waits forever. So a session
+ * always has an answer ready, and records what it gave.
+ */
+/**
+ * Dismiss unless told otherwise.
+ *
+ * Dismissing is the answer that changes least: a confirm that
+ * guards a deletion gets a no, and a prompt gets nothing rather
+ * than a value nobody chose. Accepting can be asked for.
+ */
+export const DEFAULT_DIALOG_POLICY = { accept: false };
+/** What the page asked, and what it was told. */
+export function renderDialogs(dialogs) {
+    if (dialogs.length === 0)
+        return "The page has not opened a dialog.";
+    return dialogs
+        .map((dialog) => {
+        const answered = dialog.accepted ? "accepted" : "dismissed";
+        const typed = dialog.reply === undefined || dialog.reply === ""
+            ? ""
+            : ` with "${dialog.reply}"`;
+        return `${dialog.kind}: ${dialog.message}\n  ${answered}${typed}`;
+    })
+        .join("\n");
+}
+/** How a dialog of this kind would be answered under this policy. */
+export function answerFor(kind, policy) {
+    // Only a prompt has anywhere to put text, and sending it to
+    // the others would be meaningless rather than harmless.
+    return kind === "prompt" && policy.accept && policy.promptText !== undefined
+        ? { accept: policy.accept, promptText: policy.promptText }
+        : { accept: policy.accept };
+}