@omercnet/paseo-shared-browser 0.3.1-next.72.1

package/server/browser.ts

@@ -0,0 +1,306 @@
+import type { RpcInput, RpcOutput } from "@getpaseo/plugin";
+import type { PluginHandlerContext } from "@getpaseo/plugin/server";
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+  acquireControlRpc,
+  applyDevicePresetRpc,
+  attachBrowserRpc,
+  captureBrowserRpc,
+  detachBrowserRpc,
+  listOpenBrowserWorkspacesRpc,
+  navigateBrowserRpc,
+  releaseControlRpc,
+  resizeBrowserRpc,
+  sendBrowserInputRpc,
+} from "../shared/browser";
+import type { JsonValue } from "./runtime-protocol";
+import { SupervisorClient } from "./supervisor-client";
+import { resolveSupervisorPaths } from "./supervisor";
+
+export { SessionManager, normalizeBrowserUrl } from "./browser-policy";
+export type {
+  BrowserRuntimeClient,
+  SessionManagerOptions,
+  WorkspaceValidator,
+} from "./browser-policy";
+
+type AttachInput = RpcInput<typeof attachBrowserRpc>;
+type AttachOutput = RpcOutput<typeof attachBrowserRpc>;
+type DetachInput = RpcInput<typeof detachBrowserRpc>;
+type DetachOutput = RpcOutput<typeof detachBrowserRpc>;
+type CaptureInput = RpcInput<typeof captureBrowserRpc>;
+type CaptureOutput = RpcOutput<typeof captureBrowserRpc>;
+type AcquireControlInput = RpcInput<typeof acquireControlRpc>;
+type AcquireControlOutput = RpcOutput<typeof acquireControlRpc>;
+type ReleaseControlInput = RpcInput<typeof releaseControlRpc>;
+type ReleaseControlOutput = RpcOutput<typeof releaseControlRpc>;
+type ListOpenOutput = RpcOutput<typeof listOpenBrowserWorkspacesRpc>;
+type NavigateInput = RpcInput<typeof navigateBrowserRpc>;
+type NavigateOutput = RpcOutput<typeof navigateBrowserRpc>;
+type ResizeInput = RpcInput<typeof resizeBrowserRpc>;
+type ResizeOutput = RpcOutput<typeof resizeBrowserRpc>;
+type ApplyDevicePresetInput = RpcInput<typeof applyDevicePresetRpc>;
+type ApplyDevicePresetOutput = RpcOutput<typeof applyDevicePresetRpc>;
+type SendInput = RpcInput<typeof sendBrowserInputRpc>;
+type SendOutput = RpcOutput<typeof sendBrowserInputRpc>;
+
+function paseoHome(): string {
+  return process.env.PASEO_HOME ?? join(homedir(), ".paseo");
+}
+
+class RemoteBrowserManager {
+  constructor(private readonly client: SupervisorClient) {}
+
+  async connect(): Promise<void> {
+    await this.client.connect();
+  }
+
+  attach(workspaceId: string, viewerLabel: string): Promise<AttachOutput> {
+    return this.client.requestBrowser<AttachOutput>("attach", { workspaceId, viewerLabel });
+  }
+
+  detach(viewerToken: string): Promise<DetachOutput> {
+    return this.client.requestBrowser<DetachOutput>("detach", { viewerToken });
+  }
+
+  capture(
+    viewerToken: string,
+    quality: CaptureInput["quality"],
+    knownFrameId: string | null,
+  ): Promise<CaptureOutput> {
+    return this.client.requestBrowser<CaptureOutput>("capture", {
+      viewerToken,
+      quality,
+      knownFrameId,
+    });
+  }
+
+  acquireControl(viewerToken: string, takeover: boolean): Promise<AcquireControlOutput> {
+    return this.client.requestBrowser<AcquireControlOutput>("acquire-control", {
+      viewerToken,
+      takeover,
+    });
+  }
+
+  releaseControl(viewerToken: string, controlToken: string): Promise<ReleaseControlOutput> {
+    return this.client.requestBrowser<ReleaseControlOutput>("release-control", {
+      viewerToken,
+      controlToken,
+    });
+  }
+
+  navigate(input: NavigateInput): Promise<NavigateOutput> {
+    return this.client.requestBrowser<NavigateOutput>("navigate", input as unknown as JsonValue);
+  }
+
+  resize(input: ResizeInput): Promise<ResizeOutput> {
+    return this.client.requestBrowser<ResizeOutput>("viewport", input as unknown as JsonValue);
+  }
+
+  applyDevicePreset(input: ApplyDevicePresetInput): Promise<ApplyDevicePresetOutput> {
+    return this.client.requestBrowser<ApplyDevicePresetOutput>(
+      "device",
+      input as unknown as JsonValue,
+    );
+  }
+
+  sendInput(input: SendInput): Promise<SendOutput> {
+    return this.client.requestBrowser<SendOutput>("input", input as unknown as JsonValue);
+  }
+
+  async listOpenWorkspaceIds(): Promise<string[]> {
+    const result = await this.client.requestBrowser("list", {});
+    if (
+      !result ||
+      typeof result !== "object" ||
+      Array.isArray(result) ||
+      !("workspaceIds" in result)
+    )
+      throw new Error("Supervisor returned an invalid workspace list");
+    const workspaceIds = result.workspaceIds;
+    if (
+      !Array.isArray(workspaceIds) ||
+      !workspaceIds.every((value): value is string => typeof value === "string")
+    )
+      throw new Error("Supervisor returned an invalid workspace list");
+    return workspaceIds;
+  }
+
+  async archiveWorkspace(workspaceId: string): Promise<void> {
+    await this.client.requestBrowser("archive", { workspaceId });
+  }
+
+  issueAgentTicket(ticket: string): Promise<void> {
+    return this.client.issueAgentTicket(ticket);
+  }
+
+  bindAgentTicket(ticket: string, agentId: string, workspaceId: string): Promise<void> {
+    return this.client.bindAgentTicket(ticket, agentId, workspaceId);
+  }
+
+  revokeAgent(agentId: string): Promise<void> {
+    return this.client.revokeAgent(agentId);
+  }
+
+  disconnect(): void {
+    this.client.disconnect();
+  }
+}
+
+let productionManager: RemoteBrowserManager | null = null;
+let productionStart: Promise<RemoteBrowserManager> | null = null;
+let productionStopped = false;
+
+async function launchSupervisor(): Promise<void> {
+  const supervisorPath = join(
+    paseoHome(),
+    "plugin-data",
+    "shared-browser",
+    "runtime",
+    "supervisor.cjs",
+  );
+  try {
+    await access(supervisorPath);
+  } catch {
+    throw new Error(`Shared Browser supervisor runtime is missing: ${supervisorPath}`);
+  }
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(process.execPath, [supervisorPath], {
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env, PASEO_HOME: paseoHome() },
+    });
+    child.once("spawn", () => {
+      child.unref();
+      resolve();
+    });
+    child.once("error", reject);
+  });
+}
+
+async function getProductionManager(): Promise<RemoteBrowserManager> {
+  if (productionStopped) throw new Error("Shared Browser plugin is stopping");
+  if (productionManager) return productionManager;
+  productionStart ??= (async () => {
+    const manager = new RemoteBrowserManager(
+      new SupervisorClient({ bridgeId: randomUUID(), paths: resolveSupervisorPaths(paseoHome()) }),
+    );
+    try {
+      await manager.connect();
+    } catch {
+      await launchSupervisor();
+      let lastError: unknown;
+      for (let attempt = 0; attempt < 50; attempt += 1) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        try {
+          await manager.connect();
+          lastError = undefined;
+          break;
+        } catch (error) {
+          lastError = error;
+        }
+      }
+      if (lastError) throw lastError;
+    }
+    if (productionStopped) {
+      manager.disconnect();
+      throw new Error("Shared Browser plugin is stopping");
+    }
+    productionManager = manager;
+    return manager;
+  })();
+  try {
+    return await productionStart;
+  } finally {
+    productionStart = null;
+  }
+}
+
+export async function issueAgentTicket(ticket: string): Promise<void> {
+  await (await getProductionManager()).issueAgentTicket(ticket);
+}
+
+export async function bindAgentTicket(
+  ticket: string,
+  agentId: string,
+  workspaceId: string,
+): Promise<void> {
+  await (await getProductionManager()).bindAgentTicket(ticket, agentId, workspaceId);
+}
+
+export async function revokeAgentBrowserAccess(agentId: string): Promise<void> {
+  await (await getProductionManager()).revokeAgent(agentId);
+}
+
+export async function handleAttachBrowser(
+  input: AttachInput,
+  context: PluginHandlerContext,
+): Promise<AttachOutput> {
+  const workspace = await context.paseo.workspaces.ref(input.workspaceId).refresh();
+  if (!workspace) throw new Error("Workspace not found");
+  return (await getProductionManager()).attach(input.workspaceId, input.viewerLabel);
+}
+
+export async function handleDetachBrowser({ viewerToken }: DetachInput): Promise<DetachOutput> {
+  return (await getProductionManager()).detach(viewerToken);
+}
+
+export async function handleWorkspaceArchived(workspaceId: string): Promise<void> {
+  if (productionStopped) return;
+  await (await getProductionManager()).archiveWorkspace(workspaceId);
+}
+
+export async function handleListOpenBrowserWorkspaces(): Promise<ListOpenOutput> {
+  return { workspaceIds: await (await getProductionManager()).listOpenWorkspaceIds() };
+}
+
+export async function handleCaptureBrowser({
+  viewerToken,
+  quality,
+  knownFrameId,
+}: CaptureInput): Promise<CaptureOutput> {
+  return (await getProductionManager()).capture(viewerToken, quality, knownFrameId);
+}
+
+export async function handleAcquireControl({
+  viewerToken,
+  takeover,
+}: AcquireControlInput): Promise<AcquireControlOutput> {
+  return (await getProductionManager()).acquireControl(viewerToken, takeover);
+}
+
+export async function handleReleaseControl({
+  viewerToken,
+  controlToken,
+}: ReleaseControlInput): Promise<ReleaseControlOutput> {
+  return (await getProductionManager()).releaseControl(viewerToken, controlToken);
+}
+
+export async function handleNavigateBrowser(input: NavigateInput): Promise<NavigateOutput> {
+  return (await getProductionManager()).navigate(input);
+}
+
+export async function handleResizeBrowser(input: ResizeInput): Promise<ResizeOutput> {
+  return (await getProductionManager()).resize(input);
+}
+
+export async function handleApplyDevicePreset(
+  input: ApplyDevicePresetInput,
+): Promise<ApplyDevicePresetOutput> {
+  return (await getProductionManager()).applyDevicePreset(input);
+}
+
+export async function handleSendBrowserInput(input: SendInput): Promise<SendOutput> {
+  return (await getProductionManager()).sendInput(input);
+}
+
+export async function cleanupBrowserServer(): Promise<void> {
+  productionStopped = true;
+  if (productionStart) await productionStart.catch(() => undefined);
+  productionManager?.disconnect();
+  productionManager = null;
+}

package/server/cdp.ts

@@ -0,0 +1,265 @@
+import { EventEmitter } from "node:events";
+
+export class CdpUnavailableError extends Error {
+  override readonly name = "CdpUnavailableError";
+}
+
+export class CdpUnknownOutcomeError extends Error {
+  override readonly name = "CdpUnknownOutcomeError";
+}
+
+export interface CdpEvent<T = unknown> {
+  method: string;
+  params: T;
+  sessionId?: string;
+}
+
+interface PendingCommand {
+  readonly method: string;
+  readonly mutation: boolean;
+  readonly resolve: (value: unknown) => void;
+  readonly reject: (reason: unknown) => void;
+  timer: NodeJS.Timeout;
+}
+
+interface CdpMessage {
+  id?: number;
+  method?: string;
+  params?: unknown;
+  result?: unknown;
+  error?: { code?: number; message?: string; data?: unknown };
+  sessionId?: string;
+}
+
+interface WebSocketLike {
+  readonly readyState: number;
+  binaryType: string;
+  onopen: (() => void) | null;
+  onerror: ((event: unknown) => void) | null;
+  onclose: ((event: { code?: number; reason?: string }) => void) | null;
+  onmessage: ((event: { data: string | ArrayBuffer | Blob }) => void) | null;
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+}
+
+type WebSocketConstructor = new (url: string) => WebSocketLike;
+
+export interface CdpConnectionOptions {
+  commandTimeoutMs?: number;
+  connectTimeoutMs?: number;
+  webSocket?: WebSocketConstructor;
+}
+
+export class CdpConnection extends EventEmitter {
+  private readonly socket: WebSocketLike;
+  private readonly commandTimeoutMs: number;
+  private readonly pending = new Map<number, PendingCommand>();
+  private nextId = 1;
+  private closed = false;
+
+  private constructor(socket: WebSocketLike, commandTimeoutMs: number) {
+    super();
+    this.socket = socket;
+    this.commandTimeoutMs = commandTimeoutMs;
+    socket.onmessage = (event) => void this.receive(event.data);
+    socket.onclose = (event) =>
+      this.disconnect(event.reason || `WebSocket closed (${event.code ?? 0})`);
+    socket.onerror = () => this.disconnect("CDP WebSocket failed");
+  }
+
+  static connect(url: string, options: CdpConnectionOptions = {}): Promise<CdpConnection> {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") {
+      throw new CdpUnavailableError("CDP endpoint must use ws or wss");
+    }
+    const WebSocketImpl =
+      options.webSocket ??
+      (globalThis as typeof globalThis & { WebSocket?: WebSocketConstructor }).WebSocket;
+    if (!WebSocketImpl) throw new CdpUnavailableError("This runtime does not provide WebSocket");
+    const socket = new WebSocketImpl(parsed.href);
+    socket.binaryType = "arraybuffer";
+    const timeoutMs = options.connectTimeoutMs ?? 10_000;
+    const { promise, resolve, reject } = Promise.withResolvers<CdpConnection>();
+    const timer = setTimeout(() => {
+      socket.close();
+      reject(new CdpUnavailableError(`CDP connection timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    socket.onopen = () => {
+      clearTimeout(timer);
+      resolve(new CdpConnection(socket, options.commandTimeoutMs ?? 15_000));
+    };
+    socket.onerror = () => {
+      clearTimeout(timer);
+      reject(new CdpUnavailableError("Could not connect to CDP endpoint"));
+    };
+    return promise;
+  }
+
+  get isOpen(): boolean {
+    return !this.closed && this.socket.readyState === 1;
+  }
+
+  async send<T = unknown>(
+    method: string,
+    params: Record<string, unknown> = {},
+    options: { sessionId?: string; mutation?: boolean; timeoutMs?: number } = {},
+  ): Promise<T> {
+    if (!this.isOpen) throw new CdpUnavailableError("CDP connection is closed");
+    const id = this.nextId++;
+    const mutation = options.mutation ?? false;
+    const timeoutMs = options.timeoutMs ?? this.commandTimeoutMs;
+    const message: Record<string, unknown> = { id, method, params };
+    if (options.sessionId) message.sessionId = options.sessionId;
+    const { promise, resolve, reject } = Promise.withResolvers<T>();
+    const timer = setTimeout(() => {
+      this.pending.delete(id);
+      reject(
+        mutation
+          ? new CdpUnknownOutcomeError(`${method} timed out; mutation outcome is unknown`)
+          : new CdpUnavailableError(`${method} timed out after ${timeoutMs}ms`),
+      );
+    }, timeoutMs);
+    this.pending.set(id, {
+      method,
+      mutation,
+      timer,
+      resolve: resolve as (value: unknown) => void,
+      reject,
+    });
+    try {
+      this.socket.send(JSON.stringify(message));
+    } catch (error) {
+      clearTimeout(timer);
+      this.pending.delete(id);
+      reject(
+        mutation
+          ? new CdpUnknownOutcomeError(`${method} send failed; mutation outcome is unknown`)
+          : error,
+      );
+    }
+    return promise;
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.socket.close(1000, "client shutdown");
+    this.rejectPending("CDP connection closed");
+  }
+
+  private async receive(data: string | ArrayBuffer | Blob): Promise<void> {
+    try {
+      const text =
+        typeof data === "string"
+          ? data
+          : data instanceof ArrayBuffer
+            ? Buffer.from(data).toString("utf8")
+            : await data.text();
+      const message = JSON.parse(text) as CdpMessage;
+      if (message.id !== undefined) {
+        const pending = this.pending.get(message.id);
+        if (!pending) return;
+        clearTimeout(pending.timer);
+        this.pending.delete(message.id);
+        if (message.error) {
+          pending.reject(
+            new Error(
+              `CDP ${pending.method} failed${message.error.code === undefined ? "" : ` (${message.error.code})`}: ${message.error.message ?? "unknown error"}`,
+            ),
+          );
+        } else {
+          pending.resolve(message.result);
+        }
+        return;
+      }
+      if (message.method) {
+        const event: CdpEvent = { method: message.method, params: message.params ?? {} };
+        if (message.sessionId) event.sessionId = message.sessionId;
+        this.emit("event", event);
+        this.emit(message.method, event.params, event.sessionId);
+      }
+    } catch (error) {
+      this.disconnect(
+        `Invalid CDP message: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  private disconnect(message: string): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.rejectPending(message);
+    this.emit("disconnect", new CdpUnavailableError(message));
+  }
+
+  private rejectPending(message: string): void {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(
+        pending.mutation
+          ? new CdpUnknownOutcomeError(`${pending.method} interrupted; mutation outcome is unknown`)
+          : new CdpUnavailableError(message),
+      );
+    }
+    this.pending.clear();
+  }
+}
+
+export class CdpSession extends EventEmitter {
+  constructor(
+    readonly connection: CdpConnection,
+    readonly sessionId: string,
+    readonly targetId: string,
+  ) {
+    super();
+    connection.on("event", this.forwardEvent);
+  }
+
+  send<T = unknown>(
+    method: string,
+    params: Record<string, unknown> = {},
+    options: { mutation?: boolean; timeoutMs?: number } = {},
+  ): Promise<T> {
+    return this.connection.send<T>(method, params, { ...options, sessionId: this.sessionId });
+  }
+
+  detach(): Promise<void> {
+    this.connection.off("event", this.forwardEvent);
+    return this.connection.send(
+      "Target.detachFromTarget",
+      { sessionId: this.sessionId },
+      { mutation: true },
+    );
+  }
+
+  private readonly forwardEvent = (event: CdpEvent): void => {
+    if (event.sessionId !== this.sessionId) return;
+    this.emit("event", event);
+    this.emit(event.method, event.params);
+  };
+}
+
+export interface CdpTarget {
+  targetId: string;
+  type: string;
+  title: string;
+  url: string;
+  attached: boolean;
+}
+
+export async function listPageTargets(connection: CdpConnection): Promise<CdpTarget[]> {
+  const result = await connection.send<{ targetInfos: CdpTarget[] }>("Target.getTargets");
+  return result.targetInfos.filter((target) => target.type === "page");
+}
+
+export async function attachToTarget(
+  connection: CdpConnection,
+  targetId: string,
+): Promise<CdpSession> {
+  const result = await connection.send<{ sessionId: string }>(
+    "Target.attachToTarget",
+    { targetId, flatten: true },
+    { mutation: true },
+  );
+  return new CdpSession(connection, result.sessionId, targetId);
+}

package/server/electron.d.ts

@@ -0,0 +1 @@
+declare module "electron" {}