@akanjs/devkit 3.1.0-rc.11 → 3.1.0-rc.13

package/codeAgent/agent/AkanCodeCompaction.ts

@@ -0,0 +1,49 @@
+import type { SettingsManager } from "@earendil-works/pi-coding-agent";
+import type { CodeAgentModel } from "./akanCodeModel";
+
+type CompactedModel = Pick<CodeAgentModel, "provider" | "id" | "contextWindow">;
+
+// The engine compacts above `contextWindow - reserveTokens`, so a share of the window becomes a reserve per model.
+export class AkanCodeCompaction {
+  // Twice the engine's 16,384: at 16k a reasoning model stops mid-thought at the compaction threshold,
+  // and the recovery re-sends a near-full window to retry the turn.
+  static readonly reserveFloor = 32_768;
+  static readonly steps = [10, 20, 30, 40, 50, 60, 70, 80, 90, 100] as const;
+
+  static isStep(percent: number) {
+    return AkanCodeCompaction.steps.some((step) => step === percent);
+  }
+
+  /** `100` is the default itself, so it is stored as no choice at all. */
+  static normalize(percent: number | undefined) {
+    if (percent === undefined) return undefined;
+    if (!AkanCodeCompaction.isStep(percent))
+      throw new Error(`Autocompact takes a percent in steps of 10: ${AkanCodeCompaction.steps.join(", ")}.`);
+    return percent === 100 ? undefined : percent;
+  }
+
+  static thresholdOf(contextWindow: number, percent: number | undefined) {
+    const share = percent ? Math.floor((contextWindow * percent) / 100) : contextWindow;
+    return Math.min(share, contextWindow - AkanCodeCompaction.reserveFloor);
+  }
+
+  static apply(settings: SettingsManager, model: CompactedModel, percent: number | undefined) {
+    const threshold = AkanCodeCompaction.thresholdOf(model.contextWindow, percent);
+    // Keyed by model, so the next model is never checked against a reserve sized for this one's window.
+    settings.applyOverrides({
+      compaction: {
+        modelOverrides: { [`${model.provider}/${model.id}`]: { reserveTokens: model.contextWindow - threshold } },
+      },
+    });
+  }
+
+  /** Why `percent` cannot work on `model`, or undefined when it can. */
+  static problemOf(model: CompactedModel, percent: number, keepRecentTokens: number) {
+    const name = `${model.provider}/${model.id}`;
+    if (model.contextWindow <= 0) return `${name} declares no context window, so it has no share to compact at.`;
+    const threshold = AkanCodeCompaction.thresholdOf(model.contextWindow, percent);
+    if (threshold >= keepRecentTokens) return undefined;
+    const k = (tokens: number) => `${Math.round(tokens / 1000)}k`;
+    return `Compacting at ${percent}% of the ${k(model.contextWindow)} window of ${name} starts at ${k(threshold)}, under the ${k(keepRecentTokens)} of recent turns every compaction keeps, so every turn would compact again.`;
+  }
+}

package/codeAgent/agent/AkanCodeServices.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import { type InlineExtension, ModelRuntime, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 import type { CodeAgentProfile } from "akanjs/common";
 import { AkanEnvKeys } from "../tools/AkanEnvKeys";
+import { AkanCodeCompaction } from "./AkanCodeCompaction";
 import { type AkanContextFile, AkanContextFiles } from "./AkanContextFiles";
 import { akanCodePaths } from "./akanCodePaths";
 import { akanSystemPrompt } from "./akanSystemPrompt";
@@ -27,9 +28,7 @@ export class AkanCodeServices {
       enableInstallTelemetry: false,
       enableAnalytics: false,
       quietStartup: true,
-      // Twice the engine's 16,384: at 16k a reasoning model stops mid-thought at the compaction threshold,
-      // and the recovery re-sends a near-full window to retry the turn.
-      compaction: { reserveTokens: 32_768 },
+      compaction: { reserveTokens: AkanCodeCompaction.reserveFloor },
     });
   }
 

package/codeAgent/agent/CodeAgent.ts

@@ -25,6 +25,8 @@ import {
 } from "akanjs/common";
 import type { Workspace } from "../../commandDecorators";
 import { AkanCodePlugins } from "../tools/AkanCodePlugins";
+import { DeepSeekWeb } from "../tools/DeepSeekWeb";
+import { AkanCodeCompaction } from "./AkanCodeCompaction";
 import { AkanCodeServices } from "./AkanCodeServices";
 import {
   akanCodeModel,
@@ -52,6 +54,8 @@ export interface CodeAgentOptions {
   cwd?: string;
   profile: CodeAgentProfile;
   model?: CodeAgentModelRef;
+  /** Percent of the context window that starts a compaction, in steps of 10. */
+  autoCompactAt?: number;
   /** Apps whose dev server and preview the turn-end feedback loop watches. */
   apps?: string[];
   extensions?: InlineExtension[];
@@ -85,6 +89,7 @@ export class CodeAgent {
   readonly #replay: CodeAgentEvent[] = [];
   #replayFrom = 0;
   #lastContextTokens: number | undefined;
+  #autoCompactAt: number | undefined;
 
   private constructor(profile: CodeAgentProfile) {
     this.#profile = profile;
@@ -95,8 +100,10 @@ export class CodeAgent {
     const workspaceRoot = options.workspace.workspaceRoot;
     const cwd = options.cwd ?? workspaceRoot;
     const agent = new CodeAgent(options.profile);
+    const autoCompactAt = AkanCodeCompaction.normalize(options.autoCompactAt);
     const settingsManager = AkanCodeServices.settings();
-    const modelRuntime = await AkanCodeServices.runtime(workspaceRoot, CodeAgentProxy.fromEnv(options.profile));
+    const proxy = CodeAgentProxy.fromEnv(options.profile);
+    const modelRuntime = await AkanCodeServices.runtime(workspaceRoot, proxy);
     const model = await akanCodeModel(modelRuntime, options.model);
     const compaction = settingsManager.getCompactionSettings(model);
     const modelWarnings = akanCodeModelWarnings(model, compaction.reserveTokens + compaction.keepRecentTokens);
@@ -107,6 +114,7 @@ export class CodeAgent {
       profile: options.profile,
       apps: options.apps ?? [],
       canSeeImages: akanCodeModelSupportsImages(model),
+      deepseek: await DeepSeekWeb.fromRuntime(modelRuntime, !!proxy),
       depth: options.depth ?? 0,
       ...(options.subagentSpend ? { subagentSpend: options.subagentSpend } : {}),
       currentSessionId: () => agent.sessionId,
@@ -146,10 +154,12 @@ export class CodeAgent {
     agent.#workspaceRoot = workspaceRoot;
     if (options.profile.session.store !== "memory") agent.#sessionDir = akanCodePaths.sessionsDir(workspaceRoot);
     await agent.#attach(session, options.mode ?? "print");
+    const autoCompactWarning = agent.#fitAutoCompact(autoCompactAt);
     agent.#suspended = new CodeAgentSuspended(CodeAgentSuspended.fileOf(agent.#sessionDir, agent.sessionId));
     if (agent.#sessionDir && options.profile.session.store === "file")
       agent.#openMail(akanCodePaths.mailDir(workspaceRoot), cwd);
-    for (const message of modelWarnings) agent.#emit({ type: "notice", level: "warning", message });
+    for (const message of [...modelWarnings, ...autoCompactWarning])
+      agent.#emit({ type: "notice", level: "warning", message });
     return agent;
   }
 
@@ -232,6 +242,7 @@ export class CodeAgent {
       contextTokens: model?.contextWindow,
       // Not `off`: that is a setting of a reasoning model, not the absence of reasoning.
       effort: session.supportsThinking() ? session.thinkingLevel : undefined,
+      autoCompactAt: this.#autoCompactAt,
       name: session.sessionName,
       interaction: this.#profile.interaction,
     };
@@ -396,9 +407,42 @@ export class CodeAgent {
     const model = await akanCodeModel(session.modelRuntime, ref);
     if (!model) throw new Error(`Unknown model: ${ref.provider}/${ref.id}`);
     await session.setModel(model);
+    for (const message of this.#fitAutoCompact(this.#autoCompactAt))
+      this.#emit({ type: "notice", level: "warning", message });
     this.#emit({ type: "session", info: this.info });
   }
 
+  setAutoCompactAt(percent: number | undefined) {
+    const wanted = AkanCodeCompaction.normalize(percent);
+    const problem = this.#autoCompactProblem(wanted);
+    if (problem) throw new Error(problem);
+    this.#autoCompactAt = wanted;
+    this.#applyAutoCompact();
+    this.#emit({ type: "session", info: this.info });
+  }
+
+  // A share that fit one window can fall under the kept turns of a smaller one, and would compact every turn.
+  #fitAutoCompact(percent: number | undefined) {
+    const problem = this.#autoCompactProblem(percent);
+    this.#autoCompactAt = problem ? undefined : percent;
+    this.#applyAutoCompact();
+    return problem ? [`${problem} Autocompact is back to the default.`] : [];
+  }
+
+  #autoCompactProblem(percent: number | undefined) {
+    const session = this.#require();
+    const model = session.model;
+    if (!model || !percent) return undefined;
+    const { keepRecentTokens } = session.settingsManager.getCompactionSettings(model);
+    return AkanCodeCompaction.problemOf(model, percent, keepRecentTokens);
+  }
+
+  // Never before `create` has built the session: `settingsManager.reload()` drops whatever `applyOverrides` set.
+  #applyAutoCompact() {
+    const session = this.#require();
+    if (session.model) AkanCodeCompaction.apply(session.settingsManager, session.model, this.#autoCompactAt);
+  }
+
   async waitForIdle() {
     await this.#require().waitForIdle();
   }

package/codeAgent/agent/CodeAgentRpcHost.ts

@@ -83,6 +83,9 @@ export class CodeAgentRpcHost {
       case "set_model":
         await this.#agent.setModel({ provider: command.provider, id: command.modelId });
         return await this.#agent.state();
+      case "set_auto_compact":
+        this.#agent.setAutoCompactAt(command.percent);
+        return await this.#agent.state();
       case "get_state":
         return await this.#agent.state(command.sinceSeq === undefined ? {} : { sinceSeq: command.sinceSeq });
       case "shutdown":

package/codeAgent/agent/akanCodeCompaction.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { AkanCodeCompaction } from "./AkanCodeCompaction";
+import { AkanCodeServices } from "./AkanCodeServices";
+
+const big = { provider: "deepseek", id: "deepseek-flash", contextWindow: 1_000_000 };
+const small = { provider: "openai", id: "small", contextWindow: 128_000 };
+
+describe("AkanCodeCompaction", () => {
+  test("a percent is a share of the window, never closer to the edge than the reply's floor", () => {
+    expect(AkanCodeCompaction.thresholdOf(1_000_000, 60)).toBe(600_000);
+    expect(AkanCodeCompaction.thresholdOf(128_000, 90)).toBe(128_000 - AkanCodeCompaction.reserveFloor);
+    expect(AkanCodeCompaction.thresholdOf(1_000_000, undefined)).toBe(1_000_000 - AkanCodeCompaction.reserveFloor);
+  });
+
+  test("only steps of 10 are taken, and 100 is the default rather than a choice", () => {
+    expect(AkanCodeCompaction.normalize(60)).toBe(60);
+    expect(AkanCodeCompaction.normalize(100)).toBeUndefined();
+    expect(AkanCodeCompaction.normalize(undefined)).toBeUndefined();
+    for (const wrong of [0, 55, 110, Number.NaN]) expect(() => AkanCodeCompaction.normalize(wrong)).toThrow();
+  });
+
+  test("the engine reads the share back as this model's reserve and leaves other models at the floor", () => {
+    const settings = AkanCodeServices.settings();
+    AkanCodeCompaction.apply(settings, big, 60);
+    expect(settings.getCompactionSettings(big).reserveTokens).toBe(400_000);
+    expect(settings.getCompactionSettings(small).reserveTokens).toBe(AkanCodeCompaction.reserveFloor);
+    AkanCodeCompaction.apply(settings, big, undefined);
+    expect(settings.getCompactionSettings(big).reserveTokens).toBe(AkanCodeCompaction.reserveFloor);
+  });
+
+  test("a share under the turns every compaction keeps is refused, since each turn would compact again", () => {
+    expect(AkanCodeCompaction.problemOf(big, 10, 20_000)).toBeUndefined();
+    expect(AkanCodeCompaction.problemOf(small, 10, 20_000)).toContain("every turn would compact again");
+    expect(AkanCodeCompaction.problemOf({ ...small, contextWindow: 0 }, 50, 20_000)).toContain("no context window");
+  });
+});

package/codeAgent/agent/codeAgent.test.ts

@@ -24,16 +24,31 @@ const chunk = (delta: object, finish: string | null = null) =>
     choices: [{ index: 0, delta, finish_reason: finish }],
   })}\n\n`;
 
+const usageChunk = (promptTokens: number) =>
+  `data: ${JSON.stringify({
+    id: "c1",
+    object: "chat.completion.chunk",
+    created: 0,
+    model: akanCodeDefaultModel.id,
+    choices: [],
+    usage: { prompt_tokens: promptTokens, completion_tokens: 1, total_tokens: promptTokens + 1 },
+  })}\n\n`;
+
 let llm: ReturnType<typeof Bun.serve>;
 let llmCalls = 0;
+let reportedTokens = 0;
 beforeAll(() => {
   llm = Bun.serve({
     port: 0,
     fetch: () => {
       llmCalls += 1;
-      return new Response(`${chunk({ role: "assistant", content: "ok" })}${chunk({}, "stop")}data: [DONE]\n\n`, {
-        headers: { "content-type": "text/event-stream" },
-      });
+      const usage = reportedTokens ? usageChunk(reportedTokens) : "";
+      return new Response(
+        `${chunk({ role: "assistant", content: "ok" })}${chunk({}, "stop")}${usage}data: [DONE]\n\n`,
+        {
+          headers: { "content-type": "text/event-stream" },
+        },
+      );
     },
   });
 });
@@ -84,6 +99,49 @@ describe("CodeAgent", () => {
     }
   });
 
+  test("autocompact is carried from creation, announced on the session frame, and refuses a step it lacks", async () => {
+    const root = await makeTempRoot();
+    const agent = await createAgent(root, { autoCompactAt: 60 });
+    try {
+      const events: CodeAgentEvent[] = [];
+      agent.on((event) => events.push(event));
+      expect(agent.info.autoCompactAt).toBe(60);
+      expect(() => agent.setAutoCompactAt(55)).toThrow("steps of 10");
+      expect(agent.info.autoCompactAt).toBe(60);
+      agent.setAutoCompactAt(100);
+      expect(agent.info.autoCompactAt).toBeUndefined();
+      expect(events.filter((event) => event.type === "session")).toHaveLength(1);
+    } finally {
+      agent.dispose();
+    }
+  });
+
+  test("a chosen share reaches the engine: a reply reported past it compacts, and the default lets it pass", async () => {
+    const compactions = async (options: Partial<CodeAgentOptions>) => {
+      const agent = await createAgent(await makeTempRoot(), options);
+      const reasons: string[] = [];
+      agent.on((event) => {
+        if (event.type === "compaction" && event.phase === "start") reasons.push(event.reason);
+      });
+      try {
+        // The 20k most recent tokens are kept, so a summary needs an older turn behind the filler.
+        for (const text of ["hello", "filler ".repeat(20_000)]) {
+          await agent.prompt(text);
+          await agent.waitForIdle();
+        }
+        reportedTokens = 650_000;
+        await agent.prompt("next");
+        await agent.waitForIdle();
+      } finally {
+        reportedTokens = 0;
+        agent.dispose();
+      }
+      return reasons;
+    };
+    expect(await compactions({})).toEqual([]);
+    expect(await compactions({ autoCompactAt: 60 })).toEqual(["threshold"]);
+  });
+
   test("a sub-agent hands its plugins the token tally of the tree that opened it", async () => {
     const root = await makeTempRoot();
     const build = AkanCodePlugins.build;

package/codeAgent/agent/codeAgentContract.test.ts

@@ -349,6 +349,7 @@ describe("codeAgentEventLabel", () => {
           tools: [],
           contextTokens: undefined,
           effort: undefined,
+          autoCompactAt: undefined,
           name: undefined,
           interaction: { question: "await", approval: "await" },
         },

package/codeAgent/index.ts

@@ -1,5 +1,6 @@
 // Importing this barrel loads the engine (~122MiB resident); a host needing cheap pieces imports the owning module.
 // agent/consoleToStderr is deliberately absent: it takes over globalThis.console, so an RPC entry imports it first.
+export * from "./agent/AkanCodeCompaction";
 export * from "./agent/AkanCodeServices";
 export * from "./agent/akanCodeModel";
 export * from "./agent/akanCodePaths";

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

@@ -78,6 +78,9 @@ Stored under `.akan/code/sessions` — project history, so a second checkout of
 - `/peers` lists other `akan code` sessions running in this workspace; `/msg <peer> <text>` hands one a
   message.
 - `/clear` wipes the screen and keeps the conversation; `/compact [notes]` shortens what the model carries.
+- `/autocompact <percent>` compacts on its own once the window is that full, in steps of 10 (`/autocompact 60`);
+  `100` is the default, which waits until 32k remain for the reply. `akan code --compact-at 60` (`-c`) starts
+  with it, and a share under the 20k every compaction keeps is refused.
 
 ## Model, effort, keys
 
@@ -119,6 +122,7 @@ akan code -i "<prompt>"         open the session with the prompt already sent
 --app <name>                    narrow the agent to one app
 --profile local|pod|review|web  what it may do (default local)
 --model <provider>/<id>         --thinking, --json, --rpc, --resume <id>
+--compact-at <percent>          compact once the window is this full (10, 20, … 100)
 ```
 
 `review` reads and never writes, loads no project context files, and keeps no session on disk. `pod` has

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

@@ -26,7 +26,8 @@ For a model `comment` (`<Slice>` is a signal slice suffix, e.g. `InPublic`):
 
 ## 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,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) {

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,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();
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.1.0-rc.11",
+  "version": "3.1.0-rc.13",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -48,7 +48,7 @@
     "@earendil-works/pi-tui": "1.3.0",
     "@inquirer/prompts": "^8.7.3",
     "@tailwindcss/node": "^4.3.3",
-    "akanjs": "3.1.0-rc.11",
+    "akanjs": "3.1.0-rc.13",
     "chalk": "^6.0.1",
     "commander": "^15.0.0",
     "dayjs": "^1.11.23",