docs: document web runtime tests

src/agents/tools/web-fetch-visibility.test.ts

@@ -1,3 +1,5 @@
+// web_fetch visibility tests cover hidden HTML and invisible Unicode stripping
+// before extracted content reaches the model.
 import { describe, expect, it } from "vitest";
 import { sanitizeHtml, stripInvisibleUnicode } from "./web-fetch-visibility.js";
 
@@ -196,6 +198,8 @@ describe("sanitizeHtml", () => {
   });
 
   it("drops nested hidden same-name elements without leaking trailing hidden text", async () => {
+    // Malformed hidden regions are prompt-injection territory; nested tags must
+    // not leak trailing hidden text after the inner close tag.
     const html = "<p>Visible</p><div hidden><div>Nested hidden</div>Still hidden</div><p>Shown</p>";
     const result = await sanitizeHtml(html);
     expect(result).toContain("Visible");
@@ -237,6 +241,8 @@ describe("stripInvisibleUnicode", () => {
   });
 
   it("strips directional overrides (LRO, RLO, PDF, etc.)", () => {
+    // Directional controls can make visible text render differently from the
+    // byte sequence the model sees.
     const text = "\u202AHello\u202E";
     expect(stripInvisibleUnicode(text)).toBe("Hello");
   });

src/agents/tools/web-fetch.ssrf.test.ts

@@ -1,3 +1,5 @@
+// web_fetch SSRF tests cover URL, DNS, redirect, and proxy policy enforcement
+// before network requests reach fetch or provider fallbacks.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import * as ssrf from "../../infra/net/ssrf.js";
 import { type FetchMock, withFetchPreconnect } from "../../test-utils/fetch-mock.js";
@@ -139,6 +141,8 @@ describe("web_fetch SSRF protection", () => {
   });
 
   it("blocks redirects to private hosts", async () => {
+    // Redirect targets are new network destinations and must be re-checked
+    // against the same SSRF policy as the original URL.
     lookupMock.mockResolvedValue([{ address: "93.184.216.34", family: 4 }]);
 
     const fetchSpy = setMockFetch().mockResolvedValueOnce(
@@ -163,6 +167,8 @@ describe("web_fetch SSRF protection", () => {
   });
 
   it("allows RFC2544 benchmark-range URLs only when web_fetch ssrfPolicy opts in", async () => {
+    // Benchmark ranges are fake-IP infrastructure in some deployments, but
+    // remain denied unless the web_fetch config opts in.
     const url = "http://198.18.0.153/file";
     lookupMock.mockResolvedValue([{ address: "198.18.0.153", family: 4 }]);
 

src/agents/tools/web-search-provider-credentials.test.ts

@@ -1,3 +1,5 @@
+// Web search credential tests cover precedence between configured credentials,
+// SecretRefs, and ambient environment fallbacks.
 import { describe, expect, it } from "vitest";
 import { withEnv } from "../../test-utils/env.js";
 import { resolveWebSearchProviderCredential } from "./web-search-provider-credentials.js";
@@ -32,6 +34,8 @@ describe("resolveWebSearchProviderCredential", () => {
   });
 
   it("does not override missing env SecretRefs with ambient env fallback", () => {
+    // An explicit SecretRef means "use this credential"; falling back to a
+    // different env var can silently route requests through the wrong account.
     withEnv(
       { TEST_WEB_SEARCH_REF_KEY: undefined, TEST_WEB_SEARCH_KEY: "ambient-test-value" },
       () => {

src/agents/tools/web-search.late-bind.test.ts

@@ -1,3 +1,5 @@
+// web_search late-binding tests cover runtime config and provider metadata
+// selection at execution time.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { createWebSearchTool } from "./web-search.js";
 
@@ -136,6 +138,8 @@ describe("web_search late-bound runtime fallback", () => {
   });
 
   it("prefers active runtime metadata over options.runtimeWebSearch when present", async () => {
+    // Active runtime metadata reflects the newest credential snapshot; fallback
+    // options only cover tools created before that state exists.
     mocks.getActiveRuntimeWebToolsMetadata.mockReturnValue({
       search: {
         selectedProvider: "perplexity",
@@ -161,6 +165,8 @@ describe("web_search late-bound runtime fallback", () => {
   });
 
   it("honors late-bound disabled search config at execute time", async () => {
+    // A long-lived tool must still observe an operator disabling web_search
+    // before the next call is dispatched.
     mocks.getActiveSecretsRuntimeConfigSnapshot.mockReturnValue({
       config: { tools: { web: { search: { enabled: false } } } },
     });