deepseek-web-retrieval 0.8.0 → 0.9.0

package/docs/agents/claude-code.md

@@ -168,7 +168,13 @@ The model calls `mcp__deepseek__deepseek_web_search` or `mcp__deepseek__deepseek
 
 The search tool accepts an optional `original_question` argument — the user's question in
 their own words — forwarded as DeepSeek's `ori_question` to sharpen search intent; omit it
-when the query already stands alone.
+when the query already stands alone. It also takes an optional `count` (1–50) for the call,
+and the fetch tool takes an optional `maxChars` (0–1,000,000) per-call output budget; each
+overrides the configured default for that call, so the model can widen a truncated fetch or
+ask for more results without rephrasing the query. When configured domain or language
+operators change the query actually sent, the result text opens with
+`Searched for: <effective query>` (plus any degradation applied to fit the API's
+128-character limit), so the model can attribute results to the configuration in effect.
 
 Tool output is capped at 25k tokens by default (`MAX_MCP_OUTPUT_TOKENS`), and successful
 text results longer than 50,000 characters are saved to a file and referenced — not

package/docs/agents/codex.md

@@ -148,7 +148,13 @@ The model calls `mcp__deepseek__deepseek_web_search` or `mcp__deepseek__deepseek
 
 The search tool accepts an optional `original_question` argument — the user's question in
 their own words — forwarded as DeepSeek's `ori_question` to sharpen search intent; omit it
-when the query already stands alone.
+when the query already stands alone. It also takes an optional `count` (1–50) for the call,
+and the fetch tool takes an optional `maxChars` (0–1,000,000) per-call output budget; each
+overrides the configured default for that call, so the model can widen a truncated fetch or
+ask for more results without rephrasing the query. When configured domain or language
+operators change the query actually sent, the result text opens with
+`Searched for: <effective query>` (plus any degradation applied to fit the API's
+128-character limit), so the model can attribute results to the configuration in effect.
 
 ## Configuration
 

package/docs/agents/opencode-v2.md

@@ -176,9 +176,17 @@ Fetch https://opencode.ai/v2/docs/build/plugins and summarize the plugin lifecyc
 The model calls `websearch` (provider `deepseek`) or `deepseek_fetch`. When
 `fetchOverrideWebfetch` is enabled, Markdown fetches go through `webfetch` instead.
 
-DeepSeek's optional `ori_question` is not sent on this path: OpenCode's `websearch` tool
-input is fixed to `query` at 2.0.32, so the provider has no channel for it (see the
-[research note](../research/ori-question-sourcing.md)).
+DeepSeek's optional `ori_question` is not sent on this path, and the model cannot request a
+per-call result count: OpenCode's `websearch` tool input is fixed to `query` (verified unchanged
+at 2.1.4), so the provider has no channel for either. Upstream requests:
+[anomalyco/opencode#58635](https://github.com/anomalyco/opencode/issues/58635) (session linkage)
+and [#58636](https://github.com/anomalyco/opencode/issues/58636) (per-call `count`); see the
+[research note](../research/ori-question-sourcing.md). The fetch tools are not constrained:
+they accept an optional per-call `maxChars` (0–1,000,000) that overrides the configured
+`fetchMaxChars` for one call, so the model can widen the budget after seeing a
+`[content truncated]` marker. The effective-query header and query degradation notes have no
+channel on this path either — OpenCode's result shape is closed — but degradation still runs,
+and failures that cannot degrade surface as errors.
 
 ## Configuration
 

package/docs/agents/pi.md

@@ -110,7 +110,12 @@ The search tool accepts an optional `original_question` input — the user's que
 own words — forwarded as DeepSeek's `ori_question` to sharpen search intent. When the model
 leaves it blank, the extension falls back to the most recent user message in the session
 (best-effort; truncated to the API's 128-character limit). The MCP fallback path has no
-session access, so there a blank input simply omits the parameter.
+session access, so there a blank input simply omits the parameter. The search tool also
+takes an optional `count` (1–50) for the call, and the fetch tool an optional `maxChars`
+(0–1,000,000) per-call output budget; each overrides the configured default for that call.
+When configured domain or language operators change the query actually sent, the result text
+opens with `Searched for: <effective query>` (plus any degradation applied to fit the API's
+128-character limit), so the model can attribute results to the configuration in effect.
 
 ## Configuration
 

package/docs/configuration.md

@@ -84,6 +84,7 @@ drift from the code (`bun run docs:matrix` regenerates it; CI checks it).
 | `fetchBlockPrivateHosts` | `DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS` | true |
 | `maxRetries` | `DEEPSEEK_MAX_RETRIES` | 2 |
 | `retryBaseDelayMs` | `DEEPSEEK_RETRY_BASE_DELAY_MS` | 250 |
+| `baseUrl` | `DEEPSEEK_BASE_URL` | https://api.deepseek.com |
 
 <!-- /generated: knob-table -->
 
@@ -105,5 +106,11 @@ drift from the code (`bun run docs:matrix` regenerates it; CI checks it).
 - **`searchLocalization` must be a valid IPv4 or IPv6 address**; anything else
   is dropped at option resolution. It is deployment-level configuration, never
   a per-call tool parameter.
+- **`baseUrl` routes the retrieval API** (`/v1/tools/search` and
+  `/v1/tools/fetch` are composed from it). It is infrastructure routing for
+  proxies, gateways, and mock upstreams — not a provider switch, so nothing
+  falls back to another search service. Only an http(s) URL survives
+  resolution (trailing slashes are stripped); anything else drops back to
+  `https://api.deepseek.com`.
 - **Domains** in the environment are comma-separated; entries that are not
   domains are dropped (and reported by `config`).

package/docs/design/installer-design.md

@@ -186,10 +186,10 @@ into any existing `permissions` array rather than replacing it.
   comments and formatting in `opencode.jsonc` and Pi's `mcp.json` survive apply and
   uninstall; TOML edits go through `smol-toml` and drop comments, which the plan reports
   as a note. The hand-written JSONC stripper that predated this lived in `scripts/jsonc.ts`.
-- Install state lives per host and scope (global under
-  `~/.config/deepseek-web-retrieval/`, project under `.deepseek-web-retrieval/`); it
-  records snapshots, appended entries, created files, and created path prefixes — never
-  full file contents, so other servers' secrets stay out of the state file.
+- Install records live per host and scope (global under
+  `~/.config/deepseek-web-retrieval/`, project under `.deepseek-web-retrieval/`); they
+  record snapshots, appended entries, created files, and created path prefixes — never
+  full file contents, so other servers' secrets stay out of the install record.
 - Re-applying over a previous init inherits the original snapshots instead of recording
   the installer's own output as the "previous" value. Pi forced re-inits keep their
   competitor-disable ops even when those servers are already disabled, so orphan

package/docs/research/ori-question-sourcing.md

@@ -170,6 +170,15 @@ tag (commit `843a6c5`); the `opencode-ai/opencode` repository's tags stop at `v0
   only heuristic correlation via the session hooks (which fire per model request with the
   sessionID, but no API contract binds a provider call to a session).
 
+  Post-baseline drift check (2026-10-24): the interface is unchanged at 2.1.4, the latest npm
+  release on that date (unpkg dist of `@opencode/schema`/`@opencode/plugin` 2.1.4:
+  `ProviderInput = Pick<Input, "query">`, provider context `{ signal }`). Upstream requests
+  filed the same day to widen this surface:
+  [anomalyco/opencode#58635](https://github.com/anomalyco/opencode/issues/58635) (session
+  linkage in the provider execute context) and
+  [#58636](https://github.com/anomalyco/opencode/issues/58636) (optional per-call `count`
+  passthrough) — re-check both when the baseline or the OpenCode lock bumps.
+
 Verdict: **tool path (`deepseek_fetch` / the `webfetch` override): A feasible (validated against
 the declared schema; raw JSON Schema forwarded verbatim) and B feasible
 (`ctx.session.context`). Websearch provider path (the search replacement this repo ships): neither
@@ -256,7 +265,9 @@ negotiated revision in the matrix.
   `ctx.session.context({ sessionID })` — user messages with their `text` — at call time, so
   channel B exists here without touching schemas. The `websearch` provider replacement — the path
   this repo uses for search — has neither channel at 2.0.32: its model-facing input schema is
-  fixed in host source to `query`, and its provider context is `{ signal }` only. Note also that
+  fixed in host source to `query`, and its provider context is `{ signal }` only (upstream
+  requests: [#58635](https://github.com/anomalyco/opencode/issues/58635),
+  [#58636](https://github.com/anomalyco/opencode/issues/58636)). Note also that
   `FETCH_INPUT` sets `additionalProperties: false`, which matters if a parameter is ever added on
   channel A: an undeclared field would be rejected by OpenCode's runtime validation with a
   retryable error.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "deepseek-web-retrieval",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Token-efficient DeepSeek Search and Fetch for coding agents, starting with OpenCode v2.",
   "type": "module",
   "license": "MIT",
@@ -57,7 +57,8 @@
     "prepublishOnly": "bun run check:release",
     "test": "bun test",
     "test:package": "node scripts/test-package.mjs",
-    "test:e2e:keyless": "bun run test:e2e pi pi-extension installer reinit upgrade pkg capability-off",
+    "test:e2e:keyless": "bun run test:e2e pi pi-extension pi-mock opencode-mock installer reinit upgrade pkg capability-off",
+    "test:e2e:billed": "bun run test:e2e pi-billed opencode codex claude-code preferred",
     "check:release": "bun run check && bun run test:package && bun run test:e2e:keyless",
     "test:e2e": "bun run test/e2e/run.ts",
     "docs:matrix": "bun run scripts/render-matrix.ts",

package/src/core/auth.ts

@@ -7,3 +7,10 @@ export function apiKeyFromEnv(env: Readonly<Record<string, string | undefined>>
   const key = env[API_KEY_ENV]?.trim();
   return key ? key : undefined;
 }
+
+/** Resolves the API key from the environment or fails with shared guidance. */
+export function requireApiKey(env: Readonly<Record<string, string | undefined>>): string {
+  const apiKey = apiKeyFromEnv(env);
+  if (!apiKey) throw new Error(MISSING_API_KEY_MESSAGE);
+  return apiKey;
+}

package/src/core/client.ts

@@ -1,7 +1,14 @@
-import { FETCH_ENDPOINT, MAX_ORI_QUESTION_CHARS, MAX_QUERY_CHARS, SEARCH_ENDPOINT } from "./constants";
+import {
+  DEFAULT_API_BASE_URL,
+  FETCH_ENDPOINT_PATH,
+  MAX_FETCH_CHARS,
+  MAX_ORI_QUESTION_CHARS,
+  MAX_QUERY_CHARS,
+  SEARCH_ENDPOINT_PATH,
+} from "./constants";
 import { assertFetchHostPolicy } from "./domains";
 import { formatFetchedContent, truncate } from "./format";
-import { buildQuery, processResults } from "./search";
+import { composeSearchQuery, processResults } from "./search";
 import { postJson } from "./transport";
 import type {
   DeepSeekSearchResult,
@@ -9,9 +16,10 @@ import type {
   FetchedPage,
   FetchOptions,
   RequestAuth,
+  ResolvedOptions,
   RetryOptions,
   SearchOptions,
-  SearchResult,
+  SearchOutcome,
 } from "./types";
 import { parseFetchUrl } from "./url";
 
@@ -22,6 +30,24 @@ function effectiveTimeout(configuredMs: number, perCallMs: number | undefined):
   return perCallMs === undefined ? configuredMs : Math.min(configuredMs, perCallMs);
 }
 
+/**
+ * The per-call budget wins outright, unlike timeouts: a model that just saw a
+ * truncation marker is asking for more than the default on purpose, so the
+ * configured value stays the default rather than a ceiling.
+ */
+function effectiveMaxChars(configured: number, perCall: number | undefined): number {
+  if (perCall === undefined || !Number.isFinite(perCall)) return configured;
+  return Math.min(MAX_FETCH_CHARS, Math.max(0, Math.trunc(perCall)));
+}
+
+/**
+ * Composes a request endpoint from the resolved base URL (already
+ * slash-stripped by resolveBaseUrl; absent means the production default).
+ */
+function apiUrl(baseUrl: string | undefined, path: string): string {
+  return `${baseUrl ?? DEFAULT_API_BASE_URL}${path}`;
+}
+
 /**
  * The wire value for ori_question: absent/whitespace-only means "not
  * provided"; longer values are clamped rather than rejected — the field is
@@ -49,6 +75,14 @@ export interface RequestOptions {
   readonly retry: RetryOptions;
   /** Per-call cap in milliseconds; the shorter of this and the configured timeout wins. */
   readonly timeoutMs?: number;
+  /** Per-call fetch budget in characters; overrides the configured cap for this call. */
+  readonly maxChars?: number;
+  /**
+   * The resolved API root; adapters pass `config.baseUrl` so every request
+   * follows the `baseUrl` knob. Absent falls back to the production default
+   * (unit tests composing requests by hand rely on that).
+   */
+  readonly baseUrl?: string;
 }
 
 export interface SearchRequest extends RequestOptions {
@@ -60,31 +94,46 @@ export interface SearchRequest extends RequestOptions {
   readonly oriQuestion?: string;
 }
 
-export async function searchWeb(
-  query: string,
-  options: SearchOptions,
-  request: SearchRequest,
-): Promise<SearchResult[]> {
+/**
+ * The per-request context every adapter assembles from the resolved config:
+ * bound auth, retry policy, and base URL, plus any per-call overrides a
+ * tool input supplied.
+ */
+export function requestContext(
+  config: Pick<ResolvedOptions, "retry" | "baseUrl">,
+  apiKey: string,
+  signal: AbortSignal,
+  perCall?: { readonly timeoutMs?: number; readonly maxChars?: number },
+): RequestOptions {
+  return {
+    signal,
+    auth: { apiKey },
+    retry: config.retry,
+    baseUrl: config.baseUrl,
+    ...(perCall?.timeoutMs === undefined ? {} : { timeoutMs: perCall.timeoutMs }),
+    ...(perCall?.maxChars === undefined ? {} : { maxChars: perCall.maxChars }),
+  };
+}
+
+export async function searchWeb(query: string, options: SearchOptions, request: SearchRequest): Promise<SearchOutcome> {
   const trimmed = query.trim();
   if (!trimmed) throw new Error("DeepSeek search query must not be empty");
-  if (Array.from(trimmed).length > MAX_QUERY_CHARS) {
-    throw new Error(`DeepSeek search query must be ${MAX_QUERY_CHARS} characters or fewer`);
-  }
-
-  const builtQuery = buildQuery(trimmed, options);
-  const builtQueryLength = Array.from(builtQuery).length;
-  if (builtQueryLength > MAX_QUERY_CHARS) {
+  const trimmedLength = Array.from(trimmed).length;
+  if (trimmedLength > MAX_QUERY_CHARS) {
+    // The query rides in the message so the model can see what to shorten.
     throw new Error(
-      `DeepSeek search query must be ${MAX_QUERY_CHARS} characters or fewer after applying ` +
-        `blockedDomains, includeDomains, and language ` +
-        `(built query is ${builtQueryLength} characters)`,
+      `DeepSeek search query must be ${MAX_QUERY_CHARS} characters or fewer ` +
+        `(got ${trimmedLength}: ${JSON.stringify(truncate(trimmed, 64))})`,
     );
   }
 
+  const composed = composeSearchQuery(trimmed, options);
+  const builtQuery = composed.query;
+
   const timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs);
   const oriQuestion = oriQuestionValue(request.oriQuestion);
   const payload = await postJson<SearchResponse>(
-    SEARCH_ENDPOINT,
+    apiUrl(request.baseUrl, SEARCH_ENDPOINT_PATH),
     {
       query: builtQuery,
       count: options.count,
@@ -99,7 +148,13 @@ export async function searchWeb(
   if (!Array.isArray(payload.results)) {
     throw new Error("DeepSeek Search returned a response without a results array");
   }
-  return processResults(payload.results as DeepSeekSearchResult[], options);
+  const results = processResults(payload.results as DeepSeekSearchResult[], options);
+  return {
+    results,
+    inputQuery: trimmed,
+    effectiveQuery: builtQuery,
+    notes: composed.notes,
+  };
 }
 
 export async function fetchPage(url: URL, options: FetchOptions, request: RequestOptions): Promise<FetchedPage> {
@@ -108,10 +163,15 @@ export async function fetchPage(url: URL, options: FetchOptions, request: Reques
   const target = parseFetchUrl(url.href);
   assertFetchHostPolicy(target, options);
   const timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs);
-  const payload = await postJson<FetchResponse>(FETCH_ENDPOINT, { url: target.href }, "DeepSeek Fetch", {
-    ...request,
-    timeoutMs: timeout,
-  });
+  const payload = await postJson<FetchResponse>(
+    apiUrl(request.baseUrl, FETCH_ENDPOINT_PATH),
+    { url: target.href },
+    "DeepSeek Fetch",
+    {
+      ...request,
+      timeoutMs: timeout,
+    },
+  );
   const title = typeof payload.title === "string" ? payload.title.trim() : "";
   const content = typeof payload.content === "string" ? payload.content : "";
   if (!content.trim()) {
@@ -138,7 +198,11 @@ export async function fetchDocument(
 ): Promise<FetchedDocument> {
   if (typeof url !== "string" && !(url instanceof URL)) throw new Error('"url" must be a string or URL');
   const page = await fetchPage(url instanceof URL ? url : parseFetchUrl(url), options, request);
-  const formatted = formatFetchedContent(page.title, page.content, options.maxChars);
+  const formatted = formatFetchedContent(
+    page.title,
+    page.content,
+    effectiveMaxChars(options.maxChars, request.maxChars),
+  );
   return {
     url: page.url,
     title: page.title,

package/src/core/config-summary.ts

@@ -27,6 +27,7 @@ const VOCABULARY = [
   { key: "fetchBlockPrivateHosts", read: (o: ResolvedOptions) => o.fetch.blockPrivateHosts },
   { key: "maxRetries", read: (o: ResolvedOptions) => o.retry.maxRetries },
   { key: "retryBaseDelayMs", read: (o: ResolvedOptions) => o.retry.baseDelayMs },
+  { key: "baseUrl", read: (o: ResolvedOptions) => o.baseUrl },
 ] as const;
 
 /** The config keys in vocabulary order; the shared config file accepts exactly these. */

package/src/core/constants.ts

@@ -1,5 +1,15 @@
-export const SEARCH_ENDPOINT = "https://api.deepseek.com/v1/tools/search";
-export const FETCH_ENDPOINT = "https://api.deepseek.com/v1/tools/fetch";
+/**
+ * The DeepSeek API root every request is composed from. `baseUrl` overrides it
+ * (env `DEEPSEEK_BASE_URL`, shared-file key `baseUrl`) so proxies, enterprise
+ * gateways, and mock upstreams can intercept retrieval without touching the
+ * adapters; the two endpoints below stay the production default.
+ */
+export const DEFAULT_API_BASE_URL = "https://api.deepseek.com";
+export const SEARCH_ENDPOINT_PATH = "/v1/tools/search";
+export const FETCH_ENDPOINT_PATH = "/v1/tools/fetch";
+
+export const SEARCH_ENDPOINT = `${DEFAULT_API_BASE_URL}${SEARCH_ENDPOINT_PATH}`;
+export const FETCH_ENDPOINT = `${DEFAULT_API_BASE_URL}${FETCH_ENDPOINT_PATH}`;
 
 /**
  * Search defaults are benchmarked against surveyed AI-native search APIs and
@@ -19,6 +29,10 @@ export const DEFAULT_MIN_AUTHORITY = 0;
 export const DEFAULT_MAX_SUMMARY_CHARS = 1200;
 
 export const DEFAULT_FETCH_MAX_CHARS = 16000;
+/** The ceiling for a per-call fetch budget, matching the configured knob's range. */
+export const MAX_FETCH_CHARS = 1_000_000;
+/** The API's documented count range top; per-call counts share it. */
+export const MAX_SEARCH_COUNT = 50;
 export const DEFAULT_TIMEOUT_MS = 30000;
 export const MIN_TIMEOUT_MS = 1000;
 export const MAX_TIMEOUT_MS = 120000;
@@ -45,6 +59,7 @@ export const MAX_RETRY_DELAY_MS = 10000;
 
 /** The single source for every DEEPSEEK_* environment variable name. */
 export const API_KEY_ENV = "DEEPSEEK_API_KEY";
+export const BASE_URL_ENV = "DEEPSEEK_BASE_URL";
 export const ENABLE_SEARCH_ENV = "DEEPSEEK_ENABLE_SEARCH";
 export const ENABLE_FETCH_ENV = "DEEPSEEK_ENABLE_FETCH";
 export const SEARCH_LOCALIZATION_ENV = "DEEPSEEK_SEARCH_LOCALIZATION";

package/src/core/descriptions.ts

@@ -6,7 +6,8 @@
 export const FETCH_SERVICE_LIMITS =
   "DeepSeek does not render JavaScript and cannot reach private networks; PDFs, images, and other binary files are unsupported.";
 
-export const FETCH_OUTPUT_TRUNCATED = "Output is truncated to the configured size.";
+export const FETCH_OUTPUT_TRUNCATED =
+  "Output is truncated to the configured size; the optional maxChars parameter raises or lowers that size for one call.";
 
 export const FETCH_MARKDOWN_ONLY = 'Only format "markdown" is supported.';
 
@@ -45,3 +46,11 @@ export const SEARCH_ORI_QUESTION_PARAMETER =
   "reformulated query. Optional; 1-128 characters, and longer values are truncated.";
 
 export const FETCH_URL_PARAMETER = "Absolute http:// or https:// URL to fetch. Credentials are rejected.";
+
+export const FETCH_MAX_CHARS_PARAMETER =
+  "Optional per-call character budget for this fetch, 0-1,000,000, title included. Overrides the configured cap " +
+  "for this call; a [content truncated] marker is appended when the output is cut.";
+
+export const SEARCH_COUNT_PARAMETER =
+  "Optional number of results for this call, 1-50. Overrides the configured count and result cap for this call; " +
+  "billing is per request, not per result.";

package/src/core/env.ts

@@ -1,4 +1,4 @@
-import { API_KEY_ENV, ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV, SEARCH_LOCALIZATION_ENV } from "./constants";
+import { API_KEY_ENV, BASE_URL_ENV, ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV, SEARCH_LOCALIZATION_ENV } from "./constants";
 import { normalizeDomain } from "./domains";
 import { resolvePluginOptions } from "./options";
 import type { PluginOptions, ResolvedOptions } from "./types";
@@ -23,6 +23,7 @@ const NUMBER_ENV = {
 const TEXT_ENV = {
   language: "DEEPSEEK_SEARCH_LANGUAGE",
   searchLocalization: SEARCH_LOCALIZATION_ENV,
+  baseUrl: BASE_URL_ENV,
 } as const;
 
 const DOMAINS_ENV = {
@@ -107,6 +108,7 @@ export function envOptionsReport(env: Env = process.env): EnvOptionsReport {
 
   putNumber(options, "maxRetries", env, warnings);
   putNumber(options, "retryBaseDelayMs", env, warnings);
+  putText(options, "baseUrl", env);
 
   const known = new Set(OPTION_ENV_VARS);
   for (const key of Object.keys(env)) {

package/src/core/format.ts

@@ -85,14 +85,34 @@ export function formatTimeoutError(operation: string, timeoutMs: number): string
   return `${operation} timed out after ${timeoutMs} ms`;
 }
 
+/**
+ * The query context shown to the model above the results: emitted only when
+ * the effective query differs from what the model sent (operators applied or
+ * degradation happened), so an unfiltered search adds no header noise.
+ */
+export interface SearchQueryContext {
+  readonly inputQuery: string;
+  readonly effectiveQuery: string;
+  readonly notes: readonly string[];
+}
+
+function searchHeader(context: SearchQueryContext | undefined): string | undefined {
+  if (!context) return undefined;
+  if (context.effectiveQuery === context.inputQuery && context.notes.length === 0) return undefined;
+  const header = `Searched for: ${context.effectiveQuery}`;
+  return context.notes.length > 0 ? `${header} — ${context.notes.join("; ")}` : header;
+}
+
 /**
  * Renders processed search results as Markdown for a text content block.
  * Hosts that ignore structured output read this text.
  */
-export function formatSearchResults(results: readonly SearchResult[]): string {
-  if (results.length === 0) return "No results found.";
-
-  return results
+export function formatSearchResults(results: readonly SearchResult[], context?: SearchQueryContext): string {
+  const header = searchHeader(context);
+  if (results.length === 0) {
+    return header ? `${header}\n\nNo results found.` : "No results found.";
+  }
+  const body = results
     .map((result, index) => {
       const title = result.title?.trim() || result.url;
       const marker = formatQualityMarker(result);
@@ -106,6 +126,7 @@ export function formatSearchResults(results: readonly SearchResult[]): string {
       return lines.join("\n");
     })
     .join("\n\n");
+  return header ? `${header}\n\n${body}` : body;
 }
 
 /**

package/src/core/options.ts

@@ -1,5 +1,6 @@
 import { isIP } from "node:net";
 import {
+  DEFAULT_API_BASE_URL,
   DEFAULT_API_KEY_SOURCE,
   DEFAULT_FETCH_MAX_CHARS,
   DEFAULT_MAX_RESULTS,
@@ -12,6 +13,7 @@ import {
   DEFAULT_TIMEOUT_MS,
   MAX_RETRIES,
   MAX_RETRY_DELAY_MS,
+  MAX_SEARCH_COUNT,
   MAX_TIMEOUT_MS,
   MIN_TIMEOUT_MS,
 } from "./constants";
@@ -32,9 +34,22 @@ export function resolvePluginOptions(input?: PluginOptions): ResolvedOptions {
     fetch: resolveFetchOptions(input),
     auth: resolveAuthOptions(input),
     retry: resolveRetryOptions(input),
+    baseUrl: resolveBaseUrl(input?.baseUrl),
   };
 }
 
+/**
+ * The both-disabled refusal both server surfaces share: undefined when a tool
+ * stays enabled, otherwise one message naming why both are off.
+ */
+export function bothDisabledPrecheck(
+  config: Pick<ResolvedOptions, "search" | "fetch">,
+  reason: string,
+): string | undefined {
+  if (config.search.enabled || config.fetch.enabled) return undefined;
+  return `Both tools are disabled (${reason}); at least one must stay enabled.`;
+}
+
 export function resolveSearchOptions(input?: PluginOptions): SearchOptions {
   const count = clampInt(input?.count, DEFAULT_SEARCH_COUNT, 1, 50);
   return {
@@ -82,6 +97,38 @@ export function resolveRetryOptions(input?: PluginOptions): RetryOptions {
   };
 }
 
+/**
+ * Constraint: only an http(s) URL with no fragment survives, trailing slashes
+ * stripped so endpoint composition never doubles them. Anything else — a bare
+ * hostname, a non-http scheme, an empty string — drops to the production
+ * default, the same drop-and-default contract as every other invalid knob.
+ */
+export function resolveBaseUrl(value: unknown): string {
+  if (typeof value !== "string") return DEFAULT_API_BASE_URL;
+  const trimmed = value.trim();
+  if (!trimmed) return DEFAULT_API_BASE_URL;
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return DEFAULT_API_BASE_URL;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return DEFAULT_API_BASE_URL;
+  return trimmed.replace(/\/+$/, "");
+}
+
+/**
+ * Applies a per-call result count to resolved search options. The count the
+ * model asked for is what it wants to see, so it sets both the request count
+ * and the post-filter cap for that call; the configured knobs stay the
+ * default, not a ceiling.
+ */
+export function withPerCallCount(options: SearchOptions, count: number | undefined): SearchOptions {
+  if (count === undefined || !Number.isFinite(count)) return options;
+  const clamped = Math.min(MAX_SEARCH_COUNT, Math.max(1, Math.trunc(count)));
+  return { ...options, count: clamped, maxResults: clamped };
+}
+
 /**
  * Resolves the per-call timeout from the plugin cap and the built-in tool's
  * `timeout` field (seconds). The shorter limit wins.