@omercnet/paseo-shared-browser 1.2.2 → 2.0.0-next.249.1

package/server/capture-transport-policy.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import type { RuntimeFrame } from "./agent-browser-runtime";
+import { createCaptureTransportPolicy } from "./capture-transport-policy";
+
+const frame: RuntimeFrame = {
+  dataBase64: "Zml4dHVyZQ==",
+  byteLength: 7,
+  width: 1280,
+  height: 800,
+  transport: "screenshot",
+  capturedAt: "2026-10-02T12:00:00.000Z",
+};
+
+describe("capture transport policy", () => {
+  it("keeps the true screenshot and original capture time only through1000ms at exact quality/budget", () => {
+    const policy = createCaptureTransportPolicy();
+    const token = policy.beginScreenshot();
+    expect(policy.rememberScreenshot(token, frame, 100, 100, 1000)).toBe(true);
+    policy.endScreenshot(token, 100);
+    expect(policy.readScreenshot(1100, 100, 1000)).toBe(frame);
+    expect(policy.readScreenshot(1101, 100, 1000)).toBeNull();
+    expect(policy.readScreenshot(500, 90, 1000)).toBeNull();
+    expect(policy.readScreenshot(500, 100, 1001)).toBeNull();
+  });
+
+  it("revokes old asynchronous completions on input/session invalidation", () => {
+    const policy = createCaptureTransportPolicy();
+    const old = policy.beginScreenshot();
+    policy.invalidate();
+    const fresh = policy.beginScreenshot();
+    expect(policy.rememberScreenshot(old, frame, 100, 100, 1000)).toBe(false);
+    policy.endScreenshot(old, 100);
+    expect(policy.readScreenshot(100, 100, 1000)).toBeNull();
+    expect(policy.rememberScreenshot(fresh, frame, 200, 100, 1000)).toBe(true);
+    policy.invalidate();
+    expect(policy.readScreenshot(200, 100, 1000)).toBeNull();
+  });
+
+  it("cannot recover from screenshot-induced frames or repeated sparse capture cycles", () => {
+    const policy = createCaptureTransportPolicy();
+    policy.enterFallback(0);
+    for (let time = 0; time < 6000; time += 1000) {
+      const token = policy.beginScreenshot();
+      policy.observeStream(`inside-${time}`, time + 10);
+      policy.endScreenshot(token, time + 20);
+      policy.observeStream(`queued-${time}`, time + 100);
+      expect(policy.canUseStream(time + 500)).toBe(false);
+    }
+  });
+
+  it("requires3 distinct events over500ms with bounded gaps and retains the original dwell", () => {
+    const policy = createCaptureTransportPolicy();
+    policy.enterFallback(0);
+    policy.observeStream("one", 1100);
+    policy.enterFallback(1200);
+    policy.observeStream("two", 1350);
+    expect(policy.canUseStream(1500)).toBe(false);
+    policy.observeStream("three", 1600);
+    expect(policy.canUseStream(1600)).toBe(true);
+  });
+
+  it("rejects duplicate events, burst-only evidence and stale recovery", () => {
+    const duplicate = createCaptureTransportPolicy();
+    duplicate.enterFallback(0);
+    duplicate.observeStream("same", 1000);
+    duplicate.observeStream("same", 1250);
+    duplicate.observeStream("same", 1500);
+    expect(duplicate.canUseStream(1500)).toBe(false);
+
+    const burst = createCaptureTransportPolicy();
+    burst.enterFallback(0);
+    burst.observeStream("one", 1400);
+    burst.observeStream("two", 1450);
+    burst.observeStream("three", 1500);
+    expect(burst.canUseStream(1500)).toBe(false);
+    expect(burst.canUseStream(2100)).toBe(false);
+  });
+
+  it("a long inter-event gap resets evidence and invalidation clears all recovery", () => {
+    const policy = createCaptureTransportPolicy();
+    policy.enterFallback(0);
+    policy.observeStream("one", 1000);
+    policy.observeStream("two", 1250);
+    policy.observeStream("three", 1800);
+    expect(policy.canUseStream(1800)).toBe(false);
+    policy.observeStream("four", 2050);
+    policy.invalidate();
+    policy.observeStream("five", 2300);
+    expect(policy.canUseStream(2300)).toBe(false);
+  });
+});
+
+it("quality-only captures preserve independent recovery and still exclude capture-induced events", () => {
+  const policy = createCaptureTransportPolicy();
+  policy.enterFallback(0);
+  policy.observeStream("one", 1100);
+  const token = policy.beginScreenshot({ preserveRecovery: true });
+  policy.observeStream("induced", 1120);
+  policy.endScreenshot(token, 1130);
+  policy.observeStream("queued", 1250);
+  expect(policy.canUseStream(1500)).toBe(false);
+  policy.observeStream("two", 1500);
+  policy.observeStream("three", 1750);
+  expect(policy.canUseStream(1750)).toBe(true);
+});

package/server/capture-transport-policy.ts

@@ -0,0 +1,154 @@
+/**
+ * Owns transport hysteresis and bounded screenshot reuse, independently of JPEG
+ * decoding. A quiet CDP stream can emit one frame because captureScreenshot ran;
+ * those frames are still acknowledged/cached, but cannot establish recovery.
+ * The 250ms post-capture exclusion is conservative because CDP provides no
+ * causal request ID on screencast events. Cached receipt age is monotonic.
+ */
+import type { RuntimeFrame } from "./agent-browser-runtime";
+
+export const CAPTURE_MAX_AGE_MS = 1_000;
+const FALLBACK_MIN_DWELL_MS = 1_500;
+const RECOVERY_MIN_EVENTS = 3;
+const RECOVERY_MIN_SPAN_MS = 500;
+const RECOVERY_MAX_GAP_MS = 500;
+const SCREENSHOT_EVENT_GUARD_MS = 250;
+const RECOVERY_ID_MEMORY = 32;
+
+type ScreenshotCache = {
+  frame: RuntimeFrame;
+  receivedAt: number;
+  quality: number;
+  maxBytes: number;
+};
+
+/** Create one policy per runtime. Invalidation revokes outstanding screenshot completion tokens. */
+export function createCaptureTransportPolicy() {
+  let generation = 0;
+  let fallbackSince: number | null = null;
+  let screenshot: ScreenshotCache | null = null;
+  let screenshotsInFlight = 0;
+  let ignoreStreamUntil = 0;
+  let recoveryFirstAt: number | null = null;
+  let recoveryLastAt: number | null = null;
+  let recoveryCount = 0;
+  const recoveryIds = new Set<string>();
+
+  function clearRecovery(): void {
+    recoveryFirstAt = null;
+    recoveryLastAt = null;
+    recoveryCount = 0;
+    recoveryIds.clear();
+  }
+
+  /**
+   * Clear cached screenshots/evidence and revoke old async completions. Keep an
+   * existing fallback dwell: input/session changes require fresh recovery evidence.
+   */
+  function invalidate(): void {
+    generation += 1;
+    screenshot = null;
+    screenshotsInFlight = 0;
+    ignoreStreamUntil = 0;
+    clearRecovery();
+  }
+
+  /** Enter fallback once; recapture/cache expiry must not extend the minimum dwell. */
+  function enterFallback(now: number): void {
+    if (fallbackSince !== null) return;
+    fallbackSince = now;
+    clearRecovery();
+  }
+
+  /** Feed only valid current-session CDP events, with distinct provider timestamps when available. */
+  function observeStream(identity: string, now: number): void {
+    if (fallbackSince === null) return;
+    if (screenshotsInFlight > 0 || now <= ignoreStreamUntil) return;
+    if (recoveryLastAt !== null && now - recoveryLastAt > RECOVERY_MAX_GAP_MS) {
+      clearRecovery();
+    }
+    if (recoveryIds.has(identity)) return;
+    if (recoveryFirstAt === null) recoveryFirstAt = now;
+    recoveryLastAt = now;
+    recoveryCount = Math.min(RECOVERY_MIN_EVENTS, recoveryCount + 1);
+    recoveryIds.add(identity);
+    if (recoveryIds.size > RECOVERY_ID_MEMORY) {
+      const oldest = recoveryIds.values().next().value;
+      if (oldest !== undefined) recoveryIds.delete(oldest);
+    }
+  }
+
+  /** Require sustained independent activity before allowing a fresh stream to replace fallback. */
+  function canUseStream(now: number): boolean {
+    if (fallbackSince === null) return true;
+    if (
+      recoveryFirstAt === null ||
+      recoveryLastAt === null ||
+      now - fallbackSince < FALLBACK_MIN_DWELL_MS ||
+      recoveryCount < RECOVERY_MIN_EVENTS ||
+      recoveryLastAt - recoveryFirstAt < RECOVERY_MIN_SPAN_MS ||
+      now - recoveryLastAt > RECOVERY_MAX_GAP_MS
+    )
+      return false;
+    fallbackSince = null;
+    clearRecovery();
+    return true;
+  }
+
+  /** Reuse only identical quality/budget requests; larger budgets deserve a new quality decision. */
+  function readScreenshot(now: number, quality: number, maxBytes: number): RuntimeFrame | null {
+    const cached = screenshot;
+    if (
+      !cached ||
+      now - cached.receivedAt > CAPTURE_MAX_AGE_MS ||
+      cached.quality !== quality ||
+      cached.maxBytes !== maxBytes
+    )
+      return null;
+    return cached.frame;
+  }
+
+  /**
+   * Begin capture and return its mutation/session epoch. A quality-only viewer
+   * capture keeps independent stream recovery evidence, while still excluding
+   * capture-induced events until the same causal guard expires.
+   */
+  function beginScreenshot(options: { preserveRecovery?: boolean } = {}): number {
+    screenshotsInFlight += 1;
+    if (!options.preserveRecovery) clearRecovery();
+    return generation;
+  }
+
+  /** End causal exclusion only for this still-current capture generation. */
+  function endScreenshot(token: number, now: number): void {
+    if (token !== generation) return;
+    screenshotsInFlight = Math.max(0, screenshotsInFlight - 1);
+    ignoreStreamUntil = Math.max(ignoreStreamUntil, now + SCREENSHOT_EVENT_GUARD_MS);
+  }
+
+  /** Never install a pre-input/session screenshot after its asynchronous RPC resolves. */
+  function rememberScreenshot(
+    token: number,
+    frame: RuntimeFrame,
+    now: number,
+    quality: number,
+    maxBytes: number,
+  ): boolean {
+    if (token !== generation) return false;
+    screenshot = { frame, receivedAt: now, quality, maxBytes };
+    return true;
+  }
+
+  return {
+    invalidate,
+    enterFallback,
+    observeStream,
+    canUseStream,
+    readScreenshot,
+    beginScreenshot,
+    endScreenshot,
+    rememberScreenshot,
+    currentGeneration: () => generation,
+    isCurrent: (token: number) => token === generation,
+  };
+}

package/server/capture-transport-runtime.test.ts

@@ -0,0 +1,213 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { DEFAULT_JPEG_QUALITY } from "../shared/capture-settings";
+import { AgentBrowserRuntime } from "./agent-browser-runtime";
+
+/** Header fixture exercises actual bounded JPEG validation without launching Chromium. */
+function jpeg(tag = 1): string {
+  return Buffer.from([
+    255,
+    216,
+    255,
+    224,
+    0,
+    3,
+    tag,
+    255,
+    192,
+    0,
+    11,
+    8,
+    3,
+    32,
+    5,
+    0,
+    1,
+    1,
+    17,
+    0,
+    255,
+    217,
+  ]).toString("base64");
+}
+let clock = 10_000;
+beforeEach(() => {
+  clock = 10_000;
+  vi.spyOn(performance, "now").mockImplementation(() => clock);
+  vi.spyOn(Date, "now").mockImplementation(() => 1_800_000_000_000 + clock);
+});
+afterEach(() => vi.restoreAllMocks());
+
+function fixture() {
+  const runtime = new AgentBrowserRuntime({
+    nativeVideo: true,
+    binaryPath: "/tmp/unlaunched-browser",
+    executablePath: "/tmp/unlaunched-chromium",
+    profilePath: "/tmp/uncreated-profile",
+    ipcDirectory: "/tmp/uncreated-ipc",
+    session: "test",
+  });
+  const calls: string[] = [];
+  let capture: (params: Record<string, unknown>) => Promise<{ data: string }> = async () => ({
+    data: jpeg(),
+  });
+  const page = {
+    send: async (method: string, params: Record<string, unknown> = {}) => {
+      calls.push(method);
+      if (method === "Page.captureScreenshot") return capture(params);
+      if (method === "Page.getLayoutMetrics") return { cssVisualViewport: { pageX: 0, pageY: 0 } };
+      return {};
+    },
+  };
+  const control = runtime as unknown as {
+    requirePage: () => Promise<typeof page>;
+    page: typeof page;
+    invalidateScreencastFrame: () => void;
+    onScreencastFrame: (source: typeof page, event: object) => void;
+  };
+  Object.assign(runtime, {
+    page,
+    emulationAppliedPage: page,
+    screencastActive: true,
+    viewport: { width: 1280, height: 800, deviceScaleFactor: 1, mobile: false, touch: false },
+  });
+  control.requirePage = async () => control.page;
+  const emit = (timestamp: number, source = page) =>
+    control.onScreencastFrame(source, {
+      data: jpeg(2),
+      metadata: {
+        deviceWidth: 1280,
+        deviceHeight: 800,
+        timestamp: (Date.now() + timestamp / 1000) / 1000,
+      },
+      sessionId: 17,
+    });
+  return {
+    runtime,
+    control,
+    page,
+    calls,
+    emit,
+    setCapture: (next: typeof capture) => {
+      capture = next;
+    },
+  };
+}
+
+describe("runtime capture hysteresis", () => {
+  it("captures only the visible viewport without Chromium's touch-resetting beyond-viewport mode", async () => {
+    const { runtime, setCapture } = fixture();
+    setCapture(async (params) => {
+      expect(params.captureBeyondViewport).toBe(false);
+      expect(params.clip).toEqual({ x: 0, y: 0, width: 1280, height: 800, scale: 1 });
+      return { data: jpeg() };
+    });
+    expect((await runtime.frame(100, DEFAULT_JPEG_QUALITY, 0)).transport).toBe("screenshot");
+  });
+
+  it("does not bounce to CDP after a screenshot-induced event; reuses only fresh exact-request pixels", async () => {
+    const { runtime, calls, emit, setCapture } = fixture();
+    setCapture(async () => {
+      emit(clock);
+      return { data: jpeg() };
+    });
+    const first = await runtime.frame(100, DEFAULT_JPEG_QUALITY, 0);
+    expect(first.transport).toBe("screenshot");
+    clock += 250;
+    expect(await runtime.frame(100, DEFAULT_JPEG_QUALITY, 0)).toBe(first);
+    expect(calls.filter((method) => method === "Page.captureScreenshot")).toHaveLength(1);
+    clock += 751;
+    expect(await runtime.frame(100, DEFAULT_JPEG_QUALITY, 0)).not.toBe(first);
+    expect(calls.filter((method) => method === "Page.captureScreenshot")).toHaveLength(2);
+    await runtime.frame(100, 90, 0);
+    await runtime.frame(101, 90, 0);
+    expect(calls.filter((method) => method === "Page.captureScreenshot")).toHaveLength(4);
+  });
+
+  it("only sustained valid current-session events recover CDP after dwell", async () => {
+    const { runtime, page, emit } = fixture();
+    await runtime.frame(100, DEFAULT_JPEG_QUALITY, 0);
+    clock += 1100;
+    emit(1);
+    clock += 250;
+    emit(2);
+    clock += 250;
+    emit(3, { ...page });
+    expect((await runtime.frame(100, DEFAULT_JPEG_QUALITY, 0)).transport).toBe("screenshot");
+    clock += 300;
+    emit(3);
+    clock += 250;
+    emit(4);
+    clock += 250;
+    emit(5);
+    expect((await runtime.frame(100, DEFAULT_JPEG_QUALITY, 0)).transport).toBe("cdp-screencast");
+  });
+
+  it("late screenshot completion after input cannot return or restore old cached pixels", async () => {
+    const { runtime, control, setCapture } = fixture();
+    const shot = Promise.withResolvers<{ data: string }>();
+    const started = Promise.withResolvers<void>();
+    setCapture(async () => {
+      started.resolve();
+      return shot.promise;
+    });
+    const pending = runtime.frame(100, DEFAULT_JPEG_QUALITY, 0);
+    await started.promise;
+    await runtime.insertText("owned-fixture");
+    shot.resolve({ data: jpeg() });
+    await expect(pending).rejects.toThrow("capture was invalidated");
+    setCapture(async () => ({ data: jpeg(3) }));
+    const fresh = await runtime.frame(100, DEFAULT_JPEG_QUALITY, 0);
+    expect(fresh.dataBase64).toBe(jpeg(3));
+    control.invalidateScreencastFrame();
+    setCapture(async () => ({ data: jpeg(4) }));
+    expect((await runtime.frame(100, DEFAULT_JPEG_QUALITY, 0)).dataBase64).toBe(jpeg(4));
+  });
+
+  it("late screenshot completion from a replaced page cannot authorize a frame", async () => {
+    const { runtime, control, page, setCapture } = fixture();
+    const shot = Promise.withResolvers<{ data: string }>();
+    const started = Promise.withResolvers<void>();
+    setCapture(async () => {
+      started.resolve();
+      return shot.promise;
+    });
+    const pending = runtime.frame(100, DEFAULT_JPEG_QUALITY, 0);
+    await started.promise;
+    control.page = { ...page };
+    control.invalidateScreencastFrame();
+    shot.resolve({ data: jpeg() });
+    await expect(pending).rejects.toThrow("capture was invalidated");
+  });
+});
+
+it("honors low/medium quality independently while high viewers keep the shared stream", async () => {
+  const { runtime, calls, emit, setCapture } = fixture();
+  const qualities: unknown[] = [];
+  setCapture(async (params) => {
+    qualities.push(params.quality);
+    return { data: jpeg() };
+  });
+  emit(1);
+  expect((await runtime.frame(100, DEFAULT_JPEG_QUALITY, 0)).transport).toBe("cdp-screencast");
+  const low = await runtime.frame(100, 70, 0);
+  expect(low.transport).toBe("screenshot");
+  expect(await runtime.frame(100, 70, 0)).toBe(low);
+  expect((await runtime.frame(100, DEFAULT_JPEG_QUALITY, 0)).transport).toBe("cdp-screencast");
+  expect((await runtime.frame(100, 90, 0)).transport).toBe("screenshot");
+  expect((await runtime.frame(100, DEFAULT_JPEG_QUALITY, 0)).transport).toBe("cdp-screencast");
+  expect(qualities).toEqual([70, 90]);
+  expect(calls).not.toContain("Page.startScreencast");
+  expect(calls).not.toContain("Page.stopScreencast");
+});
+
+it("reduces quality only to satisfy the byte cap and never substitutes a cached high-quality frame", async () => {
+  const { runtime, setCapture } = fixture();
+  const qualities: unknown[] = [];
+  setCapture(async (params) => {
+    qualities.push(params.quality);
+    return { data: params.quality === 70 ? jpeg() + "AAAA".repeat(50) : jpeg() };
+  });
+  await runtime.frame(100, DEFAULT_JPEG_QUALITY, 0);
+  expect((await runtime.frame(100, 70, 0)).transport).toBe("screenshot");
+  expect(qualities).toEqual([DEFAULT_JPEG_QUALITY, 70, 65]);
+});

package/server/daemon-launch-chain.test.ts

@@ -0,0 +1,70 @@
+/** Ownership must survive the shipped JS-launcher -> detached daemon chain, not just a native binary. */
+import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, it, vi } from "vitest";
+import { AgentBrowserRuntime } from "./agent-browser-runtime";
+
+const directories: string[] = [];
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await Promise.all(
+    directories.splice(0).map((path) => rm(path, { recursive: true, force: true })),
+  );
+});
+
+const launcher = `#!${process.execPath}
+const { spawn } = require("node:child_process");
+const { writeFileSync } = require("node:fs");
+const { join } = require("node:path");
+const args = process.argv.slice(2);
+const dir = process.env.AGENT_BROWSER_SOCKET_DIR;
+const session = args[args.indexOf("--session") + 1];
+if (args.includes("--version")) console.log("0.37.1");
+else if (args.includes("open")) {
+  // Like the shipped launcher: the daemon is detached but inherits this process's environment.
+  const daemon = spawn(process.execPath, ["-e", "setTimeout(() => {}, 30000)"], { detached: true, stdio: "ignore" });
+  daemon.unref();
+  writeFileSync(join(dir, session + ".pid"), String(daemon.pid));
+  console.log("{}");
+} else if (args.includes("close")) {
+  process.kill(Number(require("node:fs").readFileSync(join(dir, session + ".pid"), "utf8")), "SIGTERM");
+  console.log("{}");
+}
+`;
+
+it.skipIf(process.platform !== "linux")(
+  "verifies the detached daemon through a script launcher and observes its exit without a signal",
+  async () => {
+    const directory = await mkdtemp(join(tmpdir(), "shared-browser-chain-"));
+    directories.push(directory);
+    const binary = join(directory, "agent-browser");
+    await writeFile(binary, launcher);
+    await chmod(binary, 0o700);
+    const runtime = new AgentBrowserRuntime({
+      binaryPath: binary,
+      executablePath: join(directory, "unlaunched-chromium"),
+      profilePath: join(directory, "profile"),
+      ipcDirectory: join(directory, "ipc"),
+      session: "chain",
+      daemonExitWaitMs: 3_000,
+    });
+    const native = runtime as unknown as {
+      invoke(args: string[]): Promise<unknown>;
+      captureDaemon(): Promise<void>;
+      daemonLaunched: boolean;
+      daemon: { pid: number; identity: unknown } | null;
+    };
+    const { mkdir } = await import("node:fs/promises");
+    await mkdir(join(directory, "ipc"), { recursive: true });
+    await native.invoke(["--session", "chain", "--json", "open", "about:blank"]);
+    native.daemonLaunched = true;
+    await native.captureDaemon();
+    expect(native.daemon?.identity).toBeTruthy();
+    const pid = native.daemon?.pid as number;
+    const kill = vi.spyOn(process, "kill");
+    await runtime.shutdown();
+    expect(kill).not.toHaveBeenCalledWith(pid, "SIGKILL");
+    expect(() => process.kill(pid, 0)).toThrow();
+  },
+);