harnery 0.45.2 → 0.46.0

package/src/lib/browser/client.ts

@@ -15,6 +15,7 @@ import {
   type CookieJar,
   CookieStoreParseError,
   type Cookie as JarCookie,
+  violatesCookiePrefix,
 } from "../cookies/index.ts";
 import { PaceGate, pacePolicyFromEnv } from "../pace/index.ts";
 import { type AssertResult, type AssertSpec, buildAssertCheck } from "./asserts.js";
@@ -170,8 +171,22 @@ export interface BrowserOptions {
   userAgent?: string;
   /** Authenticated browser proxy passed directly to Playwright. */
   proxy?: { server: string; username?: string; password?: string };
+  /**
+   * Inspect the live cookies of the browser context. Runs before each request
+   * is sent, after each response, and once more at close. If it throws, the
+   * request is cancelled, the context closes without saving cookies to the
+   * jar, and the error is kept as `cookieGuardFault` for the caller to report.
+   */
+  cookieGuard?: CookieGuard;
 }
 
+export type CookieGuardPhase = "request" | "response" | "close";
+
+export type CookieGuard = (
+  cookies: readonly PWCookie[],
+  event: { phase: CookieGuardPhase; url: string | null },
+) => void | Promise<void>;
+
 export interface NavigateResult {
   url: string;
   title: string;
@@ -422,16 +437,35 @@ export class Browser {
       : undefined;
     if (identity) await this.context.addInitScript(installDocumentIdentity, identity);
 
-    if (jarCookies.length > 0) {
-      await this.context.addCookies(jarCookies.map(toPWCookie));
+    // The jar's domain field is the delivery rule: a dotless domain is
+    // host-only, which Chromium honors for exactly that host. A cookie that
+    // breaks its name prefix would make Chromium reject the whole batch, so
+    // it is left out rather than aborting the session.
+    const injectable = jarCookies.filter((cookie) => !violatesCookiePrefix(cookie));
+    if (injectable.length > 0) {
+      await this.context.addCookies(injectable.map(toPWCookie));
     }
 
     // Gate actual document requests, including links, forms, script navigation,
     // and the first request of a popup. Method-level waits miss those loads.
     // Redirect hops are part of the original load, not additional reservations.
     const headersCb = this.opts.extraHeaders;
-    if (this.getPaceGate()?.policy.enabled || headersCb || this.opts.userAgent) {
+    const cookieGuard = this.opts.cookieGuard;
+    if (cookieGuard) {
+      this.context.on("response", (response) => {
+        void this.guardCookies("response", response.url()).catch(() => undefined);
+      });
+    }
+    if (this.getPaceGate()?.policy.enabled || headersCb || this.opts.userAgent || cookieGuard) {
       await this.context.route("**/*", async (route, request) => {
+        if (cookieGuard) {
+          try {
+            await this.guardCookies("request", request.url());
+          } catch {
+            await route.abort("failed").catch(() => undefined);
+            return;
+          }
+        }
         let mainDocument = false;
         if (request.isNavigationRequest() && !request.redirectedFrom()) {
           try {
@@ -848,24 +882,31 @@ export class Browser {
           `captureRegionByScroll: rect must have a positive size (got ${rect.width}×${rect.height})`,
         );
       }
-    const settle = (top: number) =>
-      page.evaluate(async (target: number) => {
-        window.scrollTo({ left: window.scrollX, top: target, behavior: "instant" });
-        const frame = () => new Promise<void>((r) => requestAnimationFrame(() => r()));
-        let last = Number.NaN;
-        for (let i = 0; i < 8; i++) {
-          await frame();
-          const now = window.scrollY;
-          if (now === last) break;
-          last = now;
-        }
-        return {
-          scrollX: window.scrollX,
-          scrollY: window.scrollY,
-          innerWidth: window.innerWidth,
-          innerHeight: window.innerHeight,
-        };
-      }, top);
+    const settle = (top: number, left?: number) =>
+      page.evaluate(
+        async (target: { top: number; left?: number }) => {
+          window.scrollTo({
+            left: target.left ?? window.scrollX,
+            top: target.top,
+            behavior: "instant",
+          });
+          const frame = () => new Promise<void>((r) => requestAnimationFrame(() => r()));
+          let last = Number.NaN;
+          for (let i = 0; i < 8; i++) {
+            await frame();
+            const now = window.scrollY;
+            if (now === last) break;
+            last = now;
+          }
+          return {
+            scrollX: window.scrollX,
+            scrollY: window.scrollY,
+            innerWidth: window.innerWidth,
+            innerHeight: window.innerHeight,
+          };
+        },
+        { top, left },
+      );
     const original = await page.evaluate(() => ({ x: window.scrollX, y: window.scrollY }));
     const captures: Buffer[] = [];
     // Viewport-pinned candidates, measured at scroll 0 so each later capture
@@ -884,6 +925,8 @@ export class Browser {
         priorOpacityPriority: string;
         priorTransition: string;
         priorTransitionPriority: string;
+        priorStyle: string | null;
+        appliedStyle?: string;
       }> = [];
       // Fixed controls can live inside a static shadow host. Walk open roots
       // without hiding their ordinary content or exceeding the total node cap.
@@ -907,6 +950,7 @@ export class Browser {
           priorOpacityPriority: el.style.getPropertyPriority("opacity"),
           priorTransition: el.style.getPropertyValue("transition"),
           priorTransitionPriority: el.style.getPropertyPriority("transition"),
+          priorStyle: el.getAttribute("style"),
         });
       }
       return out;
@@ -916,16 +960,36 @@ export class Browser {
         async ([entries, action]) => {
           for (const entry of entries) {
             const restore = () => {
+              if (entry.appliedStyle === undefined) return;
+              const unchanged = entry.el.getAttribute("style") === entry.appliedStyle;
               // Restore opacity while transitions are still disabled. Restoring both
               // declarations in one style flush starts a new fade from zero.
-              entry.el.style.setProperty("transition", "none", "important");
-              entry.el.style.setProperty("opacity", entry.priorOpacity, entry.priorOpacityPriority);
+              if (
+                entry.el.style.getPropertyValue("opacity") === "0" &&
+                entry.el.style.getPropertyPriority("opacity") === "important"
+              )
+                entry.el.style.setProperty(
+                  "opacity",
+                  entry.priorOpacity,
+                  entry.priorOpacityPriority,
+                );
               void getComputedStyle(entry.el).opacity;
-              entry.el.style.setProperty(
-                "transition",
-                entry.priorTransition,
-                entry.priorTransitionPriority,
-              );
+              if (
+                entry.el.style.getPropertyValue("transition") === "none" &&
+                entry.el.style.getPropertyPriority("transition") === "important"
+              )
+                entry.el.style.setProperty(
+                  "transition",
+                  entry.priorTransition,
+                  entry.priorTransitionPriority,
+                );
+              // Preserve the exact original attribute, including its absence. Do
+              // not replace styles changed by the page while our override was active.
+              if (unchanged) {
+                if (entry.priorStyle === null) entry.el.removeAttribute("style");
+                else entry.el.setAttribute("style", entry.priorStyle);
+              }
+              entry.appliedStyle = undefined;
             };
             if (action === "restore") {
               restore();
@@ -933,8 +997,21 @@ export class Browser {
             }
             const now = entry.el.getBoundingClientRect().top + window.scrollY;
             if (Math.abs(now - entry.top) > 1) {
+              if (entry.appliedStyle !== undefined) {
+                if (entry.el.getAttribute("style") !== entry.appliedStyle)
+                  throw new Error(
+                    "Pinned styles changed during native capture; source is unstable.",
+                  );
+                continue;
+              }
+              entry.priorStyle = entry.el.getAttribute("style");
+              entry.priorOpacity = entry.el.style.getPropertyValue("opacity");
+              entry.priorOpacityPriority = entry.el.style.getPropertyPriority("opacity");
+              entry.priorTransition = entry.el.style.getPropertyValue("transition");
+              entry.priorTransitionPriority = entry.el.style.getPropertyPriority("transition");
               entry.el.style.setProperty("transition", "none", "important");
               entry.el.style.setProperty("opacity", "0", "important");
+              entry.appliedStyle = entry.el.getAttribute("style")!;
             } else {
               restore();
             }
@@ -990,11 +1067,8 @@ export class Browser {
         await syncPinned("restore");
       } finally {
         await pinned.dispose();
-        await page.evaluate(
-          ({ x, y }: { x: number; y: number }) =>
-            window.scrollTo({ left: x, top: y, behavior: "instant" }),
-          original,
-        );
+        await settle(original.y, original.x);
+        await this.waitForReviewReady();
       }
     }
     return captures;
@@ -1863,10 +1937,17 @@ export class Browser {
    * visual line. Word-count per line via per-word Range rects (the width
    * of the last line is deliberately NOT the signal; see runts.ts).
    */
-  async checkRunts(opts: { scope?: string | null; minChars?: number } = {}): Promise<RuntsResult> {
+  async checkRunts(
+    opts: { scope?: string | null; minChars?: number; maxFindings?: number } = {},
+  ): Promise<RuntsResult> {
+    const maxFindings = opts.maxFindings === undefined ? 50 : opts.maxFindings;
+    if (!Number.isInteger(maxFindings) || maxFindings < 1 || maxFindings > 5000) {
+      throw new Error("maxFindings must be an integer from 1 to 5000.");
+    }
     return await this.currentPage.evaluate(buildRuntsCheck(), {
       scope: opts.scope ?? null,
       minChars: opts.minChars ?? 40,
+      maxFindings,
     });
   }
 
@@ -1973,6 +2054,30 @@ export class Browser {
     await this.context.addInitScript(script);
   }
 
+  /** The error a `cookieGuard` threw, once it has stopped the session. */
+  get cookieGuardFault(): unknown {
+    return this.cookieFault;
+  }
+
+  private cookieFault: unknown;
+
+  /** Run the cookie guard; on a throw, record it, tear the context down, and rethrow. */
+  private async guardCookies(phase: CookieGuardPhase, url: string | null): Promise<void> {
+    const guard = this.opts.cookieGuard;
+    const context = this.context;
+    if (!guard || !context || this.cookieFault) {
+      if (this.cookieFault) throw this.cookieFault;
+      return;
+    }
+    try {
+      await guard(await context.cookies(), { phase, url });
+    } catch (error) {
+      this.cookieFault ??= error;
+      await this.close();
+      throw error;
+    }
+  }
+
   /** Snapshot all cookies in the live persistent context. */
   async cookies(): Promise<PWCookie[]> {
     if (!this.context) throw new Error("Browser not opened. Call open() first.");
@@ -1985,7 +2090,14 @@ export class Browser {
    */
   async close(): Promise<void> {
     if (!this.context) return;
-    if (this.opts.jar) {
+    if (this.opts.cookieGuard && !this.cookieFault) {
+      try {
+        await this.guardCookies("close", null);
+      } catch {
+        return;
+      }
+    }
+    if (this.opts.jar && !this.cookieFault) {
       try {
         const live = await this.context.cookies();
         this.opts.jar.merge(live.map(toJarCookie));

package/src/lib/browser/content-checks.ts

@@ -36,7 +36,7 @@ export interface PlaceholderHit {
 export interface PlaceholderResult {
   rule: "placeholder";
   found: boolean;
-  outcome: "pass" | "fail";
+  outcome: "pass" | "fail" | "unknown";
   scanned: number;
   truncated: boolean;
   hits: PlaceholderHit[];
@@ -100,6 +100,8 @@ export interface ContrastResult {
 }
 
 export interface ContentChecksRequest {
+  /** Explicit traversal budget; omission retains the existing node cap. */
+  scanNodeBudget?: number;
   placeholder: { scope: string | null } | null;
   image: { scope: string | null; tolerance: number } | null;
   truncation: { scope: string | null; tolerance: number } | null;
@@ -115,7 +117,15 @@ export interface ContentChecksResult {
 
 export function buildContentChecks(): (request: ContentChecksRequest) => ContentChecksResult {
   return (request) => {
-    const NODE_CAP = 6000;
+    if (
+      request.scanNodeBudget !== undefined &&
+      (!Number.isSafeInteger(request.scanNodeBudget) ||
+        request.scanNodeBudget < 1 ||
+        request.scanNodeBudget > 100_000)
+    ) {
+      throw new Error("scanNodeBudget must be an integer from 1 to 100000.");
+    }
+    const NODE_CAP = request.scanNodeBudget ?? 6000;
     const HIT_CAP = 100;
 
     const sx = window.scrollX;
@@ -234,6 +244,7 @@ export function buildContentChecks(): (request: ContentChecksRequest) => Content
         // when the trimmed text of a leaf element is exactly the tell).
         if (hits.length < HIT_CAP) {
           const leaves = root.querySelectorAll("*");
+          if (leaves.length > NODE_CAP) truncated = true;
           for (let i = 0; i < leaves.length && i < NODE_CAP; i++) {
             const el = leaves[i];
             if (!el || el.children.length > 0) continue;
@@ -258,7 +269,7 @@ export function buildContentChecks(): (request: ContentChecksRequest) => Content
       placeholder = {
         rule: "placeholder",
         found: root !== null,
-        outcome: root && hits.length === 0 ? "pass" : "fail",
+        outcome: !root || hits.length > 0 ? "fail" : truncated ? "unknown" : "pass",
         scanned,
         truncated,
         hits,

package/src/lib/browser/critique.ts

@@ -18,6 +18,7 @@
 //      orchestration live here; the model call lives in the host.
 
 import { PNG } from "pngjs";
+import { PAGE_REVIEW_MAX_TILE_BUDGET } from "./page-review-contracts.js";
 import {
   bandOversizedRect,
   bandsCoveringRects,
@@ -76,6 +77,87 @@ export interface CritiqueResult {
   error?: string;
   /** Host-reported provider provenance (route, attempts, fallbacks, usage). */
   provider_meta?: Record<string, unknown>;
+  /** Tokens the provider reported across every tile it was called for. */
+  usage?: CritiqueUsageTotals;
+}
+
+/** Tokens one provider call spent, as the host's backend reported them.
+ * `input_tokens` counts every input token, cached or not. */
+export interface CritiqueUsage {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_input_tokens?: number;
+  cache_write_input_tokens?: number;
+  /** Cost at the backend's list price, when the backend reports one. */
+  cost_usd?: number;
+}
+
+/** Usage summed over tiles. A tile whose provider reported nothing counts in
+ * `tiles_unreported`, never as zero tokens. */
+export interface CritiqueUsageTotals {
+  tiles_reported: number;
+  tiles_unreported: number;
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_input_tokens: number;
+  cache_write_input_tokens: number;
+  /** Present only when every reported tile carried a cost. */
+  cost_usd?: number;
+}
+
+/** Add one call's usage to a tile's running usage (a retried tile reports twice). */
+export function addCritiqueUsage(
+  into: CritiqueUsage | undefined,
+  usage: CritiqueUsage,
+): CritiqueUsage {
+  const n = (v: number | undefined) => (Number.isFinite(v) ? (v as number) : 0);
+  const out: CritiqueUsage = {
+    input_tokens: n(into?.input_tokens) + n(usage.input_tokens),
+    output_tokens: n(into?.output_tokens) + n(usage.output_tokens),
+  };
+  const read = n(into?.cache_read_input_tokens) + n(usage.cache_read_input_tokens);
+  const write = n(into?.cache_write_input_tokens) + n(usage.cache_write_input_tokens);
+  if (read > 0) out.cache_read_input_tokens = read;
+  if (write > 0) out.cache_write_input_tokens = write;
+  const costKnown =
+    usage.cost_usd !== undefined && (into === undefined || into.cost_usd !== undefined);
+  if (costKnown) out.cost_usd = n(into?.cost_usd) + n(usage.cost_usd);
+  return out;
+}
+
+export function sumCritiqueUsage(
+  perTile: ReadonlyArray<CritiqueUsage | undefined>,
+): CritiqueUsageTotals {
+  const reported = perTile.filter((u): u is CritiqueUsage => u !== undefined);
+  const totals: CritiqueUsageTotals = {
+    tiles_reported: reported.length,
+    tiles_unreported: perTile.length - reported.length,
+    input_tokens: 0,
+    output_tokens: 0,
+    cache_read_input_tokens: 0,
+    cache_write_input_tokens: 0,
+  };
+  for (const u of reported) {
+    totals.input_tokens += u.input_tokens;
+    totals.output_tokens += u.output_tokens;
+    totals.cache_read_input_tokens += u.cache_read_input_tokens ?? 0;
+    totals.cache_write_input_tokens += u.cache_write_input_tokens ?? 0;
+  }
+  if (reported.length > 0 && reported.every((u) => u.cost_usd !== undefined)) {
+    totals.cost_usd =
+      Math.round(reported.reduce((sum, u) => sum + (u.cost_usd ?? 0), 0) * 1e6) / 1e6;
+  }
+  return totals;
+}
+
+/** "1,234,567 tokens over 96 tiles (3 unreported), $1.23" for log lines. */
+export function formatCritiqueUsage(totals: CritiqueUsageTotals): string {
+  const tokens = (totals.input_tokens + totals.output_tokens).toLocaleString("en-US");
+  return (
+    `${tokens} tokens over ${totals.tiles_reported} tile(s)` +
+    (totals.tiles_unreported > 0 ? ` (${totals.tiles_unreported} unreported)` : "") +
+    (totals.cost_usd !== undefined ? `, $${totals.cost_usd.toFixed(2)} at list price` : "")
+  );
 }
 
 /**
@@ -93,6 +175,9 @@ export type CritiqueProvider = ((input: {
   url: string;
   rubric: string;
   tile: CritiqueTile;
+  /** Optional sink for the tokens this call spent. A provider that knows its
+   * usage calls it once per backend call; callers that omit it lose nothing. */
+  reportUsage?: (usage: CritiqueUsage) => void;
 }) => Promise<CritiqueFinding[]>) & {
   concurrency?: number;
   meta?: () => Record<string, unknown> | undefined;
@@ -242,12 +327,16 @@ export function tilesFromFullPage(
       pngBase64: PNG.sync.write(dst).toString("base64"),
     };
   };
-  const kept = rects.slice(0, opts.maxTiles);
+  const kept = rects.slice(0, Math.min(opts.maxTiles, PAGE_REVIEW_MAX_TILE_BUDGET));
   const tiles: CritiqueTile[] = kept.map(cutTile);
+  const hitBandCap = Math.min(
+    opts.maxHitBands ?? 50,
+    Math.max(0, PAGE_REVIEW_MAX_TILE_BUDGET - kept.length),
+  );
   let hitBands = 0;
   const banding = !(opts.elementRects && opts.elementRects.length > 0);
   if (banding && opts.hitRects && opts.hitRects.length > 0) {
-    for (const index of bandsCoveringRects(rects, kept.length, opts.hitRects, opts.maxHitBands)) {
+    for (const index of bandsCoveringRects(rects, kept.length, opts.hitRects, hitBandCap)) {
       const band = rects[index];
       if (!band) continue;
       tiles.push(cutTile({ ...band, label: `hit band ${index + 1}` }));
@@ -323,10 +412,23 @@ export async function runCritique(args: {
         "no critiqueProvider injected by the host (see HarneryProgramContext.critiqueProvider)",
     };
   }
+  if (tiles.length > PAGE_REVIEW_MAX_TILE_BUDGET) {
+    return {
+      rule: "critique",
+      tiles: tiles.length,
+      provider: true,
+      findings: [],
+      outcome: "skipped",
+      error:
+        `${tiles.length} tiles exceed the per-invocation ceiling of ${PAGE_REVIEW_MAX_TILE_BUDGET} ` +
+        "vision calls; lower the tile cap",
+    };
+  }
   // Tiles are judged independently, so run them concurrently (bounded) and
   // reassemble findings in tile order so artifacts stay deterministic.
   const concurrency = Math.max(1, Math.min(provider.concurrency ?? 4, tiles.length || 1));
   const perTile: CritiqueFinding[][] = tiles.map(() => []);
+  const perTileUsage: Array<CritiqueUsage | undefined> = tiles.map(() => undefined);
   let cursor = 0;
   const worker = async (): Promise<void> => {
     while (true) {
@@ -334,7 +436,14 @@ export async function runCritique(args: {
       if (i >= tiles.length) return;
       const tile = tiles[i];
       try {
-        const tileFindings = await provider({ url, rubric, tile });
+        const tileFindings = await provider({
+          url,
+          rubric,
+          tile,
+          reportUsage: (usage) => {
+            perTileUsage[i] = addCritiqueUsage(perTileUsage[i], usage);
+          },
+        });
         perTile[i] = tileFindings.map((f) => ({ ...f, tile: tile.index }));
       } catch (err: unknown) {
         perTile[i] = [
@@ -359,5 +468,6 @@ export async function runCritique(args: {
     findings,
     outcome,
     ...(meta ? { provider_meta: meta } : {}),
+    usage: sumCritiqueUsage(perTileUsage),
   };
 }