@jitsusama/agentic-harness.core 0.1.0

package/dist/web/screenshot.js

@@ -0,0 +1,108 @@
+/**
+ * Bounded, tiled screenshot capture.
+ *
+ * `preparePage` settles the page (capture-width viewport, lazy-content
+ * scroll) so every representation is read from one state. `captureTiles`
+ * then captures the page as an ordered stack of vertical bands rather than
+ * one full-page image. Each band stays under the model provider's image
+ * dimension limit, so a long page can never produce an image the model
+ * rejects. A page taller than the tile budget is truncated and the caller
+ * is told.
+ */
+/**
+ * Plan the vertical clip bands that tile a page of the given height. No
+ * band exceeds `bandHeight`, and the plan stops at `maxTiles`, reporting
+ * `truncated` when the page runs past the tile budget.
+ */
+export function planTiles(pageHeight, opts) {
+    const { bandHeight, maxTiles } = opts;
+    const bands = [];
+    for (let y = 0; y < pageHeight && bands.length < maxTiles; y += bandHeight) {
+        bands.push({ y, height: Math.min(bandHeight, pageHeight - y) });
+    }
+    const last = bands.at(-1);
+    const covered = last ? last.y + last.height : 0;
+    return { bands, truncated: covered < pageHeight };
+}
+/** Milliseconds to wait between scroll steps for lazy content to load. */
+const SCROLL_STEP_WAIT = 100;
+/** Maximum scroll steps before we give up and capture what we have. */
+const MAX_SCROLL_STEPS = 40;
+/**
+ * Milliseconds to wait after resizing and scrolling for the reflow and
+ * any scroll-triggered lazy loads to settle before capture.
+ */
+const SETTLE_WAIT = 500;
+/**
+ * Scroll to the bottom in viewport-sized steps to trigger lazy-loaded
+ * content, then return to the top so the capture starts from the top.
+ */
+async function scrollToBottom(page) {
+    await page.evaluate(({ wait, max }) => new Promise((resolve) => {
+        let steps = 0;
+        const timer = setInterval(() => {
+            const before = window.scrollY;
+            window.scrollBy(0, window.innerHeight);
+            steps += 1;
+            const reachedBottom = window.scrollY === before;
+            if (steps >= max || reachedBottom) {
+                clearInterval(timer);
+                window.scrollTo(0, 0);
+                resolve();
+            }
+        }, wait);
+    }), { wait: SCROLL_STEP_WAIT, max: MAX_SCROLL_STEPS });
+}
+/**
+ * Fixed capture width in CSS pixels. Well under the provider's long-edge
+ * downscale threshold, so width is never the offending dimension.
+ */
+const CAPTURE_WIDTH = 1280;
+/**
+ * Height of each tile in CSS pixels. Kept under the standard tier's
+ * 1568-pixel long-edge limit so a tile is not downscaled and its text
+ * stays legible.
+ */
+const BAND_HEIGHT = 1500;
+/**
+ * Ceiling on the number of tiles per page. Eight 1500-pixel bands cover
+ * 12000 pixels of page while staying well under the 20-image request
+ * rule, so a runaway page never floods the response.
+ */
+const MAX_TILES = 8;
+/**
+ * Settle the page into the state every representation is captured from:
+ * fix the viewport to the capture width, then scroll to the bottom so
+ * lazy-loaded content renders, returning to the top. Call this once before
+ * reading the DOM, inner text or screenshots so they all agree.
+ */
+export async function preparePage(page) {
+    await page.setViewport({ width: CAPTURE_WIDTH, height: 1024 });
+    await scrollToBottom(page);
+    // Let the resize reflow and any scroll-triggered lazy loads settle so
+    // the text, DOM and screenshots that follow agree on one rendered state.
+    await page.evaluate((ms) => new Promise((r) => setTimeout(r, ms)), SETTLE_WAIT);
+}
+/**
+ * Capture the page as an ordered stack of PNG tiles, each a base64 string,
+ * by clipping successive vertical bands planned by `planTiles`. No tile
+ * exceeds the band height, and the capture stops at the tile ceiling.
+ * Assumes `preparePage` has already settled the viewport and lazy content.
+ */
+export async function captureTiles(page) {
+    const pageHeight = await page.evaluate(() => Math.ceil(document.documentElement.scrollHeight));
+    const { bands, truncated } = planTiles(pageHeight, {
+        bandHeight: BAND_HEIGHT,
+        maxTiles: MAX_TILES,
+    });
+    const tiles = [];
+    for (const band of bands) {
+        const shot = await page.screenshot({
+            type: "png",
+            encoding: "base64",
+            clip: { x: 0, y: band.y, width: CAPTURE_WIDTH, height: band.height },
+        });
+        tiles.push(typeof shot === "string" ? shot : Buffer.from(shot).toString("base64"));
+    }
+    return { tiles, truncated };
+}

package/dist/web/search.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Web search via headless Chrome. DuckDuckGo's HTML interface
+ * is the primary provider; Bing's HTML results are the
+ * fallback when DuckDuckGo returns nothing or errors. Google
+ * blocks headless browsers, so it is not used.
+ */
+/** A single web search result. */
+export interface SearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+/** A search backend: a URL to visit and a page-side extractor. */
+interface SearchProvider {
+    readonly name: string;
+    url(query: string): string;
+    /** Runs in the page context; returns raw title/href/snippet rows. */
+    extract(): {
+        title: string;
+        url: string;
+        snippet: string;
+    }[];
+    /** Normalize a raw href into a real destination URL. */
+    cleanUrl(href: string): string;
+}
+/** Extract the real URL from a DuckDuckGo redirect link. */
+export declare function extractDuckDuckGoUrl(ddgHref: string): string;
+/**
+ * Unwrap a Bing `ck/a` redirect to its destination. Bing
+ * wraps organic result links as `.../ck/a?...&u=a1<base64url>`;
+ * the segment after the `a1` marker is the base64url-encoded
+ * target. A link that is not wrapped is returned unchanged.
+ */
+export declare function extractBingUrl(href: string): string;
+/**
+ * Try each provider in order and return the first non-empty
+ * result. A provider that throws or returns nothing hands off to
+ * the next; when all are exhausted the result is an empty list.
+ * The runner is passed in so the fallback order can be exercised
+ * without a live browser.
+ */
+export declare function firstProviderResults(providers: readonly SearchProvider[], run: (provider: SearchProvider) => Promise<SearchResult[]>): Promise<SearchResult[]>;
+/**
+ * Search the web, trying each provider in turn until one
+ * returns results. DuckDuckGo is primary and Bing is the
+ * fallback; when all are exhausted the result is an empty list.
+ */
+export declare function webSearch(query: string, numResults?: number, signal?: AbortSignal): Promise<SearchResult[]>;
+export {};

package/dist/web/search.js

@@ -0,0 +1,137 @@
+/**
+ * Web search via headless Chrome. DuckDuckGo's HTML interface
+ * is the primary provider; Bing's HTML results are the
+ * fallback when DuckDuckGo returns nothing or errors. Google
+ * blocks headless browsers, so it is not used.
+ */
+import { newPage } from "./browser.js";
+/** Timeout for search page navigation in milliseconds. */
+const SEARCH_PAGE_TIMEOUT = 15_000;
+/** Extract the real URL from a DuckDuckGo redirect link. */
+export function extractDuckDuckGoUrl(ddgHref) {
+    const match = ddgHref.match(/uddg=([^&]+)/);
+    if (match) {
+        try {
+            return decodeURIComponent(match[1]);
+        }
+        catch {
+            // Malformed encoding: return the href unchanged rather than
+            // promoting the redirect wrapper as if it were the target.
+            return ddgHref;
+        }
+    }
+    if (ddgHref.startsWith("//"))
+        return `https:${ddgHref}`;
+    return ddgHref;
+}
+const DUCKDUCKGO = {
+    name: "duckduckgo",
+    url: (query) => `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`,
+    extract: () => {
+        const entries = [];
+        for (const item of document.querySelectorAll(".result")) {
+            const anchor = item.querySelector("a.result__a");
+            const snippetEl = item.querySelector(".result__snippet");
+            const title = anchor?.textContent?.trim() || "";
+            const href = anchor?.getAttribute("href") || "";
+            const snippet = snippetEl?.textContent?.trim() || "";
+            if (title && href)
+                entries.push({ title, url: href, snippet });
+        }
+        return entries;
+    },
+    cleanUrl: extractDuckDuckGoUrl,
+};
+/**
+ * Unwrap a Bing `ck/a` redirect to its destination. Bing
+ * wraps organic result links as `.../ck/a?...&u=a1<base64url>`;
+ * the segment after the `a1` marker is the base64url-encoded
+ * target. A link that is not wrapped is returned unchanged.
+ */
+export function extractBingUrl(href) {
+    try {
+        const u = new URL(href, "https://www.bing.com").searchParams.get("u");
+        if (u?.startsWith("a1")) {
+            const b64 = u.slice(2).replace(/-/g, "+").replace(/_/g, "/");
+            const decoded = Buffer.from(b64, "base64").toString("utf8");
+            if (/^https?:\/\//.test(decoded))
+                return decoded;
+        }
+    }
+    catch {
+        // Not a parseable redirect; fall back to the raw href.
+    }
+    return href;
+}
+const BING = {
+    name: "bing",
+    url: (query) => `https://www.bing.com/search?q=${encodeURIComponent(query)}`,
+    extract: () => {
+        const entries = [];
+        for (const item of document.querySelectorAll("li.b_algo")) {
+            const anchor = item.querySelector("h2 a");
+            const snippetEl = item.querySelector(".b_caption p, p");
+            const title = anchor?.textContent?.trim() || "";
+            const href = anchor?.getAttribute("href") || "";
+            const snippet = snippetEl?.textContent?.trim() || "";
+            if (title && href)
+                entries.push({ title, url: href, snippet });
+        }
+        return entries;
+    },
+    cleanUrl: extractBingUrl,
+};
+/** Providers in the order they are tried. */
+const PROVIDERS = [DUCKDUCKGO, BING];
+/** Run one provider, returning its results or an empty list. */
+async function runProvider(provider, query, numResults, signal) {
+    const page = await newPage();
+    try {
+        if (signal?.aborted)
+            return [];
+        await page.goto(provider.url(query), {
+            waitUntil: "domcontentloaded",
+            timeout: SEARCH_PAGE_TIMEOUT,
+        });
+        if (signal?.aborted)
+            return [];
+        const raw = await page.evaluate(provider.extract);
+        return raw.slice(0, numResults).map((r) => ({
+            ...r,
+            url: provider.cleanUrl(r.url),
+        }));
+    }
+    finally {
+        await page.close();
+    }
+}
+/**
+ * Try each provider in order and return the first non-empty
+ * result. A provider that throws or returns nothing hands off to
+ * the next; when all are exhausted the result is an empty list.
+ * The runner is passed in so the fallback order can be exercised
+ * without a live browser.
+ */
+export async function firstProviderResults(providers, run) {
+    for (const provider of providers) {
+        try {
+            const results = await run(provider);
+            if (results.length > 0)
+                return results;
+        }
+        catch {
+            // This provider failed; fall through to the next one.
+        }
+    }
+    return [];
+}
+/**
+ * Search the web, trying each provider in turn until one
+ * returns results. DuckDuckGo is primary and Bing is the
+ * fallback; when all are exhausted the result is an empty list.
+ */
+export async function webSearch(query, numResults = 10, signal) {
+    return firstProviderResults(PROVIDERS, (provider) => signal?.aborted
+        ? Promise.resolve([])
+        : runProvider(provider, query, numResults, signal));
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Everything a session puts on disk, and the bookkeeping that
+ * keeps one write from trampling another.
+ *
+ * The sink is made on first use rather than at open, because
+ * most sessions never write anything and a directory per
+ * session would be litter. The stamps exist so no picture or
+ * archive overwrites another, and the ledger of paths exists so
+ * status can recite what was written, in order.
+ */
+import { type BundleSink } from "../envelope/index.js";
+/** The disk side of a session: sink, stamps and ledger. */
+export declare class ArtifactLedger {
+    /** Where this session's files are written, made on demand. */
+    private bundle?;
+    /** How many pictures have been taken. */
+    private shots;
+    /** How many archives have been written. */
+    private archives;
+    /** Everything this session has put on disk, in order. */
+    private readonly paths;
+    /** The sink artifacts go to, made on first use. */
+    sink(): BundleSink;
+    /** The next picture's stamp, so none overwrites another. */
+    nextShot(): string;
+    /** The next archive's stamp, for the same reason. */
+    nextArchive(): string;
+    /** Note a path in the ledger and hand it back. */
+    keep(path: string): string;
+    /** Everything written, in order. */
+    get written(): readonly string[];
+}

package/dist/web/session/artifacts.js

@@ -0,0 +1,47 @@
+/**
+ * Everything a session puts on disk, and the bookkeeping that
+ * keeps one write from trampling another.
+ *
+ * The sink is made on first use rather than at open, because
+ * most sessions never write anything and a directory per
+ * session would be litter. The stamps exist so no picture or
+ * archive overwrites another, and the ledger of paths exists so
+ * status can recite what was written, in order.
+ */
+import { diskSink } from "../envelope/index.js";
+/** The disk side of a session: sink, stamps and ledger. */
+export class ArtifactLedger {
+    /** Where this session's files are written, made on demand. */
+    bundle;
+    /** How many pictures have been taken. */
+    shots = 0;
+    /** How many archives have been written. */
+    archives = 0;
+    /** Everything this session has put on disk, in order. */
+    paths = [];
+    /** The sink artifacts go to, made on first use. */
+    sink() {
+        if (!this.bundle)
+            this.bundle = diskSink();
+        return this.bundle;
+    }
+    /** The next picture's stamp, so none overwrites another. */
+    nextShot() {
+        this.shots += 1;
+        return String(this.shots).padStart(2, "0");
+    }
+    /** The next archive's stamp, for the same reason. */
+    nextArchive() {
+        this.archives += 1;
+        return String(this.archives).padStart(2, "0");
+    }
+    /** Note a path in the ledger and hand it back. */
+    keep(path) {
+        this.paths.push(path);
+        return path;
+    }
+    /** Everything written, in order. */
+    get written() {
+        return this.paths;
+    }
+}

package/dist/web/session/emulation.d.ts

@@ -0,0 +1,118 @@
+/**
+ * What a session pretends to be, and how the pretence is kept.
+ *
+ * The intent is held whole and re-applied in full, because
+ * Chrome's media emulation forgets anything a call omits, and a
+ * cross-process navigation swaps the renderer the flags live in.
+ * Applying, observing and diverging all live here so the one
+ * piece of state has one keeper.
+ */
+import { type Divergence, type EmulationState, type ObservedEnvironment } from "../environment/index.js";
+import type { SessionWires } from "./wires.js";
+/** What emulation needs from the session besides the browser. */
+interface EmulationHooks {
+    /** Wait for the reflow an emulation change starts to finish. */
+    readonly settle: () => Promise<unknown>;
+}
+/** The standing pretence, applied, observed and diverged. */
+export declare class EmulationController {
+    private readonly wires;
+    private readonly hooks;
+    /** What this session is pretending to be. */
+    private state;
+    /**
+     * Media features this browser turned down.
+     *
+     * Kept so the refusal can be reported once, rather than lost
+     * silently or, worse, left in the intent to fail again on every
+     * navigation that replays it.
+     */
+    private refused;
+    constructor(wires: SessionWires, hooks: EmulationHooks);
+    /** What this session has asked the browser to pretend. */
+    get asked(): EmulationState;
+    /** Whether the page believes it is being touched. */
+    get touch(): boolean;
+    /**
+     * Put the emulation back exactly as it was.
+     *
+     * change merges, which is right for a caller adding one
+     * condition and wrong for anything that has to undo itself: a
+     * merge cannot clear a field, so a sweep that widened the
+     * viewport could never restore a session that had none. This
+     * replaces the state wholesale.
+     */
+    restore(state: EmulationState): Promise<void>;
+    /**
+     * Pretend to be a different visitor, then report what the page
+     * actually experiences.
+     *
+     * The intent is kept whole and re-applied in full, because
+     * Chrome's media emulation forgets anything a call omits, so
+     * asking for reduced motion after asking for dark mode would
+     * otherwise turn the dark mode back off.
+     */
+    change(change?: EmulationState, 
+    /** Overrides to take off, which an absent key cannot express. */
+    clear?: readonly (keyof EmulationState)[]): Promise<{
+        asked: EmulationState;
+        observed: ObservedEnvironment;
+        gaps: readonly Divergence[];
+    }>;
+    /**
+     * Put the standing intent to the browser again, after arriving.
+     *
+     * Kept, though the driver now carries emulation across a
+     * navigation itself, because this same path restores a session
+     * after a crash and because it costs nothing when nothing is
+     * being emulated.
+     *
+     * What is gone is what used to sit under here: a second
+     * application on the document-arrival event, and a loop that
+     * asked the page whether the first two had worked. Both were
+     * workarounds for sending emulation on a protocol session of our
+     * own, and neither made it certain. Removing the cause removed
+     * the need for either, measured twelve times out of twelve
+     * through the shape that used to fail one time in three.
+     */
+    reassert(): Promise<void>;
+    /**
+     * How the pretence and the page disagree right now.
+     *
+     * Checked rather than recited. What is being emulated is what
+     * the session asked for, and a navigation can quietly drop part
+     * of it, so the page is asked whether it agrees before status
+     * says it is pretending to be a phone. A blank page has nothing
+     * laid out to check, so it reports no gaps rather than fake ones.
+     */
+    currentGaps(): Promise<readonly Divergence[]>;
+    /**
+     * The standing intent with any named device resolved.
+     *
+     * A device is shorthand for a viewport and a touch screen, and
+     * anything the caller said explicitly outranks it: asking for a
+     * phone and a width means the phone with that width.
+     */
+    private get effective();
+    /**
+     * Put the media features to the browser, dropping any it refuses.
+     *
+     * The set goes over in one call and Chrome rejects the whole set on
+     * the first feature it does not recognise, so a feature this build
+     * of Chrome has never heard of would otherwise take every working
+     * feature with it. Worse, the intent is replayed on navigation, so
+     * a single refusal became an error on later calls that asked for
+     * nothing at all: one real session failed a plain navigate with
+     * "Unsupported media feature: prefers-contrast" long after the
+     * emulate call that set it.
+     *
+     * Dropping is per feature and one at a time, because the message
+     * names only the first offender.
+     */
+    private applyMediaFeatures;
+    /** Put the whole standing intent to the browser. */
+    apply(): Promise<void>;
+    /** What the page says it is experiencing. */
+    private observe;
+}
+export {};