@pi-harness/pi-harness 0.1.13 → 0.1.14

package/packages/core/test/browser-session.test.ts

@@ -0,0 +1,1236 @@
+import { Context } from "@deepseek-ai/cordis";
+import { describe, expect, test, vi } from "vitest";
+import { PiPluginUiRegistry, PiToolRegistry, provideLaunchContext } from "../src/services.js";
+import browserSessionPlugin from "../src/plugins/browser-session.js";
+import toolsPlugin from "../src/plugins/tools.js";
+
+async function createBrowserSession(): Promise<Context> {
+  const context = new Context();
+  provideLaunchContext(context, { cwd: "/tmp", agentDir: "/tmp", args: [], requestExit() {} });
+  await context.plugin(toolsPlugin, { names: [] });
+  await context.plugin(browserSessionPlugin, { endpoint: "http://127.0.0.1:9222" });
+  return context;
+}
+
+function browserTool(context: Context, name: string) {
+  const tool = context.piTools.snapshot().customTools.find((candidate) => candidate.name === name);
+  if (tool === undefined) throw new Error(`Browser session tool was not registered: ${name}`);
+  return tool;
+}
+
+describe("browser session boundaries", () => {
+  test("declares bounded browser session inputs", async () => {
+    const context = await createBrowserSession();
+    try {
+      expect(browserSessionPlugin.Config.dict?.endpoint?.meta).toMatchObject({ min: 1, max: 2_048 });
+      expect(browserTool(context, "browser_navigate").parameters).toMatchObject({
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          targetId: { type: "string", minLength: 1, maxLength: 512 },
+          url: { type: "string", minLength: 1, maxLength: 8_192 },
+        },
+      });
+      expect(browserTool(context, "browser_read").parameters).toMatchObject({
+        type: "object",
+        additionalProperties: false,
+        properties: { targetId: { type: "string", minLength: 1, maxLength: 512 } },
+      });
+      expect(browserTool(context, "browser_click").parameters).toMatchObject({
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          targetId: { type: "string", minLength: 1, maxLength: 512 },
+          selector: { type: "string", minLength: 1, maxLength: 512 },
+        },
+      });
+      expect(browserTool(context, "browser_screenshot").parameters).toMatchObject({
+        type: "object",
+        additionalProperties: false,
+        properties: { targetId: { type: "string", minLength: 1, maxLength: 512 } },
+      });
+    } finally {
+      await context.fiber.dispose();
+    }
+  });
+
+  test("rolls back every tool when panel registration fails", async () => {
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const panels = new PiPluginUiRegistry();
+    provideLaunchContext(context, { cwd: "/tmp", agentDir: "/tmp", args: [], requestExit() {} });
+    context.provide("piTools", tools);
+    context.provide("piPluginUi", panels);
+    panels.register({ id: "browser-session-panel", pluginId: "fixture", title: "Fixture", read: () => ({}) });
+    try {
+      await expect(context.plugin(browserSessionPlugin, { endpoint: "http://127.0.0.1:9222" })).rejects.toThrow(/already registered.*browser-session-panel/iu);
+      expect(tools.snapshot().customTools).toEqual([]);
+    } finally {
+      await context.fiber.dispose();
+    }
+  });
+
+  test("rejects malformed tool inputs before browser discovery", async () => {
+    const originalFetch = globalThis.fetch;
+    let fetches = 0;
+    globalThis.fetch = () => {
+      fetches += 1;
+      return Promise.resolve(Response.json([]));
+    };
+    const context = await createBrowserSession();
+    try {
+      await expect(browserTool(context, "browser_read").execute("read", null, undefined, undefined, {} as never)).rejects.toThrow(/parameters.*object/iu);
+      await expect(
+        browserTool(context, "browser_click").execute("click", { targetId: "tab-1", selector: null }, undefined, undefined, {} as never),
+      ).rejects.toThrow(/selector must be a string/iu);
+      await expect(
+        browserTool(context, "browser_navigate").execute("navigate", { targetId: "tab-1", url: null }, undefined, undefined, {} as never),
+      ).rejects.toThrow(/navigation URL must be a string/iu);
+      await expect(browserTool(context, "browser_screenshot").execute("screenshot", { targetId: null }, undefined, undefined, {} as never)).rejects.toThrow(
+        /target ID must be a string/iu,
+      );
+      expect(fetches).toBe(0);
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("strictly validates raw tool parameters without invoking accessors", async () => {
+    const originalFetch = globalThis.fetch;
+    let fetches = 0;
+    globalThis.fetch = () => {
+      fetches += 1;
+      return Promise.resolve(Response.json([]));
+    };
+    const context = await createBrowserSession();
+    let accessed = false;
+    const params = { url: "https://example.com/" } as { targetId?: string; url: string };
+    Object.defineProperty(params, "targetId", {
+      enumerable: true,
+      get() {
+        accessed = true;
+        throw new Error("browser target accessor executed");
+      },
+    });
+    try {
+      await expect(browserTool(context, "browser_navigate").execute("navigate", params, undefined, undefined, {} as never)).rejects.toThrow(
+        /parameters.*data properties/iu,
+      );
+      expect(accessed).toBe(false);
+      await expect(browserTool(context, "browser_tabs").execute("tabs", { unexpected: true }, undefined, undefined, {} as never)).rejects.toThrow(
+        /parameters.*unknown property/iu,
+      );
+      expect(fetches).toBe(0);
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("rejects an oversized DevTools tab list before reading its body", async () => {
+    const originalFetch = globalThis.fetch;
+    let bodyRead = false;
+    let bodyCancelled = false;
+    globalThis.fetch = () =>
+      Promise.resolve({
+        ok: true,
+        status: 200,
+        headers: new Headers({ "content-length": String(1024 * 1024 + 1) }),
+        body: {
+          cancel() {
+            bodyCancelled = true;
+            return Promise.resolve();
+          },
+          getReader() {
+            bodyRead = true;
+            throw new Error("oversized body was read");
+          },
+        },
+        json() {
+          bodyRead = true;
+          return Promise.reject(new Error("oversized body was read"));
+        },
+      } as unknown as Response);
+    const context = await createBrowserSession();
+    try {
+      await expect(browserTool(context, "browser_tabs").execute("call-1", {}, undefined, undefined, {} as never)).rejects.toThrow(/1 MiB limit/iu);
+      expect(bodyRead).toBe(false);
+      expect(bodyCancelled).toBe(true);
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("rejects invalid UTF-8 DevTools tab lists", async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = () => Promise.resolve(new Response(new Uint8Array([0xc3, 0x28]), { status: 200 }));
+    const context = await createBrowserSession();
+    try {
+      await expect(browserTool(context, "browser_tabs").execute("call-1", {}, undefined, undefined, {} as never)).rejects.toThrow(/valid UTF-8/iu);
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("rejects DevTools tab inventories above the item limit", async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json(
+          Array.from({ length: 257 }, (_, index) => ({
+            id: `tab-${index}`,
+            title: `Tab ${index}`,
+            url: `https://example.com/${index}`,
+            type: "page",
+            webSocketDebuggerUrl: `ws://127.0.0.1:9222/devtools/page/tab-${index}`,
+          })),
+        ),
+      );
+    const context = await createBrowserSession();
+    try {
+      await expect(browserTool(context, "browser_tabs").execute("tabs", {}, undefined, undefined, {} as never)).rejects.toThrow(
+        /tab inventory cannot exceed 256 items/iu,
+      );
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+    }
+  });
+
+  test.each([
+    [{ title: "Missing id", url: "https://example.com/", type: "page" }, /tab 1 target ID must be a string/iu],
+    [{ id: "tab\0one", title: "NUL id", url: "https://example.com/", type: "page" }, /tab 1 target ID.*NUL/iu],
+    [{ id: "tab-1", title: "x".repeat(4_097), url: "https://example.com/", type: "page" }, /tab 1 title.*4096/iu],
+    [{ id: "tab-1", title: "Fixture", url: "x".repeat(8_193), type: "page" }, /tab 1 URL.*8192/iu],
+    [{ id: "tab-1", title: "Fixture", url: "https://example.com/", type: "x".repeat(65) }, /tab 1 type.*64/iu],
+    [{ id: "tab-1", title: "Fixture", url: "https://example.com/", type: "page", webSocketDebuggerUrl: "x".repeat(2_049) }, /tab 1 WebSocket URL.*2048/iu],
+  ])("rejects malformed DevTools tab descriptors", async (tab, expected) => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = () => Promise.resolve(Response.json([tab]));
+    const context = await createBrowserSession();
+    try {
+      await expect(browserTool(context, "browser_tabs").execute("tabs", {}, undefined, undefined, {} as never)).rejects.toThrow(expected);
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("bounds the browser tab summary while retaining the complete bounded inventory in details", async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json(
+          Array.from({ length: 40 }, (_, index) => ({
+            id: `tab-${index}`,
+            title: `${index}-${"t".repeat(4_000)}`,
+            url: `https://example.com/${index}/${"u".repeat(4_000)}`,
+            type: "page",
+          })),
+        ),
+      );
+    const context = await createBrowserSession();
+    try {
+      const result = await browserTool(context, "browser_tabs").execute("tabs", {}, undefined, undefined, {} as never);
+      const content = result.content[0];
+      expect(content?.type).toBe("text");
+      if (content?.type !== "text") throw new Error("Expected a browser tab text summary");
+      expect(Buffer.byteLength(content.text, "utf8")).toBeLessThanOrEqual(128 * 1024);
+      expect(content.text).toMatch(/summary truncated.*40 tabs/iu);
+      expect((result.details as { tabs: unknown[] }).tabs).toHaveLength(40);
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("times out DevTools discovery requests", async () => {
+    const originalFetch = globalThis.fetch;
+    let rejectFallback: ((reason: Error) => void) | undefined;
+    globalThis.fetch = (_input, init) =>
+      new Promise<Response>((_resolve, reject) => {
+        rejectFallback = reject;
+        init?.signal?.addEventListener(
+          "abort",
+          () => {
+            const reason: unknown = init.signal?.reason;
+            reject(reason instanceof Error ? reason : new Error("DevTools discovery aborted"));
+          },
+          { once: true },
+        );
+      });
+    vi.useFakeTimers();
+    const context = await createBrowserSession();
+    try {
+      const pending = browserTool(context, "browser_tabs").execute("call-1", {}, undefined, undefined, {} as never);
+      const timedOut = expect(pending).rejects.toThrow(/timed out after 15000 ms/iu);
+
+      await vi.advanceTimersByTimeAsync(15_000);
+      rejectFallback?.(new Error("test fallback rejection"));
+      await timedOut;
+    } finally {
+      rejectFallback?.(new Error("test cleanup"));
+      vi.useRealTimers();
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("cancels in-flight DevTools discovery when the plugin is disposed", async () => {
+    const originalFetch = globalThis.fetch;
+    let rejectPending: ((reason: Error) => void) | undefined;
+    let aborted = false;
+    globalThis.fetch = (_input, init) =>
+      new Promise<Response>((_resolve, reject) => {
+        rejectPending = reject;
+        init?.signal?.addEventListener(
+          "abort",
+          () => {
+            aborted = true;
+            const reason: unknown = init.signal?.reason;
+            reject(reason instanceof Error ? reason : new Error("DevTools discovery aborted"));
+          },
+          { once: true },
+        );
+      });
+    const context = await createBrowserSession();
+    const tools = context.piTools;
+    const panels = context.piPluginUi;
+    let fallback: ReturnType<typeof setTimeout> | undefined;
+    let execution: Promise<unknown> | undefined;
+    try {
+      execution = browserTool(context, "browser_tabs").execute("call-1", {}, undefined, undefined, {} as never);
+
+      await context.fiber.dispose();
+      const outcome = await Promise.race([
+        execution.then(
+          () => new Error("Browser discovery unexpectedly succeeded"),
+          (error: unknown) => error,
+        ),
+        new Promise<string>((resolve) => {
+          fallback = setTimeout(() => resolve("Browser discovery remained pending"), 500);
+        }),
+      ]);
+
+      expect(outcome).toBeInstanceOf(Error);
+      expect(String(outcome)).toMatch(/disposed|cancelled/iu);
+      expect(aborted).toBe(true);
+      expect(tools.snapshot().customTools).toEqual([]);
+      await expect(panels.snapshot()).resolves.toEqual([]);
+    } finally {
+      if (fallback !== undefined) clearTimeout(fallback);
+      rejectPending?.(new Error("test cleanup"));
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+      await execution?.catch(() => undefined);
+    }
+  });
+
+  test("rejects navigation URLs containing credentials before tab discovery", async () => {
+    const originalFetch = globalThis.fetch;
+    let fetches = 0;
+    globalThis.fetch = () => {
+      fetches += 1;
+      return Promise.resolve(Response.json([]));
+    };
+    const context = await createBrowserSession();
+    try {
+      await expect(
+        browserTool(context, "browser_navigate").execute(
+          "call-1",
+          { targetId: "tab-1", url: "https://user:password@example.com/private" },
+          undefined,
+          undefined,
+          {} as never,
+        ),
+      ).rejects.toThrow(/without credentials/iu);
+      expect(fetches).toBe(0);
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("rejects a navigation result containing a CDP errorText", async () => {
+    const originalFetch = globalThis.fetch;
+    const OriginalWebSocket = globalThis.WebSocket;
+    const methods: string[] = [];
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json([
+          {
+            id: "tab-1",
+            title: "Fixture",
+            type: "page",
+            url: "about:blank",
+            webSocketDebuggerUrl: "ws://127.0.0.1:9222/devtools/page/tab-1",
+          },
+        ]),
+      );
+    class NavigationSocket extends EventTarget {
+      constructor() {
+        super();
+        queueMicrotask(() => this.dispatchEvent(new Event("open")));
+      }
+
+      send(source: string): void {
+        const request = JSON.parse(source) as { id: number; method: string };
+        methods.push(request.method);
+        const result = request.method === "Page.navigate" ? { errorText: "net::ERR_NAME_NOT_RESOLVED" } : { result: { value: "complete" } };
+        queueMicrotask(() => this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify({ id: request.id, result }) })));
+      }
+
+      close(): void {}
+    }
+    globalThis.WebSocket = NavigationSocket as unknown as typeof WebSocket;
+    const context = await createBrowserSession();
+    try {
+      await expect(
+        browserTool(context, "browser_navigate").execute(
+          "call-1",
+          { targetId: "tab-1", url: "https://does-not-resolve.invalid/" },
+          undefined,
+          undefined,
+          {} as never,
+        ),
+      ).rejects.toThrow(/ERR_NAME_NOT_RESOLVED/iu);
+      expect(methods).toEqual(["Page.enable", "Page.navigate"]);
+    } finally {
+      globalThis.fetch = originalFetch;
+      globalThis.WebSocket = OriginalWebSocket;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("records successful navigation in panel state", async () => {
+    const originalFetch = globalThis.fetch;
+    const OriginalWebSocket = globalThis.WebSocket;
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json([
+          {
+            id: "tab-1",
+            title: "Fixture",
+            type: "page",
+            url: "about:blank",
+            webSocketDebuggerUrl: "ws://127.0.0.1:9222/devtools/page/tab-1",
+          },
+        ]),
+      );
+    class NavigationSocket extends EventTarget {
+      constructor() {
+        super();
+        queueMicrotask(() => this.dispatchEvent(new Event("open")));
+      }
+
+      send(source: string): void {
+        const request = JSON.parse(source) as { id: number; method: string };
+        const result = request.method === "Runtime.evaluate" ? { result: { value: "complete" } } : {};
+        queueMicrotask(() => this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify({ id: request.id, result }) })));
+      }
+
+      close(): void {}
+    }
+    globalThis.WebSocket = NavigationSocket as unknown as typeof WebSocket;
+    const context = await createBrowserSession();
+    try {
+      await browserTool(context, "browser_navigate").execute(
+        "call-1",
+        { targetId: "tab-1", url: "https://example.com/next" },
+        undefined,
+        undefined,
+        {} as never,
+      );
+
+      await expect(context.piPluginUi.snapshot()).resolves.toMatchObject([
+        { id: "browser-session-panel", data: { latest: { targetId: "tab-1", status: "navigated", url: "https://example.com/next" } } },
+      ]);
+    } finally {
+      globalThis.fetch = originalFetch;
+      globalThis.WebSocket = OriginalWebSocket;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("records an empty page read in panel state", async () => {
+    const originalFetch = globalThis.fetch;
+    const OriginalWebSocket = globalThis.WebSocket;
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json([
+          {
+            id: "tab-1",
+            title: "Empty",
+            type: "page",
+            url: "https://example.com/empty",
+            webSocketDebuggerUrl: "ws://127.0.0.1:9222/devtools/page/tab-1",
+          },
+        ]),
+      );
+    class ReadSocket extends EventTarget {
+      constructor() {
+        super();
+        queueMicrotask(() => this.dispatchEvent(new Event("open")));
+      }
+
+      send(source: string): void {
+        const request = JSON.parse(source) as { id: number };
+        queueMicrotask(() => this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify({ id: request.id, result: { result: { value: "" } } }) })));
+      }
+
+      close(): void {}
+    }
+    globalThis.WebSocket = ReadSocket as unknown as typeof WebSocket;
+    const context = await createBrowserSession();
+    try {
+      await browserTool(context, "browser_read").execute("call-1", { targetId: "tab-1" }, undefined, undefined, {} as never);
+
+      await expect(context.piPluginUi.snapshot()).resolves.toMatchObject([
+        { id: "browser-session-panel", data: { latest: { status: "read", text: "", truncated: false } } },
+      ]);
+    } finally {
+      globalThis.fetch = originalFetch;
+      globalThis.WebSocket = OriginalWebSocket;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("publishes bounded tab and text previews with explicit panel inventory metadata", async () => {
+    const originalFetch = globalThis.fetch;
+    const OriginalWebSocket = globalThis.WebSocket;
+    const pageText = "x".repeat(20_000);
+    const tabList = Array.from({ length: 25 }, (_, index) => ({
+      id: `tab-${index}`,
+      title: `Fixture ${index}`,
+      type: "page",
+      url: `https://example.com/${index}`,
+      webSocketDebuggerUrl: `ws://127.0.0.1:9222/devtools/page/tab-${index}`,
+    }));
+    globalThis.fetch = () => Promise.resolve(Response.json(tabList));
+    class ReadSocket extends EventTarget {
+      constructor() {
+        super();
+        queueMicrotask(() => this.dispatchEvent(new Event("open")));
+      }
+
+      send(source: string): void {
+        const request = JSON.parse(source) as { id: number };
+        queueMicrotask(() =>
+          this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify({ id: request.id, result: { result: { value: pageText } } }) })),
+        );
+      }
+
+      close(): void {}
+    }
+    globalThis.WebSocket = ReadSocket as unknown as typeof WebSocket;
+    const context = await createBrowserSession();
+    try {
+      await browserTool(context, "browser_read").execute("call-1", { targetId: "tab-0" }, undefined, undefined, {} as never);
+
+      const panel = (await context.piPluginUi.snapshot())[0];
+      expect((panel?.data as { tabs: unknown[] }).tabs).toHaveLength(20);
+      expect(panel?.data).toMatchObject({
+        inventory: { total: 25, shown: 20, truncated: true },
+        limits: { tabs: 20, textPreviewCharacters: 12_000 },
+        latest: { text: "x".repeat(12_000), truncated: false, previewTruncated: true },
+      });
+    } finally {
+      globalThis.fetch = originalFetch;
+      globalThis.WebSocket = OriginalWebSocket;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("rejects screenshots larger than 8 MiB", async () => {
+    const originalFetch = globalThis.fetch;
+    const OriginalWebSocket = globalThis.WebSocket;
+    const screenshotData = "A".repeat(11_184_812);
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json([
+          {
+            id: "tab-1",
+            title: "Fixture",
+            type: "page",
+            url: "https://example.com/",
+            webSocketDebuggerUrl: "ws://127.0.0.1:9222/devtools/page/tab-1",
+          },
+        ]),
+      );
+    class ScreenshotSocket extends EventTarget {
+      constructor() {
+        super();
+        queueMicrotask(() => this.dispatchEvent(new Event("open")));
+      }
+
+      send(source: string): void {
+        const request = JSON.parse(source) as { id: number };
+        queueMicrotask(() => this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify({ id: request.id, result: { data: screenshotData } }) })));
+      }
+
+      close(): void {}
+    }
+    globalThis.WebSocket = ScreenshotSocket as unknown as typeof WebSocket;
+    const context = await createBrowserSession();
+    try {
+      const outcome = await browserTool(context, "browser_screenshot")
+        .execute("call-1", { targetId: "tab-1" }, undefined, undefined, {} as never)
+        .then(
+          () => "resolved" as const,
+          (error: unknown) => error,
+        );
+      expect(outcome).toBeInstanceOf(Error);
+      if (!(outcome instanceof Error)) throw new Error("Expected screenshot rejection");
+      expect(outcome.message).toMatch(/screenshot exceeded the 8 MiB limit/iu);
+    } finally {
+      globalThis.fetch = originalFetch;
+      globalThis.WebSocket = OriginalWebSocket;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("cancels an in-flight DevTools command", async () => {
+    const originalFetch = globalThis.fetch;
+    const OriginalWebSocket = globalThis.WebSocket;
+    const caller = new AbortController();
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json([
+          {
+            id: "tab-1",
+            title: "Fixture",
+            type: "page",
+            url: "https://example.com/",
+            webSocketDebuggerUrl: "ws://127.0.0.1:9222/devtools/page/tab-1",
+          },
+        ]),
+      );
+    class HangingSocket extends EventTarget {
+      constructor() {
+        super();
+        queueMicrotask(() => this.dispatchEvent(new Event("open")));
+      }
+
+      send(): void {
+        caller.abort(new Error("cancel DevTools command"));
+        queueMicrotask(() => this.dispatchEvent(new Event("close")));
+      }
+
+      close(): void {}
+    }
+    globalThis.WebSocket = HangingSocket as unknown as typeof WebSocket;
+    const context = await createBrowserSession();
+    try {
+      await expect(browserTool(context, "browser_read").execute("call-1", { targetId: "tab-1" }, caller.signal, undefined, {} as never)).rejects.toThrow(
+        /cancelled/iu,
+      );
+    } finally {
+      globalThis.fetch = originalFetch;
+      globalThis.WebSocket = OriginalWebSocket;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("does not miss cancellation while constructing a DevTools socket", async () => {
+    const originalFetch = globalThis.fetch;
+    const OriginalWebSocket = globalThis.WebSocket;
+    const caller = new AbortController();
+    let closed = false;
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json([
+          {
+            id: "tab-1",
+            title: "Fixture",
+            type: "page",
+            url: "https://example.com/",
+            webSocketDebuggerUrl: "ws://127.0.0.1:9222/devtools/page/tab-1",
+          },
+        ]),
+      );
+    class CancellingSocket extends EventTarget {
+      constructor() {
+        super();
+        caller.abort(new Error("cancel during socket construction"));
+      }
+
+      send(): void {}
+
+      close(): void {
+        closed = true;
+      }
+    }
+    globalThis.WebSocket = CancellingSocket as unknown as typeof WebSocket;
+    vi.useFakeTimers();
+    const context = await createBrowserSession();
+    try {
+      const pending = browserTool(context, "browser_read").execute("call-1", { targetId: "tab-1" }, caller.signal, undefined, {} as never);
+      const outcomePromise = pending.then(
+        () => new Error("Browser command unexpectedly succeeded"),
+        (error: unknown) => error,
+      );
+
+      await vi.advanceTimersByTimeAsync(15_000);
+
+      const outcome = await outcomePromise;
+      expect(outcome).toBeInstanceOf(Error);
+      if (!(outcome instanceof Error)) throw new Error("Expected cancellation");
+      expect(outcome.message).toMatch(/cancel during socket construction|cancelled/iu);
+      expect(closed).toBe(true);
+    } finally {
+      vi.useRealTimers();
+      globalThis.fetch = originalFetch;
+      globalThis.WebSocket = OriginalWebSocket;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("rejects immediately when sending a DevTools command fails", async () => {
+    const originalFetch = globalThis.fetch;
+    const OriginalWebSocket = globalThis.WebSocket;
+    let closed = false;
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json([
+          {
+            id: "tab-1",
+            title: "Fixture",
+            type: "page",
+            url: "https://example.com/",
+            webSocketDebuggerUrl: "ws://127.0.0.1:9222/devtools/page/tab-1",
+          },
+        ]),
+      );
+    class ThrowingSocket {
+      addEventListener(type: string, listener: EventListener): void {
+        if (type !== "open") return;
+        queueMicrotask(() => {
+          try {
+            listener(new Event("open"));
+          } catch {
+            // Simulate an event target reporting the handler error without settling the CDP promise.
+          }
+        });
+      }
+
+      removeEventListener(): void {}
+
+      send(): void {
+        throw new Error("send failed");
+      }
+
+      close(): void {
+        closed = true;
+      }
+    }
+    globalThis.WebSocket = ThrowingSocket as unknown as typeof WebSocket;
+    vi.useFakeTimers();
+    const context = await createBrowserSession();
+    try {
+      const pending = browserTool(context, "browser_read").execute("call-1", { targetId: "tab-1" }, undefined, undefined, {} as never);
+      const outcomePromise = pending.then(
+        () => new Error("Browser command unexpectedly succeeded"),
+        (error: unknown) => error,
+      );
+
+      await vi.advanceTimersByTimeAsync(15_000);
+
+      const outcome = await outcomePromise;
+      expect(outcome).toBeInstanceOf(Error);
+      if (!(outcome instanceof Error)) throw new Error("Expected send failure");
+      expect(outcome.message).toMatch(/send failed/iu);
+      expect(closed).toBe(true);
+    } finally {
+      vi.useRealTimers();
+      globalThis.fetch = originalFetch;
+      globalThis.WebSocket = OriginalWebSocket;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("closes a DevTools socket after an error event", async () => {
+    const originalFetch = globalThis.fetch;
+    const OriginalWebSocket = globalThis.WebSocket;
+    let closed = false;
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json([
+          {
+            id: "tab-1",
+            title: "Fixture",
+            type: "page",
+            url: "https://example.com/",
+            webSocketDebuggerUrl: "ws://127.0.0.1:9222/devtools/page/tab-1",
+          },
+        ]),
+      );
+    class ErrorSocket extends EventTarget {
+      constructor() {
+        super();
+        queueMicrotask(() => this.dispatchEvent(new Event("error")));
+      }
+
+      send(): void {}
+
+      close(): void {
+        closed = true;
+      }
+    }
+    globalThis.WebSocket = ErrorSocket as unknown as typeof WebSocket;
+    const context = await createBrowserSession();
+    try {
+      await expect(browserTool(context, "browser_read").execute("call-1", { targetId: "tab-1" }, undefined, undefined, {} as never)).rejects.toThrow(
+        /Could not connect/iu,
+      );
+      expect(closed).toBe(true);
+    } finally {
+      globalThis.fetch = originalFetch;
+      globalThis.WebSocket = OriginalWebSocket;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("rejects browser session endpoints containing credentials", async () => {
+    const context = new Context();
+    provideLaunchContext(context, { cwd: "/tmp", agentDir: "/tmp", args: [], requestExit() {} });
+    await context.plugin(toolsPlugin, { names: [] });
+    try {
+      let activationError: unknown;
+      try {
+        await context.plugin(browserSessionPlugin, { endpoint: "http://user:password@127.0.0.1:9222" });
+      } catch (error) {
+        activationError = error;
+      }
+      expect(activationError).toBeInstanceOf(Error);
+      if (!(activationError instanceof Error)) throw new Error("Expected invalid endpoint rejection");
+      expect(activationError.message).toMatch(/must not contain credentials/iu);
+    } finally {
+      await context.fiber.dispose();
+    }
+  });
+
+  test("disables redirects while discovering DevTools tabs", async () => {
+    const originalFetch = globalThis.fetch;
+    let redirect: RequestRedirect | undefined;
+    globalThis.fetch = (_input, init) => {
+      redirect = init?.redirect;
+      return Promise.resolve(Response.json([]));
+    };
+    const context = await createBrowserSession();
+    try {
+      await browserTool(context, "browser_tabs").execute("call-1", {}, undefined, undefined, {} as never);
+      expect(redirect).toBe("error");
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("rejects remote WebSocket URLs returned by local DevTools discovery", async () => {
+    const originalFetch = globalThis.fetch;
+    const OriginalWebSocket = globalThis.WebSocket;
+    let connections = 0;
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json([
+          {
+            id: "tab-1",
+            title: "Fixture",
+            type: "page",
+            url: "https://example.com/",
+            webSocketDebuggerUrl: "ws://remote.example.com/devtools/page/tab-1",
+          },
+        ]),
+      );
+    class RemoteSocket extends EventTarget {
+      constructor() {
+        super();
+        connections += 1;
+        queueMicrotask(() => this.dispatchEvent(new Event("open")));
+      }
+
+      send(source: string): void {
+        const request = JSON.parse(source) as { id: number };
+        queueMicrotask(() => this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify({ id: request.id, result: { data: "AAAA" } }) })));
+      }
+
+      close(): void {}
+    }
+    globalThis.WebSocket = RemoteSocket as unknown as typeof WebSocket;
+    const context = await createBrowserSession();
+    try {
+      await expect(browserTool(context, "browser_screenshot").execute("call-1", { targetId: "tab-1" }, undefined, undefined, {} as never)).rejects.toThrow(
+        /must stay on the configured local endpoint/iu,
+      );
+      expect(connections).toBe(0);
+    } finally {
+      globalThis.fetch = originalFetch;
+      globalThis.WebSocket = OriginalWebSocket;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("rejects malformed base64 screenshot data", async () => {
+    const originalFetch = globalThis.fetch;
+    const OriginalWebSocket = globalThis.WebSocket;
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json([
+          {
+            id: "tab-1",
+            title: "Fixture",
+            type: "page",
+            url: "https://example.com/",
+            webSocketDebuggerUrl: "ws://127.0.0.1:9222/devtools/page/tab-1",
+          },
+        ]),
+      );
+    class InvalidScreenshotSocket extends EventTarget {
+      constructor() {
+        super();
+        queueMicrotask(() => this.dispatchEvent(new Event("open")));
+      }
+
+      send(source: string): void {
+        const request = JSON.parse(source) as { id: number };
+        queueMicrotask(() => this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify({ id: request.id, result: { data: "not base64!" } }) })));
+      }
+
+      close(): void {}
+    }
+    globalThis.WebSocket = InvalidScreenshotSocket as unknown as typeof WebSocket;
+    const context = await createBrowserSession();
+    try {
+      await expect(browserTool(context, "browser_screenshot").execute("call-1", { targetId: "tab-1" }, undefined, undefined, {} as never)).rejects.toThrow(
+        /invalid base64/iu,
+      );
+    } finally {
+      globalThis.fetch = originalFetch;
+      globalThis.WebSocket = OriginalWebSocket;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("keeps screenshot payload bytes out of tool details and panel state", async () => {
+    const originalFetch = globalThis.fetch;
+    const OriginalWebSocket = globalThis.WebSocket;
+    const screenshotData = "iVBORw0KGgo=";
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json([
+          {
+            id: "tab-1",
+            title: "Fixture",
+            type: "page",
+            url: "https://example.com/",
+            webSocketDebuggerUrl: "ws://127.0.0.1:9222/devtools/page/tab-1",
+          },
+        ]),
+      );
+    class ScreenshotSocket extends EventTarget {
+      constructor() {
+        super();
+        queueMicrotask(() => this.dispatchEvent(new Event("open")));
+      }
+
+      send(source: string): void {
+        const request = JSON.parse(source) as { id: number };
+        queueMicrotask(() => this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify({ id: request.id, result: { data: screenshotData } }) })));
+      }
+
+      close(): void {}
+    }
+    globalThis.WebSocket = ScreenshotSocket as unknown as typeof WebSocket;
+    const context = await createBrowserSession();
+    try {
+      const result = await browserTool(context, "browser_screenshot").execute("call-1", { targetId: "tab-1" }, undefined, undefined, {} as never);
+
+      expect(result.content).toEqual([{ type: "image", data: screenshotData, mimeType: "image/png" }]);
+      expect(result.details).toMatchObject({ screenshot: { bytes: 8, mimeType: "image/png" } });
+      expect((result.details as { screenshot: Record<string, unknown> }).screenshot).not.toHaveProperty("data");
+      const panel = (await context.piPluginUi.snapshot())[0];
+      expect(panel?.data).toMatchObject({ latest: { screenshot: { bytes: 8, mimeType: "image/png" } } });
+      expect((panel?.data as { latest?: { screenshot?: Record<string, unknown> } } | undefined)?.latest?.screenshot ?? {}).not.toHaveProperty("data");
+    } finally {
+      globalThis.fetch = originalFetch;
+      globalThis.WebSocket = OriginalWebSocket;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("rejects DevTools WebSocket responses larger than 12 MiB", async () => {
+    const originalFetch = globalThis.fetch;
+    const OriginalWebSocket = globalThis.WebSocket;
+    const oversizedText = "x".repeat(12 * 1024 * 1024);
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json([
+          {
+            id: "tab-1",
+            title: "Fixture",
+            type: "page",
+            url: "https://example.com/",
+            webSocketDebuggerUrl: "ws://127.0.0.1:9222/devtools/page/tab-1",
+          },
+        ]),
+      );
+    class OversizedSocket extends EventTarget {
+      constructor() {
+        super();
+        queueMicrotask(() => this.dispatchEvent(new Event("open")));
+      }
+
+      send(source: string): void {
+        const request = JSON.parse(source) as { id: number };
+        queueMicrotask(() =>
+          this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify({ id: request.id, result: { result: { value: oversizedText } } }) })),
+        );
+      }
+
+      close(): void {}
+    }
+    globalThis.WebSocket = OversizedSocket as unknown as typeof WebSocket;
+    const context = await createBrowserSession();
+    try {
+      const outcome = await browserTool(context, "browser_read")
+        .execute("call-1", { targetId: "tab-1" }, undefined, undefined, {} as never)
+        .then(
+          () => "resolved" as const,
+          (error: unknown) => error,
+        );
+      expect(outcome).toBeInstanceOf(Error);
+      if (!(outcome instanceof Error)) throw new Error("Expected oversized response rejection");
+      expect(outcome.message).toMatch(/response exceeded the 12 MiB limit/iu);
+    } finally {
+      globalThis.fetch = originalFetch;
+      globalThis.WebSocket = OriginalWebSocket;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("rejects malformed DevTools JSON responses and closes the socket", async () => {
+    const originalFetch = globalThis.fetch;
+    const OriginalWebSocket = globalThis.WebSocket;
+    let closed = false;
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json([
+          {
+            id: "tab-1",
+            title: "Fixture",
+            type: "page",
+            url: "https://example.com/",
+            webSocketDebuggerUrl: "ws://127.0.0.1:9222/devtools/page/tab-1",
+          },
+        ]),
+      );
+    class MalformedSocket extends EventTarget {
+      constructor() {
+        super();
+        queueMicrotask(() => this.dispatchEvent(new Event("open")));
+      }
+
+      send(): void {
+        queueMicrotask(() => this.dispatchEvent(new MessageEvent("message", { data: "not json" })));
+      }
+
+      close(): void {
+        closed = true;
+      }
+    }
+    globalThis.WebSocket = MalformedSocket as unknown as typeof WebSocket;
+    vi.useFakeTimers();
+    const context = await createBrowserSession();
+    try {
+      const pending = browserTool(context, "browser_read").execute("call-1", { targetId: "tab-1" }, undefined, undefined, {} as never);
+      const outcomePromise = pending.then(
+        () => new Error("Browser command unexpectedly succeeded"),
+        (error: unknown) => error,
+      );
+
+      await vi.advanceTimersByTimeAsync(15_000);
+
+      const outcome = await outcomePromise;
+      expect(outcome).toBeInstanceOf(Error);
+      if (!(outcome instanceof Error)) throw new Error("Expected invalid JSON rejection");
+      expect(outcome.message).toMatch(/invalid JSON/iu);
+      expect(closed).toBe(true);
+    } finally {
+      vi.useRealTimers();
+      globalThis.fetch = originalFetch;
+      globalThis.WebSocket = OriginalWebSocket;
+      await context.fiber.dispose();
+    }
+  });
+
+  test.each([
+    [[{ id: 1, result: { result: { value: "text" } } }], /invalid response envelope/iu],
+    [{ id: 1, result: { result: { value: "text" } }, error: { message: "ambiguous" } }, /invalid response envelope/iu],
+    [{ id: 1, error: { code: -1 } }, /invalid error response/iu],
+    [{ id: 1, result: [] }, /invalid result response/iu],
+  ])("rejects malformed DevTools response envelopes immediately", async (envelope, expected) => {
+    const originalFetch = globalThis.fetch;
+    const OriginalWebSocket = globalThis.WebSocket;
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json([
+          {
+            id: "tab-1",
+            title: "Fixture",
+            type: "page",
+            url: "https://example.com/",
+            webSocketDebuggerUrl: "ws://127.0.0.1:9222/devtools/page/tab-1",
+          },
+        ]),
+      );
+    class EnvelopeSocket extends EventTarget {
+      constructor() {
+        super();
+        queueMicrotask(() => this.dispatchEvent(new Event("open")));
+      }
+
+      send(): void {
+        queueMicrotask(() => this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify(envelope) })));
+      }
+
+      close(): void {}
+    }
+    globalThis.WebSocket = EnvelopeSocket as unknown as typeof WebSocket;
+    vi.useFakeTimers();
+    const context = await createBrowserSession();
+    try {
+      const pending = browserTool(context, "browser_read").execute("call-1", { targetId: "tab-1" }, undefined, undefined, {} as never);
+      const outcomePromise = pending.then(
+        () => new Error("Malformed envelope unexpectedly succeeded"),
+        (error: unknown) => error,
+      );
+
+      await vi.advanceTimersByTimeAsync(15_000);
+
+      const outcome = await outcomePromise;
+      expect(outcome).toBeInstanceOf(Error);
+      if (!(outcome instanceof Error)) throw new Error("Expected malformed envelope rejection");
+      expect(outcome.message).toMatch(expected);
+      expect(outcome.message).not.toMatch(/timed out/iu);
+    } finally {
+      vi.useRealTimers();
+      globalThis.fetch = originalFetch;
+      globalThis.WebSocket = OriginalWebSocket;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("does not split a UTF-8 character at the browser text byte limit", async () => {
+    const originalFetch = globalThis.fetch;
+    const OriginalWebSocket = globalThis.WebSocket;
+    const prefix = "a".repeat(128 * 1024 - 1);
+    const pageText = `${prefix}😀`;
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json([
+          {
+            id: "tab-1",
+            title: "Fixture",
+            type: "page",
+            url: "https://example.com/",
+            webSocketDebuggerUrl: "ws://127.0.0.1:9222/devtools/page/tab-1",
+          },
+        ]),
+      );
+    class TextSocket extends EventTarget {
+      constructor() {
+        super();
+        queueMicrotask(() => this.dispatchEvent(new Event("open")));
+      }
+
+      send(source: string): void {
+        const request = JSON.parse(source) as { id: number };
+        queueMicrotask(() =>
+          this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify({ id: request.id, result: { result: { value: pageText } } }) })),
+        );
+      }
+
+      close(): void {}
+    }
+    globalThis.WebSocket = TextSocket as unknown as typeof WebSocket;
+    const context = await createBrowserSession();
+    try {
+      const result = await browserTool(context, "browser_read").execute("call-1", { targetId: "tab-1" }, undefined, undefined, {} as never);
+
+      const content = result.content[0];
+      if (content?.type !== "text") throw new Error("Expected browser text content");
+      expect(content.text.endsWith("�")).toBe(false);
+      expect(content.text.length).toBe(prefix.length);
+      expect(Buffer.byteLength(content.text, "utf8")).toBeLessThanOrEqual(128 * 1024);
+      expect(result.details).toMatchObject({ truncated: true });
+      expect((result.details as { text: string }).text).toBe(content.text);
+    } finally {
+      globalThis.fetch = originalFetch;
+      globalThis.WebSocket = OriginalWebSocket;
+      await context.fiber.dispose();
+    }
+  });
+
+  test("does not expose mutable session state through tool results", async () => {
+    const originalFetch = globalThis.fetch;
+    const OriginalWebSocket = globalThis.WebSocket;
+    globalThis.fetch = () =>
+      Promise.resolve(
+        Response.json([
+          {
+            id: "tab-1",
+            title: "Fixture",
+            type: "page",
+            url: "https://example.com/",
+            webSocketDebuggerUrl: "ws://127.0.0.1:9222/devtools/page/tab-1",
+          },
+        ]),
+      );
+    class ClickSocket extends EventTarget {
+      constructor() {
+        super();
+        queueMicrotask(() => this.dispatchEvent(new Event("open")));
+      }
+
+      send(source: string): void {
+        const request = JSON.parse(source) as { id: number };
+        queueMicrotask(() =>
+          this.dispatchEvent(new MessageEvent("message", { data: JSON.stringify({ id: request.id, result: { result: { value: true } } }) })),
+        );
+      }
+
+      close(): void {}
+    }
+    globalThis.WebSocket = ClickSocket as unknown as typeof WebSocket;
+    const context = await createBrowserSession();
+    try {
+      const result = await browserTool(context, "browser_click").execute(
+        "call-1",
+        { targetId: "tab-1", selector: "#button" },
+        undefined,
+        undefined,
+        {} as never,
+      );
+
+      (result.details as { title: string }).title = "mutated";
+
+      await expect(context.piPluginUi.snapshot()).resolves.toMatchObject([{ id: "browser-session-panel", data: { latest: { title: "Fixture" } } }]);
+      const panel = (await context.piPluginUi.snapshot())[0];
+      if (panel === undefined) throw new Error("Browser session panel was not registered");
+      (panel.data as { latest: { title: string } }).latest.title = "panel-mutated";
+
+      await expect(context.piPluginUi.snapshot()).resolves.toMatchObject([{ id: "browser-session-panel", data: { latest: { title: "Fixture" } } }]);
+      globalThis.fetch = () => Promise.resolve(new Response("unavailable", { status: 503 }));
+      await expect(context.piPluginUi.snapshot()).resolves.toMatchObject([
+        { id: "browser-session-panel", data: { connected: false, latest: { title: "Fixture" }, error: "Chrome DevTools returned HTTP 503" } },
+      ]);
+    } finally {
+      globalThis.fetch = originalFetch;
+      globalThis.WebSocket = OriginalWebSocket;
+      await context.fiber.dispose();
+    }
+  });
+});