harnery 0.40.0 → 0.42.0

package/src/lib/browser/collect/scroll-plan.ts

@@ -0,0 +1,179 @@
+/**
+ * Seeded randomness and the human-like scroll schedule for `browse --collect`.
+ *
+ * Everything here is pure: given a seed and a pacing policy, the plan for each
+ * step (wheel notches, pauses, reading pauses, small scroll-backs) is fully
+ * reproducible, which is what the unit tests rely on.
+ */
+
+/** A random source returning floats in [0, 1). */
+export type Rng = () => number;
+
+/** mulberry32: a small, fast, well-distributed 32-bit seeded generator. */
+export function createRng(seed: number): Rng {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** A fresh 32-bit seed for runs that did not pass one. */
+export function randomSeed(): number {
+  return Math.floor(Math.random() * 0x1_0000_0000) >>> 0;
+}
+
+export interface Range {
+  min: number;
+  max: number;
+}
+
+export function uniform(rng: Rng, range: Range): number {
+  return range.min + (range.max - range.min) * rng();
+}
+
+export interface ScrollPacing {
+  /** Scroll distance per step, as a fraction of the viewport height. */
+  step: Range;
+  /** Pause after each step, in ms. */
+  pauseMs: Range;
+  /** Probability that a step is followed by a longer reading pause instead. */
+  readChance: number;
+  /** Reading pause, in ms. */
+  readPauseMs: Range;
+  /** Probability that a step starts with a small scroll back up. */
+  backChance: number;
+  /** Scroll-back distance, as a fraction of the viewport height. */
+  back: Range;
+  /** Size of one wheel notch, in px. */
+  tickPx: Range;
+  /** Gap between wheel notches, in ms. */
+  tickGapMs: Range;
+}
+
+export const DEFAULT_SCROLL_PACING: ScrollPacing = {
+  step: { min: 0.6, max: 1.1 },
+  pauseMs: { min: 1_200, max: 3_500 },
+  readChance: 0.12,
+  readPauseMs: { min: 4_000, max: 9_000 },
+  backChance: 0.08,
+  back: { min: 0.1, max: 0.3 },
+  tickPx: { min: 80, max: 140 },
+  tickGapMs: { min: 12, max: 45 },
+};
+
+/** Upper bounds that keep every pause and step bounded. */
+export const PACING_LIMITS = {
+  maxStepFraction: 3,
+  maxPauseMs: 120_000,
+} as const;
+
+export interface WheelTick {
+  /** Positive scrolls down, negative scrolls up. */
+  deltaY: number;
+  /** Wait after this notch, in ms. */
+  gapMs: number;
+}
+
+export interface ScrollStepPlan {
+  /** Optional scroll-back notches run before the main step (negative deltas). */
+  back: WheelTick[];
+  /** Pause after the scroll-back, in ms (0 when there is no scroll-back). */
+  backPauseMs: number;
+  /** Main downward notches. */
+  ticks: WheelTick[];
+  /** Total downward distance, in px. */
+  deltaY: number;
+  /** Pause after the main step, in ms. */
+  pauseMs: number;
+  /** True when the pause is a longer reading pause. */
+  reading: boolean;
+}
+
+/** Split a distance into wheel notches the way a mouse wheel reports them. */
+export function wheelTicks(rng: Rng, pacing: ScrollPacing, distance: number): WheelTick[] {
+  const sign = distance < 0 ? -1 : 1;
+  let remaining = Math.round(Math.abs(distance));
+  const ticks: WheelTick[] = [];
+  while (remaining > 0) {
+    const size = Math.min(remaining, Math.max(1, Math.round(uniform(rng, pacing.tickPx))));
+    remaining -= size;
+    ticks.push({ deltaY: sign * size, gapMs: Math.round(uniform(rng, pacing.tickGapMs)) });
+  }
+  return ticks;
+}
+
+export function planScrollStep(
+  rng: Rng,
+  pacing: ScrollPacing,
+  viewportHeight: number,
+): ScrollStepPlan {
+  const height = Math.max(1, viewportHeight);
+  let back: WheelTick[] = [];
+  let backPauseMs = 0;
+  if (rng() < pacing.backChance) {
+    back = wheelTicks(rng, pacing, -uniform(rng, pacing.back) * height);
+    backPauseMs = Math.round(uniform(rng, { min: 400, max: 1_100 }));
+  }
+  const deltaY = Math.max(1, Math.round(uniform(rng, pacing.step) * height));
+  const ticks = wheelTicks(rng, pacing, deltaY);
+  const reading = rng() < pacing.readChance;
+  const pauseMs = Math.round(uniform(rng, reading ? pacing.readPauseMs : pacing.pauseMs));
+  return { back, backPauseMs, ticks, deltaY, pauseMs, reading };
+}
+
+/**
+ * Parse `min-max` (or a single value meaning min = max). Throws a message that
+ * names the flag when the value is malformed or out of bounds.
+ */
+export function parseRange(raw: string, flag: string, bounds: { min: number; max: number }): Range {
+  const text = raw.trim();
+  const m = /^(\d+(?:\.\d+)?)(?:\s*-\s*(\d+(?:\.\d+)?))?$/.exec(text);
+  if (!m) throw new Error(`${flag} must be <min>-<max> or a single number (got "${raw}").`);
+  const min = Number(m[1]);
+  const max = m[2] === undefined ? min : Number(m[2]);
+  if (min > max) throw new Error(`${flag}: min (${min}) must not exceed max (${max}).`);
+  if (min < bounds.min || max > bounds.max) {
+    throw new Error(`${flag} must stay within ${bounds.min}-${bounds.max} (got "${raw}").`);
+  }
+  return { min, max };
+}
+
+export function parseProbability(raw: string, flag: string): number {
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0 || n > 1) {
+    throw new Error(`${flag} must be a number from 0 to 1 (got "${raw}").`);
+  }
+  return n;
+}
+
+/**
+ * Machine-wide pacing defaults from the environment, in the same style as the
+ * page-load pace gate (`HARNERY_PACE_*`):
+ *
+ * - `HARNERY_COLLECT_PAUSE_MS`: pause after each step, `min-max` in ms.
+ * - `HARNERY_COLLECT_STEP`: step size as a viewport fraction, `min-max`.
+ *
+ * Command flags override these.
+ */
+export function scrollPacingFromEnv(env: NodeJS.ProcessEnv = process.env): ScrollPacing {
+  const pacing: ScrollPacing = { ...DEFAULT_SCROLL_PACING };
+  const pause = env.HARNERY_COLLECT_PAUSE_MS?.trim();
+  if (pause) {
+    pacing.pauseMs = parseRange(pause, "HARNERY_COLLECT_PAUSE_MS", {
+      min: 0,
+      max: PACING_LIMITS.maxPauseMs,
+    });
+  }
+  const step = env.HARNERY_COLLECT_STEP?.trim();
+  if (step) {
+    pacing.step = parseRange(step, "HARNERY_COLLECT_STEP", {
+      min: 0.05,
+      max: PACING_LIMITS.maxStepFraction,
+    });
+  }
+  return pacing;
+}

package/src/lib/browser/identity.ts

@@ -0,0 +1,64 @@
+/** Keep Chromium's UA, navigator.platform and client hints in one profile. */
+export function browserIdentity(userAgent: string, browserVersion?: string) {
+  const chrome = /(?:Chrome|Chromium)\/(\d+)\.([\d.]+)/.exec(userAgent);
+  const windows = userAgent.includes("Windows NT");
+  const mac = userAgent.includes("Macintosh");
+  // A custom non-Chromium or non-desktop UA is an explicit caller choice.
+  if (!chrome || (!windows && !mac)) return undefined;
+  const major = chrome[1]!;
+  const fullVersion = browserVersion?.startsWith(`${major}.`)
+    ? browserVersion
+    : `${major}.${chrome[2]}`;
+  const brand = userAgent.includes("Edg/") ? "Microsoft Edge" : "Google Chrome";
+  return {
+    userAgent,
+    platform: windows ? "Win32" : "MacIntel",
+    userAgentMetadata: {
+      brands: [
+        { brand: "Chromium", version: major },
+        { brand, version: major },
+      ],
+      fullVersionList: [
+        { brand: "Chromium", version: fullVersion },
+        { brand, version: fullVersion },
+      ],
+      platform: windows ? "Windows" : "macOS",
+      platformVersion: windows ? "10.0.0" : "10.15.7",
+      architecture: "x86",
+      bitness: "64",
+      model: "",
+      mobile: false,
+      wow64: false,
+    },
+  };
+}
+
+/** Initial popup documents exist before Playwright can attach a page session. */
+export function installDocumentIdentity(identity: NonNullable<ReturnType<typeof browserIdentity>>) {
+  const metadata = identity.userAgentMetadata;
+  const basics = { brands: metadata.brands, mobile: metadata.mobile, platform: metadata.platform };
+  Object.defineProperty(Navigator.prototype, "platform", {
+    configurable: true,
+    get: () => identity.platform,
+  });
+  if (!("userAgentData" in navigator)) return;
+  const nativeData = (navigator as Navigator & { userAgentData: object }).userAgentData;
+  const data = Object.create(Object.getPrototypeOf(nativeData));
+  for (const [name, value] of Object.entries(basics)) {
+    Object.defineProperty(data, name, { enumerable: true, get: () => value });
+  }
+  Object.defineProperty(data, "toJSON", { value: () => ({ ...basics }) });
+  Object.defineProperty(data, "getHighEntropyValues", {
+    value: async (hints: string[]) => {
+      const result: Record<string, unknown> = { ...basics };
+      for (const hint of hints) {
+        if (Object.hasOwn(metadata, hint)) result[hint] = metadata[hint as keyof typeof metadata];
+      }
+      return result;
+    },
+  });
+  Object.defineProperty(Navigator.prototype, "userAgentData", {
+    configurable: true,
+    get: () => data,
+  });
+}

package/src/lib/browser/index.ts

@@ -76,7 +76,14 @@ export type {
   OverlapResult,
 } from "./geometry.js";
 export { buildLayoutLintCheck } from "./geometry.js";
-export { isWSL, wslHeadedLaunchArgs } from "./launch-args.js";
+export {
+  AUTOMATION_DEFAULT_ARGS_TO_DROP,
+  automationDisguiseArgs,
+  installedChromeChannel,
+  installedChromePath,
+  isWSL,
+  wslHeadedLaunchArgs,
+} from "./launch-args.js";
 export type {
   OverflowElement,
   OverflowResult,
@@ -178,6 +185,7 @@ export {
   type QaRunContext,
   type QaRunCritiqueOutcome,
   type QaRunCritiquePool,
+  type QaRunCritiqueTileTiming,
   type QaRunInteraction,
   type QaRunJob,
   type QaRunJobValidation,
@@ -237,6 +245,13 @@ export {
   snappedBandRects,
   type VisualAtom,
 } from "./tiling.js";
+export {
+  chromeMajorFromExecutable,
+  hostFamily,
+  normalUserAgent,
+  readStoredUserAgent,
+  resolveUserAgent,
+} from "./user-agent.js";
 export type {
   CheckVisibilityOptions,
   VisibilityResult,

package/src/lib/browser/launch-args.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 
 /**
  * Chromium launch-arg helpers for environment-specific workarounds.
@@ -31,3 +31,55 @@ export function isWSL(): boolean {
 export function wslHeadedLaunchArgs(): string[] {
   return isWSL() ? ["--disable-gpu"] : [];
 }
+
+/**
+ * Playwright's bundled browser is "Chrome for Testing", launched with
+ * `--enable-automation`. Both are visible to the page: the User-Agent brand
+ * list carries "Chrome for Testing" and `navigator.webdriver` reads true, so
+ * sign-in flows on sites that screen for automation (X, some banks, some
+ * Cloudflare-fronted apps) silently refuse clicks in a headed window that a
+ * person is driving. Headed sessions therefore launch the operator's real
+ * Google Chrome when one is installed and drop the automation signals.
+ */
+
+/** Default Chromium args Playwright adds that a headed session must not carry. */
+export const AUTOMATION_DEFAULT_ARGS_TO_DROP: readonly string[] = ["--enable-automation"];
+
+/** Launch flags that stop Blink from reporting the automation state to pages. */
+export function automationDisguiseArgs(): string[] {
+  return ["--disable-blink-features=AutomationControlled"];
+}
+
+const CHROME_PATHS: Record<string, string[]> = {
+  linux: ["/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/opt/google/chrome/chrome"],
+  darwin: ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"],
+  win32: [
+    "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+    "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+  ],
+};
+
+/**
+ * `"chrome"` when a stable Google Chrome install is present at a well-known
+ * path for this platform, else `undefined` (use Playwright's bundled
+ * Chromium). Playwright resolves the `chrome` channel to the same install, so
+ * the check only has to answer whether asking for it can succeed.
+ */
+export function installedChromeChannel(
+  platform: NodeJS.Platform = process.platform,
+  exists: (path: string) => boolean = existsSync,
+): "chrome" | undefined {
+  return installedChromePath(platform, exists) ? "chrome" : undefined;
+}
+
+/**
+ * Filesystem path of the installed stable Google Chrome for this platform, or
+ * `undefined`. Used to spawn Chrome with nothing attached for sign-in flows
+ * whose verification vendors detect the DevTools protocol itself.
+ */
+export function installedChromePath(
+  platform: NodeJS.Platform = process.platform,
+  exists: (path: string) => boolean = existsSync,
+): string | undefined {
+  return (CHROME_PATHS[platform] ?? []).find((candidate) => exists(candidate));
+}

package/src/lib/browser/page-review-judge.ts

@@ -25,6 +25,7 @@ import {
 } from "./page-review-pack.js";
 import type { QaContext } from "./qa-plan.js";
 import type { CritiqueReusePlan } from "./qa-reuse.js";
+import type { QaRunCritiqueTileTiming } from "./qa-run-contracts.js";
 import { loadQaSnapshot, type QaSnapshotStoreOptions } from "./qa-snapshot.js";
 
 export interface JudgePageReviewPackOptions {
@@ -62,6 +63,7 @@ export interface JudgedContext extends PageReviewCritiqueRecord {
 export interface JudgePageReviewPackResult {
   contexts: JudgedContext[];
   pool: { concurrency: number; wall_time_ms: number; provider: string };
+  tile_timings: QaRunCritiqueTileTiming[];
   tiles_total: number;
   tiles_reviewed: number;
   tiles_reused: number;
@@ -261,6 +263,7 @@ export async function judgePageReviewPack(
 
   let meta: Record<string, unknown> | undefined;
   let concurrency = 0;
+  const tileTimings: Array<QaRunCritiqueTileTiming | undefined> = new Array(work.length);
   if (provider && work.length > 0) {
     concurrency = Math.max(
       1,
@@ -277,12 +280,15 @@ export async function judgePageReviewPack(
         const entry = perContext[item.contextIndex];
         if (!entry) continue;
         entry.judged.add(item.tile.id);
+        const tileStarted = performance.now();
+        let tileOutcome: QaRunCritiqueTileTiming["outcome"] = "passed";
         try {
           const found = await provider({ url: item.url, rubric: item.rubric, tile: item.tile });
           for (const finding of found) {
             entry.findings.push({ ...finding, tile: item.tile.index, tile_id: item.tile.id });
           }
         } catch (err: unknown) {
+          tileOutcome = "failed";
           entry.findings.push({
             tile: item.tile.index,
             tile_id: item.tile.id,
@@ -290,6 +296,13 @@ export async function judgePageReviewPack(
             category: "provider-error",
             description: `critique provider failed on ${item.tile.label}: ${err instanceof Error ? err.message : String(err)}`,
           });
+        } finally {
+          tileTimings[i] = {
+            context_id: entry.record.id,
+            tile_id: item.tile.id,
+            duration_ms: Math.max(0, Math.round(performance.now() - tileStarted)),
+            outcome: tileOutcome,
+          };
         }
       }
     };
@@ -360,6 +373,9 @@ export async function judgePageReviewPack(
   return {
     contexts,
     pool: { concurrency, wall_time_ms: Date.now() - started, provider: label },
+    tile_timings: tileTimings.filter(
+      (timing): timing is QaRunCritiqueTileTiming => timing !== undefined,
+    ),
     tiles_total: tilesTotal,
     tiles_reviewed: tilesReviewed,
     tiles_reused: tilesReused,

package/src/lib/browser/qa-run-contracts.ts

@@ -145,6 +145,15 @@ export interface QaRunCritiqueLatency {
   p95: number;
 }
 
+/** Wall time for one tile's complete vision call, including provider retries
+ * and failover. Reused and unjudged tiles have no call and no timing entry. */
+export interface QaRunCritiqueTileTiming {
+  context_id: string;
+  tile_id: string;
+  duration_ms: number;
+  outcome: "passed" | "failed";
+}
+
 /** What share of the page the critique tiles covered, lifted from the browse
  * envelope. `capped` means the tiler dropped bands past its per-context
  * maximum; in signoff mode that is a blocker, in review mode a flag. Across
@@ -188,6 +197,8 @@ export interface QaRunCritiquePool {
   wall_time_ms: number;
   provider: string;
   latency_ms?: Record<string, QaRunCritiqueLatency>;
+  /** One entry per attempted tile, in context and tile order. */
+  tile_timings?: QaRunCritiqueTileTiming[];
 }
 
 /** Where the run's page review pack lives: the on-disk evidence an agent can

package/src/lib/browser/qa-run.ts

@@ -1397,6 +1397,7 @@ export async function runQaMatrix(options: QaRunMatrixOptions): Promise<QaRunRes
       wall_time_ms: judged.pool.wall_time_ms,
       provider: judged.pool.provider,
       ...(latency ? { latency_ms: latency } : {}),
+      tile_timings: judged.tile_timings,
     };
     for (const row of judged.contexts) {
       judgedById.set(row.context_id, row);

package/src/lib/browser/user-agent.ts

@@ -0,0 +1,130 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+
+/**
+ * Present as a normal browser.
+ *
+ * A desktop-Linux user agent is itself a block signal: web application
+ * firewalls commonly deny "X11; Linux" outright because almost no customer
+ * browses from desktop Linux, and headless builds announce "HeadlessChrome".
+ * Sunbelt Network's Cloudflare rule was the reported case: the same page
+ * answered 200 the moment the browser said Windows. Every Harnery page load
+ * therefore uses a user agent for the host the operator actually sits at
+ * (Windows under WSL or on Windows, macOS on a Mac), never Linux, with the
+ * Chrome major version of the browser that is really running.
+ *
+ * The resolved string is persisted at `~/.cache/harnery/user-agent.json` so
+ * every process reuses the one that works; `HARNERY_BROWSER_UA` overrides it
+ * for a run (`native` disables the override), and `--user-agent` on `browse`
+ * rewrites the stored value.
+ */
+
+export type HostFamily = "windows" | "mac";
+
+const STORE_PATH = resolve(homedir(), ".cache", "harnery", "user-agent.json");
+
+/** Windows unless the operator is on a Mac. Linux never presents as Linux. */
+export function hostFamily(platform: NodeJS.Platform = process.platform): HostFamily {
+  return platform === "darwin" ? "mac" : "windows";
+}
+
+/** A current-shape Chrome user agent for the host family and Chrome major. */
+export function normalUserAgent(chromeMajor: number, family: HostFamily): string {
+  const os = family === "mac" ? "Macintosh; Intel Mac OS X 10_15_7" : "Windows NT 10.0; Win64; x64";
+  return `Mozilla/5.0 (${os}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${chromeMajor}.0.0.0 Safari/537.36`;
+}
+
+/** Major version from `<chrome> --version` output, or `undefined`. */
+export function parseChromeMajor(versionOutput: string): number | undefined {
+  const match = /(\d+)\.\d+\.\d+\.\d+/.exec(versionOutput);
+  return match ? Number(match[1]) : undefined;
+}
+
+/** Ask an installed Chrome binary for its major version. */
+export function chromeMajorFromExecutable(executable: string): number | undefined {
+  try {
+    const res = spawnSync(executable, ["--version"], { encoding: "utf8", timeout: 5000 });
+    return parseChromeMajor(`${res.stdout ?? ""}${res.stderr ?? ""}`);
+  } catch {
+    return undefined;
+  }
+}
+
+export interface StoredUserAgent {
+  userAgent: string;
+  source: "auto" | "manual";
+  chromeMajor?: number;
+  updatedAt: string;
+}
+
+export function readStoredUserAgent(path: string = STORE_PATH): StoredUserAgent | undefined {
+  try {
+    if (!existsSync(path)) return undefined;
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<StoredUserAgent>;
+    return typeof parsed.userAgent === "string" && parsed.userAgent.length > 0
+      ? (parsed as StoredUserAgent)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function writeStoredUserAgent(entry: StoredUserAgent, path: string = STORE_PATH): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(entry, null, 2)}\n`, { mode: 0o600 });
+}
+
+export interface ResolveUserAgentInput {
+  /** Explicit `--user-agent` value: a string, `"native"`, or `"auto"`. */
+  requested?: string;
+  /** `HARNERY_BROWSER_UA` from the environment. */
+  env?: string;
+  /** Major version of the Chrome that will actually launch, when known. */
+  chromeMajor?: number;
+  platform?: NodeJS.Platform;
+  storePath?: string;
+  now?: () => string;
+}
+
+/**
+ * The user agent to launch with, or `undefined` for the browser's native
+ * string. Precedence: explicit request, then environment, then the stored
+ * value (refreshed when the Chrome major moved), then a fresh auto value.
+ * An explicit string or `auto` request rewrites the store; `native` does not.
+ */
+export function resolveUserAgent(input: ResolveUserAgentInput = {}): string | undefined {
+  const now = input.now ?? (() => new Date().toISOString());
+  const family = hostFamily(input.platform);
+  const requested = input.requested?.trim();
+  if (requested && requested !== "auto") {
+    if (requested === "native") return undefined;
+    writeStoredUserAgent(
+      { userAgent: requested, source: "manual", updatedAt: now() },
+      input.storePath,
+    );
+    return requested;
+  }
+  const env = input.env?.trim();
+  if (env && requested !== "auto") {
+    return env === "native" ? undefined : env;
+  }
+  const stored = readStoredUserAgent(input.storePath);
+  if (
+    stored &&
+    requested !== "auto" &&
+    (stored.source === "manual" ||
+      input.chromeMajor === undefined ||
+      stored.chromeMajor === input.chromeMajor)
+  ) {
+    return stored.userAgent;
+  }
+  const major = input.chromeMajor ?? stored?.chromeMajor ?? 149;
+  const userAgent = normalUserAgent(major, family);
+  writeStoredUserAgent(
+    { userAgent, source: "auto", chromeMajor: major, updatedAt: now() },
+    input.storePath,
+  );
+  return userAgent;
+}