@akanjs/devkit 3.1.0-rc.2 → 3.1.0-rc.20

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,13 @@
+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;
 }
 
 interface SearchProvider {
@@ -12,9 +16,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 +74,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 +85,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 +94,125 @@ 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 && !WebToolPack.#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.
+  static #isLocal(hostname: string) {
+    const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    const family = isIP(host);
+    if (family === 6) return host === "::1" || /^(f[cd]|fe[89ab])/.test(host);
+    if (family === 4) {
+      const [a = 0, b = 0] = host.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)
+      );
+    }
+    return !host.includes(".") || /\.(localhost|local|internal|lan|home\.arpa)$/.test(host);
   }
 
   static #refuseHost(url: string, allowHosts: string[] | undefined) {
@@ -132,14 +231,14 @@ export class WebToolPack {
   /** Enough to read a documentation page; a full HTML parser is not worth a dependency for that. */
   static #readable(html: string) {
     return html
-      .replace(/<script[\s\S]*?<\/script>/gi, " ")
-      .replace(/<style[\s\S]*?<\/style>/gi, " ")
-      .replace(/<[^>]+>/g, " ")
+      .replace(/<script[\s\S]*?<\/script[^<>]*>/gi, " ")
+      .replace(/<style[\s\S]*?<\/style[^<>]*>/gi, " ")
+      .replace(/<[^<>]+>/g, " ")
       .replace(/&nbsp;/g, " ")
-      .replace(/&amp;/g, "&")
       .replace(/&lt;/g, "<")
       .replace(/&gt;/g, ">")
       .replace(/&quot;/g, '"')
+      .replace(/&amp;/g, "&")
       .replace(/[ \t]+/g, " ")
       .replace(/\n{3,}/g, "\n\n")
       .trim();

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";
@@ -247,22 +248,26 @@ describe("PreviewView", () => {
     expect(typeof PreviewView.available).toBe("boolean");
   });
 
-  test.skipIf(!PreviewView.available)("finds an empty body and a console error on a real page", async () => {
-    const server = Bun.serve({
-      port: 0,
-      fetch: () =>
-        new Response('<!doctype html><html><body></body><script>console.error("boom")</script></html>', {
-          headers: { "content-type": "text/html" },
-        }),
-    });
-    try {
-      const probe = await PreviewView.probe(`http://localhost:${server.port}/`);
-      expect(probe.pageErrors.join(" ")).toContain("rendered empty");
-      expect(probe.consoleErrors.join(" ")).toContain("boom");
-    } finally {
-      server.stop(true);
-    }
-  });
+  test.skipIf(!PreviewView.available)(
+    "finds an empty body and a console error on a real page",
+    async () => {
+      const server = Bun.serve({
+        port: 0,
+        fetch: () =>
+          new Response('<!doctype html><html><body></body><script>console.error("boom")</script></html>', {
+            headers: { "content-type": "text/html" },
+          }),
+      });
+      try {
+        const probe = await PreviewView.probe(`http://localhost:${server.port}/`);
+        expect(probe.pageErrors.join(" ")).toContain("rendered empty");
+        expect(probe.consoleErrors.join(" ")).toContain("boom");
+      } finally {
+        server.stop(true);
+      }
+    },
+    30_000,
+  );
 });
 
 describe("SubagentPool", () => {
@@ -648,6 +653,128 @@ 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 fetchTool = toolsOf(new WebToolPack({ profile: codeAgentPresets.local(root), deepseek }).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("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", () => {

package/codeAgent/tools/deepSeekWeb.test.ts

@@ -0,0 +1,113 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { DeepSeekWeb } from "./DeepSeekWeb";
+
+interface Received {
+  path: string;
+  body: { query?: string; count?: number; url?: string };
+  auth: string | null;
+}
+
+const received: Received[] = [];
+let answers: Response[] = [];
+let server: ReturnType<typeof Bun.serve>;
+beforeAll(() => {
+  server = Bun.serve({
+    port: 0,
+    fetch: async (request) => {
+      received.push({
+        path: new URL(request.url).pathname,
+        body: (await request.json()) as Received["body"],
+        auth: request.headers.get("authorization"),
+      });
+      return answers.shift() ?? Response.json({ results: [] });
+    },
+  });
+});
+afterAll(() => server.stop(true));
+
+const client = () => new DeepSeekWeb("sk-test", `http://127.0.0.1:${server.port}/v1/tools`);
+const rateLimited = () =>
+  Response.json({ error: { message: "QPS exceeded" } }, { status: 429, headers: { "retry-after": "0.01" } });
+
+describe("DeepSeekWeb", () => {
+  test("search lists each page once, without tracking parameters, with its date and a clipped summary", async () => {
+    answers = [
+      Response.json({
+        results: [
+          {
+            title: "Bun v1.3.13",
+            url: "https://bun.com/blog/bun-v1.3.13?utm_source=x&utm_medium=y&ref=keep",
+            summary: "word ".repeat(400),
+            date: "2026-04-19T16:00:00+00:00",
+          },
+          { title: "Isolate issue", url: "https://github.com/oven-sh/bun/issues/31771#1", snippet: "only a snippet" },
+          { title: "Same issue again", url: "https://github.com/oven-sh/bun/issues/31771", summary: "dup" },
+        ],
+      }),
+    ];
+    const text = await client().search("bun isolate", 5);
+    expect(received.at(-1)).toEqual({
+      path: "/v1/tools/search",
+      body: { query: "bun isolate", count: 5 },
+      auth: "Bearer sk-test",
+    });
+    expect(text).toContain("- Bun v1.3.13\n  https://bun.com/blog/bun-v1.3.13?ref=keep · 2026-04-19\n  word word");
+    expect(text).toContain("- Isolate issue\n  https://github.com/oven-sh/bun/issues/31771\n  only a snippet");
+    expect(text).not.toContain("Same issue again");
+    expect(text.split("\n")[2]?.trim().length).toBe(DeepSeekWeb.summaryChars);
+  });
+
+  test("a query longer than DeepSeek takes is refused before any request is spent", async () => {
+    const before = received.length;
+    await expect(client().search("x".repeat(DeepSeekWeb.maxQueryChars + 1), 5)).rejects.toThrow("shorten the query");
+    expect(received.length).toBe(before);
+  });
+
+  test("search waits out a rate limit, and gives up with DeepSeek's own message after the last attempt", async () => {
+    answers = [rateLimited(), Response.json({ results: [{ title: "t", url: "https://a.com/", summary: "s" }] })];
+    expect(await client().search("q", 1)).toContain("https://a.com/");
+
+    answers = [rateLimited(), rateLimited(), rateLimited()];
+    await expect(client().search("q", 1)).rejects.toThrow("429: QPS exceeded");
+  });
+
+  test("fetch waits only on its quota and hands any other failure straight back", async () => {
+    answers = [rateLimited(), Response.json({ title: "Page", content: "body" })];
+    expect(await client().fetch("https://a.com/")).toEqual({ title: "Page", content: "body" });
+
+    const before = received.length;
+    answers = [Response.json({ error: { message: "downstream timeout" } }, { status: 504 })];
+    await expect(client().fetch("https://a.com/")).rejects.toThrow("504: downstream timeout");
+    expect(received.length).toBe(before + 1);
+  });
+
+  test("fetch hands back Markdown with its blanket escaping undone", async () => {
+    answers = [
+      Response.json({
+        title: "Example",
+        content: "\\#\\# Usage\n\nCall \\`foo\\(1\\)\\` \\- it returns 2\\.\n\nconst re \\= \\/\\\\s\\+\\/\\;",
+      }),
+    ];
+    const page = await client().fetch("https://example.com/usage");
+    expect(received.at(-1)?.body).toEqual({ url: "https://example.com/usage" });
+    expect(page).toEqual({
+      title: "Example",
+      content: "## Usage\n\nCall `foo(1)` - it returns 2.\n\nconst re = /\\s+/;",
+    });
+  });
+
+  test("a page that was never escaped keeps the backslashes it has", () => {
+    const clean = "Match a dot with `a\\.b`. See (the docs), [a link](x) and {a: 1}; done!";
+    expect(DeepSeekWeb.unescape(clean)).toBe(clean);
+  });
+
+  test("the key comes from the model runtime, and never from behind a proxy", async () => {
+    const runtime = (apiKey?: string) =>
+      ({ getAuth: async () => (apiKey ? { auth: { apiKey } } : undefined) }) as unknown as Parameters<
+        typeof DeepSeekWeb.fromRuntime
+      >[0];
+    expect(await DeepSeekWeb.fromRuntime(runtime("sk"), false)).toBeInstanceOf(DeepSeekWeb);
+    expect(await DeepSeekWeb.fromRuntime(runtime("sk"), true)).toBeUndefined();
+    expect(await DeepSeekWeb.fromRuntime(runtime(), false)).toBeUndefined();
+  });
+});