pi-browser-harness 0.12.0 → 0.14.0

package/src/cdp/target-factory.ts

@@ -3,7 +3,9 @@
 import { randomUUID } from "node:crypto";
 import type { BrowserClient } from "../client";
 import { type Result, err, ok } from "../util/result";
+import { safeJs } from "../util/js-template";
 import { type CdpError, cdpError } from "./errors";
+import { reconcileOwnership } from "./ownership";
 
 const SPAWN_DEADLINE_MS = 8_000;
 const SPAWN_POLL_MS = 100;
@@ -26,30 +28,46 @@ const listPageTargets = async (client: BrowserClient): Promise<Result<ReadonlyAr
   return ok(r.data.targetInfos.filter((t) => t.type === "page"));
 };
 
-const sessionForTarget = async (client: BrowserClient, targetId: string): Promise<Result<string, CdpError>> => {
-  const current = client.current();
-  if (current?.targetId === targetId) return ok(current.sessionId);
-  return client.session().attach(targetId);
+export type BorrowedSession = { readonly sessionId: string; readonly release: () => Promise<void> };
+
+// Reuses the tracked, domain-enabled session when the harness holds one for the target; otherwise attaches a raw throwaway session that `release` detaches, so no session outlives its single use.
+export const borrowSession = async (client: BrowserClient, targetId: string): Promise<Result<BorrowedSession, CdpError>> => {
+  const tracked = client.session().sessionFor(targetId);
+  if (tracked !== undefined) return ok({ sessionId: tracked, release: () => Promise.resolve() });
+  const attached = await client.session().attach(targetId);
+  if (!attached.success) return attached;
+  const sessionId = attached.data;
+  return ok({
+    sessionId,
+    release: async () => {
+      await client.session().detach(sessionId);
+    },
+  });
 };
 
 const spawnTabViaOpener = async (
   client: BrowserClient,
   openerTargetId: string,
 ): Promise<Result<string, CdpError>> => {
-  const session = await sessionForTarget(client, openerTargetId);
-  if (!session.success) return session;
+  const borrowed = await borrowSession(client, openerTargetId);
+  if (!borrowed.success) return borrowed;
 
   const token = `pi-${randomUUID()}`;
   // userGesture: true is what gets this past the popup blocker.
-  const opened = await client.session().callOnTarget(
-    "Runtime.evaluate",
-    {
-      expression: `!!window.open('about:blank#${token}', '_blank')`,
-      returnByValue: true,
-      userGesture: true,
-    },
-    session.data,
-  );
+  let opened;
+  try {
+    opened = await client.session().callOnTarget(
+      "Runtime.evaluate",
+      {
+        expression: safeJs`!!window.open(${`about:blank#${token}`}, '_blank')`,
+        returnByValue: true,
+        userGesture: true,
+      },
+      borrowed.data.sessionId,
+    );
+  } finally {
+    await borrowed.data.release();
+  }
   if (!opened.success) return opened;
   if (opened.data.result.value !== true) {
     return err(cdpError(
@@ -93,6 +111,7 @@ const ensureHarnessWindowUncoordinated = async (
   const live = new Set(targets.data.map((t) => t.targetId));
 
   const ownership = client.ownership();
+  reconcileOwnership(ownership, live);
   const pinnedCtx = client.profileContextId();
   // With a pin set but no context resolved yet, a recorded tab's profile cannot be verified, so seed a new window rather than risk adopting one from the wrong profile.
   const canReuse = client.profilePin() === null || pinnedCtx !== undefined;

package/src/cdp/types.ts

@@ -11,7 +11,7 @@ export type CdpEvent = {
 export type CdpRawMessage = {
   readonly id?: number;
   readonly method?: string;
-  readonly params?: Record<string, unknown>;
+  readonly params?: Readonly<Record<string, unknown>>;
   readonly result?: unknown;
   readonly error?: { readonly message: string; readonly code?: number };
   readonly sessionId?: string;
@@ -30,6 +30,15 @@ export type TabInfo = {
   readonly owned?: boolean;
 };
 
+// The identity of an interactive element as seen in one snapshot. Kept on the tab session per ref so the next
+// mutation can report what changed without re-running a full snapshot.
+export type RefSignature = {
+  readonly role: string;
+  readonly name: string;
+  readonly value: string;
+  readonly state: string;
+};
+
 export type PageInfo = {
   readonly url: string;
   readonly title: string;
@@ -41,6 +50,11 @@ export type PageInfo = {
   readonly pageHeight: number;
 };
 
+// Discriminated on `kind`.
+export type PageInfoResult =
+  | ({ readonly kind: "page" } & PageInfo)
+  | { readonly kind: "dialog"; readonly dialog: DialogInfo };
+
 export type DaemonStatus = {
   readonly alive: boolean;
   readonly sessionId: string | null;
@@ -56,6 +70,8 @@ export const isCdpRawMessage = (v: unknown): v is CdpRawMessage => {
   if (method !== undefined && typeof method !== "string") return false;
   const sessionId = v["sessionId"];
   if (sessionId !== undefined && typeof sessionId !== "string") return false;
+  const params = v["params"];
+  if (params !== undefined && !isRecord(params)) return false;
   const errVal = v["error"];
   if (errVal !== undefined) {
     if (!isRecord(errVal)) return false;

package/src/client.ts

@@ -1,3 +1,4 @@
+import { DAEMON_RECONNECT_METHOD } from "./daemon/protocol";
 import { Type } from "typebox";
 import { Compile } from "typebox/compile";
 import { parseJson } from "./schemas/parse";
@@ -8,11 +9,26 @@ import { discoverEndpoint } from "./cdp/discovery";
 import { type CdpError, cdpError } from "./cdp/errors";
 import type { CdpTransport } from "./cdp/types";
 import { type CdpSession, createCdpSession } from "./cdp/session";
-import { type OwnershipRegistry, createOwnershipRegistry } from "./cdp/ownership";
+import { type OwnershipRegistry, createOwnershipRegistry, reconcileOwnership } from "./cdp/ownership";
 import { ensureHarnessWindow, openHarnessTab } from "./cdp/target-factory";
 import { seedProfileWindow } from "./profile/bind";
 import type { ProfilePin } from "./profile/store";
-import type { DaemonStatus, DialogInfo, PageInfo, TabInfo } from "./cdp/types";
+import type { DaemonStatus, DialogInfo, PageInfo, PageInfoResult, TabInfo } from "./cdp/types";
+import { pageExpression } from "./util/js-source";
+
+// REPL mode lets a later call declare the same const or let again, as the console does.
+export const evaluateParams = (
+  expression: string,
+): { readonly expression: string; readonly returnByValue: true; readonly awaitPromise: true; readonly replMode: true } => ({
+  expression: pageExpression(expression),
+  returnByValue: true,
+  awaitPromise: true,
+  replMode: true,
+});
+
+const CLOSE_ATTEMPTS = 2;
+const CLOSE_CONFIRM_MS = 2_500;
+const CLOSE_POLL_MS = 100;
 
 export type BrowserClientOptions = {
   readonly namespace: string;
@@ -24,6 +40,8 @@ export type BrowserClientOptions = {
     readonly harnessWindowId?: number;
   };
   readonly profilePin?: ProfilePin | null;
+  // How long one close may take to show in Chrome's target list before it is sent again; tests shorten it.
+  readonly closeConfirmMs?: number;
   readonly onOwnershipChange?: (snapshot: {
     readonly ownedTargetIds: ReadonlyArray<string>;
     readonly harnessWindowTargetId: string | undefined;
@@ -35,12 +53,14 @@ export type BrowserClient = {
   readonly namespace: string;
   ensureAlive(): Promise<Result<void, CdpError>>;
   status(): DaemonStatus;
-  start(): Promise<Result<void, CdpError>>;
+  // `reconnectNow` is for explicit human demand (/browser-setup, /browser-reload-daemon): it asks the
+  // daemon to dial Chrome immediately even if it is cooling down after a failed attempt.
+  start(opts?: { readonly reconnectNow?: boolean }): Promise<Result<void, CdpError>>;
   stop(): Promise<void>;
   detach(): Promise<void>;
   closeOwnedTabs(): Promise<void>;
   evaluateJs(expression: string, sessionId?: string): Promise<Result<unknown, CdpError>>;
-  pageInfo(): Promise<Result<PageInfo | { readonly dialog: DialogInfo }, CdpError>>;
+  pageInfo(): Promise<Result<PageInfoResult, CdpError>>;
   takeDialog(): DialogInfo | null;
   listTabs(includeInternal?: boolean): Promise<Result<ReadonlyArray<TabInfo>, CdpError>>;
   switchTab(targetId: string): Promise<Result<void, CdpError>>;
@@ -123,7 +143,8 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
   });
   const mutationMutex = createMutex();
   let lastHealth = 0;
-  let pageCaches = new Map<string, { readonly info: PageInfo; readonly at: number }>();
+  let healthCheck: Promise<Result<void, CdpError>> | null = null;
+  const pageCaches = new Map<string, { readonly info: PageInfo; readonly at: number }>();
   let remote: BrowserClientOptions["remote"] | null = opts.remote ?? null;
   let userDataDir: string | undefined;
   let profilePin: ProfilePin | null = opts.profilePin ?? null;
@@ -137,7 +158,7 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     return ok(undefined);
   };
 
-  const start = async (): Promise<Result<void, CdpError>> => {
+  const start = async (opts: { readonly reconnectNow?: boolean } = {}): Promise<Result<void, CdpError>> => {
     if (transport.state() === "open" && session.current()) return ok(undefined);
     let wsUrl: string;
     if (remote?.cdpUrl) {
@@ -150,9 +171,18 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     }
     const connected = await transport.connect(wsUrl, { timeoutMs: 10_000 });
     if (!connected.success) return connected;
+    if (opts.reconnectNow) {
+      // Only the daemon understands this; a direct Chrome transport answers "method not found",
+      // which is fine because it has no cooldown to clear.
+      const dialed = await transport.request(DAEMON_RECONNECT_METHOD, {}, { timeoutMs: 15_000 });
+      if (!dialed.success && dialed.error.kind !== "remote_error") {
+        await transport.close();
+        return dialed;
+      }
+    }
 
     const newBrowserId: string = wsUrl.split("/").pop() ?? "unknown";
-    if (!remote || remote.browserId !== newBrowserId) {
+    if (remote?.browserId !== newBrowserId) {
       profileContextId = undefined;
     }
     remote = { cdpUrl: wsUrl, browserId: newBrowserId };
@@ -177,43 +207,62 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     lastHealth = 0;
   };
 
-  const ensureAlive = async (): Promise<Result<void, CdpError>> => {
-    if (transport.state() !== "open" || !session.current()) {
-      await stop();
-      return start();
+  const restart = async (): Promise<Result<void, CdpError>> => {
+    await stop();
+    return start();
+  };
+
+  const reattach = async (): Promise<Result<void, CdpError>> => {
+    const seeded = await seedIfPinned();
+    if (!seeded.success) return seeded;
+    const reattached = await session.attachFirstPage();
+    if (reattached.success) {
+      pageCaches.clear();
+      return ok(undefined);
     }
+    return restart();
+  };
+
+  // Two probes: the browser one proves the socket works, the page one proves the current session does.
+  // Only transport-level failures (closed socket, timeout) mean the connection is dead. A page probe that
+  // fails for a page-level reason (navigation in flight, a throwing page) still proves the session routes,
+  // so it counts as alive; only a dead session id triggers a re-attach.
+  const checkHealth = async (): Promise<Result<void, CdpError>> => {
+    if (transport.state() !== "open" || !session.current()) return restart();
     if (Date.now() - lastHealth < HEALTH_TTL_MS) return ok(undefined);
-    const probe = await transport.request("Target.getTargets", {}, { sessionId: null, timeoutMs: 2_000 });
-    if (!probe.success) {
-      await stop();
-      return start();
-    }
+    const probe = await session.callBrowser("Target.getTargets", {}, { timeoutMs: 2_000 });
+    if (!probe.success) return restart();
     lastHealth = Date.now();
     const jsProbe = await session.call("Runtime.evaluate", {
       expression: "1", returnByValue: true,
     }, { timeoutMs: 2_000 });
-    if (!jsProbe.success && jsProbe.error.kind === "session_not_found") {
-      const seeded = await seedIfPinned();
-      if (!seeded.success) return seeded;
-      const reattached = await session.attachFirstPage();
-      if (reattached.success) {
-        pageCaches.clear();
+    if (jsProbe.success) return ok(undefined);
+    switch (jsProbe.error.kind) {
+      case "session_not_found":
+        return reattach();
+      case "transport_closed":
+      case "timeout":
+        return restart();
+      case "discovery_failed":
+      case "invalid_response":
+      case "remote_error":
         return ok(undefined);
-      }
-      await stop();
-      return start();
     }
-    return ok(undefined);
+  };
+
+  // Concurrent callers share one in-flight check, so two tools racing after a disconnect cannot both restart the transport.
+  const ensureAlive = (): Promise<Result<void, CdpError>> => {
+    if (healthCheck) return healthCheck;
+    const running = checkHealth().finally(() => {
+      healthCheck = null;
+    });
+    healthCheck = running;
+    return running;
   };
 
   const evaluateJs = async (expression: string, sessionId?: string): Promise<Result<unknown, CdpError>> => {
-    // Wrap only when the trimmed source *starts with* `return` — matching the substring anywhere silently turned expressions mentioning it into `undefined`.
-    const trimmed = expression.trim();
-    const isReturnStatement = /^return[\s(]/.test(trimmed);
-    const wrapped = isReturnStatement ? `(function(){${expression}})()` : expression;
-    const r = sessionId
-      ? await session.callOnTarget("Runtime.evaluate", { expression: wrapped, returnByValue: true, awaitPromise: true }, sessionId)
-      : await session.call("Runtime.evaluate", { expression: wrapped, returnByValue: true, awaitPromise: true });
+    const params = evaluateParams(expression);
+    const r = sessionId ? await session.callOnTarget("Runtime.evaluate", params, sessionId) : await session.call("Runtime.evaluate", params);
     if (!r.success) return r;
     if (r.data.exceptionDetails !== undefined) {
       return err(cdpError("remote_error", `JS evaluation failed: ${JSON.stringify(r.data.exceptionDetails)}`, "Runtime.evaluate"));
@@ -236,10 +285,12 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     return ok(info.data);
   };
 
-  const pageInfo = async (): Promise<Result<PageInfo | { readonly dialog: DialogInfo }, CdpError>> => {
+  const pageInfo = async (): Promise<Result<PageInfoResult, CdpError>> => {
     const d = session.takeDialog();
-    if (d) return ok({ dialog: d });
-    return readPageInfo();
+    if (d) return ok({ kind: "dialog", dialog: d });
+    const info = await readPageInfo();
+    if (!info.success) return info;
+    return ok({ kind: "page", ...info.data });
   };
 
   const listTabs = async (includeInternal = true): Promise<Result<ReadonlyArray<TabInfo>, CdpError>> => {
@@ -255,11 +306,7 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
         owned: ownership.has(t.targetId),
       }));
     const live = new Set(tabs.map((t) => t.targetId));
-    const owned = ownership.list();
-    const survivors = owned.filter((id) => live.has(id));
-    if (survivors.length !== owned.length) ownership.replaceAll(survivors);
-    const hw = ownership.harnessWindow();
-    if (hw && !live.has(hw)) ownership.setHarnessWindow(undefined);
+    reconcileOwnership(ownership, live);
     for (const tid of pageCaches.keys()) {
       if (!live.has(tid)) pageCaches.delete(tid);
     }
@@ -276,9 +323,7 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
   };
 
   const newTab = async (url?: string): Promise<Result<string, CdpError>> => {
-    const tabsResult = await listTabs(true);
-    if (!tabsResult.success) return tabsResult;
-
+    // ensureHarnessWindow lists live targets and reconciles ownership itself, so no listing is needed here.
     const window = await ensureHarnessWindow(api);
     if (!window.success) return window;
     let tabId: string;
@@ -299,17 +344,46 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     return ok(tabId);
   };
 
+  // True once Chrome no longer lists the target, false if it still does at the deadline, undefined when the list
+  // cannot be read (then the close is taken at its word, as before).
+  const targetGone = async (targetId: string, timeoutMs: number): Promise<boolean | undefined> => {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      const r = await session.callBrowser("Target.getTargets", {}, { timeoutMs: 2_000 });
+      if (!r.success) return undefined;
+      if (!r.data.targetInfos.some((t) => t.targetId === targetId)) return true;
+      if (Date.now() >= deadline) return false;
+      await new Promise((resolve) => setTimeout(resolve, CLOSE_POLL_MS));
+    }
+  };
+
+  // Chrome answers Target.closeTarget with success even when it then keeps the tab: a tab closed while its page is
+  // still loading stays open. So the close is checked against Chrome's own target list and sent once more if the
+  // tab is still there; the tab leaves the owned list only once it is gone, so a tab left open is not lost track of.
   const closeTab = async (targetId: string): Promise<Result<void, CdpError>> => {
-    const r = await session.callBrowser("Target.closeTarget", { targetId });
-    if (!r.success) return r;
-    ownership.remove(targetId);
-    return ok(undefined);
+    for (let attempt = 1; attempt <= CLOSE_ATTEMPTS; attempt++) {
+      const r = await session.callBrowser("Target.closeTarget", { targetId });
+      if (!r.success) return r;
+      const gone = await targetGone(targetId, opts.closeConfirmMs ?? CLOSE_CONFIRM_MS);
+      if (gone !== false) {
+        ownership.remove(targetId);
+        return ok(undefined);
+      }
+    }
+    return err(
+      cdpError(
+        "timeout",
+        `Chrome accepted the close but tab ${targetId} is still open after ${CLOSE_ATTEMPTS} attempts (a page that is still loading can ignore a close); wait for it to load, then close it again`,
+        "Target.closeTarget",
+      ),
+    );
   };
 
   const closeOwnedTabs = async (): Promise<void> => {
     for (const id of ownership.list()) {
-      await session.callBrowser("Target.closeTarget", { targetId: id }).catch(() => {});
-      ownership.remove(id);
+      const closed = await session.callBrowser("Target.closeTarget", { targetId: id });
+      // A remote error means the browser answered (typically "no target with given id"): the tab is gone either way. A transport failure means nothing was closed, so keep the record for the next attempt.
+      if (closed.success || closed.error.kind === "remote_error") ownership.remove(id);
     }
     ownership.setHarnessWindow(undefined);
     ownership.setHarnessWindowId(undefined);
@@ -323,9 +397,8 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
   });
 
   const detach = async (): Promise<void> => {
-    const cur = session.current();
-    if (!cur) return;
-    await transport.request("Target.detachFromTarget", { sessionId: cur.sessionId }, { sessionId: null });
+    if (transport.state() !== "open") return;
+    await session.detachAll();
   };
 
   const api: BrowserClient = {
@@ -344,7 +417,7 @@ export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient =
     setProfilePin: (pin) => {
       const changed = pin === null
         ? profilePin !== null
-        : profilePin === null || profilePin.userDataDir !== pin.userDataDir || profilePin.profileDir !== pin.profileDir;
+        : profilePin?.userDataDir !== pin.userDataDir || profilePin.profileDir !== pin.profileDir;
       profilePin = pin;
       if (changed) {
         profileContextId = undefined;