feat: add browser provider to connect to a remote chrome instance

[pasdam]

This adds a new browser provider to allow the user to connect to a remote chrome instance. Helpful in cases where you want to connect for instance to a playwright instance running in docker.

Example

Compose file:

services:
  # The Browser Instance
  playwright-server:
    image: mcr.microsoft.com/playwright:v1.57.0-noble
    command: /bin/sh -c "npx -y playwright@1.57.0 run-server --port 3000 --host 0.0.0.0"
    environment:
      - DEBUG=pw:api,pw:browser*
    ports:
      - "3000:3000"
    shm_size: "2gb"

  hyper-agent-runner:
    build: .
    environment:
      - BROWSER_WS_ENDPOINT=ws://playwright-server:3000
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./index.ts:/app/index.ts
    depends_on:
      - playwright-server

Typescript client:

import { chromium, Browser, Page } from "playwright-core";
import { HyperAgent } from "@hyperbrowser/agent";

async function runRemoteAgent() {
  const wsEndpoint = process.env.BROWSER_WS_ENDPOINT;

  console.log("--- Initializing HyperAgent Connection ---");
  // 2. Initialize HyperAgent
  const agent = new HyperAgent({
    llm: { provider: "openai", model: "gpt-5-mini" },
    browserProvider: "RemoteChrome",
    remoteChromeConfig: {
      wsEndpoint: wsEndpoint!,
    },
    debug: true,
  });

  console.log("Starting AI Task...");

  try {
    const result = await agent.executeTask("Go to news.ycombinator.com and give me the top story.");
    console.log("✅ Task Completed Successfully!");
    console.log(result.output);

  } catch (error: any) {
    // 4. Catch and Log Errors
    console.error("❌ Agent Execution Failed!");

    // Detailed error logging
    if (error.message.includes("ECONNREFUSED")) {
      console.error("DEBUG: Could not reach the Docker container. Is it running on the correct port?");
    } else if (error.message.includes("401") || error.message.includes("API key")) {
      console.error("DEBUG: Authentication error. Check your HYPERBROWSER_API_KEY or OPENAI_API_KEY");
    } else {
      console.error("STACK TRACE:", error);
    }

  } finally {
    console.log("--- Cleaning Up Resources ---");
    await agent.closeAgent();
    console.log("Session ended.");
  }
}

runRemoteAgent()