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

package/server/runtime-page-state.test.ts

@@ -0,0 +1,249 @@
+/** Fresh metadata reads overlap CDP latency but never accept mixed native identities. */
+import { describe, expect, it, vi } from "vitest";
+import { AgentBrowserRuntime } from "./agent-browser-runtime";
+
+function fixture() {
+  const runtime = new AgentBrowserRuntime({
+    binaryPath: "/tmp/unlaunched-browser",
+    executablePath: "/tmp/unlaunched-chromium",
+    profilePath: "/tmp/uncreated-state-profile",
+    ipcDirectory: "/tmp/uncreated-state-ipc",
+    session: "state-test",
+  });
+  const calls: string[] = [];
+  const history = Promise.withResolvers<{
+    currentIndex: number;
+    entries: { url: string; title: string }[];
+  }>();
+  const metadata = Promise.withResolvers<{
+    result: { value?: { url?: string; title?: string } };
+  }>();
+  const retryHistory = Promise.withResolvers<Awaited<typeof history.promise>>();
+  const retryMetadata = Promise.withResolvers<Awaited<typeof metadata.promise>>();
+  const timeouts: number[] = [];
+  let onRead: (method: string, attempt: number) => void = () => {};
+  const page = {
+    send: (method: string, _input: unknown, options: { timeoutMs: number }) => {
+      const attempt = calls.filter((call) => call === method).length;
+      calls.push(method);
+      timeouts.push(options.timeoutMs);
+      onRead(method, attempt);
+      if (method === "Page.getNavigationHistory") {
+        return attempt === 0 ? history.promise : retryHistory.promise;
+      }
+      return attempt === 0 ? metadata.promise : retryMetadata.promise;
+    },
+  };
+  const control = runtime as unknown as {
+    page: typeof page;
+    attachmentGeneration: number;
+    documentGeneration: number;
+    stopping: boolean;
+    requirePage(): Promise<typeof page>;
+  };
+  control.page = page;
+  control.requirePage = async () => page;
+  return {
+    runtime,
+    control,
+    page,
+    calls,
+    history,
+    metadata,
+    retryHistory,
+    retryMetadata,
+    timeouts,
+    intercept: (callback: typeof onRead) => {
+      onRead = callback;
+    },
+  };
+}
+const entries = [
+  { url: "https://example.test/previous", title: "Previous" },
+  { url: "https://example.test/current", title: "History title" },
+];
+
+describe("fresh parallel native page metadata", () => {
+  it("discards both old reads and returns one fresh pair after a same-page document change", async () => {
+    const f = fixture();
+    const pending = f.runtime.state();
+    await Promise.resolve();
+    f.control.documentGeneration++;
+    f.retryHistory.resolve({
+      currentIndex: 0,
+      entries: [{ url: "https://example.test/new", title: "New history" }],
+    });
+    f.retryMetadata.resolve({
+      result: { value: { url: "https://example.test/new#ready", title: "New DOM" } },
+    });
+    f.history.resolve({ currentIndex: 1, entries });
+    f.metadata.resolve({
+      result: { value: { url: "https://example.test/old", title: "Old DOM" } },
+    });
+    expect(await pending).toEqual({
+      url: "https://example.test/new#ready",
+      title: "New DOM",
+      canGoBack: false,
+      canGoForward: false,
+      inputGeneration: "0:1",
+    });
+    expect(f.calls).toEqual([
+      "Page.getNavigationHistory",
+      "Runtime.evaluate",
+      "Page.getNavigationHistory",
+      "Runtime.evaluate",
+    ]);
+  });
+
+  it("starts both independent reads before either resolves and retains native history facts", async () => {
+    const f = fixture();
+    const pending = f.runtime.state();
+    await Promise.resolve();
+    expect(f.calls).toEqual(["Page.getNavigationHistory", "Runtime.evaluate"]);
+    f.metadata.resolve({
+      result: { value: { url: "https://example.test/current#hash", title: "Fresh title" } },
+    });
+    f.history.resolve({ currentIndex: 1, entries });
+    expect(await pending).toMatchObject({
+      url: "https://example.test/current#hash",
+      title: "Fresh title",
+      canGoBack: true,
+      canGoForward: false,
+    });
+  });
+  it("preserves existing native-history fallback when DOM values are absent", async () => {
+    const f = fixture();
+    const pending = f.runtime.state();
+    f.metadata.resolve({ result: {} });
+    f.history.resolve({ currentIndex: 0, entries });
+    expect(await pending).toMatchObject({
+      url: entries[0]!.url,
+      title: "Previous",
+      canGoBack: false,
+      canGoForward: true,
+    });
+  });
+  it("refuses attachment, page replacement or shutdown during either pending observation", async () => {
+    for (const kind of ["attachment", "page", "shutdown"] as const) {
+      const f = fixture();
+      const pending = f.runtime.state();
+      await Promise.resolve();
+      if (kind === "shutdown") f.control.stopping = true;
+      if (kind === "attachment") f.control.attachmentGeneration++;
+      if (kind === "page")
+        f.control.page = { send: () => Promise.resolve({}) } as unknown as typeof f.page;
+      f.history.resolve({ currentIndex: 1, entries });
+      f.metadata.resolve({ result: { value: { title: "Obsolete document" } } });
+      await expect(pending).rejects.toThrow(
+        kind === "shutdown" ? "shutting down" : "metadata changed",
+      );
+      expect(f.calls).toHaveLength(2);
+    }
+  });
+  it("refuses repeated document changes after exactly two read pairs", async () => {
+    const f = fixture();
+    f.intercept((method, attempt) => {
+      if (method === "Runtime.evaluate" && attempt === 1) f.control.documentGeneration++;
+    });
+    const pending = f.runtime.state();
+    await Promise.resolve();
+    f.control.documentGeneration++;
+    f.history.resolve({ currentIndex: 1, entries });
+    f.metadata.resolve({ result: {} });
+    f.retryHistory.resolve({ currentIndex: 0, entries });
+    f.retryMetadata.resolve({ result: {} });
+    await expect(pending).rejects.toThrow("metadata changed");
+    expect(f.calls).toHaveLength(4);
+  });
+
+  it("shares the original timeout budget across both pairs without restarting attachment", async () => {
+    const f = fixture();
+    let clock = 1_000;
+    const monotonic = vi.spyOn(performance, "now").mockImplementation(() => clock);
+    try {
+      const pending = f.runtime.state({ timeoutMs: 1_000 });
+      await Promise.resolve();
+      clock += 700;
+      f.control.documentGeneration++;
+      f.history.resolve({ currentIndex: 1, entries });
+      f.metadata.resolve({ result: {} });
+      f.retryHistory.resolve({ currentIndex: 0, entries });
+      f.retryMetadata.resolve({ result: {} });
+      await pending;
+      expect(f.timeouts).toHaveLength(4);
+      expect(f.timeouts.slice(0, 2).every((timeout) => timeout <= 1_000)).toBe(true);
+      expect(f.timeouts.slice(2).every((timeout) => timeout <= 300)).toBe(true);
+    } finally {
+      monotonic.mockRestore();
+    }
+  });
+
+  it("does not begin a second pair after the original budget expires", async () => {
+    const f = fixture();
+    let clock = 1_000;
+    const monotonic = vi.spyOn(performance, "now").mockImplementation(() => clock);
+    try {
+      const pending = f.runtime.state({ timeoutMs: 1_000 });
+      await Promise.resolve();
+      clock += 1_000;
+      f.control.documentGeneration++;
+      f.history.resolve({ currentIndex: 1, entries });
+      f.metadata.resolve({ result: {} });
+      await expect(pending).rejects.toThrow("metadata observation timed out");
+      expect(f.calls).toHaveLength(2);
+    } finally {
+      monotonic.mockRestore();
+    }
+  });
+
+  for (const phase of ["first", "second"] as const) {
+    it(`refuses successful held ${phase} replies at or after the original deadline`, async () => {
+      const f = fixture();
+      let clock = 1_000;
+      const monotonic = vi.spyOn(performance, "now").mockImplementation(() => clock);
+      try {
+        const secondStarted = Promise.withResolvers<void>();
+        f.intercept((method, attempt) => {
+          if (method === "Runtime.evaluate" && attempt === 1) secondStarted.resolve();
+        });
+        const pending = f.runtime.state({ timeoutMs: 1_000 });
+        await Promise.resolve();
+        if (phase === "second") {
+          clock += 700;
+          f.control.documentGeneration++;
+          f.history.resolve({ currentIndex: 1, entries });
+          f.metadata.resolve({ result: {} });
+          await secondStarted.promise;
+          expect(f.calls).toHaveLength(4);
+          clock += 301;
+          f.retryHistory.resolve({ currentIndex: 0, entries });
+          f.retryMetadata.resolve({ result: { value: { title: "Late fresh metadata" } } });
+        } else {
+          clock += 1_000;
+          f.history.resolve({ currentIndex: 1, entries });
+          f.metadata.resolve({ result: { value: { title: "Late metadata" } } });
+        }
+        await expect(pending).rejects.toThrow("metadata observation timed out");
+        expect(f.calls).toHaveLength(phase === "second" ? 4 : 2);
+      } finally {
+        monotonic.mockRestore();
+      }
+    });
+  }
+
+  it("propagates failed native reads rather than reusing earlier metadata", async () => {
+    for (const failed of ["history", "metadata"]) {
+      const f = fixture();
+      const pending = f.runtime.state();
+      const refusal = expect(pending).rejects.toThrow("Read unavailable");
+      await Promise.resolve();
+      f.control.documentGeneration++;
+      if (failed === "history") f.history.reject(new Error("Read unavailable"));
+      else f.history.resolve({ currentIndex: 1, entries });
+      if (failed === "metadata") f.metadata.reject(new Error("Read unavailable"));
+      else f.metadata.resolve({ result: {} });
+      await refusal;
+      expect(f.calls).toHaveLength(2);
+    }
+  });
+});

package/server/runtime-protocol.ts

@@ -36,7 +36,11 @@ export type AgentBrowserOperation =
   | "release-control"
   | "navigate"
   | "input"
-  | "viewport";
+  | "viewport"
+  | "tabs.list"
+  | "tabs.create"
+  | "tabs.select"
+  | "tabs.close";
 
 export type RuntimeRequest =
   | (AdminRequestBase & { method: "bridge.claim"; takeover?: boolean })
@@ -58,6 +62,12 @@ export type RuntimeRequest =
       epoch: number;
       workspaceId: string;
     })
+  | (AdminRequestBase & {
+      method: "workspace.close";
+      epoch: number;
+      workspaceId: string;
+      runtimeId: string;
+    })
   | (AdminRequestBase & {
       method: "browser.request";
       epoch: number;
@@ -107,6 +117,7 @@ export type RuntimeErrorCode =
   | "WORKSPACE_NOT_FOUND"
   | "RUNTIME_BUSY"
   | "UNKNOWN_OUTCOME"
+  | "RUNTIME_LOST"
   | "RUNTIME_FAILURE";
 
 export class RuntimeProtocolError extends Error {
@@ -119,6 +130,14 @@ export class RuntimeProtocolError extends Error {
   }
 }
 
+/** The owned runtime can never serve again; the next explicit attach must replace it. */
+export class RuntimeLostError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RuntimeLostError";
+  }
+}
+
 export function isRuntimeResponse(value: unknown): value is RuntimeResponse {
   if (!isRecord(value) || typeof value.id !== "string" || typeof value.ok !== "boolean")
     return false;
@@ -183,6 +202,17 @@ export function parseRuntimeRequest(value: unknown): RuntimeRequest {
       epoch,
       workspaceId: requireString(value, "workspaceId"),
     };
+  if (method === "workspace.close")
+    return {
+      id,
+      version: RUNTIME_PROTOCOL_VERSION,
+      method,
+      token,
+      bridgeId,
+      epoch,
+      workspaceId: requireString(value, "workspaceId"),
+      runtimeId: requireString(value, "runtimeId"),
+    };
   if (method === "workspace.request")
     return {
       id,

package/server/runtime-target-retention.test.ts

@@ -0,0 +1,181 @@
+/** Exercise real target attachment/reconnect methods without native sockets or profiles. */
+import { EventEmitter } from "node:events";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { AgentBrowserRuntime } from "./agent-browser-runtime";
+import { CdpConnection, type CdpSession } from "./cdp";
+
+class ConnectionFixture extends EventEmitter {
+  isOpen = true;
+  nextSession = 0;
+  readonly calls: { method: string; params: Record<string, unknown> }[] = [];
+  constructor(readonly targetIds: string[]) {
+    super();
+  }
+
+  async send<T>(method: string, params: Record<string, unknown> = {}): Promise<T> {
+    this.calls.push({ method, params });
+    if (method === "Target.getTargets")
+      return {
+        targetInfos: this.targetIds.map((targetId) => ({
+          targetId,
+          type: "page",
+          url: "about:blank",
+          title: targetId,
+        })),
+      } as T;
+    if (method === "Target.attachToTarget")
+      return { sessionId: `fixture-${++this.nextSession}` } as T;
+    if (method === "Page.getNavigationHistory") return { currentIndex: 0, entries: [] } as T;
+    if (method === "Page.getFrameTree") return { frameTree: { frame: { id: "root" } } } as T;
+    return {} as T;
+  }
+
+  close(): void {
+    this.isOpen = false;
+    this.emit("disconnect");
+  }
+}
+
+interface RuntimeControl {
+  invoke(args: string[]): Promise<unknown>;
+  assertVersion(): Promise<void>;
+  connectCdp(targetId?: string | null): Promise<void>;
+  reattachPageForScreencast(previous: CdpSession): Promise<CdpSession>;
+  connection: CdpConnection;
+  targetId: string | null;
+  page: CdpSession | null;
+}
+
+/** Stub only binary discovery and CDP transport, preserving runtime selection policy. */
+function fixture(targetLists: string[][]) {
+  const connections = targetLists.map((ids) => new ConnectionFixture(ids));
+  let next = 0;
+  vi.spyOn(CdpConnection, "connect").mockImplementation(async () => {
+    const connection = connections[next++];
+    if (!connection) throw new Error("Unexpected reconnect");
+    return connection as unknown as CdpConnection;
+  });
+  const runtime = new AgentBrowserRuntime({
+    binaryPath: "/tmp/unlaunched-browser",
+    executablePath: "/tmp/unlaunched-chromium",
+    profilePath: "/tmp/uncreated-profile",
+    ipcDirectory: "/tmp/uncreated-ipc",
+    session: "target-retention-test",
+  });
+  const control = runtime as unknown as RuntimeControl;
+  control.invoke = vi.fn(async () => ({ cdpUrl: "ws://127.0.0.1:1/fixture" }));
+  control.assertVersion = async () => {};
+  return { runtime, control, connections };
+}
+
+afterEach(() => vi.restoreAllMocks());
+describe("exact selected target retention", () => {
+  it("permits initial selection when no page has ever been selected", async () => {
+    const { control } = fixture([["first", "second"]]);
+    await control.connectCdp();
+    expect(control.targetId).toBe("first");
+  });
+
+  it("retains the selected surviving page across disconnect instead of adopting the first tab", async () => {
+    const { runtime, control, connections } = fixture([
+      ["other", "original"],
+      ["other", "original"],
+    ]);
+    await control.connectCdp("original");
+    connections[0]!.close();
+    expect(control.page).toBeNull();
+    expect(control.targetId).toBe("original");
+    await runtime.reconnect();
+    expect(control.page?.targetId).toBe("original");
+    expect(
+      connections[1]!.calls
+        .filter((call) => call.method === "Target.activateTarget")
+        .map((call) => call.params.targetId),
+    ).toEqual(["original"]);
+    expect(control.invoke).toHaveBeenCalledWith([
+      "--session",
+      "target-retention-test",
+      "--json",
+      "get",
+      "cdp-url",
+    ]);
+    expect(
+      connections
+        .flatMap((connection) => connection.calls)
+        .some((call) => call.method === "Page.navigate"),
+    ).toBe(false);
+  });
+
+  it("refuses a missing selected page on every reconnect without adopting another tab", async () => {
+    const { runtime, control, connections } = fixture([["original"], ["other"], ["other"]]);
+    await control.connectCdp("original");
+    connections[0]!.close();
+    await expect(runtime.reconnect()).rejects.toThrow(
+      "selected browser page is no longer available",
+    );
+    await expect(runtime.reconnect()).rejects.toThrow(
+      "selected browser page is no longer available",
+    );
+    expect(control.targetId).toBe("original");
+    expect(control.page).toBeNull();
+    expect(
+      connections
+        .slice(1)
+        .flatMap((connection) => connection.calls)
+        .some(
+          (call) =>
+            call.method === "Target.attachToTarget" || call.method === "Target.activateTarget",
+        ),
+    ).toBe(false);
+  });
+
+  it("requires an explicit initial target rather than replacing a missing launch target", async () => {
+    const { runtime, control, connections } = fixture([["other"], ["other"]]);
+    await expect(control.connectCdp("missing")).rejects.toThrow(
+      "selected browser page is no longer available",
+    );
+    expect(control.targetId).toBe("missing");
+    await expect(runtime.reconnect()).rejects.toThrow(
+      "selected browser page is no longer available",
+    );
+    expect(control.page).toBeNull();
+    expect(
+      connections
+        .flatMap((connection) => connection.calls)
+        .some((call) => call.method === "Target.activateTarget"),
+    ).toBe(false);
+  });
+
+  it("retains a newly explicitly selected page across later disconnects", async () => {
+    const { runtime, control, connections } = fixture([
+      ["first", "chosen"],
+      ["first", "chosen"],
+    ]);
+    await control.connectCdp();
+    await runtime.selectTarget("chosen");
+    connections[0]!.close();
+    await runtime.reconnect();
+    expect(control.page?.targetId).toBe("chosen");
+  });
+
+  it("refuses screencast reattachment when its exact former page disappeared", async () => {
+    const { control, connections } = fixture([["original", "other"]]);
+    await control.connectCdp("original");
+    const previous = control.page!;
+    connections[0]!.targetIds.splice(0, 1);
+    const before = connections[0]!.calls.length;
+    await expect(control.reattachPageForScreencast(previous)).rejects.toThrow(
+      "selected browser page is no longer available",
+    );
+    expect(control.page).toBe(previous);
+    expect(control.targetId).toBe("original");
+    expect(
+      connections[0]!.calls
+        .slice(before)
+        .some(
+          (call) =>
+            call.method === "Target.activateTarget" || call.method === "Target.attachToTarget",
+        ),
+    ).toBe(false);
+  });
+});

package/server/runtime-video-opt-in.test.ts

@@ -0,0 +1,82 @@
+/** Encoded video is host-opt-in: image-only sessions never load the capture extension. */
+
+import { mkdtemp, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { AgentBrowserRuntime } from "./agent-browser-runtime";
+
+// The owned CLI is simulated at the process boundary, as in daemon-shutdown.test.ts: a
+// POSIX-shebang script is not executable on Windows, so no executable file is required.
+vi.mock("node:child_process", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("node:child_process")>()),
+  execFile: (
+    _file: string,
+    _args: string[],
+    _options: unknown,
+    callback: (error: null, result: { stdout: string }) => void,
+  ) => callback(null, { stdout: "0.38.2\n" }),
+}));
+
+const temporary: string[] = [];
+afterEach(async () => {
+  await Promise.all(temporary.splice(0).map((path) => rm(path, { recursive: true, force: true })));
+});
+
+async function fixture(nativeVideo?: boolean) {
+  const directory = await mkdtemp(join(tmpdir(), "shared-browser-video-opt-in-"));
+  temporary.push(directory);
+  const binary = join(directory, "owned-cli");
+  const ipcDirectory = join(directory, "ipc");
+  const runtime = new AgentBrowserRuntime({
+    binaryPath: binary,
+    executablePath: join(directory, "unlaunched-chromium"),
+    profilePath: join(directory, "profile"),
+    ipcDirectory,
+    session: "video-opt-in",
+    ...(nativeVideo === undefined ? {} : { nativeVideo }),
+  });
+  const internal = runtime as unknown as {
+    invoke(args: string[]): Promise<unknown>;
+    video: unknown;
+  };
+  const launches: string[][] = [];
+  internal.invoke = async (args) => {
+    launches.push(args);
+    throw new Error("Owned fixture stops before a browser exists");
+  };
+  return { runtime, internal, launches, ipcDirectory };
+}
+
+describe("encoded video opt-in", () => {
+  it("launches image-only sessions without the extension, its allowlist or any materialized files", async () => {
+    for (const option of [undefined, false]) {
+      const f = await fixture(option);
+      await expect(f.runtime.launch()).rejects.toThrow("stops before a browser");
+      const [args] = f.launches;
+      expect(args).not.toContain("--extension");
+      expect(args?.join(" ")).not.toContain("allowlisted-extension-id");
+      expect(await readdir(f.ipcDirectory)).toEqual([]);
+    }
+  });
+
+  it("loads and allowlists the capture extension only when the host opted in", async () => {
+    const f = await fixture(true);
+    await expect(f.runtime.launch()).rejects.toThrow("stops before a browser");
+    const [args] = f.launches;
+    expect(args).toContain("--extension");
+    expect(args?.join(" ")).toContain("--allowlisted-extension-id=");
+  });
+
+  it("reports a typed disabled reply without creating any capture source", async () => {
+    const f = await fixture();
+    const reply = await f.runtime.readVideo({ quality: "high" });
+    expect(reply).toMatchObject({
+      status: "unsupported",
+      reasonCode: "video-disabled",
+      streamId: null,
+      packets: [],
+    });
+    expect(f.internal.video).toBeNull();
+  });
+});