@sensaiorg/adapter-chrome 0.1.0

package/src/chrome-adapter.ts

@@ -0,0 +1,117 @@
+/**
+ * ChromeAdapter — implements IPlatformAdapter for Chrome browser debugging.
+ *
+ * Communication flow:
+ *   MCP Server <-> ChromeAdapter <-> WebSocket <-> Chrome Extension <-> chrome.debugger API <-> CDP
+ *
+ * The Chrome Extension uses chrome.debugger to attach to the active tab and
+ * forwards CDP commands/responses through a WebSocket connection to this adapter.
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type {
+  IPlatformAdapter,
+  IUiProvider,
+  ILogProvider,
+  IInteractionProvider,
+  INetworkProvider,
+  IPerformanceProvider,
+  IScreenshotProvider,
+  IAppStateProvider,
+  PlatformCapabilities,
+  ConnectionStatus,
+} from "@sensai/core";
+
+import { CdpBridge } from "./transport/cdp-bridge.js";
+import { CdpEventCollector, registerChromeTools } from "./tools/chrome-tools.js";
+
+export interface ChromeAdapterConfig {
+  /** WebSocket port for extension communication (default: 9230) */
+  wsPort?: number;
+  /** Auto-attach to tab matching this URL pattern */
+  tabUrlPattern?: string;
+}
+
+export class ChromeAdapter implements IPlatformAdapter {
+  readonly platform = "chrome" as const;
+  readonly displayName: string;
+  readonly capabilities: PlatformCapabilities = {
+    uiTree: true,        // DOM tree -> UiNode
+    logs: true,          // Console API messages
+    interaction: true,   // Input.dispatch* via CDP
+    network: true,       // Network domain (full request/response)
+    performance: true,   // Performance domain + Web Vitals
+    screenshot: true,    // Page.captureScreenshot
+    appState: true,      // localStorage, cookies, sessionStorage
+    hotReload: false,    // Not applicable for web (use browser refresh)
+    evalCode: true,      // Runtime.evaluate
+  };
+
+  private readonly config: Required<ChromeAdapterConfig>;
+  private readonly bridge: CdpBridge;
+  private readonly collector: CdpEventCollector;
+  private currentTabUrl = "";
+
+  readonly ui: IUiProvider | null = null;         // TODO: DomUiProvider
+  readonly logs: ILogProvider | null = null;       // TODO: ConsoleLogProvider
+  readonly interaction: IInteractionProvider | null = null;  // TODO: CdpInteractionProvider
+  readonly network: INetworkProvider | null = null; // TODO: CdpNetworkProvider
+  readonly performance: IPerformanceProvider | null = null;
+  readonly screenshot: IScreenshotProvider | null = null;
+  readonly appState: IAppStateProvider | null = null;
+
+  constructor(config: ChromeAdapterConfig = {}) {
+    this.config = {
+      wsPort: config.wsPort ?? parseInt(process.env.SENSAI_CHROME_PORT ?? "9230", 10),
+      tabUrlPattern: config.tabUrlPattern ?? process.env.SENSAI_CHROME_TAB_URL ?? "",
+    };
+
+    this.displayName = `Chrome (port ${this.config.wsPort})`;
+    this.bridge = new CdpBridge(this.config.wsPort);
+    this.collector = new CdpEventCollector();
+  }
+
+  async initialize(): Promise<ConnectionStatus> {
+    try {
+      const connected = await this.bridge.connect();
+      if (connected) {
+        this.currentTabUrl = await this.bridge.getCurrentUrl();
+        // Enable CDP domains and start collecting console/network events
+        await this.collector.enableDomains(this.bridge).catch(() => {
+          // Non-fatal: tools will still work, just no buffered events
+        });
+      }
+
+      return {
+        platform: "chrome",
+        device: `Chrome Tab: ${this.currentTabUrl || "none"}`,
+        connected,
+        capabilities: this.capabilities,
+        details: {
+          wsPort: this.config.wsPort,
+          tabUrl: this.currentTabUrl,
+        },
+      };
+    } catch {
+      return {
+        platform: "chrome",
+        device: "Chrome (not connected)",
+        connected: false,
+        capabilities: this.capabilities,
+      };
+    }
+  }
+
+  shutdown(): void {
+    this.bridge.disconnect();
+  }
+
+  isConnected(): boolean {
+    return this.bridge.isConnected();
+  }
+
+  registerPlatformTools(server: McpServer): void {
+    const prefix = "chrome_";
+    registerChromeTools(server, this.bridge, this.collector, prefix);
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @sensai/adapter-chrome — Chrome/web platform adapter for SensAI.
+ *
+ * Provides debugging tools via Chrome DevTools Protocol (CDP).
+ * Communicates with the SensAI Chrome Extension via Native Messaging or WebSocket.
+ */
+
+export { ChromeAdapter } from "./chrome-adapter.js";

package/src/tools/chrome-tools.test.ts

@@ -0,0 +1,547 @@
+/**
+ * Unit tests for CdpEventCollector.
+ *
+ * CdpEventCollector is already exported from chrome-tools.ts, no modifications needed.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { CdpEventCollector } from "./chrome-tools.js";
+import type { CdpBridge } from "../transport/cdp-bridge.js";
+
+/* ── Helpers ──────────────────────────────────────────────────────── */
+
+type EventHandler = (params: Record<string, unknown>) => void;
+
+/** Creates a minimal CdpBridge mock that captures event handlers. */
+function createMockBridge() {
+  const handlers = new Map<string, EventHandler[]>();
+
+  const bridge = {
+    onEvent: vi.fn((method: string, handler: EventHandler) => {
+      const list = handlers.get(method) ?? [];
+      list.push(handler);
+      handlers.set(method, list);
+    }),
+    send: vi.fn(async () => undefined),
+  } as unknown as CdpBridge;
+
+  /** Simulate a CDP event arriving. */
+  function emit(method: string, params: Record<string, unknown>) {
+    for (const h of handlers.get(method) ?? []) {
+      h(params);
+    }
+  }
+
+  return { bridge, emit };
+}
+
+/** Enable domains on a collector with the mock bridge. */
+async function setup() {
+  const collector = new CdpEventCollector();
+  const { bridge, emit } = createMockBridge();
+  await collector.enableDomains(bridge);
+  return { collector, bridge, emit };
+}
+
+/* ── Console message buffering ────────────────────────────────────── */
+
+describe("CdpEventCollector", () => {
+  describe("console messages", () => {
+    it("buffers a console log with timestamp", async () => {
+      const { collector, emit } = await setup();
+
+      emit("Runtime.consoleAPICalled", {
+        type: "log",
+        args: [{ value: "hello world" }],
+        timestamp: 1000,
+      });
+
+      const logs = collector.getConsoleLogs();
+      expect(logs).toHaveLength(1);
+      expect(logs[0]).toEqual({
+        level: "log",
+        text: "hello world",
+        timestamp: 1000,
+        url: undefined,
+        line: undefined,
+      });
+    });
+
+    it("concatenates multiple args with a space", async () => {
+      const { collector, emit } = await setup();
+
+      emit("Runtime.consoleAPICalled", {
+        type: "log",
+        args: [{ value: "a" }, { value: "b" }, { description: "c-desc" }],
+        timestamp: 2000,
+      });
+
+      expect(collector.getConsoleLogs()[0].text).toBe("a b c-desc");
+    });
+
+    it("captures source location from stackTrace", async () => {
+      const { collector, emit } = await setup();
+
+      emit("Runtime.consoleAPICalled", {
+        type: "warn",
+        args: [{ value: "warning" }],
+        timestamp: 3000,
+        stackTrace: {
+          callFrames: [{ url: "https://example.com/app.js", lineNumber: 42 }],
+        },
+      });
+
+      const entry = collector.getConsoleLogs()[0];
+      expect(entry.url).toBe("https://example.com/app.js");
+      expect(entry.line).toBe(42);
+    });
+
+    it("buffers Runtime.exceptionThrown as error level", async () => {
+      const { collector, emit } = await setup();
+
+      emit("Runtime.exceptionThrown", {
+        timestamp: 5000,
+        exceptionDetails: {
+          text: "Uncaught Error",
+          exception: { description: "TypeError: x is not a function" },
+          url: "https://example.com/main.js",
+          lineNumber: 10,
+        },
+      });
+
+      const logs = collector.getConsoleLogs();
+      expect(logs).toHaveLength(1);
+      expect(logs[0].level).toBe("error");
+      expect(logs[0].text).toBe("TypeError: x is not a function");
+      expect(logs[0].url).toBe("https://example.com/main.js");
+      expect(logs[0].line).toBe(10);
+    });
+
+    it("falls back to text when exception description is missing", async () => {
+      const { collector, emit } = await setup();
+
+      emit("Runtime.exceptionThrown", {
+        timestamp: 5000,
+        exceptionDetails: { text: "Uncaught SyntaxError" },
+      });
+
+      expect(collector.getConsoleLogs()[0].text).toBe("Uncaught SyntaxError");
+    });
+
+    it("falls back to 'Unknown exception' when all fields missing", async () => {
+      const { collector, emit } = await setup();
+
+      emit("Runtime.exceptionThrown", { timestamp: 5000 });
+
+      expect(collector.getConsoleLogs()[0].text).toBe("Unknown exception");
+    });
+
+    it("getConsoleLogs() returns all buffered messages", async () => {
+      const { collector, emit } = await setup();
+
+      for (let i = 0; i < 10; i++) {
+        emit("Runtime.consoleAPICalled", {
+          type: "log",
+          args: [{ value: `msg-${i}` }],
+          timestamp: 1000 + i,
+        });
+      }
+
+      expect(collector.getConsoleLogs()).toHaveLength(10);
+    });
+
+    it("getConsoleLogs(maxCount) returns the most recent entries", async () => {
+      const { collector, emit } = await setup();
+
+      for (let i = 0; i < 10; i++) {
+        emit("Runtime.consoleAPICalled", {
+          type: "log",
+          args: [{ value: `msg-${i}` }],
+          timestamp: 1000 + i,
+        });
+      }
+
+      const last3 = collector.getConsoleLogs(3);
+      expect(last3).toHaveLength(3);
+      expect(last3[0].text).toBe("msg-7");
+      expect(last3[2].text).toBe("msg-9");
+    });
+  });
+
+  /* ── Console buffer size limit ──────────────────────────────────── */
+
+  describe("console buffer eviction", () => {
+    it("enforces max buffer size of 500, evicting oldest entries", async () => {
+      const { collector, emit } = await setup();
+
+      for (let i = 0; i < 520; i++) {
+        emit("Runtime.consoleAPICalled", {
+          type: "log",
+          args: [{ value: `entry-${i}` }],
+          timestamp: i,
+        });
+      }
+
+      const logs = collector.getConsoleLogs();
+      expect(logs).toHaveLength(500);
+      // Oldest 20 entries (0..19) should have been evicted
+      expect(logs[0].text).toBe("entry-20");
+      expect(logs[499].text).toBe("entry-519");
+    });
+  });
+
+  /* ── Network request buffering ──────────────────────────────────── */
+
+  describe("network requests", () => {
+    it("buffers a network request with timing info", async () => {
+      const { collector, emit } = await setup();
+
+      emit("Network.requestWillBeSent", {
+        requestId: "r1",
+        request: { method: "GET", url: "https://api.example.com/data" },
+        type: "Fetch",
+        timestamp: 100.5,
+      });
+
+      emit("Network.responseReceived", {
+        requestId: "r1",
+        response: { status: 200, statusText: "OK" },
+        timestamp: 100.8,
+      });
+
+      emit("Network.loadingFinished", {
+        requestId: "r1",
+        encodedDataLength: 1234,
+        timestamp: 100.9,
+      });
+
+      const entries = collector.getNetworkEntries();
+      expect(entries).toHaveLength(1);
+      expect(entries[0]).toMatchObject({
+        requestId: "r1",
+        method: "GET",
+        url: "https://api.example.com/data",
+        status: 200,
+        statusText: "OK",
+        type: "Fetch",
+        startTime: 100.5,
+        endTime: 100.9,
+        encodedDataLength: 1234,
+      });
+    });
+
+    it("records network errors via loadingFailed", async () => {
+      const { collector, emit } = await setup();
+
+      emit("Network.requestWillBeSent", {
+        requestId: "r2",
+        request: { method: "POST", url: "https://api.example.com/fail" },
+        timestamp: 200,
+      });
+
+      emit("Network.loadingFailed", {
+        requestId: "r2",
+        errorText: "net::ERR_CONNECTION_REFUSED",
+        timestamp: 201,
+      });
+
+      const entries = collector.getNetworkEntries();
+      expect(entries).toHaveLength(1);
+      expect(entries[0].error).toBe("net::ERR_CONNECTION_REFUSED");
+      expect(entries[0].endTime).toBe(201);
+    });
+
+    it("getNetworkEntries() returns all buffered requests", async () => {
+      const { collector, emit } = await setup();
+
+      for (let i = 0; i < 5; i++) {
+        emit("Network.requestWillBeSent", {
+          requestId: `r${i}`,
+          request: { method: "GET", url: `https://example.com/${i}` },
+          timestamp: i,
+        });
+      }
+
+      expect(collector.getNetworkEntries()).toHaveLength(5);
+    });
+
+    it("getNetworkEntries(maxCount) returns the most recent entries", async () => {
+      const { collector, emit } = await setup();
+
+      for (let i = 0; i < 10; i++) {
+        emit("Network.requestWillBeSent", {
+          requestId: `r${i}`,
+          request: { method: "GET", url: `https://example.com/${i}` },
+          timestamp: i,
+        });
+      }
+
+      const last3 = collector.getNetworkEntries(3);
+      expect(last3).toHaveLength(3);
+      expect(last3[0].url).toBe("https://example.com/7");
+      expect(last3[2].url).toBe("https://example.com/9");
+    });
+
+    it("ignores response/finished events for unknown requestIds", async () => {
+      const { collector, emit } = await setup();
+
+      // These should not throw or create entries
+      emit("Network.responseReceived", {
+        requestId: "unknown",
+        response: { status: 200, statusText: "OK" },
+        timestamp: 1,
+      });
+
+      emit("Network.loadingFinished", {
+        requestId: "unknown",
+        encodedDataLength: 100,
+        timestamp: 2,
+      });
+
+      emit("Network.loadingFailed", {
+        requestId: "unknown",
+        errorText: "error",
+        timestamp: 3,
+      });
+
+      expect(collector.getNetworkEntries()).toHaveLength(0);
+    });
+  });
+
+  /* ── Network buffer eviction ────────────────────────────────────── */
+
+  describe("network buffer eviction", () => {
+    it("enforces max buffer size of 500, evicting oldest entries", async () => {
+      const { collector, emit } = await setup();
+
+      for (let i = 0; i < 520; i++) {
+        emit("Network.requestWillBeSent", {
+          requestId: `r${i}`,
+          request: { method: "GET", url: `https://example.com/${i}` },
+          timestamp: i,
+        });
+      }
+
+      const entries = collector.getNetworkEntries();
+      expect(entries).toHaveLength(500);
+      // Oldest 20 entries should be evicted
+      expect(entries[0].url).toBe("https://example.com/20");
+      expect(entries[499].url).toBe("https://example.com/519");
+    });
+  });
+
+  /* ── Filter by level ────────────────────────────────────────────── */
+
+  describe("filtering console logs by level", () => {
+    it("stores different levels and allows external filtering", async () => {
+      const { collector, emit } = await setup();
+
+      emit("Runtime.consoleAPICalled", {
+        type: "log",
+        args: [{ value: "info msg" }],
+        timestamp: 1,
+      });
+      emit("Runtime.consoleAPICalled", {
+        type: "warn",
+        args: [{ value: "warn msg" }],
+        timestamp: 2,
+      });
+      emit("Runtime.consoleAPICalled", {
+        type: "error",
+        args: [{ value: "error msg" }],
+        timestamp: 3,
+      });
+
+      const all = collector.getConsoleLogs();
+      expect(all).toHaveLength(3);
+
+      // Filter externally (as the tool chrome_get_console_logs does)
+      const errors = all.filter((e) => e.level === "error");
+      expect(errors).toHaveLength(1);
+      expect(errors[0].text).toBe("error msg");
+
+      const warnings = all.filter((e) => e.level === "warn");
+      expect(warnings).toHaveLength(1);
+      expect(warnings[0].text).toBe("warn msg");
+
+      const logs = all.filter((e) => e.level === "log");
+      expect(logs).toHaveLength(1);
+      expect(logs[0].text).toBe("info msg");
+    });
+  });
+
+  /* ── enableDomains idempotency ──────────────────────────────────── */
+
+  describe("enableDomains", () => {
+    it("sends Runtime.enable, Network.enable, Page.enable", async () => {
+      const collector = new CdpEventCollector();
+      const { bridge } = createMockBridge();
+
+      await collector.enableDomains(bridge);
+
+      expect(bridge.send).toHaveBeenCalledWith("Runtime.enable");
+      expect(bridge.send).toHaveBeenCalledWith("Network.enable");
+      expect(bridge.send).toHaveBeenCalledWith("Page.enable");
+    });
+
+    it("only enables domains once (idempotent)", async () => {
+      const collector = new CdpEventCollector();
+      const { bridge } = createMockBridge();
+
+      await collector.enableDomains(bridge);
+      await collector.enableDomains(bridge);
+
+      // send should have been called exactly 3 times (Runtime, Network, Page)
+      expect(bridge.send).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  /* ── Fresh instance (clear equivalent) ──────────────────────────── */
+
+  describe("reset / clear equivalent", () => {
+    it("a new CdpEventCollector instance starts with empty buffers", () => {
+      const collector = new CdpEventCollector();
+      expect(collector.getConsoleLogs()).toHaveLength(0);
+      expect(collector.getNetworkEntries()).toHaveLength(0);
+    });
+
+    it("creating a new instance effectively clears all state", async () => {
+      const { collector, emit } = await setup();
+
+      emit("Runtime.consoleAPICalled", {
+        type: "log",
+        args: [{ value: "test" }],
+        timestamp: 1,
+      });
+      emit("Network.requestWillBeSent", {
+        requestId: "r1",
+        request: { method: "GET", url: "https://example.com" },
+        timestamp: 1,
+      });
+
+      expect(collector.getConsoleLogs()).toHaveLength(1);
+      expect(collector.getNetworkEntries()).toHaveLength(1);
+
+      // "Reset" by creating a new collector
+      const freshCollector = new CdpEventCollector();
+      expect(freshCollector.getConsoleLogs()).toHaveLength(0);
+      expect(freshCollector.getNetworkEntries()).toHaveLength(0);
+    });
+  });
+
+  /* ── Rapid concurrent events ────────────────────────────────────── */
+
+  describe("rapid concurrent events", () => {
+    it("handles many console and network events fired in rapid succession", async () => {
+      const { collector, emit } = await setup();
+
+      // Fire 200 console + 200 network events synchronously
+      for (let i = 0; i < 200; i++) {
+        emit("Runtime.consoleAPICalled", {
+          type: i % 3 === 0 ? "error" : i % 3 === 1 ? "warn" : "log",
+          args: [{ value: `rapid-${i}` }],
+          timestamp: i,
+        });
+
+        emit("Network.requestWillBeSent", {
+          requestId: `rapid-r${i}`,
+          request: { method: "GET", url: `https://example.com/rapid/${i}` },
+          timestamp: i,
+        });
+      }
+
+      expect(collector.getConsoleLogs()).toHaveLength(200);
+      expect(collector.getNetworkEntries()).toHaveLength(200);
+    });
+
+    it("handles interleaved request/response events correctly", async () => {
+      const { collector, emit } = await setup();
+
+      // Start multiple requests
+      for (let i = 0; i < 50; i++) {
+        emit("Network.requestWillBeSent", {
+          requestId: `req-${i}`,
+          request: { method: "GET", url: `https://example.com/${i}` },
+          timestamp: i * 0.1,
+        });
+      }
+
+      // Responses arrive in a different order
+      for (let i = 49; i >= 0; i--) {
+        emit("Network.responseReceived", {
+          requestId: `req-${i}`,
+          response: { status: 200, statusText: "OK" },
+          timestamp: 10 + i * 0.1,
+        });
+      }
+
+      const entries = collector.getNetworkEntries();
+      expect(entries).toHaveLength(50);
+
+      // All should have status populated
+      for (const entry of entries) {
+        expect(entry.status).toBe(200);
+      }
+    });
+  });
+
+  /* ── Edge cases ─────────────────────────────────────────────────── */
+
+  describe("edge cases", () => {
+    it("handles console entry with no args", async () => {
+      const { collector, emit } = await setup();
+
+      emit("Runtime.consoleAPICalled", {
+        type: "log",
+        timestamp: 1000,
+        // no args field
+      });
+
+      const logs = collector.getConsoleLogs();
+      expect(logs).toHaveLength(1);
+      expect(logs[0].text).toBe("");
+    });
+
+    it("handles console entry with empty args array", async () => {
+      const { collector, emit } = await setup();
+
+      emit("Runtime.consoleAPICalled", {
+        type: "log",
+        args: [],
+        timestamp: 1000,
+      });
+
+      const logs = collector.getConsoleLogs();
+      expect(logs).toHaveLength(1);
+      expect(logs[0].text).toBe("");
+    });
+
+    it("uses Date.now() fallback when timestamp is missing", async () => {
+      const { collector, emit } = await setup();
+      const before = Date.now();
+
+      emit("Runtime.consoleAPICalled", {
+        type: "log",
+        args: [{ value: "no-ts" }],
+        // no timestamp
+      });
+
+      const after = Date.now();
+      const ts = collector.getConsoleLogs()[0].timestamp;
+      expect(ts).toBeGreaterThanOrEqual(before);
+      expect(ts).toBeLessThanOrEqual(after);
+    });
+
+    it("uses description when value is undefined in args", async () => {
+      const { collector, emit } = await setup();
+
+      emit("Runtime.consoleAPICalled", {
+        type: "log",
+        args: [{ description: "Promise { <pending> }" }],
+        timestamp: 1,
+      });
+
+      expect(collector.getConsoleLogs()[0].text).toBe("Promise { <pending> }");
+    });
+  });
+});