pi-feats 0.1.2 → 0.1.4

package/extensions/browser-harness/cdp/target-factory.ts

@@ -0,0 +1,153 @@
+// `window.open` with userGesture is the only CDP-reachable way into a non-default browser context: createTarget rejects a foreign browserContextId and `openerId` does not inherit the opener's context.
+
+import { randomUUID } from "node:crypto";
+import type { BrowserClient } from "../client";
+import { type Result, err, ok } from "../util/result";
+import { type CdpError, cdpError } from "./errors";
+
+const SPAWN_DEADLINE_MS = 8_000;
+const SPAWN_POLL_MS = 100;
+
+export type HarnessWindow = {
+  readonly targetId: string;
+  readonly freshlyCreated: boolean;
+};
+
+type PageTarget = {
+  readonly targetId: string;
+  readonly type: string;
+  readonly url: string;
+  readonly browserContextId?: string;
+};
+
+const listPageTargets = async (client: BrowserClient): Promise<Result<ReadonlyArray<PageTarget>, CdpError>> => {
+  const r = await client.session().callBrowser("Target.getTargets");
+  if (!r.success) return r;
+  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);
+};
+
+const spawnTabViaOpener = async (
+  client: BrowserClient,
+  openerTargetId: string,
+): Promise<Result<string, CdpError>> => {
+  const session = await sessionForTarget(client, openerTargetId);
+  if (!session.success) return session;
+
+  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,
+  );
+  if (!opened.success) return opened;
+  if (opened.data.result.value !== true) {
+    return err(cdpError(
+      "invalid_response",
+      "the browser blocked window.open in the pinned profile's window — the page may have navigated away; retry, or run /browser-profile to re-seed",
+      "Runtime.evaluate",
+    ));
+  }
+
+  const deadline = Date.now() + SPAWN_DEADLINE_MS;
+  while (Date.now() < deadline) {
+    const targets = await listPageTargets(client);
+    if (targets.success) {
+      const spawned = targets.data.find((t) => t.url.includes(token));
+      if (spawned) return ok(spawned.targetId);
+    }
+    await new Promise((r) => setTimeout(r, SPAWN_POLL_MS));
+  }
+  return err(cdpError("timeout", `the tab opened in the pinned profile did not report back within ${SPAWN_DEADLINE_MS}ms`));
+};
+
+const inFlight = new WeakMap<BrowserClient, Promise<Result<HarnessWindow, CdpError>>>();
+
+export const ensureHarnessWindow = async (client: BrowserClient): Promise<Result<HarnessWindow, CdpError>> => {
+  const pending = inFlight.get(client);
+  if (pending) {
+    const shared = await pending;
+    // `freshlyCreated` is a claim on the seed tab that only the caller which started the creation may hold, or two callers would drive the same tab.
+    return shared.success ? ok({ targetId: shared.data.targetId, freshlyCreated: false }) : shared;
+  }
+  const attempt = ensureHarnessWindowUncoordinated(client).finally(() => inFlight.delete(client));
+  inFlight.set(client, attempt);
+  return attempt;
+};
+
+const ensureHarnessWindowUncoordinated = async (
+  client: BrowserClient,
+): Promise<Result<HarnessWindow, CdpError>> => {
+  const targets = await listPageTargets(client);
+  if (!targets.success) return targets;
+  const live = new Set(targets.data.map((t) => t.targetId));
+
+  const ownership = client.ownership();
+  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;
+  const inPinnedProfile = (targetId: string): boolean => {
+    if (!pinnedCtx) return true;
+    const info = targets.data.find((t) => t.targetId === targetId);
+    return info?.browserContextId === pinnedCtx;
+  };
+
+  if (canReuse) {
+    const harnessWindow = ownership.harnessWindow();
+    if (harnessWindow && live.has(harnessWindow) && inPinnedProfile(harnessWindow)) {
+      return ok({ targetId: harnessWindow, freshlyCreated: false });
+    }
+    const survivor = ownership.list().find((id) => live.has(id) && inPinnedProfile(id));
+    if (survivor) {
+      ownership.setHarnessWindow(survivor);
+      return ok({ targetId: survivor, freshlyCreated: false });
+    }
+  }
+
+  const seeded = client.profilePin()
+    ? await client.seedPinnedProfileWindow()
+    : await createDedicatedWindow(client);
+  if (!seeded.success) return seeded;
+  return ok({ targetId: seeded.data, freshlyCreated: true });
+};
+
+const createDedicatedWindow = async (client: BrowserClient): Promise<Result<string, CdpError>> => {
+  const created = await client.session().callBrowser("Target.createTarget", { url: "about:blank", newWindow: true });
+  if (!created.success) return created;
+  const { targetId } = created.data;
+  const ownership = client.ownership();
+  ownership.setHarnessWindow(targetId);
+  ownership.add(targetId);
+  const win = await client.session().windowId(targetId);
+  if (win.success) ownership.setHarnessWindowId(win.data);
+  return ok(targetId);
+};
+
+export const openHarnessTab = async (
+  client: BrowserClient,
+  openerTargetId: string,
+): Promise<Result<string, CdpError>> => {
+  const spawned = client.profileContextId()
+    ? await spawnTabViaOpener(client, openerTargetId)
+    : await (async (): Promise<Result<string, CdpError>> => {
+        const created = await client.session().callBrowser("Target.createTarget", {
+          url: "about:blank",
+          openerId: openerTargetId,
+        });
+        if (!created.success) return created;
+        return ok(created.data.targetId);
+      })();
+  if (!spawned.success) return spawned;
+  client.ownership().add(spawned.data);
+  return ok(spawned.data);
+};

package/extensions/browser-harness/cdp/types.ts

@@ -0,0 +1,82 @@
+import type { Result } from "../util/result";
+import { isRecord } from "../util/guards";
+import type { CdpError } from "./errors";
+
+export type CdpEvent = {
+  readonly method: string;
+  readonly params: unknown;
+  readonly sessionId?: string;
+};
+
+export type CdpRawMessage = {
+  readonly id?: number;
+  readonly method?: string;
+  readonly params?: Record<string, unknown>;
+  readonly result?: unknown;
+  readonly error?: { readonly message: string; readonly code?: number };
+  readonly sessionId?: string;
+};
+
+export type DialogInfo = {
+  readonly type: "alert" | "confirm" | "prompt" | "beforeunload";
+  readonly message: string;
+  readonly defaultPrompt?: string;
+};
+
+export type TabInfo = {
+  readonly targetId: string;
+  readonly title: string;
+  readonly url: string;
+  readonly owned?: boolean;
+};
+
+export type PageInfo = {
+  readonly url: string;
+  readonly title: string;
+  readonly width: number;
+  readonly height: number;
+  readonly scrollX: number;
+  readonly scrollY: number;
+  readonly pageWidth: number;
+  readonly pageHeight: number;
+};
+
+export type DaemonStatus = {
+  readonly alive: boolean;
+  readonly sessionId: string | null;
+  readonly namespace: string;
+  readonly remoteBrowserId?: string;
+};
+
+export const isCdpRawMessage = (v: unknown): v is CdpRawMessage => {
+  if (!isRecord(v)) return false;
+  const id = v["id"];
+  if (id !== undefined && typeof id !== "number") return false;
+  const method = v["method"];
+  if (method !== undefined && typeof method !== "string") return false;
+  const sessionId = v["sessionId"];
+  if (sessionId !== undefined && typeof sessionId !== "string") return false;
+  const errVal = v["error"];
+  if (errVal !== undefined) {
+    if (!isRecord(errVal)) return false;
+    if (typeof errVal["message"] !== "string") return false;
+    const code = errVal["code"];
+    if (code !== undefined && typeof code !== "number") return false;
+  }
+  return true;
+};
+
+export const DEFAULT_TIMEOUT_MS = 15_000;
+
+export type CdpTransport = {
+  connect(url: string, opts?: { timeoutMs?: number }): Promise<Result<void, CdpError>>;
+  close(): Promise<void>;
+  request(
+    method: string,
+    params: Record<string, unknown>,
+    opts?: { sessionId?: string | null; timeoutMs?: number },
+  ): Promise<Result<unknown, CdpError>>;
+  events(): AsyncIterable<CdpEvent>;
+  state(): "open" | "closed" | "connecting";
+  onClose(cb: () => void): () => void;
+};

package/extensions/browser-harness/client.ts

@@ -0,0 +1,366 @@
+import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { parseJson } from "./schemas/parse";
+import { type Result, err, ok } from "./util/result";
+import { safeJs } from "./util/js-template";
+import { type Mutex, createMutex } from "./util/mutex";
+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 { 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";
+
+export type BrowserClientOptions = {
+  readonly namespace: string;
+  readonly transport: CdpTransport;
+  readonly remote?: { readonly cdpUrl: string; readonly browserId: string };
+  readonly initialOwnership?: {
+    readonly ownedTargetIds?: ReadonlyArray<string>;
+    readonly harnessWindowTargetId?: string;
+    readonly harnessWindowId?: number;
+  };
+  readonly profilePin?: ProfilePin | null;
+  readonly onOwnershipChange?: (snapshot: {
+    readonly ownedTargetIds: ReadonlyArray<string>;
+    readonly harnessWindowTargetId: string | undefined;
+    readonly harnessWindowId: number | undefined;
+  }) => void;
+};
+
+export type BrowserClient = {
+  readonly namespace: string;
+  ensureAlive(): Promise<Result<void, CdpError>>;
+  status(): DaemonStatus;
+  start(): 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>>;
+  takeDialog(): DialogInfo | null;
+  listTabs(includeInternal?: boolean): Promise<Result<ReadonlyArray<TabInfo>, CdpError>>;
+  switchTab(targetId: string): Promise<Result<void, CdpError>>;
+  newTab(url?: string): Promise<Result<string, CdpError>>;
+  closeTab(targetId: string): Promise<Result<void, CdpError>>;
+  owns(targetId: string): boolean;
+  ownership(): OwnershipRegistry;
+  current(): { readonly sessionId: string; readonly targetId: string } | null;
+  session(): CdpSession;
+  transport(): CdpTransport;
+  userDataDir(): string | undefined;
+  profilePin(): ProfilePin | null;
+  setProfilePin(pin: ProfilePin | null): void;
+  profileContextId(): string | undefined;
+  setProfileContextId(contextId: string | undefined): void;
+  seedPinnedProfileWindow(): Promise<Result<string, CdpError>>;
+  mutationMutex(): Mutex;
+};
+
+const HEALTH_TTL_MS = 30_000;
+const PAGE_INFO_TTL_MS = 1_000;
+
+const PageInfoPayload = Type.Object({
+  url: Type.String(),
+  title: Type.String(),
+  w: Type.Number(),
+  h: Type.Number(),
+  sx: Type.Number(),
+  sy: Type.Number(),
+  pw: Type.Number(),
+  ph: Type.Number(),
+});
+
+const pageInfoValidator = Compile(PageInfoPayload);
+
+const parsePageInfoPayload = (raw: string): Result<PageInfo, CdpError> => {
+  const parsed = parseJson(raw, pageInfoValidator);
+  if (!parsed.success) {
+    return err(cdpError("invalid_response", `page info payload is invalid: ${parsed.error}`));
+  }
+  const o = parsed.data;
+  return ok({
+    url: o.url,
+    title: o.title,
+    width: o.w,
+    height: o.h,
+    scrollX: o.sx,
+    scrollY: o.sy,
+    pageWidth: o.pw,
+    pageHeight: o.ph,
+  });
+};
+
+export const createBrowserClient = (opts: BrowserClientOptions): BrowserClient => {
+  const transport = opts.transport;
+  const ownershipInit: { ownedTargetIds?: ReadonlyArray<string>; harnessWindowTargetId?: string; harnessWindowId?: number } = {};
+  if (opts.initialOwnership?.ownedTargetIds !== undefined) {
+    ownershipInit.ownedTargetIds = opts.initialOwnership.ownedTargetIds;
+  }
+  if (opts.initialOwnership?.harnessWindowTargetId !== undefined) {
+    ownershipInit.harnessWindowTargetId = opts.initialOwnership.harnessWindowTargetId;
+  }
+  if (opts.initialOwnership?.harnessWindowId !== undefined) {
+    ownershipInit.harnessWindowId = opts.initialOwnership.harnessWindowId;
+  }
+  const ownership = createOwnershipRegistry(ownershipInit);
+  if (opts.onOwnershipChange) {
+    const cb = opts.onOwnershipChange;
+    ownership.onChange(() => {
+      cb({
+        ownedTargetIds: ownership.list(),
+        harnessWindowTargetId: ownership.harnessWindow(),
+        harnessWindowId: ownership.harnessWindowId(),
+      });
+    });
+  }
+  const session = createCdpSession(transport, ownership, async () => {
+    const window = await ensureHarnessWindow(api);
+    return window.success ? ok(window.data.targetId) : window;
+  });
+  const mutationMutex = createMutex();
+  let lastHealth = 0;
+  let 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;
+  let profileContextId: string | undefined;
+
+  // With a pin set the window must exist BEFORE anything attaches, or attachFirstPage's bare Target.createTarget lands in the focus-derived default profile.
+  const seedIfPinned = async (): Promise<Result<void, CdpError>> => {
+    if (!profilePin) return ok(undefined);
+    const window = await ensureHarnessWindow(api);
+    if (!window.success) return window;
+    return ok(undefined);
+  };
+
+  const start = async (): Promise<Result<void, CdpError>> => {
+    if (transport.state() === "open" && session.current()) return ok(undefined);
+    let wsUrl: string;
+    if (remote?.cdpUrl) {
+      wsUrl = remote.cdpUrl;
+    } else {
+      const discovered = await discoverEndpoint();
+      if (!discovered.success) return discovered;
+      wsUrl = discovered.data.wsUrl;
+      userDataDir = discovered.data.userDataDir;
+    }
+    const connected = await transport.connect(wsUrl, { timeoutMs: 10_000 });
+    if (!connected.success) return connected;
+
+    const newBrowserId: string = wsUrl.split("/").pop() ?? "unknown";
+    if (!remote || remote.browserId !== newBrowserId) {
+      profileContextId = undefined;
+    }
+    remote = { cdpUrl: wsUrl, browserId: newBrowserId };
+    const seeded = await seedIfPinned();
+    if (!seeded.success) {
+      await transport.close();
+      return seeded;
+    }
+    const attached = await session.attachFirstPage();
+    if (!attached.success) {
+      await transport.close();
+      return attached;
+    }
+    lastHealth = Date.now();
+    pageCaches.clear();
+    return ok(undefined);
+  };
+
+  const stop = async (): Promise<void> => {
+    await transport.close();
+    pageCaches.clear();
+    lastHealth = 0;
+  };
+
+  const ensureAlive = async (): Promise<Result<void, CdpError>> => {
+    if (transport.state() !== "open" || !session.current()) {
+      await stop();
+      return start();
+    }
+    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();
+    }
+    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();
+        return ok(undefined);
+      }
+      await stop();
+      return start();
+    }
+    return ok(undefined);
+  };
+
+  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 });
+    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"));
+    }
+    return ok(r.data.result.value);
+  };
+
+  const readPageInfo = async (): Promise<Result<PageInfo, CdpError>> => {
+    const dirty = session.drainPageInfoInvalidations();
+    const currentTid = session.current()?.targetId;
+    const cached = currentTid ? pageCaches.get(currentTid) : undefined;
+    if (cached && !dirty && Date.now() - cached.at < PAGE_INFO_TTL_MS) return ok(cached.info);
+    const expr = safeJs`JSON.stringify((function(){var e=document.documentElement||{scrollWidth:0,scrollHeight:0};return {url:location.href,title:document.title,w:innerWidth,h:innerHeight,sx:scrollX,sy:scrollY,pw:e.scrollWidth,ph:e.scrollHeight};})())`;
+    const raw = await evaluateJs(expr);
+    if (!raw.success) return raw;
+    if (typeof raw.data !== "string") return err(cdpError("invalid_response", "page info evaluation did not return a string"));
+    const info = parsePageInfoPayload(raw.data);
+    if (!info.success) return info;
+    if (currentTid) pageCaches.set(currentTid, { info: info.data, at: Date.now() });
+    return ok(info.data);
+  };
+
+  const pageInfo = async (): Promise<Result<PageInfo | { readonly dialog: DialogInfo }, CdpError>> => {
+    const d = session.takeDialog();
+    if (d) return ok({ dialog: d });
+    return readPageInfo();
+  };
+
+  const listTabs = async (includeInternal = true): Promise<Result<ReadonlyArray<TabInfo>, CdpError>> => {
+    const r = await session.callBrowser("Target.getTargets");
+    if (!r.success) return r;
+    const tabs = r.data.targetInfos
+      .filter((t) => t.type === "page")
+      .filter((t) => includeInternal || !t.url.startsWith("chrome://"))
+      .map((t): TabInfo => ({
+        targetId: t.targetId,
+        title: t.title,
+        url: t.url,
+        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);
+    for (const tid of pageCaches.keys()) {
+      if (!live.has(tid)) pageCaches.delete(tid);
+    }
+    return ok(tabs);
+  };
+
+  const switchTab = async (targetId: string): Promise<Result<void, CdpError>> => {
+    const r = await session.switchTo(targetId);
+    if (!r.success) return r;
+    await session.call("Runtime.evaluate", {
+      expression: safeJs`if(!document.title.startsWith('🟢'))document.title='🟢 '+document.title`,
+    });
+    return ok(undefined);
+  };
+
+  const newTab = async (url?: string): Promise<Result<string, CdpError>> => {
+    const tabsResult = await listTabs(true);
+    if (!tabsResult.success) return tabsResult;
+
+    const window = await ensureHarnessWindow(api);
+    if (!window.success) return window;
+    let tabId: string;
+    if (window.data.freshlyCreated) {
+      tabId = window.data.targetId;
+    } else {
+      const opened = await openHarnessTab(api, window.data.targetId);
+      if (!opened.success) return opened;
+      tabId = opened.data;
+    }
+
+    const switched = await switchTab(tabId);
+    if (!switched.success) return switched;
+    if (url && url !== "about:blank") {
+      const nav = await session.call("Page.navigate", { url });
+      if (!nav.success) return nav;
+    }
+    return ok(tabId);
+  };
+
+  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);
+  };
+
+  const closeOwnedTabs = async (): Promise<void> => {
+    for (const id of ownership.list()) {
+      await session.callBrowser("Target.closeTarget", { targetId: id }).catch(() => {});
+      ownership.remove(id);
+    }
+    ownership.setHarnessWindow(undefined);
+    ownership.setHarnessWindowId(undefined);
+  };
+
+  const status = (): DaemonStatus => ({
+    alive: transport.state() === "open" && session.current() !== null,
+    sessionId: session.current()?.sessionId ?? null,
+    namespace: opts.namespace,
+    ...(remote?.browserId !== undefined ? { remoteBrowserId: remote.browserId } : {}),
+  });
+
+  const detach = async (): Promise<void> => {
+    const cur = session.current();
+    if (!cur) return;
+    await transport.request("Target.detachFromTarget", { sessionId: cur.sessionId }, { sessionId: null });
+  };
+
+  const api: BrowserClient = {
+    namespace: opts.namespace,
+    ensureAlive, status, start, stop, detach, closeOwnedTabs,
+    evaluateJs, pageInfo,
+    takeDialog: () => session.takeDialog(),
+    listTabs, switchTab, newTab, closeTab,
+    owns: (id: string) => ownership.has(id),
+    ownership: () => ownership,
+    current: () => session.current(),
+    session: () => session,
+    transport: () => transport,
+    userDataDir: () => userDataDir,
+    profilePin: () => profilePin,
+    setProfilePin: (pin) => {
+      const changed = pin === null
+        ? profilePin !== null
+        : profilePin === null || profilePin.userDataDir !== pin.userDataDir || profilePin.profileDir !== pin.profileDir;
+      profilePin = pin;
+      if (changed) {
+        profileContextId = undefined;
+      }
+    },
+    profileContextId: () => profileContextId,
+    setProfileContextId: (contextId) => {
+      profileContextId = contextId;
+    },
+    seedPinnedProfileWindow: async () => {
+      if (!profilePin) {
+        return err(cdpError("discovery_failed", "no browser profile is selected — run /browser-profile"));
+      }
+      return seedProfileWindow(api, profilePin);
+    },
+    mutationMutex: () => mutationMutex,
+  };
+  return api;
+};