Skip to content

Open-source AI browser agent for Chrome and Firefox (monorepo) 🧠

13.7 KB
Raw Blame
import assert from "node:assert/strict";
import { createHmac } from "node:crypto";
import { once } from "node:events";
import { createServer } from "node:net";
import { after, before, test } from "node:test";
import WebSocket from "ws";

import {
  browserAbort,
  browserRespond,
  browserStatus,
  browserTask,
} from "../dist/tools/browserTask.js";
import { main } from "../dist/index.js";
import { BridgeClient, sharedBridge } from "../dist/util/bridgeClient.js";
import { pairingProof } from "../dist/util/pairing.js";

const PAIRING_KEY = "lmstudio-test-pairing-key-0123456789";
let socket;
let toolsProvider;
const received = [];

/** Computed independently of dist/util/pairing.js so a drift in either side fails here. */
function proofFor(key, nonce) {
  return createHmac("sha256", key).update(`webbrain-bridge-pairing-v1:${nonce}`).digest("hex");
}

/** Answer the bridge's pairing challenge the way the extension does. */
function answerPairing(ws, key = PAIRING_KEY) {
  ws.on("message", (raw) => {
    const message = JSON.parse(raw.toString());
    if (message.type === "pairing_challenge" || message.type === "auth_challenge") {
      ws.send(JSON.stringify({ type: "pairing_proof", scheme: message.scheme, proof: proofFor(key, message.nonce) }));
    }
  });
}

async function freePort() {
  const server = createServer();
  server.listen(0, "127.0.0.1");
  await once(server, "listening");
  const address = server.address();
  const port = typeof address === "object" && address ? address.port : 0;
  server.close();
  await once(server, "close");
  return port;
}

function reply(message, result) {
  socket.send(JSON.stringify({ id: message.id, ok: true, result }));
}

before(async () => {
  process.env.WEBBRAIN_BRIDGE_PORT = String(await freePort());
  process.env.WEBBRAIN_COMMAND_TIMEOUT_MS = "50";
  process.env.WEBBRAIN_BRIDGE_KEY = PAIRING_KEY;
  const context = {
    withConfigSchematics() {
      return context;
    },
    withToolsProvider(provider) {
      toolsProvider = provider;
      return context;
    },
  };
  await main(context);

  const bridge = sharedBridge();

  socket = new WebSocket(bridge.url);
  answerPairing(socket);
  socket.on("message", (raw) => {
    const message = JSON.parse(raw.toString());
    if (!message.action) return;
    received.push(message);

    if (message.action === "cloud_run") {
      if (message.payload.task === "disconnect initial response") {
        socket.terminate();
        return;
      }
      if (message.payload.task === "unsupported prompt") {
        reply(message, {
          runId: "unsupported-run",
          status: "needs_user_input",
          pendingInput: { promptKind: "futureGate", question: "Choose.", clarifyId: "future-1" },
        });
        return;
      }
      if (message.payload.task === "legacy prompt") {
        reply(message, {
          runId: "legacy-run",
          status: "needs_user_input",
          pendingInput: {
            permission: { capability: "send_message", host: "example.com" },
            question: "Allow it?",
            clarifyId: "legacy-1",
            options: ["once", "always", "deny"],
          },
        });
        return;
      }
      if (message.payload.task === "stall initial response") return;
      if (message.payload.task === "stall status response") {
        reply(message, { runId: "stalled-run", status: "running" });
        return;
      }
      reply(message, {
        runId: "clarify-run",
        status: "needs_user_input",
        pendingInput: { promptKind: "clarify", question: "Which account?", clarifyId: "clarify-1" },
      });
      return;
    }
    if (message.action === "cloud_respond") {
      reply(message, { runId: message.payload.runId, status: "running" });
      return;
    }
    if (message.action === "cloud_abort") {
      reply(message, {
        runId: message.payload.runId,
        status: "aborted",
        error: "Abort requested.",
      });
      return;
    }
    if (message.action === "cloud_status") {
      if (message.payload.runId === "stalled-run") return;
      reply(message, {
        runId: message.payload.runId,
        status: "completed",
        result: `result for ${message.payload.runId}`,
      });
    }
  });
  await once(socket, "open");
  socket.send(JSON.stringify({ type: "hello", client: "webbrain-extension" }));
  assert.equal(await bridge.waitForExtension(3_000), true);
});

after(async () => {
  if (socket?.readyState === WebSocket.OPEN) {
    socket.close();
    await once(socket, "close");
  }
  await sharedBridge().stop();
});

test("plugin initialization starts the bridge and registers browser recovery tools", async () => {
  assert.equal(typeof toolsProvider, "function");
  const tools = await toolsProvider();
  const names = tools.map((registeredTool) => registeredTool.name);
  assert.ok(names.includes("browser_status"));
  assert.ok(names.includes("browser_respond"));
  assert.ok(names.includes("browser_abort"));
  assert.equal(sharedBridge().isConnected(), true);
});

test("browser_status polls an existing run and returns its result", async () => {
  const result = await browserStatus("finished-run");
  assert.equal(result.ok, true);
  assert.equal(result.runId, "finished-run");
  assert.equal(result.status, "completed");
  assert.equal(result.text, "result for finished-run");
});

test("browser_task tells the model how to answer a paused run", async () => {
  const result = await browserTask({ task: "Open the requested account", timeout: 5_000 });
  assert.equal(result.needsUserInput, true);
  assert.equal(result.runId, "clarify-run");
  assert.equal(result.clarifyId, "clarify-1");
  assert.match(result.hint, /browser_respond/);
});

test("browser_task rejects an unknown prompt kind instead of treating it as free text", async () => {
  const result = await browserTask({ task: "unsupported prompt", timeout: 5_000 });
  assert.equal(result.needsUserInput, true);
  assert.equal(result.promptKind, "futureGate");
  assert.match(result.error, /unsupported prompt kind/);
  assert.match(result.hint, /Do not send a free-form answer/);
});

test("browser_task still relays a prompt from an extension older than promptKind", async () => {
  const result = await browserTask({ task: "legacy prompt", timeout: 5_000 });
  assert.equal(result.needsUserInput, true);
  assert.equal(result.promptKind, "permission");
  assert.equal(result.question, "Allow it?");
  assert.equal(result.clarifyId, "legacy-1");
  assert.deepEqual(result.options, ["once", "always", "deny"]);
  assert.equal(result.error, undefined);
});

test("browser_task rejects API mutation permission in ask mode before dispatch", async () => {
  const before = received.filter((message) => message.action === "cloud_run").length;
  const result = await browserTask({
    task: "read the page",
    mode: "ask",
    allowApiMutations: true,
  });

  assert.equal(result.ok, false);
  assert.match(result.error, /requires mode 'act'/);
  const after = received.filter((message) => message.action === "cloud_run").length;
  assert.equal(after, before);
});

test("browser_respond forwards IDs and the user's answer, then returns completion", async () => {
  const result = await browserRespond({
    runId: "clarify-run",
    clarifyId: "clarify-1",
    answer: "The work account",
    timeout: 5_000,
  });

  assert.equal(result.ok, true);
  assert.equal(result.text, "result for clarify-run");
  const response = received.find((message) => message.action === "cloud_respond");
  assert.deepEqual(response.payload, {
    runId: "clarify-run",
    clarifyId: "clarify-1",
    answer: "The work account",
  });
});

test("browser_task bounds a stalled status request by its run timeout", async () => {
  const startedAt = Date.now();
  const result = await browserTask({ task: "stall status response", timeout: 5_000 });
  const elapsedMs = Date.now() - startedAt;

  assert.equal(result.stillRunning, true);
  assert.equal(result.runId, "stalled-run");
  assert.ok(elapsedMs < 1_500, `command timeout lost the run for ${elapsedMs}ms`);
});

test("browser_task honors a timeout below five seconds", async () => {
  const statusRequestsBefore = received.filter(
    (message) => message.action === "cloud_status" && message.payload.runId === "stalled-run",
  ).length;
  const startedAt = Date.now();
  const result = await browserTask({ task: "stall status response", timeout: 100 });
  const elapsedMs = Date.now() - startedAt;

  assert.equal(result.stillRunning, true);
  assert.equal(result.runId, "stalled-run");
  const statusRequestsAfter = received.filter(
    (message) => message.action === "cloud_status" && message.payload.runId === "stalled-run",
  ).length;
  assert.equal(statusRequestsAfter, statusRequestsBefore + 1);
  assert.ok(elapsedMs < 500, `100ms timeout was stretched to ${elapsedMs}ms`);
});

test("browser_task preserves its generated run ID when the initial response stalls", async () => {
  const startedAt = Date.now();
  const result = await browserTask({ task: "stall initial response", timeout: 5_000 });
  const elapsedMs = Date.now() - startedAt;

  assert.equal(result.stillRunning, true);
  assert.match(result.runId, /^lm_/);
  const request = received.find(
    (message) =>
      message.action === "cloud_run" && message.payload.task === "stall initial response",
  );
  assert.equal(request.payload.runId, result.runId);
  assert.ok(elapsedMs < 500, `initial command timeout took ${elapsedMs}ms`);
});

test("browser_abort forwards the continuing run ID", async () => {
  const result = await browserAbort("stalled-run");
  assert.equal(result.runId, "stalled-run");
  assert.equal(result.status, "aborted");

  const abort = received.find((message) => message.action === "cloud_abort");
  assert.deepEqual(abort.payload, { runId: "stalled-run" });
});

test("a web-page origin cannot replace the connected extension", async () => {
  const page = new WebSocket(sharedBridge().url, {
    headers: { Origin: "https://attacker.example" },
  });
  let receivedCommands = 0;
  page.on("message", () => {
    receivedCommands += 1;
  });
  await once(page, "close");

  assert.equal(sharedBridge().isConnected(), true);
  const result = await browserStatus("origin-safe-run");
  assert.equal(result.ok, true);
  assert.equal(result.runId, "origin-safe-run");
  assert.equal(receivedCommands, 0);
});

test("a local process with a forged hello cannot replace the paired extension", async () => {
  for (const key of [null, "a-guessed-pairing-key-000000"]) {
    const rogue = new WebSocket(sharedBridge().url);
    const closed = once(rogue, "close");
    const frames = [];
    rogue.on("message", (raw) => frames.push(JSON.parse(raw.toString())));
    if (key) answerPairing(rogue, key);
    await once(rogue, "open");
    rogue.send(JSON.stringify({ type: "hello", client: "webbrain-extension" }));
    await new Promise((resolve) => setTimeout(resolve, 30));

    assert.equal(sharedBridge().isConnected(), true, "an unpaired hello displaced the extension");
    const result = await browserStatus("still-private-run");
    assert.equal(result.ok, true);
    assert.equal(result.runId, "still-private-run");
    assert.deepEqual(frames.map((frame) => frame.type), ["pairing_challenge"]);

    if (key) {
      const [code, reason] = await closed;
      assert.equal(code, 4001);
      assert.equal(reason.toString(), "Pairing key mismatch");
    } else {
      rogue.close();
      await closed;
    }
  }
});

test("the pairing proof matches the vector the MCP server and extension tests check", () => {
  assert.equal(
    pairingProof("webbrain-pairing-test-vector-key", "fixed-nonce-for-cross-checks"),
    "5d2a446bcc1734f26d8b94e20d3329a07fb2513aa6d036f47f687065d33c55da",
  );
});

test("a pairing key shorter than 16 characters keeps the listener closed", async () => {
  const bridge = new BridgeClient({ port: await freePort(), pairingKey: "short" });
  await assert.rejects(() => bridge.ensureStarted(), /at least 16 characters/);
  await bridge.stop();
});

test("browser_task preserves its generated run ID when the start socket disconnects", async () => {
  const result = await browserTask({ task: "disconnect initial response", timeout: 5_000 });

  assert.equal(result.stillRunning, true);
  assert.match(result.runId, /^lm_/);
  const request = received.find(
    (message) =>
      message.action === "cloud_run" && message.payload.task === "disconnect initial response",
  );
  assert.equal(request.payload.runId, result.runId);
});

test("an unpaired socket receives no commands while no extension is connected", async () => {
  const rogue = new WebSocket(sharedBridge().url);
  let receivedCommands = 0;
  rogue.on("message", (raw) => {
    if (JSON.parse(raw.toString()).action) receivedCommands += 1;
  });
  await once(rogue, "open");
  await new Promise((resolve) => setTimeout(resolve, 20));

  assert.equal(sharedBridge().isConnected(), false);
  const taskStartedAt = Date.now();
  const task = await browserTask({ task: "wait for extension", timeout: 100 });
  const taskElapsedMs = Date.now() - taskStartedAt;
  assert.equal(task.ok, false);
  assert.match(task.error, /not connected/i);
  assert.ok(taskElapsedMs < 500, `100ms task connection wait took ${taskElapsedMs}ms`);

  const respondStartedAt = Date.now();
  const response = await browserRespond({
    runId: "paused-run",
    clarifyId: "clarify-1",
    answer: "yes",
    timeout: 100,
  });
  const respondElapsedMs = Date.now() - respondStartedAt;
  assert.equal(response.ok, false);
  assert.equal(response.runId, "paused-run");
  assert.match(response.error, /not connected/i);
  assert.ok(respondElapsedMs < 500, `100ms response connection wait took ${respondElapsedMs}ms`);

  await assert.rejects(
    () => sharedBridge().request("cloud_run", { task: "private task", mode: "ask" }),
    /No WebBrain browser extension is connected/,
  );
  assert.equal(receivedCommands, 0);

  rogue.close();
  await once(rogue, "close");
});