deepseek-web-retrieval 0.7.0 → 0.9.0

package/src/installer/hosts/pi.ts

@@ -13,8 +13,8 @@ import { buildRulesBlock } from "../formats/rules";
 import { isPlainObject } from "../formats/value";
 import { lineageMatcher } from "../ownership";
 import { join } from "../paths";
+import { appendedByPrevious } from "../record";
 import { MCP_TOOL_IDS, RAW_MCP_TOOL_IDS, rulesLines } from "../rulesContent";
-import { appendedByPrevious } from "../state";
 import type { ConfigOp, FileEdit, HostPaths, InstallerInput, InstallPlan, InstallRecord, PlanError } from "../types";
 import { planHeader } from "./shared";
 
@@ -37,6 +37,15 @@ function piSourceRef(packageRef: string): string {
   return packageRef.startsWith("npm:") ? packageRef : `npm:${packageRef}`;
 }
 
+/** Both Pi paths write the same rules note; one wording so the paths cannot drift. */
+const rulesUpsertNote = (rules: string) =>
+  `Rules block upserted in ${rules}; Pi loads AGENTS.md context files from the working directory and its parents.`;
+
+/** Forced tier, both paths: with no built-in web tool to displace, routing is de-facto exclusive. */
+const FORCED_NO_BUILTIN_NOTE =
+  "Forced tier: Pi 1.3.0 ships no built-in web tool, so the registered tools are the only web path (de-facto). " +
+  FORCED_COST_NOTE;
+
 export function planPi(input: InstallerInput, previous: InstallRecord | undefined): InstallPlan {
   return input.path === "mcp" ? planPiMcp(input) : planPiExtension(input, previous);
 }
@@ -128,7 +137,15 @@ function planPiExtension(input: InstallerInput, previous: InstallRecord | undefi
       previous: typeof namespace.enableFetch === "boolean" ? namespace.enableFetch : undefined,
     });
   }
-  edits.push({ file: paths.config, format: "json", ops });
+  edits.push({
+    file: paths.config,
+    format: "json",
+    // Global-scope files live outside the install record's config home, so they
+    // need the owner sidecar that stops a second install (another project or
+    // XDG_CONFIG_HOME) from claiming them — the codex topology.
+    ...(input.scope === "global" ? { shared: true as const } : {}),
+    ops,
+  });
 
   notes.push(
     "Pi resolves the packages source at session start; the first launch after apply fetches the package from npm " +
@@ -161,16 +178,11 @@ function planPiExtension(input: InstallerInput, previous: InstallRecord | undefi
       format: "rules",
       block: buildRulesBlock(input.host, rulesLines(RAW_MCP_TOOL_IDS, input.search, input.fetch)),
     });
-    notes.push(
-      `Rules block upserted in ${paths.rules}; Pi loads AGENTS.md context files from the working directory and its parents.`,
-    );
+    notes.push(rulesUpsertNote(paths.rules));
   }
 
   if (forced) {
-    notes.push(
-      "Forced tier: Pi 1.3.0 ships no built-in web tool, so the registered tools are the only web path (de-facto). " +
-        FORCED_COST_NOTE,
-    );
+    notes.push(FORCED_NO_BUILTIN_NOTE);
   }
 
   return { host: "pi", scope: input.scope, tiers, edits, notes, errors };
@@ -234,7 +246,14 @@ function planMcpCompetitorDisables(input: InstallerInput, notes: string[], error
   const edits: FileEdit[] = [];
   if (competitors.length > 0) {
     const ops = planCompetitorDisables(servers, competitors, notes, errors);
-    if (ops.length > 0) edits.push({ file: mcpFile, format: "json", ops });
+    if (ops.length > 0) {
+      edits.push({
+        file: mcpFile,
+        format: "json",
+        ...(input.scope === "global" ? { shared: true as const } : {}),
+        ops,
+      });
+    }
   }
   if (bystanders.length > 0) notes.push(othersStayRegisteredNote(bystanders));
   return edits;
@@ -267,7 +286,13 @@ function planPiMcp(input: InstallerInput): InstallPlan {
   const servers = loaded.value.mcpServers;
   const existingEntry = isPlainObject(servers) ? servers.deepseek : undefined;
   const ops: ConfigOp[] = [{ op: "set", path: ["mcpServers", "deepseek"], value: entry, previous: existingEntry }];
-  edits.push({ file: paths.config, format: "json", ops });
+  edits.push({
+    file: paths.config,
+    format: "json",
+    // Same shared-file reason as the extension path's settings.json above.
+    ...(input.scope === "global" ? { shared: true as const } : {}),
+    ops,
+  });
 
   if (isPlainObject(servers)) {
     if (servers.deepseek !== undefined) notes.push(replacingExistingEntryNote("mcpServers.deepseek"));
@@ -292,16 +317,11 @@ function planPiMcp(input: InstallerInput): InstallPlan {
       format: "rules",
       block: buildRulesBlock(input.host, rulesLines(MCP_TOOL_IDS, input.search, input.fetch)),
     });
-    notes.push(
-      `Rules block upserted in ${paths.rules}; Pi loads AGENTS.md context files from the working directory and its parents.`,
-    );
+    notes.push(rulesUpsertNote(paths.rules));
   }
 
   if (input.search === "forced" || input.fetch === "forced") {
-    notes.push(
-      "Forced tier: Pi 1.3.0 ships no built-in web tool, so the registered tools are the only web path (de-facto). " +
-        FORCED_COST_NOTE,
-    );
+    notes.push(FORCED_NO_BUILTIN_NOTE);
   }
 
   return { host: "pi", scope: input.scope, tiers, edits, notes, errors };

package/src/installer/hosts/shared.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { BOTH_CAPABILITIES_OFF, competitorSteeringNote, findCompetitorSteering } from "../detect";
 import { codecFor, type LoadedConfig } from "../formats";
 import type { HostPaths, InstallerInput, PlanError } from "../types";
@@ -34,3 +35,25 @@ export function planHeader(input: InstallerInput, paths: HostPaths, loaded: Load
   if (steering.length > 0) notes.push(competitorSteeringNote(paths.rules, steering));
   return { notes, errors, abort: false };
 }
+
+/**
+ * The one subprocess shape the installer runs: `<command> --version`, probed
+ * for the version-drift note. A missing binary or unreadable output skips the
+ * check with a stderr note and never blocks the plan — honor or report.
+ * env is passed explicitly: runtime PATH edits (tests) must reach the lookup.
+ * The shell hop is required because npm's global install on Windows provides
+ * only a .cmd shim, which spawnSync cannot launch without a shell; the command
+ * and args are hardcoded, so it is safe.
+ */
+export function probeHostVersion(
+  command: string,
+  parse: (output: string) => string | undefined,
+  err: (line: string) => void,
+): string | undefined {
+  const result = spawnSync(command, ["--version"], { timeout: 5000, encoding: "utf8", env: process.env, shell: true });
+  const version = result.status === 0 ? parse(result.stdout ?? "") : undefined;
+  if (version === undefined) {
+    err(`note: ${command} was not found on PATH or printed no version; the version-drift check was skipped`);
+  }
+  return version;
+}

package/src/installer/ownership.ts

@@ -1,8 +1,8 @@
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { isPlainObject } from "../core/object";
+import { recordPathFor, recordReadPath } from "./record";
 import { pruneEmptyDir } from "./revert";
-import { recordReadPath, statePathFor } from "./state";
 import type { InstallerInput, RecordedFile, Scope } from "./types";
 
 type ClaimedFile = Pick<RecordedFile, "file" | "format" | "shared">;
@@ -70,7 +70,7 @@ export function canonicalPath(file: string): string {
 }
 
 function ownerOf(input: InstallerInput): FileOwner {
-  return { recordPath: canonicalPath(statePathFor(input)), scope: input.scope, cwd: canonicalPath(input.cwd) };
+  return { recordPath: canonicalPath(recordPathFor(input)), scope: input.scope, cwd: canonicalPath(input.cwd) };
 }
 
 /**

package/src/installer/paths.ts

@@ -18,8 +18,8 @@ export function configHome(roots: FsRoots): string {
   return roots.configHome ?? join(roots.home, ".config");
 }
 
-/** State records live with their scope: global installs under the config home, project installs in the checkout. */
-export function stateDir(roots: FsRoots, scope: Scope): string {
+/** Install records live with their scope: global installs under the config home, project installs in the checkout. */
+export function recordDir(roots: FsRoots, scope: Scope): string {
   return scope === "global"
     ? join(configHome(roots), "deepseek-web-retrieval")
     : join(roots.cwd, ".deepseek-web-retrieval");

package/src/installer/{state.ts → record.ts}

@@ -1,12 +1,12 @@
 import { existsSync, lstatSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { z } from "zod/v4";
-import { stateDir } from "./paths";
+import { recordDir } from "./paths";
 import { atomicWrite } from "./persistence";
 import type { FsRoots, InstallerInput, InstallRecord, Scope } from "./types";
 
-export function statePathFor(input: InstallerInput): string {
-  return join(stateDir(input, input.scope), `install.${input.host}.json`);
+export function recordPathFor(input: InstallerInput): string {
+  return join(recordDir(input, input.scope), `install.${input.host}.json`);
 }
 
 /** The platform a read resolves for: injected at the CLI edge, process.platform otherwise. */
@@ -19,19 +19,19 @@ function platformOf(roots: FsRoots): NodeJS.Platform {
  * home moved to %APPDATA% live under `~/.config`. Kept readable so `list` and
  * `uninstall` keep tracking installs made by older releases.
  */
-export function legacyGlobalStateDir(roots: FsRoots): string {
+export function legacyGlobalRecordDir(roots: FsRoots): string {
   return join(roots.home, ".config", "deepseek-web-retrieval");
 }
 
 /**
- * The file a record is read from: the canonical state path, except that a
+ * The file a record is read from: the canonical record path, except that a
  * missing win32 global record falls back to the legacy `~/.config` location
- * (see legacyGlobalStateDir). Writes always target the canonical path.
+ * (see legacyGlobalRecordDir). Writes always target the canonical path.
  */
 export function recordReadPath(input: InstallerInput, platform: NodeJS.Platform = platformOf(input)): string {
-  const canonical = statePathFor(input);
+  const canonical = recordPathFor(input);
   if (platform !== "win32" || input.scope !== "global" || existsSync(canonical)) return canonical;
-  const legacy = join(legacyGlobalStateDir(input), `install.${input.host}.json`);
+  const legacy = join(legacyGlobalRecordDir(input), `install.${input.host}.json`);
   return existsSync(legacy) ? legacy : canonical;
 }
 
@@ -49,7 +49,7 @@ const operation = z.discriminatedUnion("op", [
 const recordSchema = z.object({
   version: z.literal(1),
   installerVersion: z.string().optional(),
-  host: z.enum(["opencode", "pi", "codex"]),
+  host: z.enum(["opencode", "pi", "codex", "claude-code"]),
   scope: z.enum(["global", "project"]),
   tiers: z.object({ search: tier, fetch: tier }),
   createdAt: z.string().refine((value) => Number.isFinite(Date.parse(value))),
@@ -74,7 +74,7 @@ export class InstallRecordError extends Error {
   ) {
     super(
       `${kind === "invalid" ? "Invalid install record" : "Cannot read install record"} at ${file} (${detail}). ` +
-        "Restore a valid record from backup or repair its permissions before retrying; configuration was not changed. Do not delete undo state to bypass this check.",
+        "Restore a valid install record from your own copy or repair its permissions before retrying; configuration was not changed. Do not delete the install record to bypass this check.",
     );
     this.name = "InstallRecordError";
   }
@@ -131,7 +131,7 @@ export function claimedByOtherScope(input: InstallerInput, files: readonly strin
  * owner-only permissions regardless of umask.
  */
 export function writeRecord(input: InstallerInput, record: InstallRecord): void {
-  const file = statePathFor(input);
+  const file = recordPathFor(input);
   atomicWrite(file, `${JSON.stringify(record, null, 2)}\n`, 0o600);
 }
 
@@ -189,14 +189,14 @@ function hasRecordFiles(dir: string): boolean {
  */
 export function readingLegacyGlobalRecords(roots: FsRoots): boolean {
   if (platformOf(roots) !== "win32") return false;
-  if (hasRecordFiles(stateDir(roots, "global"))) return false;
-  return hasRecordFiles(legacyGlobalStateDir(roots));
+  if (hasRecordFiles(recordDir(roots, "global"))) return false;
+  return hasRecordFiles(legacyGlobalRecordDir(roots));
 }
 
 /** Lists install records found in both scope locations for the given roots. */
 export function listRecords(roots: FsRoots): InstallRecord[] {
-  const global = readRecordsFromDir(stateDir(roots, "global"), "global");
-  const project = readRecordsFromDir(stateDir(roots, "project"), "project");
-  const legacy = readingLegacyGlobalRecords(roots) ? readRecordsFromDir(legacyGlobalStateDir(roots), "global") : [];
+  const global = readRecordsFromDir(recordDir(roots, "global"), "global");
+  const project = readRecordsFromDir(recordDir(roots, "project"), "project");
+  const legacy = readingLegacyGlobalRecords(roots) ? readRecordsFromDir(legacyGlobalRecordDir(roots), "global") : [];
   return [...global, ...legacy, ...project];
 }

package/src/installer/types.ts

@@ -1,5 +1,5 @@
 /** Hosts the installer supports. */
-export type HostName = "opencode" | "pi" | "codex";
+export type HostName = "opencode" | "pi" | "codex" | "claude-code";
 
 /** Install scope, a first-class user choice. */
 export type Scope = "project" | "global";
@@ -105,7 +105,7 @@ export interface PlanError {
 }
 
 export interface InstallPlan {
-  /** Plan-time undo state; apply rejects a plan superseded by another operation. */
+  /** The plan-time install record; apply rejects a plan superseded by another operation. */
   readonly previousRecord?: InstallRecord;
   readonly host: HostName;
   readonly scope: Scope;

package/src/installer/uninstall.ts

@@ -1,9 +1,9 @@
 import { codecFor } from "./formats";
 import { withOperationLock } from "./operation-lock";
 import { assertFileOwnership, releaseFileOwnership } from "./ownership";
-import { stateDir } from "./paths";
+import { recordDir } from "./paths";
+import { claimedByOtherScope, deleteRecord, readRecord, recordPathFor } from "./record";
 import { pruneEmptyDir, revertRecordedFile } from "./revert";
-import { claimedByOtherScope, deleteRecord, readRecord, statePathFor } from "./state";
 import type { InstallerInput, InstallRecord } from "./types";
 
 /**
@@ -13,7 +13,7 @@ import type { InstallerInput, InstallRecord } from "./types";
  * rules blocks are removed, and files the installer created are deleted.
  */
 export function uninstall(input: InstallerInput): string[] {
-  return withOperationLock([statePathFor(input)], () => {
+  return withOperationLock([recordPathFor(input)], () => {
     const record = readRecord(input);
     if (record === undefined) {
       throw new Error(`No ${input.host} install is recorded for the ${input.scope} scope.`);
@@ -48,9 +48,12 @@ function uninstallLocked(input: InstallerInput, record: InstallRecord): string[]
   for (const file of [...record.files].reverse()) {
     lines.push(...revertRecordedFile(file, record.host, { label: "", whole: true }));
   }
-  deleteRecord(input);
+  // Release claims before deleting the record: releaseClaim re-asserts lineage
+  // through recordReadPath, whose legacy win32 fallback needs the record file
+  // to still exist on disk.
   releaseFileOwnership(input, record.files);
-  pruneEmptyDir(stateDir(input, input.scope));
+  deleteRecord(input);
+  pruneEmptyDir(recordDir(input, input.scope));
   lines.push(`removed install record (${input.host}, ${input.scope})`);
   return lines;
 }

package/src/mcp/serve.ts

@@ -1,9 +1,8 @@
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
-import { apiKeyFromEnv } from "../core/auth";
+import { apiKeyFromEnv, MISSING_API_KEY_MESSAGE } from "../core/auth";
 import { sharedFileOptions } from "../core/config-file";
 import { configDeviations } from "../core/config-summary";
 import { resolveEnvOptions } from "../core/env";
-import { MISSING_API_KEY_MESSAGE } from "./auth";
 import { isJsonReplacingClient } from "./client";
 import { createDeepSeekServer, servePrecheck } from "./server";
 

package/src/mcp/server.ts

@@ -2,20 +2,23 @@ import type { CallToolResult, ServerContext } from "@modelcontextprotocol/server
 import { McpServer } from "@modelcontextprotocol/server";
 import * as z from "zod/v4";
 import pkg from "../../package.json";
+import { requireApiKey } from "../core/auth";
 import type { RetrievalClient } from "../core/client";
-import { retrievalClient } from "../core/client";
-import { ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV } from "../core/constants";
+import { requestContext, retrievalClient } from "../core/client";
+import { ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV, MAX_FETCH_CHARS, MAX_SEARCH_COUNT } from "../core/constants";
 import {
+  FETCH_MAX_CHARS_PARAMETER,
   FETCH_TOOL_DESCRIPTION,
   FETCH_URL_PARAMETER,
+  SEARCH_COUNT_PARAMETER,
   SEARCH_ORI_QUESTION_PARAMETER,
   SEARCH_QUERY_PARAMETER,
   SEARCH_TOOL_DESCRIPTION,
 } from "../core/descriptions";
 import type { Env } from "../core/env";
 import { formatSearchResults, toStructuredResult } from "../core/format";
+import { bothDisabledPrecheck, withPerCallCount } from "../core/options";
 import type { ResolvedOptions } from "../core/types";
-import { requireApiKey } from "./auth";
 import { omitStructuredContent } from "./client";
 
 export const MCP_SERVER_NAME = "deepseek-web-retrieval";
@@ -23,10 +26,12 @@ export const MCP_SERVER_NAME = "deepseek-web-retrieval";
 const SEARCH_INPUT = z.object({
   query: z.string().min(1).describe(SEARCH_QUERY_PARAMETER),
   original_question: z.string().optional().describe(SEARCH_ORI_QUESTION_PARAMETER),
+  count: z.number().int().min(1).max(MAX_SEARCH_COUNT).optional().describe(SEARCH_COUNT_PARAMETER),
 });
 
 const FETCH_INPUT = z.object({
   url: z.string().min(1).describe(FETCH_URL_PARAMETER),
+  maxChars: z.number().int().min(0).max(MAX_FETCH_CHARS).optional().describe(FETCH_MAX_CHARS_PARAMETER),
 });
 
 /**
@@ -49,15 +54,15 @@ export function createDeepSeekServer(
         inputSchema: SEARCH_INPUT,
         annotations: { readOnlyHint: true },
       },
-      async ({ query, original_question }, ctx) => {
+      async ({ query, original_question, count }, ctx) => {
         try {
-          const request = requestContext(config, env, ctx.mcpReq.signal);
-          const results = await client.searchWeb(query, config.search, {
+          const request = requestContext(config, requireApiKey(env), ctx.mcpReq.signal);
+          const outcome = await client.searchWeb(query, withPerCallCount(config.search, count), {
             ...request,
             oriQuestion: original_question,
           });
-          return callResult(server, ctx, formatSearchResults(results), {
-            results: results.map(toStructuredResult),
+          return callResult(server, ctx, formatSearchResults(outcome.results, outcome), {
+            results: outcome.results.map(toStructuredResult),
           });
         } catch (error) {
           return toErrorResult(error);
@@ -75,9 +80,9 @@ export function createDeepSeekServer(
         inputSchema: FETCH_INPUT,
         annotations: { readOnlyHint: true },
       },
-      async ({ url }, ctx) => {
+      async ({ url, maxChars }, ctx) => {
         try {
-          const request = requestContext(config, env, ctx.mcpReq.signal);
+          const request = requestContext(config, requireApiKey(env), ctx.mcpReq.signal, { maxChars });
           const page = await client.fetchDocument(url, config.fetch, request);
           return callResult(server, ctx, page.content, {
             url: page.url,
@@ -95,10 +100,6 @@ export function createDeepSeekServer(
   return server;
 }
 
-function requestContext(config: ResolvedOptions, env: Env, signal: AbortSignal) {
-  return { signal, auth: { apiKey: requireApiKey(env) }, retry: config.retry };
-}
-
 /**
  * Text content always reaches the model; the structured mirror is dropped for
  * clients that would replace the text with its serialized JSON (Codex does).
@@ -118,11 +119,7 @@ function callResult(
 
 /** Returns the both-disabled message, or undefined when a tool stays enabled. */
 export function servePrecheck(config: ResolvedOptions): string | undefined {
-  if (config.search.enabled || config.fetch.enabled) return undefined;
-  return (
-    `Both tools are disabled (${ENABLE_SEARCH_ENV} and ${ENABLE_FETCH_ENV} are false); ` +
-    "at least one must stay enabled."
-  );
+  return bothDisabledPrecheck(config, `${ENABLE_SEARCH_ENV} and ${ENABLE_FETCH_ENV} are false`);
 }
 
 function toErrorResult(error: unknown): CallToolResult {

package/src/opencode/plugin.ts

@@ -2,10 +2,10 @@ import { Plugin } from "@opencode/plugin";
 import type { Context } from "@opencode/plugin/promise/plugin";
 import type { ToolContext } from "@opencode/plugin/promise/tool";
 import type { RetrievalClient } from "../core/client";
-import { inspectFetchTarget, retrievalClient } from "../core/client";
+import { inspectFetchTarget, requestContext, retrievalClient } from "../core/client";
 import { sharedFileOptions } from "../core/config-file";
 import { configDeviations } from "../core/config-summary";
-import { FETCH_MARKDOWN_ONLY, FETCH_OUTPUT_TRUNCATED } from "../core/descriptions";
+import { FETCH_MARKDOWN_ONLY, FETCH_MAX_CHARS_PARAMETER, FETCH_OUTPUT_TRUNCATED } from "../core/descriptions";
 import { pluginOptionsFromEnv } from "../core/env";
 import { formatQualityMarker } from "../core/format";
 import { resolveFetchTimeoutMs, resolvePluginOptions } from "../core/options";
@@ -16,6 +16,7 @@ type FetchInput = {
   readonly url: string;
   readonly format?: "markdown" | "text" | "html";
   readonly timeout?: number;
+  readonly maxChars?: number;
 };
 
 const FETCH_INPUT = {
@@ -38,6 +39,12 @@ const FETCH_INPUT = {
       description:
         "Optional timeout in seconds (maximum: 120). The effective limit is the shorter of this and fetchTimeoutMs.",
     },
+    maxChars: {
+      type: "integer",
+      minimum: 0,
+      maximum: 1_000_000,
+      description: FETCH_MAX_CHARS_PARAMETER,
+    },
   },
   required: ["url"],
   additionalProperties: false,
@@ -89,11 +96,6 @@ export function resolveRegistration(input?: PluginOptions): Registration {
   };
 }
 
-/** One place builds the per-request context the core expects. */
-function requestContext(config: ResolvedOptions, apiKey: string, signal: AbortSignal, timeoutMs?: number) {
-  return { signal, auth: { apiKey }, retry: config.retry, ...(timeoutMs === undefined ? {} : { timeoutMs }) };
-}
-
 async function runFetch(
   ctx: Context,
   config: ResolvedOptions,
@@ -135,7 +137,7 @@ async function runFetch(
   const page = await client.fetchDocument(
     target,
     config.fetch,
-    requestContext(config, apiKey, context.signal, timeoutMs),
+    requestContext(config, apiKey, context.signal, { timeoutMs, maxChars: input.maxChars }),
   );
   return {
     content: page.content,
@@ -173,12 +175,15 @@ export function createOpenCodePlugin(client: RetrievalClient = retrievalClient)
             name: "DeepSeek",
             execute: async (input, { signal }) => {
               const apiKey = await resolveApiKey(ctx, config.auth.source);
-              const results = await client.searchWeb(
+              const outcome = await client.searchWeb(
                 input.query,
                 config.search,
                 requestContext(config, apiKey, signal),
               );
-              return results.map(toOpenCodeResult);
+              // OpenCode's result shape is closed, so the effective-query header
+              // has nowhere to ride on this path (documented in the guide);
+              // degradation notes still surface through thrown error messages.
+              return outcome.results.map(toOpenCodeResult);
             },
           });
           if (registration.setDefault) editor.default.set("deepseek");

package/src/pi/extension.ts

@@ -3,14 +3,16 @@ import { Type } from "@earendil-works/pi-ai";
 import type { AgentToolResult, ExtensionAPI, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { apiKeyFromEnv } from "../core/auth";
-import type { RequestOptions, RetrievalClient } from "../core/client";
-import { inspectFetchTarget, retrievalClient } from "../core/client";
+import type { RetrievalClient } from "../core/client";
+import { inspectFetchTarget, requestContext, retrievalClient } from "../core/client";
 import { sharedFileOptions } from "../core/config-file";
 import { configDeviations } from "../core/config-summary";
-import { API_KEY_ENV, ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV } from "../core/constants";
+import { API_KEY_ENV, ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV, MAX_FETCH_CHARS, MAX_SEARCH_COUNT } from "../core/constants";
 import {
+  FETCH_MAX_CHARS_PARAMETER,
   FETCH_TOOL_DESCRIPTION,
   FETCH_URL_PARAMETER,
+  SEARCH_COUNT_PARAMETER,
   SEARCH_ORI_QUESTION_PARAMETER,
   SEARCH_QUERY_PARAMETER,
   SEARCH_TOOL_DESCRIPTION,
@@ -18,7 +20,7 @@ import {
 import type { Env } from "../core/env";
 import { pluginOptionsFromEnv } from "../core/env";
 import { formatSearchResults, toStructuredResult } from "../core/format";
-import { resolvePluginOptions } from "../core/options";
+import { bothDisabledPrecheck, resolvePluginOptions, withPerCallCount } from "../core/options";
 import type { ResolvedOptions } from "../core/types";
 import type { ExtensionSettings } from "./settings";
 import { readExtensionSettings, SETTINGS_NAMESPACE } from "./settings";
@@ -30,6 +32,7 @@ const SEARCH_PARAMETERS = Type.Object({
       description: `${SEARCH_ORI_QUESTION_PARAMETER} When left blank, the most recent user message in the session is sent instead, truncated to fit.`,
     }),
   ),
+  count: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_SEARCH_COUNT, description: SEARCH_COUNT_PARAMETER })),
 });
 
 const SEARCH_OUTPUT = Type.Object({
@@ -48,6 +51,9 @@ const SEARCH_OUTPUT = Type.Object({
 
 const FETCH_PARAMETERS = Type.Object({
   url: Type.String({ minLength: 1, description: FETCH_URL_PARAMETER }),
+  maxChars: Type.Optional(
+    Type.Integer({ minimum: 0, maximum: MAX_FETCH_CHARS, description: FETCH_MAX_CHARS_PARAMETER }),
+  ),
 });
 
 const FETCH_OUTPUT = Type.Object({
@@ -77,10 +83,10 @@ export function resolveExtensionOptions(env: Env = process.env, settings: Extens
 
 /** Returns the both-disabled message, or undefined when a tool stays enabled. */
 export function extensionPrecheck(config: ResolvedOptions): string | undefined {
-  if (config.search.enabled || config.fetch.enabled) return undefined;
-  return (
-    `Both tools are disabled (${ENABLE_SEARCH_ENV} and ${ENABLE_FETCH_ENV} are false, or the ` +
-    `${SETTINGS_NAMESPACE} settings namespace disabled them); at least one must stay enabled.`
+  return bothDisabledPrecheck(
+    config,
+    `${ENABLE_SEARCH_ENV} and ${ENABLE_FETCH_ENV} are false, or the ` +
+      `${SETTINGS_NAMESPACE} settings namespace disabled them`,
   );
 }
 
@@ -100,13 +106,13 @@ export function searchTool(config: ResolvedOptions, client: RetrievalClient = re
         // The explicit parameter wins; only when the model left it blank does
         // the session fallback get a say.
         const explicit = params.original_question?.trim() ? params.original_question : undefined;
-        const results = await client.searchWeb(params.query, config.search, {
-          ...requestContext(config, signal),
+        const outcome = await client.searchWeb(params.query, withPerCallCount(config.search, params.count), {
+          ...requestContext(config, requireApiKey(), signal ?? NEVER_ABORTS),
           oriQuestion: explicit ?? sessionOriQuestion(ctx),
         });
         return {
-          content: [{ type: "text", text: formatSearchResults(results) }],
-          structuredContent: { results: results.map(toStructuredResult) },
+          content: [{ type: "text", text: formatSearchResults(outcome.results, outcome) }],
+          structuredContent: { results: outcome.results.map(toStructuredResult) },
           details: undefined,
         };
       } catch (error) {
@@ -130,7 +136,11 @@ export function fetchTool(config: ResolvedOptions, client: RetrievalClient = ret
     async execute(_toolCallId, params, signal): Promise<AgentToolResult> {
       try {
         const target = inspectFetchTarget(params.url, config.fetch);
-        const page = await client.fetchDocument(target, config.fetch, requestContext(config, signal));
+        const page = await client.fetchDocument(
+          target,
+          config.fetch,
+          requestContext(config, requireApiKey(), signal ?? NEVER_ABORTS, { maxChars: params.maxChars }),
+        );
         return {
           content: [{ type: "text", text: page.content }],
           structuredContent: {
@@ -168,10 +178,6 @@ export default function deepSeekWebRetrieval(pi: ExtensionAPI): void {
   if (config.fetch.enabled) pi.registerTool(fetchTool(config));
 }
 
-function requestContext(config: ResolvedOptions, signal: AbortSignal | undefined): RequestOptions {
-  return { signal: signal ?? NEVER_ABORTS, auth: { apiKey: requireApiKey() }, retry: config.retry };
-}
-
 /**
  * Best-effort `ori_question` fallback for when the model left the tool input
  * blank: the most recent user message text in the session projection, readable

package/src/mcp/auth.ts

@@ -1,11 +0,0 @@
-import { apiKeyFromEnv, MISSING_API_KEY_MESSAGE } from "../core/auth";
-import type { Env } from "../core/env";
-
-export { MISSING_API_KEY_MESSAGE };
-
-/** Resolves the API key from the environment or fails with shared guidance. */
-export function requireApiKey(env: Env): string {
-  const apiKey = apiKeyFromEnv(env);
-  if (!apiKey) throw new Error(MISSING_API_KEY_MESSAGE);
-  return apiKey;
-}