@akanjs/devkit 3.1.0-rc.8 → 3.1.0

package/codeAgent/skills/akan-store/SKILL.md

@@ -19,14 +19,16 @@ For a model `comment` (`<Slice>` is a signal slice suffix, e.g. `InPublic`):
   `add<Field>OnComment(value)` / `sub<Field>OnComment(idx)` for arrays, `upload<Field>OnComment(fileList)`
   for file fields, `checkCommentSubmitable()`, `submitComment()`, `createCommentInForm()`,
   `updateCommentInForm()`
-- single: `viewComment(model)`, `mergeComment(model, data)`, `setComment(...models)`, `resetComment()`
+- single: `viewComment(model)`, `mergeComment(model, data)`, `setComment(...models)`, `resetComment()`,
+  `invalidateComment()` (marks every slice stale after a custom mutation, so the next mount refetches)
 - per slice: `initComment<Slice>(...args)`, `refreshComment<Slice>()`, `selectComment<Slice>(model)`,
   `setPageOfComment<Slice>(page)`, `loadMoreOfComment<Slice>()`, `setLimitOfComment<Slice>(limit)`,
   `setQueryArgsOfComment<Slice>(...)`, `setSortOfComment<Slice>(sort)`
 
 ## Generated state — `st.use.*`
 
-`comment`, `commentLoading`, `commentForm`, `commentFormLoading`, `commentSubmit`, `commentModal`,
+`comment`, `commentLoading`, `commentForm`, `commentFormLoading`, `commentFormUploading` (uploads in flight, per
+`File` field — non-empty means do not submit), `commentSubmit`, `commentModal`,
 `commentViewAt`, `commentOperation`; per slice `commentList<Slice>`, `commentListLoading<Slice>`,
 `commentInitList<Slice>`, `commentSelection<Slice>`, `commentInsight<Slice>`, `pageOfComment<Slice>`,
 `lastPageOfComment<Slice>`, `hasMoreOfComment<Slice>`, `limitOfComment<Slice>`, `sortOfComment<Slice>`.

package/codeAgent/tools/AkanCodePlugins.ts

@@ -10,6 +10,7 @@ import { TurnFeedback, type TurnFeedbackSource } from "../feedback/TurnFeedback"
 import { VerifyFeedback } from "../feedback/VerifyFeedback";
 import { AkanToolPack } from "./AkanToolPack";
 import { AskToolPack } from "./AskToolPack";
+import type { DeepSeekWeb } from "./DeepSeekWeb";
 import { MailToolPack } from "./MailToolPack";
 import { McpToolPack } from "./McpToolPack";
 import { SessionToolPack } from "./SessionToolPack";
@@ -22,6 +23,7 @@ export interface AkanCodePluginsOptions {
   /** Apps whose dev server should be watched, and whose page should be probed. */
   apps: string[];
   canSeeImages: boolean;
+  deepseek?: DeepSeekWeb | undefined;
   /** How many `task` levels deep the owning agent is. */
   depth: number;
   /** The tally of the sub-agent tree the owning agent belongs to, when a `task` opened it. */
@@ -56,7 +58,7 @@ export class AkanCodePlugins {
     });
     const dispose = () => mcp?.close();
     const mcpStatus = mcp?.status ?? [];
-    const web = new WebToolPack({ profile: options.profile });
+    const web = new WebToolPack({ profile: options.profile, deepseek: options.deepseek });
     const sessions = new SessionToolPack({
       workspaceRoot: options.workspace.workspaceRoot,
       cwd: options.cwd,

package/codeAgent/tools/DeepSeekWeb.ts

@@ -0,0 +1,127 @@
+import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import { codeAgentClip } from "akanjs/common";
+
+interface DeepSeekSearchResult {
+  title: string;
+  url: string;
+  snippet?: string;
+  summary?: string;
+  date?: string | null;
+}
+
+export interface DeepSeekPage {
+  title: string;
+  content: string;
+}
+
+export class DeepSeekWeb {
+  static readonly baseUrl = "https://api.deepseek.com/v1/tools";
+  static readonly maxQueryChars = 128;
+  static readonly summaryChars = 600;
+  // Only a successful call is billed, so a retry costs nothing. Search has no fallback and waits out every transient
+  // status; fetch waits only on its quota and otherwise falls back to a direct read, which beats DeepSeek's 504.
+  static readonly #retryable: { [tool in "search" | "fetch"]: number[] } = {
+    search: [408, 429, 500, 502, 503, 504],
+    fetch: [429],
+  };
+  static readonly #attempts = 3;
+
+  readonly #key: string;
+  readonly #baseUrl: string;
+
+  constructor(key: string, baseUrl = DeepSeekWeb.baseUrl) {
+    this.#key = key;
+    this.#baseUrl = baseUrl;
+  }
+
+  /** Undefined behind a proxy, where the runtime holds only a placeholder and the real key stays with the host. */
+  static async fromRuntime(runtime: ModelRuntime, proxied: boolean) {
+    if (proxied) return undefined;
+    const key = (await runtime.getAuth("deepseek").catch(() => undefined))?.auth.apiKey;
+    return key ? new DeepSeekWeb(key) : undefined;
+  }
+
+  async search(query: string, count: number, signal?: AbortSignal) {
+    if ([...query].length > DeepSeekWeb.maxQueryChars)
+      throw new Error(`DeepSeek search takes at most ${DeepSeekWeb.maxQueryChars} characters; shorten the query.`);
+    const body = await this.#call<{ results?: DeepSeekSearchResult[] }>("search", { query, count }, 20_000, signal);
+    const byUrl = new Map<string, DeepSeekSearchResult>();
+    for (const result of body.results ?? []) {
+      const url = DeepSeekWeb.#cleanUrl(result.url);
+      if (!byUrl.has(url)) byUrl.set(url, { ...result, url });
+    }
+    return [...byUrl.values()]
+      .map((result) => {
+        const date = result.date ? ` · ${result.date.slice(0, 10)}` : "";
+        const summary = DeepSeekWeb.unescape(result.summary || result.snippet || "")
+          .replace(/\s+/g, " ")
+          .trim();
+        return `- ${result.title}\n  ${result.url}${date}\n  ${codeAgentClip(summary, DeepSeekWeb.summaryChars)}`;
+      })
+      .join("\n");
+  }
+
+  async fetch(url: string, signal?: AbortSignal): Promise<DeepSeekPage> {
+    const page = await this.#call<{ title?: string; content?: string }>("fetch", { url }, 30_000, signal);
+    return { title: page.title ?? "", content: DeepSeekWeb.unescape(page.content ?? "") };
+  }
+
+  // Fetch escapes every ASCII punctuation mark, structure included (`\#\# Title`, `foo\(\)`), which costs tokens
+  // and garbles code. Undone only when nearly all punctuation is escaped, so a page already clean keeps its `\.`.
+  static unescape(markdown: string) {
+    const escaped = markdown.match(/\\[!-/:-@[-`{-~]/g)?.length ?? 0;
+    const punctuation = markdown.match(/[!-/:-@[-`{-~]/g)?.length ?? 0;
+    if (!escaped || escaped < (punctuation - escaped) / 2) return markdown;
+    return markdown.replace(/\\([!-/:-@[-`{-~])/g, "$1");
+  }
+
+  async #call<T>(tool: "search" | "fetch", body: object, timeoutMs: number, signal?: AbortSignal): Promise<T> {
+    for (let attempt = 1; ; attempt++) {
+      const response = await fetch(`${this.#baseUrl}/${tool}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${this.#key}`, "content-type": "application/json" },
+        body: JSON.stringify(body),
+        signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs),
+      });
+      if (response.ok) return (await response.json()) as T;
+      if (!DeepSeekWeb.#retryable[tool].includes(response.status) || attempt >= DeepSeekWeb.#attempts) {
+        const error = (await response.json().catch(() => undefined)) as { error?: { message?: string } } | undefined;
+        throw new Error(
+          `DeepSeek ${tool} answered ${response.status}: ${error?.error?.message ?? response.statusText}`,
+        );
+      }
+      await DeepSeekWeb.#wait(DeepSeekWeb.#delayOf(response, attempt), signal);
+    }
+  }
+
+  static #delayOf(response: Response, attempt: number) {
+    const retryAfter = Number(response.headers.get("retry-after"));
+    return Number.isFinite(retryAfter) && retryAfter > 0 ? Math.min(retryAfter, 5) * 1000 : 1000 * 2 ** (attempt - 1);
+  }
+
+  static #wait(ms: number, signal?: AbortSignal) {
+    return new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, ms);
+      signal?.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(timer);
+          resolve();
+        },
+        { once: true },
+      );
+    });
+  }
+
+  /** Drops the tracking parameters and the bare `#1` chunk marker DeepSeek appends to result URLs. */
+  static #cleanUrl(url: string) {
+    try {
+      const parsed = new URL(url);
+      for (const name of [...parsed.searchParams.keys()]) if (name.startsWith("utm_")) parsed.searchParams.delete(name);
+      if (/^#\d+$/.test(parsed.hash)) parsed.hash = "";
+      return parsed.toString();
+    } catch {
+      return url;
+    }
+  }
+}

package/codeAgent/tools/WebToolPack.ts

@@ -1,9 +1,15 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
 import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
-import { type CodeAgentProfile, codeAgentClip, codeAgentOutputChars } from "akanjs/common";
+import { type CodeAgentProfile, codeAgentClip } from "akanjs/common";
 import { Type } from "typebox";
+import { DeepSeekWeb } from "./DeepSeekWeb";
 
 export interface WebToolPackOptions {
   profile: CodeAgentProfile;
+  /** Serves search after any key-named provider, and reads public pages to Markdown ahead of a direct fetch. */
+  deepseek?: DeepSeekWeb | undefined;
+  lookup?: ((host: string) => Promise<string[]>) | undefined;
 }
 
 interface SearchProvider {
@@ -12,9 +18,27 @@ interface SearchProvider {
   search(key: string, query: string, count: number): Promise<string>;
 }
 
+interface WebSearcher {
+  name: string;
+  search(query: string, count: number, signal?: AbortSignal): Promise<string>;
+}
+
+interface WebPage {
+  status: number;
+  ok: boolean;
+  title: string;
+  text: string;
+}
+
 // web_search only with a provider key set: a tool that can never work costs prompt tokens and invites retries.
 export class WebToolPack {
+  static readonly pageChars = 10_000;
+  static readonly maxResults = 10;
+  static readonly #rememberedPages = 16;
   readonly #options: WebToolPackOptions;
+  // A continuation reads the snapshot its first page came from; a fresh read always refetches, since a local dev
+  // page changes between edits.
+  readonly #pages = new Map<string, WebPage>();
 
   constructor(options: WebToolPackOptions) {
     this.#options = options;
@@ -52,7 +76,7 @@ export class WebToolPack {
   names() {
     const names: string[] = [];
     if (this.#options.profile.tools.web.fetch) names.push("web_fetch");
-    if (this.#options.profile.tools.web.search && WebToolPack.#provider()) names.push("web_search");
+    if (this.#options.profile.tools.web.search && this.#searcher()) names.push("web_search");
     return names;
   }
 
@@ -63,8 +87,8 @@ export class WebToolPack {
 
   #register(pi: ExtensionAPI) {
     if (this.#options.profile.tools.web.fetch) this.#registerFetch(pi);
-    const provider = WebToolPack.#provider();
-    if (this.#options.profile.tools.web.search && provider) this.#registerSearch(pi, provider);
+    const searcher = this.#searcher();
+    if (this.#options.profile.tools.web.search && searcher) this.#registerSearch(pi, searcher);
   }
 
   #registerFetch(pi: ExtensionAPI) {
@@ -72,48 +96,148 @@ export class WebToolPack {
     pi.registerTool({
       name: "web_fetch",
       label: "Fetch",
-      description: "Fetch a URL and return its readable text. HTML is stripped to text; the result is truncated.",
+      description: `Fetch a URL and return its readable text, ${WebToolPack.pageChars} characters at a time. A longer page ends with the offset that continues it.`,
       promptSnippet: "web_fetch: fetch a URL and return its readable text",
-      parameters: Type.Object({ url: Type.String({ description: "Absolute http(s) URL." }) }),
-      execute: async (_id, params) => {
+      parameters: Type.Object({
+        url: Type.String({ description: "Absolute http(s) URL." }),
+        offset: Type.Optional(Type.Number({ description: "Character offset a previous call named, to read on." })),
+      }),
+      execute: async (_id, params, signal) => {
         const refusal = WebToolPack.#refuseHost(params.url, allowHosts);
         if (refusal) return { content: [{ type: "text", text: refusal }], details: undefined, isError: true };
-        const response = await fetch(params.url, { signal: AbortSignal.timeout(20_000), redirect: "follow" });
-        const text = WebToolPack.#readable(await response.text());
+        const offset = Math.max(0, Math.floor(params.offset ?? 0));
+        const cached = offset ? this.#pages.get(params.url) : undefined;
+        const page = cached ?? (await this.#read(params.url, signal));
+        if (page.ok) this.#remember(params.url, page);
         return {
-          content: [
-            { type: "text", text: `${response.status} ${params.url}\n\n${codeAgentClip(text, codeAgentOutputChars)}` },
-          ],
+          content: [{ type: "text", text: WebToolPack.#window(params.url, page, offset) }],
           details: undefined,
-          isError: !response.ok,
+          isError: !page.ok,
         };
       },
     });
   }
 
-  #registerSearch(pi: ExtensionAPI, provider: SearchProvider) {
+  #registerSearch(pi: ExtensionAPI, searcher: WebSearcher) {
+    const hint =
+      searcher.name === "deepseek"
+        ? ` Keep the query within ${DeepSeekWeb.maxQueryChars} characters; site:, -site: and quoted phrases work.`
+        : "";
     pi.registerTool({
       name: "web_search",
       label: "Search",
-      description: `Search the web (${provider.name}) and return the top results as title, url and snippet.`,
+      description: `Search the web (${searcher.name}) and return the top results as title, url and summary.${hint}`,
       promptSnippet: "web_search: search the web and return titles, urls and snippets",
       parameters: Type.Object({
         query: Type.String(),
-        count: Type.Optional(Type.Number({ description: "How many results, default 5." })),
+        count: Type.Optional(
+          Type.Number({ description: `How many results, default 5, at most ${WebToolPack.maxResults}.` }),
+        ),
       }),
-      execute: async (_id, params) => {
-        const key = process.env[provider.envKey] ?? "";
-        const results = await provider.search(key, params.query, params.count ?? 5);
-        return {
-          content: [{ type: "text", text: codeAgentClip(results || "(no results)", codeAgentOutputChars) }],
-          details: undefined,
-        };
+      execute: async (_id, params, signal) => {
+        const count = Math.min(Math.max(Math.round(params.count ?? 5), 1), WebToolPack.maxResults);
+        try {
+          const results = await searcher.search(params.query, count, signal);
+          return {
+            content: [{ type: "text", text: codeAgentClip(results || "(no results)", WebToolPack.pageChars) }],
+            details: undefined,
+          };
+        } catch (error: unknown) {
+          const message = error instanceof Error ? error.message : String(error);
+          return { content: [{ type: "text", text: message }], details: undefined, isError: true };
+        }
       },
     });
   }
 
-  static #provider() {
-    return WebToolPack.providers.find((provider) => !!process.env[provider.envKey]);
+  #searcher(): WebSearcher | undefined {
+    const provider = WebToolPack.providers.find((entry) => !!process.env[entry.envKey]);
+    if (provider)
+      return {
+        name: provider.name,
+        search: (query, count) => provider.search(process.env[provider.envKey] ?? "", query, count),
+      };
+    const deepseek = this.#options.deepseek;
+    return deepseek
+      ? { name: "deepseek", search: (query, count, signal) => deepseek.search(query, count, signal) }
+      : undefined;
+  }
+
+  async #read(url: string, signal?: AbortSignal): Promise<WebPage> {
+    const deepseek = this.#options.deepseek;
+    if (deepseek && !(await this.#isLocal(new URL(url).hostname))) {
+      try {
+        const page = await deepseek.fetch(url, signal);
+        return { status: 200, ok: true, title: page.title, text: page.content };
+      } catch (error: unknown) {
+        if (signal?.aborted) throw error;
+      }
+    }
+    const response = await fetch(url, {
+      signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(20_000)]) : AbortSignal.timeout(20_000),
+      redirect: "follow",
+    });
+    return { status: response.status, ok: response.ok, title: "", text: WebToolPack.#readable(await response.text()) };
+  }
+
+  #remember(url: string, page: WebPage) {
+    this.#pages.delete(url);
+    this.#pages.set(url, page);
+    const oldest = this.#pages.keys().next().value;
+    if (this.#pages.size > WebToolPack.#rememberedPages && oldest) this.#pages.delete(oldest);
+  }
+
+  static #window(url: string, page: WebPage, offset: number) {
+    const head = [`${page.status} ${url}`, page.title].filter(Boolean).join("\n");
+    const total = page.text.length;
+    if (offset && offset >= total)
+      return `${head}\n\nOffset ${offset} is past the end; the page has ${total} characters.`;
+    const end = Math.min(offset + WebToolPack.pageChars, total);
+    const rest = end < total ? `\n\n[characters ${offset}–${end} of ${total}; offset ${end} reads on]` : "";
+    return `${head}\n\n${page.text.slice(offset, end)}${rest}`;
+  }
+
+  // DeepSeek's servers cannot reach these, and an intranet name has no business leaving the machine.
+  async #isLocal(hostname: string) {
+    const host = hostname.replace(/^\[|\]$|\.$/g, "").toLowerCase();
+    if (isIP(host)) return WebToolPack.#isLocalAddress(host);
+    if (!host.includes(".") || /\.(localhost|local|internal|lan|home\.arpa)$/.test(host)) return true;
+    try {
+      const addresses = await (this.#options.lookup ?? WebToolPack.#lookup)(host);
+      return !addresses.length || addresses.some((address) => WebToolPack.#isLocalAddress(address));
+    } catch {
+      // Fails closed: an intranet name this machine cannot resolve right now is still an intranet name.
+      return true;
+    }
+  }
+
+  static async #lookup(host: string) {
+    return (await lookup(host, { all: true })).map((entry) => entry.address);
+  }
+
+  static #isLocalAddress(literal: string) {
+    const address = WebToolPack.#unmapped(literal);
+    if (isIP(address) === 6) return address === "::" || address === "::1" || /^(f[cd]|fe[89ab])/.test(address);
+    const [a = 0, b = 0] = address.split(".").map(Number);
+    return (
+      a === 0 ||
+      a === 10 ||
+      a === 127 ||
+      (a === 100 && b >= 64 && b <= 127) ||
+      (a === 169 && b === 254) ||
+      (a === 172 && b >= 16 && b <= 31) ||
+      (a === 192 && b === 168)
+    );
+  }
+
+  // The URL parser writes `[::ffff:127.0.0.1]` as `::ffff:7f00:1`; a resolver hands a mapped address back dotted.
+  static #unmapped(address: string) {
+    const mapped = /^::ffff:(?:(\d+\.\d+\.\d+\.\d+)|([0-9a-f]{1,4}):([0-9a-f]{1,4}))$/i.exec(address);
+    if (!mapped) return address;
+    if (mapped[1]) return mapped[1];
+    const high = Number.parseInt(mapped[2] ?? "0", 16);
+    const low = Number.parseInt(mapped[3] ?? "0", 16);
+    return [high >> 8, high & 255, low >> 8, low & 255].join(".");
   }
 
   static #refuseHost(url: string, allowHosts: string[] | undefined) {

package/codeAgent/tools/akanCodePlugins.test.ts

@@ -11,6 +11,7 @@ import { AkanCodePlugins } from "./AkanCodePlugins";
 import { AkanEditScope } from "./AkanEditScope";
 import { AkanEnvKeys } from "./AkanEnvKeys";
 import { AkanVerifier } from "./AkanVerifier";
+import { DeepSeekWeb } from "./DeepSeekWeb";
 import { McpClient } from "./McpClient";
 import { McpToolPack } from "./McpToolPack";
 import { SessionToolPack } from "./SessionToolPack";
@@ -652,6 +653,196 @@ describe("WebToolPack", () => {
       server.stop(true);
     }
   });
+
+  test("reads a long page a window at a time, continuing from the snapshot it first read", async () => {
+    let hits = 0;
+    const server = Bun.serve({
+      port: 0,
+      fetch: () => {
+        hits += 1;
+        return new Response(`${"a".repeat(10_000)}${"b".repeat(10_000)}${"c".repeat(500)}`);
+      },
+    });
+    try {
+      const fetchTool = toolsOf(new WebToolPack({ profile: codeAgentPresets.local(root) }).extension()).get(
+        "web_fetch",
+      );
+      const url = `http://localhost:${server.port}/long`;
+      const read = async (offset?: number) =>
+        (await fetchTool?.("1", { url, ...(offset === undefined ? {} : { offset }) } as never))?.content[0]?.text ?? "";
+
+      const first = await read();
+      expect(first).toContain(`${"a".repeat(10_000)}\n\n[characters 0–10000 of 20500; offset 10000 reads on]`);
+      const second = await read(10_000);
+      expect(second).toContain(`\n\n${"b".repeat(10_000)}\n\n[characters 10000–20000 of 20500; offset 20000 reads on]`);
+      expect(await read(20_000)).toEndWith(`\n\n${"c".repeat(500)}`);
+      expect(await read(30_000)).toContain("Offset 30000 is past the end; the page has 20500 characters.");
+      expect(hits).toBe(1);
+      await read();
+      expect(hits).toBe(2);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("reads a public page through DeepSeek, a local one directly, and a refused one directly too", async () => {
+    const asked: string[] = [];
+    const deepseekServer = Bun.serve({
+      port: 0,
+      fetch: async (request) => {
+        const { url } = (await request.json()) as { url: string };
+        asked.push(url);
+        if (url.endsWith("/refused"))
+          return Response.json({ error: { message: "rejected by security policy" } }, { status: 403 });
+        return Response.json({ title: "Install", content: "\\#\\# Install\n\nRun \\`bun add akanjs\\`\\." });
+      },
+    });
+    const page = Bun.serve({ port: 0, fetch: () => new Response("<h1>local dev page</h1>") });
+    const realFetch = globalThis.fetch;
+    const direct = spyOn(globalThis, "fetch").mockImplementation((async (
+      input: RequestInfo | URL,
+      init?: RequestInit,
+    ) => {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+      if (new URL(url).hostname === "docs.example.com") return new Response("<p>read directly</p>");
+      return await realFetch(input, init);
+    }) as typeof fetch);
+    try {
+      const deepseek = new DeepSeekWeb("sk-test", `http://127.0.0.1:${deepseekServer.port}/v1/tools`);
+      const lookup = async () => ["93.184.215.14"];
+      const pack = new WebToolPack({ profile: codeAgentPresets.local(root), deepseek, lookup });
+      const fetchTool = toolsOf(pack.extension()).get("web_fetch");
+      const read = async (url: string) => (await fetchTool?.("1", { url } as never))?.content[0]?.text ?? "";
+
+      expect(await read("https://docs.example.com/install")).toBe(
+        "200 https://docs.example.com/install\nInstall\n\n## Install\n\nRun `bun add akanjs`.",
+      );
+      expect(await read(`http://localhost:${page.port}/`)).toContain("local dev page");
+      expect(asked).toEqual(["https://docs.example.com/install"]);
+      expect(await read("https://docs.example.com/refused")).toContain("read directly");
+      expect(asked.at(-1)).toBe("https://docs.example.com/refused");
+    } finally {
+      direct.mockRestore();
+      deepseekServer.stop(true);
+      page.stop(true);
+    }
+  });
+
+  test("reads an intranet name, a mapped or unspecified loopback, and a name that does not resolve directly", async () => {
+    const asked: string[] = [];
+    const deepseekServer = Bun.serve({
+      port: 0,
+      fetch: async (request) => {
+        asked.push(((await request.json()) as { url: string }).url);
+        return Response.json({ title: "Public", content: "read by DeepSeek" });
+      },
+    });
+    const realFetch = globalThis.fetch;
+    const direct = spyOn(globalThis, "fetch").mockImplementation((async (
+      input: RequestInfo | URL,
+      init?: RequestInit,
+    ) => {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+      if (new URL(url).port === String(deepseekServer.port)) return await realFetch(input, init);
+      return new Response("<p>read directly</p>");
+    }) as typeof fetch);
+    const addresses: { [host: string]: string[] } = {
+      "jira.corp.example.com": ["10.0.0.7"],
+      "wiki.example.com": ["93.184.215.14", "fd12::1"],
+      "hosts.example.com": ["::ffff:192.168.0.2"],
+      "docs.example.com": ["93.184.215.14", "2606:2800:21f:cb07:6820:80da:af6b:8b2c"],
+    };
+    const looked: string[] = [];
+    const lookup = async (host: string) => {
+      looked.push(host);
+      const found = addresses[host];
+      if (!found) throw new Error(`getaddrinfo ENOTFOUND ${host}`);
+      return found;
+    };
+    try {
+      const deepseek = new DeepSeekWeb("sk-test", `http://127.0.0.1:${deepseekServer.port}/v1/tools`);
+      const pack = new WebToolPack({ profile: codeAgentPresets.local(root), deepseek, lookup });
+      const fetchTool = toolsOf(pack.extension()).get("web_fetch");
+      const read = async (url: string) => (await fetchTool?.("1", { url } as never))?.content[0]?.text ?? "";
+
+      for (const url of [
+        "http://jira.corp.example.com/browse/SEC-1",
+        "http://wiki.example.com/",
+        "http://hosts.example.com/",
+        "http://foo.test/",
+        "http://[::ffff:127.0.0.1]:8282/x",
+        "http://[::ffff:10.0.0.5]/wiki",
+        "http://[::]:8282/",
+        "http://0.0.0.0:8282/",
+        "http://localhost.:8282/",
+        "http://app.local./",
+      ])
+        expect(await read(url)).toContain("read directly");
+      expect(asked).toEqual([]);
+
+      expect(await read("https://docs.example.com/install")).toContain("read by DeepSeek");
+      expect(await read("http://[2606:4700:4700::1111]/")).toContain("read by DeepSeek");
+      expect(asked).toEqual(["https://docs.example.com/install", "http://[2606:4700:4700::1111]/"]);
+      expect(looked).toEqual([
+        "jira.corp.example.com",
+        "wiki.example.com",
+        "hosts.example.com",
+        "foo.test",
+        "docs.example.com",
+      ]);
+    } finally {
+      direct.mockRestore();
+      deepseekServer.stop(true);
+    }
+  });
+
+  test("searches through DeepSeek when no key-named provider is set, and a key-named one wins", async () => {
+    const had = { brave: process.env.BRAVE_API_KEY, tavily: process.env.TAVILY_API_KEY };
+    const counts: number[] = [];
+    const deepseekServer = Bun.serve({
+      port: 0,
+      fetch: async (request) => {
+        counts.push(((await request.json()) as { count: number }).count);
+        return Response.json({
+          results: [{ title: "Akan.js", url: "https://akanjs.com/?utm_source=x", summary: "s" }],
+        });
+      },
+    });
+    const descriptionsOf = (pack: WebToolPack) => {
+      const descriptions = new Map<string, string>();
+      (pack.extension() as { factory: (pi: unknown) => void }).factory({
+        registerTool: (tool: { name: string; description: string }) => descriptions.set(tool.name, tool.description),
+      });
+      return descriptions;
+    };
+    try {
+      delete process.env.BRAVE_API_KEY;
+      delete process.env.TAVILY_API_KEY;
+      const deepseek = new DeepSeekWeb("sk-test", `http://127.0.0.1:${deepseekServer.port}/v1/tools`);
+      const pack = new WebToolPack({ profile: codeAgentPresets.local(root), deepseek });
+      expect(new WebToolPack({ profile: codeAgentPresets.review(root), deepseek }).names()).toEqual([]);
+      expect(descriptionsOf(pack).get("web_search")).toContain("(deepseek)");
+
+      const search = toolsOf(pack.extension()).get("web_search");
+      const found = await search?.("1", { query: "akan", count: 50 } as never);
+      expect(found?.content[0]?.text).toBe("- Akan.js\n  https://akanjs.com/\n  s");
+      expect(counts).toEqual([WebToolPack.maxResults]);
+      const tooLong = await search?.("1", { query: "x".repeat(DeepSeekWeb.maxQueryChars + 1) } as never);
+      expect(tooLong?.isError).toBe(true);
+      expect(counts).toHaveLength(1);
+
+      process.env.BRAVE_API_KEY = "test";
+      expect(descriptionsOf(pack).get("web_search")).toContain("(brave)");
+    } finally {
+      for (const [name, value] of [
+        ["BRAVE_API_KEY", had.brave],
+        ["TAVILY_API_KEY", had.tavily],
+      ] as const)
+        if (value === undefined) delete process.env[name];
+        else process.env[name] = value;
+      deepseekServer.stop(true);
+    }
+  });
 });
 
 describe("SessionToolPack", () => {