@pi-harness/pi-harness 0.1.13 → 0.1.14

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

@@ -0,0 +1,844 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { createServer, type ServerResponse } from "node:http";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Context } from "@deepseek-ai/cordis";
+import { describe, expect, test } from "vitest";
+import browserFetchPlugin from "../src/plugins/browser-fetch.js";
+import { PiPluginUiRegistry, PiToolRegistry, provideLaunchContext } from "../src/services.js";
+
+describe("browser-fetch", () => {
+  test("declares the URL length bounds in the tool schema", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin);
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+
+      expect(tool?.executionMode).toBe("sequential");
+      expect(tool?.parameters).toMatchObject({
+        type: "object",
+        additionalProperties: false,
+        properties: { url: { type: "string", minLength: 1, maxLength: 4096 } },
+      });
+    } finally {
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("rolls back the tool when panel registration fails", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const panels = new PiPluginUiRegistry();
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", panels);
+      panels.register({ id: "browser-fetch-panel", pluginId: "fixture", title: "Fixture", read: () => ({}) });
+      await expect(context.plugin(browserFetchPlugin)).rejects.toThrow(/already registered.*browser-fetch-panel/iu);
+      expect(tools.snapshot().customTools).toEqual([]);
+    } finally {
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("declares bounded integer request timeouts in the plugin config schema", () => {
+    expect(browserFetchPlugin.Config.dict?.timeoutMs?.meta).toMatchObject({ default: 20_000, min: 100, max: 60_000, step: 1 });
+  });
+
+  test("rejects a non-finite request timeout during config validation", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", new PiToolRegistry());
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+
+      await expect(context.plugin(browserFetchPlugin, { timeoutMs: Number.NaN })).rejects.toThrow(/invalid config/iu);
+    } finally {
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("rejects a non-string URL with a stable validation error", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin);
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+
+      await expect(tool.execute("fetch", { url: null }, undefined, undefined, {} as never)).rejects.toThrow(/URL must be a string/iu);
+      await expect(tool.execute("fetch", null, undefined, undefined, {} as never)).rejects.toThrow(/URL must be a string/iu);
+    } finally {
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("validates raw tool parameters without invoking accessors", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    let accessed = false;
+    const params = {} as { url?: string };
+    Object.defineProperty(params, "url", {
+      enumerable: true,
+      get() {
+        accessed = true;
+        throw new Error("browser URL accessor executed");
+      },
+    });
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin);
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+
+      await expect(tool.execute("accessor", params, undefined, undefined, {} as never)).rejects.toThrow(/parameters.*data properties/iu);
+      expect(accessed).toBe(false);
+    } finally {
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("rejects unknown raw tool parameters", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin);
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+
+      await expect(tool.execute("unknown", { url: "file:///etc/passwd", unexpected: true }, undefined, undefined, {} as never)).rejects.toThrow(
+        /parameters.*unknown property/iu,
+      );
+    } finally {
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("does not expose mutable fetch state through tool results", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const panels = new PiPluginUiRegistry();
+    const server = createServer((_request, response) => {
+      response.writeHead(200, { "content-type": "text/plain" });
+      response.end("original");
+    });
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    try {
+      const address = server.address();
+      if (address === null || typeof address === "string") throw new Error("Browser fetch test server did not bind to a port");
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", panels);
+      await context.plugin(browserFetchPlugin, { allowPrivate: true });
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+      const result = await tool.execute("fetch", { url: `http://127.0.0.1:${address.port}/` }, undefined, undefined, {} as never);
+
+      (result.details as { text: string }).text = "mutated";
+
+      await expect(panels.snapshot()).resolves.toMatchObject([{ id: "browser-fetch-panel", data: { latest: { text: "original" } } }]);
+    } finally {
+      await context.fiber.dispose();
+      await new Promise<void>((resolve, reject) => server.close((error) => (error === undefined ? resolve() : reject(error))));
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("does not expose mutable fetch state through panel snapshots", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const panels = new PiPluginUiRegistry();
+    const server = createServer((_request, response) => {
+      response.writeHead(200, { "content-type": "text/plain" });
+      response.end("original");
+    });
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    try {
+      const address = server.address();
+      if (address === null || typeof address === "string") throw new Error("Browser fetch test server did not bind to a port");
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", panels);
+      await context.plugin(browserFetchPlugin, { allowPrivate: true });
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+      await tool.execute("fetch", { url: `http://127.0.0.1:${address.port}/` }, undefined, undefined, {} as never);
+      const firstPanel = (await panels.snapshot())[0];
+      if (firstPanel === undefined) throw new Error("browser-fetch-panel was not registered");
+
+      (firstPanel.data as { latest: { text: string } }).latest.text = "mutated";
+
+      await expect(panels.snapshot()).resolves.toMatchObject([{ id: "browser-fetch-panel", data: { latest: { text: "original" } } }]);
+    } finally {
+      await context.fiber.dispose();
+      await new Promise<void>((resolve, reject) => server.close((error) => (error === undefined ? resolve() : reject(error))));
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("aborts a response body when the tool call is cancelled", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    let activeResponse: ServerResponse | undefined;
+    let markHeadersSent!: () => void;
+    const headersSent = new Promise<void>((resolve) => {
+      markHeadersSent = resolve;
+    });
+    const server = createServer((_request, response) => {
+      activeResponse = response;
+      response.writeHead(200, { "content-type": "text/plain" });
+      response.write("partial");
+      markHeadersSent();
+    });
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    try {
+      const address = server.address();
+      if (address === null || typeof address === "string") throw new Error("Browser fetch test server did not bind to a port");
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin, { allowPrivate: true });
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+      const caller = new AbortController();
+      const execution = tool.execute("fetch", { url: `http://127.0.0.1:${address.port}/` }, caller.signal, undefined, {} as never);
+      await headersSent;
+
+      caller.abort(new Error("cancelled by test"));
+      activeResponse?.end("done");
+
+      await expect(execution).rejects.toThrow(/cancelled by test/iu);
+    } finally {
+      activeResponse?.end();
+      await context.fiber.dispose();
+      await new Promise<void>((resolve, reject) => server.close((error) => (error === undefined ? resolve() : reject(error))));
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("does not start a fetch when the tool call is already cancelled", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const originalFetch = globalThis.fetch;
+    let requests = 0;
+    globalThis.fetch = () => {
+      requests += 1;
+      return Promise.resolve(new Response("unexpected"));
+    };
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin);
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+      const caller = new AbortController();
+      caller.abort(new Error("cancelled before fetch"));
+
+      await expect(tool.execute("fetch", { url: "https://1.1.1.1/" }, caller.signal, undefined, {} as never)).rejects.toThrow(/cancelled before fetch/iu);
+      expect(requests).toBe(0);
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("times out a stalled response body", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    let activeResponse: ServerResponse | undefined;
+    let fallback: ReturnType<typeof setTimeout> | undefined;
+    const server = createServer((_request, response) => {
+      activeResponse = response;
+      response.writeHead(200, { "content-type": "text/plain" });
+      response.write("partial");
+      fallback = setTimeout(() => response.end("fallback"), 500);
+    });
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    try {
+      const address = server.address();
+      if (address === null || typeof address === "string") throw new Error("Browser fetch test server did not bind to a port");
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin, { allowPrivate: true, timeoutMs: 100 });
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+
+      await expect(tool.execute("fetch", { url: `http://127.0.0.1:${address.port}/` }, undefined, undefined, {} as never)).rejects.toThrow(
+        /timed out after 100 ms/iu,
+      );
+    } finally {
+      if (fallback !== undefined) clearTimeout(fallback);
+      activeResponse?.end();
+      await context.fiber.dispose();
+      await new Promise<void>((resolve, reject) => server.close((error) => (error === undefined ? resolve() : reject(error))));
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("aborts an in-flight fetch when the plugin is disposed", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    let activeResponse: ServerResponse | undefined;
+    let markHeadersSent!: () => void;
+    const headersSent = new Promise<void>((resolve) => {
+      markHeadersSent = resolve;
+    });
+    const server = createServer((_request, response) => {
+      activeResponse = response;
+      response.writeHead(200, { "content-type": "text/plain" });
+      response.write("partial");
+      markHeadersSent();
+    });
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    try {
+      const address = server.address();
+      if (address === null || typeof address === "string") throw new Error("Browser fetch test server did not bind to a port");
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin, { allowPrivate: true });
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+      const execution = tool.execute("fetch", { url: `http://127.0.0.1:${address.port}/` }, undefined, undefined, {} as never);
+      await headersSent;
+
+      await context.fiber.dispose();
+      activeResponse?.end("done");
+
+      await expect(execution).rejects.toThrow(/disposed/iu);
+    } finally {
+      activeResponse?.end();
+      await context.fiber.dispose();
+      await new Promise<void>((resolve, reject) => server.close((error) => (error === undefined ? resolve() : reject(error))));
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("rejects non-public IPv6 literal ranges before fetching", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin, { timeoutMs: 100 });
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+
+      for (const url of [
+        "http://[::]/",
+        "http://[ff02::1]/",
+        "http://[::ffff:7f00:1]/",
+        "http://[100:0:0:1::1]/",
+        "http://[2001:100::1]/",
+        "http://[2001:db8::1]/",
+        "http://[2002:7f00:1::]/",
+        "http://[3fff::1]/",
+        "http://[4000::1]/",
+        "http://[5f00::1]/",
+      ]) {
+        await expect(tool.execute("fetch", { url }, undefined, undefined, {} as never)).rejects.toThrow(/private or local network/iu);
+      }
+    } finally {
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("allows globally reachable IPv6 special-purpose ranges", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = () => Promise.resolve(new Response("public"));
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin);
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+
+      for (const url of ["http://[2001:1::1]/", "http://[2001:3::1]/", "http://[2001:4:112::1]/", "http://[2001:20::1]/", "http://[2001:30::1]/"]) {
+        await expect(tool.execute("fetch", { url }, undefined, undefined, {} as never)).resolves.toMatchObject({ details: { text: "public" } });
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("rejects non-public IPv4 literal ranges before fetching", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin);
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+
+      for (const address of ["0.0.0.0", "100.64.0.1", "192.0.2.1", "198.51.100.1", "203.0.113.1", "224.0.0.1"]) {
+        await expect(tool.execute("fetch", { url: `http://${address}/` }, undefined, undefined, {} as never)).rejects.toThrow(/private or local network/iu);
+      }
+    } finally {
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("allows globally reachable IPv4 special-purpose ranges", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = () => Promise.resolve(new Response("public"));
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin);
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+
+      for (const url of ["http://192.0.0.9/", "http://192.0.0.10/"]) {
+        await expect(tool.execute("fetch", { url }, undefined, undefined, {} as never)).resolves.toMatchObject({ details: { text: "public" } });
+      }
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("rejects invalid URL protocols, credentials, and lengths", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin);
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+
+      await expect(tool.execute("empty", { url: "" }, undefined, undefined, {} as never)).rejects.toThrow(/between 1 and 4096/iu);
+      await expect(tool.execute("long", { url: "x".repeat(4_097) }, undefined, undefined, {} as never)).rejects.toThrow(/between 1 and 4096/iu);
+      await expect(tool.execute("protocol", { url: "file:///etc/passwd" }, undefined, undefined, {} as never)).rejects.toThrow(/http and https/iu);
+      await expect(tool.execute("credentials", { url: "https://user:secret@example.com/" }, undefined, undefined, {} as never)).rejects.toThrow(
+        /must not contain credentials/iu,
+      );
+    } finally {
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("blocks a redirect to a private target before making the next request", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const originalFetch = globalThis.fetch;
+    let requests = 0;
+    let cancelled = false;
+    globalThis.fetch = () => {
+      requests += 1;
+      return Promise.resolve(
+        new Response(
+          new ReadableStream({
+            cancel() {
+              cancelled = true;
+            },
+          }),
+          { status: 302, headers: { location: "http://127.0.0.1/private" } },
+        ),
+      );
+    };
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin);
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+
+      await expect(tool.execute("fetch", { url: "https://1.1.1.1/start" }, undefined, undefined, {} as never)).rejects.toThrow(/private or local network/iu);
+      expect(requests).toBe(1);
+      expect(cancelled).toBe(true);
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("returns non-redirect 3xx responses without requiring a Location header", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = () => Promise.resolve(new Response(null, { status: 304 }));
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin);
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+
+      await expect(tool.execute("not-modified", { url: "https://1.1.1.1/page" }, undefined, undefined, {} as never)).resolves.toMatchObject({
+        details: { status: 304, text: "", truncated: false },
+      });
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("rejects and cancels non-text response bodies", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const originalFetch = globalThis.fetch;
+    let cancelled = false;
+    let sent = false;
+    globalThis.fetch = () =>
+      Promise.resolve(
+        new Response(
+          new ReadableStream({
+            pull(controller) {
+              if (sent) return;
+              sent = true;
+              controller.enqueue(new Uint8Array([0, 1, 2, 3]));
+              controller.close();
+            },
+            cancel() {
+              cancelled = true;
+            },
+          }),
+          { headers: { "content-type": "application/octet-stream" } },
+        ),
+      );
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin);
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+
+      await expect(tool.execute("binary", { url: "https://1.1.1.1/archive" }, undefined, undefined, {} as never)).rejects.toThrow(
+        /unsupported content type.*application\/octet-stream/iu,
+      );
+      expect(cancelled).toBe(true);
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("rejects text responses with invalid UTF-8 instead of replacing bytes", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = () =>
+      Promise.resolve(
+        new Response(new Uint8Array([0xc3, 0x28]), {
+          headers: { "content-type": "text/plain; charset=utf-8" },
+        }),
+      );
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin);
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+
+      await expect(tool.execute("invalid-utf8", { url: "https://1.1.1.1/page" }, undefined, undefined, {} as never)).rejects.toThrow(/not valid utf-8/iu);
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("cancels a redirect response body when the Location header is missing", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const originalFetch = globalThis.fetch;
+    let cancelled = false;
+    globalThis.fetch = () =>
+      Promise.resolve(
+        new Response(
+          new ReadableStream({
+            cancel() {
+              cancelled = true;
+            },
+          }),
+          { status: 302 },
+        ),
+      );
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin);
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+
+      await expect(tool.execute("fetch", { url: "https://1.1.1.1/start" }, undefined, undefined, {} as never)).rejects.toThrow(/no Location header/iu);
+      expect(cancelled).toBe(true);
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("follows relative redirects and enforces the redirect limit", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const originalFetch = globalThis.fetch;
+    const requestedUrls: string[] = [];
+    let redirectBodiesCancelled = 0;
+    globalThis.fetch = (input) => {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+      requestedUrls.push(url);
+      if (url.endsWith("/start")) {
+        return Promise.resolve(
+          new Response(
+            new ReadableStream({
+              cancel() {
+                redirectBodiesCancelled += 1;
+              },
+            }),
+            { status: 302, headers: { location: "/next" } },
+          ),
+        );
+      }
+      if (url.endsWith("/next")) return Promise.resolve(new Response("done", { status: 200, headers: { "content-type": "text/plain" } }));
+      return Promise.resolve(
+        new Response(
+          new ReadableStream({
+            cancel() {
+              redirectBodiesCancelled += 1;
+            },
+          }),
+          { status: 302, headers: { location: "/loop" } },
+        ),
+      );
+    };
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin);
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+
+      await expect(tool.execute("relative", { url: "https://1.1.1.1/start" }, undefined, undefined, {} as never)).resolves.toMatchObject({
+        details: { finalUrl: "https://1.1.1.1/next", text: "done" },
+      });
+      await expect(tool.execute("limit", { url: "https://1.1.1.1/loop" }, undefined, undefined, {} as never)).rejects.toThrow(
+        /exceeded the 3-redirect limit/iu,
+      );
+      expect(requestedUrls).toEqual([
+        "https://1.1.1.1/start",
+        "https://1.1.1.1/next",
+        "https://1.1.1.1/loop",
+        "https://1.1.1.1/loop",
+        "https://1.1.1.1/loop",
+        "https://1.1.1.1/loop",
+      ]);
+      expect(redirectBodiesCancelled).toBe(5);
+    } finally {
+      globalThis.fetch = originalFetch;
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("enforces the response byte limit at its exact boundary", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const server = createServer((request, response) => {
+      response.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+      response.end(Buffer.alloc(request.url === "/exact" ? 512 * 1024 : 512 * 1024 + 1, 0x61));
+    });
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    try {
+      const address = server.address();
+      if (address === null || typeof address === "string") throw new Error("Browser fetch test server did not bind to a port");
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", new PiPluginUiRegistry());
+      await context.plugin(browserFetchPlugin, { allowPrivate: true });
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+
+      await expect(tool.execute("exact", { url: `http://127.0.0.1:${address.port}/exact` }, undefined, undefined, {} as never)).resolves.toMatchObject({
+        details: { bytes: 512 * 1024, contentType: "text/plain", truncated: false },
+      });
+      const oversized = await tool.execute("oversized", { url: `http://127.0.0.1:${address.port}/oversized` }, undefined, undefined, {} as never);
+      expect(oversized.details).toMatchObject({ bytes: 512 * 1024, contentType: "text/plain", truncated: true });
+      expect((oversized.details as { text: string }).text).toHaveLength(512 * 1024);
+    } finally {
+      await context.fiber.dispose();
+      await new Promise<void>((resolve, reject) => server.close((error) => (error === undefined ? resolve() : reject(error))));
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("publishes a bounded text preview to the plugin panel", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const panels = new PiPluginUiRegistry();
+    const server = createServer((_request, response) => {
+      response.writeHead(200, { "content-type": "text/plain" });
+      response.end("x".repeat(12_001));
+    });
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    try {
+      const address = server.address();
+      if (address === null || typeof address === "string") throw new Error("Browser fetch test server did not bind to a port");
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", panels);
+      await context.plugin(browserFetchPlugin, { allowPrivate: true });
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+
+      const result = await tool.execute("panel-preview", { url: `http://127.0.0.1:${address.port}/` }, undefined, undefined, {} as never);
+      expect((result.details as { text: string }).text).toHaveLength(12_001);
+      const snapshot = await panels.snapshot();
+      expect((snapshot[0]?.data as { latest: { text: string } }).latest.text).toHaveLength(12_000);
+      expect(snapshot).toMatchObject([{ data: { latest: { previewTruncated: true }, maxPanelTextChars: 12_000 } }]);
+    } finally {
+      await context.fiber.dispose();
+      await new Promise<void>((resolve, reject) => server.close((error) => (error === undefined ? resolve() : reject(error))));
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("preserves the last successful result when a later fetch fails", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const panels = new PiPluginUiRegistry();
+    const server = createServer((_request, response) => response.end("original"));
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    try {
+      const address = server.address();
+      if (address === null || typeof address === "string") throw new Error("Browser fetch test server did not bind to a port");
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", panels);
+      await context.plugin(browserFetchPlugin, { allowPrivate: true });
+      const tool = tools.snapshot().customTools.find((candidate) => candidate.name === "browser_fetch");
+      if (tool === undefined) throw new Error("browser_fetch was not registered");
+      await tool.execute("success", { url: `http://127.0.0.1:${address.port}/` }, undefined, undefined, {} as never);
+
+      await expect(tool.execute("failure", { url: "file:///etc/passwd" }, undefined, undefined, {} as never)).rejects.toThrow(/http and https/iu);
+      await expect(panels.snapshot()).resolves.toMatchObject([{ id: "browser-fetch-panel", data: { latest: { text: "original" } } }]);
+    } finally {
+      await context.fiber.dispose();
+      await new Promise<void>((resolve, reject) => server.close((error) => (error === undefined ? resolve() : reject(error))));
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  test("unregisters its tool and panel on disposal", async () => {
+    const root = await mkdtemp(join(tmpdir(), "pi-harness-browser-fetch-"));
+    const context = new Context();
+    const tools = new PiToolRegistry();
+    const panels = new PiPluginUiRegistry();
+    try {
+      provideLaunchContext(context, { cwd: root, agentDir: root, args: [], requestExit() {} });
+      context.provide("piTools", tools);
+      context.provide("piPluginUi", panels);
+      await context.plugin(browserFetchPlugin);
+      expect(tools.snapshot().customTools.map((tool) => tool.name)).toEqual(["browser_fetch"]);
+      await expect(panels.snapshot()).resolves.toMatchObject([
+        { id: "browser-fetch-panel", data: { latest: null, allowPrivate: false, maxResponseBytes: 512 * 1024, timeoutMs: 20_000 } },
+      ]);
+
+      await context.fiber.dispose();
+
+      expect(tools.snapshot().customTools).toEqual([]);
+      await expect(panels.snapshot()).resolves.toEqual([]);
+    } finally {
+      await context.fiber.dispose();
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+});