deepseek-web-retrieval 0.8.0 → 0.10.0

package/docs/research/search-inline-content.md

@@ -17,6 +17,12 @@ source at the repo's locked tag. Secondhand blogs are excluded. Where no primary
 a fact — most importantly the size of `content` — that is stated as such: an undocumented
 size is itself a decision-relevant fact.
 
+**Short answer:** DeepSeek documents **no size bound** for `need_content` content and no
+per-result budget knob; of the eight architectures surveyed below, only Jina ships
+content-bearing search as the default; and the binding host cap is Pi's 20 KB MCP-path
+truncation — the volume math below puts a safe per-result budget in the ~1k–2k char
+range.
+
 ## What `need_content=true` provably returns
 
 From the official Search & Fetch guide, the parameter and its response field, verbatim:
@@ -101,15 +107,36 @@ search response without setting any parameter.
 
 | Vendor | Content inline by default? | Opt-in mechanism | Per-result content budget knob | Separate fetch tool? |
 | --- | --- | --- | --- | --- |
-| **Tavily** | Partial — default response carries per-result `content` of **relevance chunks**: `chunks_per_source` **3** chunks of ~500 chars (~1,500 chars/result) | Full body via `include_raw_content` (default **false**; accepts `markdown`/`text`/`true`) | Chunk count only (`chunks_per_source` 1–3, sizes `content`, **not** `raw_content`); no knob limits `raw_content` size in `/search` | Yes — `/extract` (up to 20 URLs; `extract_depth` basic/advanced; no per-URL cap; ~800-char chunks only when `query` is given) |
+| **Tavily** | Partial — per-result `content` of relevance chunks by default | Full body via `include_raw_content` (default **false**) | Chunk count only (`chunks_per_source` 1–3); no knob limits `raw_content` size in `/search` | Yes — `/extract` (up to 20 URLs) |
 | **Exa** | No — `contents.text` defaults **false** | `contents.text: true` in the **same** `POST /search` body | **`maxCharacters`** (1–1,000,000, no published default) plus `verbosity` `compact`/`standard`/`full` | Yes — `/contents` endpoint by result ID/URL |
 | **You.com** | No — “Omit `extraction` for a plain search that returns snippets only” | `extraction.full_page` (“crawls each result and returns the page content”) | **None for `full_page`** (only `crawl_timeout`); the `highlights` mode has a response-wide `total_max_tokens` budget of **8192** (1,024–8,192) | No dedicated fetch endpoint documented on `/v1/search` |
-| **Perplexity** | No — Search API results are `title`/`url`/`snippet`/`date` only | Token budgets: `max_tokens` ("Maximum total webpage content tokens to return across all search results") and **`max_tokens_per_page`** ("Maximum webpage content tokens to extract from each result page"), on both the Search API and the Agent API `web_search` tool; **no default published** for either ("the default budgets apply"); on the Search API the extracted text surfaces through `snippet` | **`max_tokens_per_page`** (min 1, max 1,000,000, no default) | Yes — Agent API "Fetch URL Content" tool ("Fetch full content from known URLs") |
-| **Anthropic** | Not caller-visible — `web_search` results carry `url`/`title`/`page_age` plus `encrypted_content` (“Encrypted content that you must pass back in multi-turn conversations”); the model reads content in its context, the caller cannot | `response_inclusion` (`"full"` default / `"excluded"`) only controls whether consumed search blocks are echoed in the response — it is not a content-size knob | **None** (dynamic filtering on `web_search_20260209+` has Claude write code to filter results before they reach context, but no caller-set budget) | Yes — `web_fetch` with token-based `max_content_tokens` (no published default) |
-| **Firecrawl** | No — search returns `title`/`description`/`url` (+ `highlights`, default true) | `scrapeOptions` (default `{}`): "Include `scrapeOptions` with `formats: [{"type": "markdown"}] to get complete markdown content for each search result" | **None** for content size (`onlyMainContent` default true trims boilerplate, not length) | Collapsed into search via `scrapeOptions`; standalone `/scrape` endpoint also exists |
-| **Jina** (`s.jina.ai`) | **Yes — the only default-content architecture surveyed**: "Reader searches the web, fetches the top 5 results, visits each URL, and applies `r.jina.ai` to it"; result count is fixed at 5, not a parameter | None needed (content is the product) | **`x-token-budget`** header, no default (parsed only when sent) — a global budget, not per-result | Same product (`r.jina.ai`) serves plain fetch |
+| **Perplexity** | No — Search API results are `title`/`url`/`snippet`/`date` only | Token budgets on both the Search API and the Agent API `web_search` tool (detail below) | **`max_tokens_per_page`** (min 1, max 1,000,000, no default) | Yes — Agent API “Fetch URL Content” tool (“Fetch full content from known URLs”) |
+| **Anthropic** | Not caller-visible — content is model-only (`encrypted_content`) | None — `response_inclusion` is not a content-size knob | **None** (no caller-set budget) | Yes — `web_fetch` with token-based `max_content_tokens` (no published default) |
+| **Firecrawl** | No — search returns `title`/`description`/`url` (+ `highlights`, default true) | `scrapeOptions` (default `{}`): “Include `scrapeOptions` with `formats: [{“type”: “markdown”}]` to get complete markdown content for each search result” | **None** for content size (`onlyMainContent` default true trims boilerplate, not length) | Collapsed into search via `scrapeOptions`; standalone `/scrape` endpoint also exists |
+| **Jina** (`s.jina.ai`) | **Yes — the only default-content architecture surveyed**; result count is fixed at 5, not a parameter | None needed (content is the product) | **`x-token-budget`** header, no default (parsed only when sent) — a global budget, not per-result | Same product (`r.jina.ai`) serves plain fetch |
 | **DeepSeek (subject of this note)** | No — `need_content` defaults **false** | `need_content: true` | **None documented** (see above) | Yes — Fetch API, Markdown, no documented size cap |
 
+Detail for the trimmed rows above:
+
+- **Tavily:** the default per-result `content` carries **relevance chunks** —
+  `chunks_per_source` **3** chunks of ~500 chars (~1,500 chars/result); `include_raw_content`
+  accepts `markdown`/`text`/`true`; the chunk sizes apply to `content`, **not**
+  `raw_content`; `/extract` takes up to 20 URLs with `extract_depth` basic/advanced, no
+  per-URL cap, ~800-char chunks only when `query` is given.
+- **Perplexity:** `max_tokens` (“Maximum total webpage content tokens to return across
+  all search results”) and **`max_tokens_per_page`** (“Maximum webpage content tokens to
+  extract from each result page”), **no default published** for either (“the default
+  budgets apply”); on the Search API the extracted text surfaces through `snippet`.
+- **Anthropic:** `web_search` results carry `url`/`title`/`page_age` plus
+  `encrypted_content` (“Encrypted content that you must pass back in multi-turn
+  conversations”) — the model reads content in its context, the caller cannot.
+  `response_inclusion` (`”full”` default / `”excluded”`) only controls whether consumed
+  search blocks are echoed in the response; dynamic filtering on `web_search_20260209+`
+  has Claude write code to filter results before they reach context, but no caller-set
+  budget exists.
+- **Jina:** “Reader searches the web, fetches the top 5 results, visits each URL, and
+  applies `r.jina.ai` to it.”
+
 The split, stated plainly: of the eight architectures surveyed, exactly one (Jina
 `s.jina.ai`) ships content-bearing search as the default, and it pins the result count at 5.
 Every other vendor makes inline content opt-in (Tavily `raw_content`, Exa `contents.text`,
@@ -119,6 +146,17 @@ exist they are per-result character caps (Exa `maxCharacters`) or per-result tok
 (Perplexity `max_tokens_per_page`); Tavily and You.com ship full-content modes with **no**
 per-result size knob at all — the two closest analogues to DeepSeek's `need_content`.
 
+One further architecture reading (added 2026-10-24, same sources): **no surveyed vendor
+narrows another parameter's value range when inline content is requested.** Every budget
+knob in the table is static-range, conditional-effect — Exa's `maxCharacters` and
+Perplexity's `max_tokens_per_page` keep their 1–1,000,000 ranges whether or not
+`contents.text`/extraction is engaged, Tavily's `chunks_per_source` and Anthropic's
+`max_content_tokens` are likewise unconditional, and none shrinks `count`/`numResults`
+or any other parameter's domain when content flows (Jina's fixed 5 is its architecture,
+not a conditional rule). The only conditional behavior anywhere in the table is which
+budget *applies*; a content flag that reshaped other parameters' allowed values appears
+in none of the eight.
+
 Sources: [Tavily /search](https://docs.tavily.com/documentation/api-reference/endpoint/search) ·
 [Tavily /extract](https://docs.tavily.com/documentation/api-reference/endpoint/extract) ·
 [Exa /search](https://exa.ai/docs/reference/search) ·
@@ -173,8 +211,9 @@ With `count=10` (the repo's default, and DeepSeek's) and `need_content: true`:
   [mcp_types.rs at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/config/src/mcp_types.rs)).
   [control-matrix.md](control-matrix.md) records Codex's 300 s MCP tool timeout — latency,
   not size, is that host's documented ceiling.
-- **The binding constraint is Pi's 20 KB**, roughly an order of magnitude tighter than
-  Claude Code's 25k-token default: a per-result content budget in the **~1k–2k char**
+- **The binding constraint is Pi's 20 KB**, roughly 5× tighter than Claude Code's
+  25k-token default (≈100k English chars by the conversions above): a per-result
+  content budget in the **~1k–2k char**
   range keeps count=10 under every published cap; reusing the repo's fetch budget (16,000
   chars) *per search result* would reach 160k chars per response — 8× Pi's cap and ~40k
   tokens on Claude Code.
@@ -195,8 +234,9 @@ maintainer decides.
 - **Today's pipeline would silently drop the content.** `DeepSeekSearchResult`
   ([types.ts](../../src/core/types.ts)) has no `content` field, and `processResults`
   ([search.ts](../../src/core/search.ts)) maps `SearchResult.content` from
-  `summary ?? snippet` only — a `need_content` response's page bodies would be received and
-  discarded, unbilled-for-nothing but also unrendered.
+  `summary ?? snippet` only — a `need_content` response's page bodies would be received
+  and discarded: they cost nothing extra (billing is per request), but they are also
+  never rendered.
 - **The only per-result clamp in the search path is `maxSummaryChars` (1,200)** — a
   summary/snippet budget. `fetchMaxChars` (16,000) and `formatFetchedContent`'s
   truncation-marker logic apply exclusively to the fetch tool path. There is **no per-result

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "deepseek-web-retrieval",
-  "version": "0.8.0",
+  "version": "0.10.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 {
@@ -58,37 +92,59 @@ export interface SearchRequest extends RequestOptions {
    * ori_question to sharpen intent; adapters fill it from tool input.
    */
   readonly oriQuestion?: string;
+  /**
+   * Per-call only. The tool input's need_content flag: true asks for each
+   * result's page body, sent as the API's need_content and timed against
+   * contentTimeoutMs instead of timeoutMs.
+   */
+  readonly needContent?: boolean;
+}
+
+/**
+ * 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<SearchResult[]> {
+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 timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs);
+  const composed = composeSearchQuery(trimmed, options);
+  const builtQuery = composed.query;
+
+  const needContent = request.needContent === true;
+  const timeout = effectiveTimeout(needContent ? options.contentTimeoutMs : 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,
-      need_content: false,
+      need_content: needContent,
       ...(oriQuestion === undefined ? {} : { ori_question: oriQuestion }),
       ...(options.localization === undefined ? {} : { localization: options.localization }),
     },
@@ -99,7 +155,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 +170,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 +205,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

@@ -19,6 +19,8 @@ const VOCABULARY = [
   { key: "language", read: (o: ResolvedOptions) => o.search.language },
   { key: "searchLocalization", read: (o: ResolvedOptions) => o.search.localization },
   { key: "maxSummaryChars", read: (o: ResolvedOptions) => o.search.maxSummaryChars },
+  { key: "searchContentMaxChars", read: (o: ResolvedOptions) => o.search.contentMaxChars },
+  { key: "searchContentTimeoutMs", read: (o: ResolvedOptions) => o.search.contentTimeoutMs },
   { key: "searchTimeoutMs", read: (o: ResolvedOptions) => o.search.timeoutMs },
   { key: "fetchMaxChars", read: (o: ResolvedOptions) => o.fetch.maxChars },
   { key: "fetchAllowedDomains", read: (o: ResolvedOptions) => o.fetch.allowedDomains },
@@ -27,6 +29,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
@@ -17,8 +27,25 @@ export const DEFAULT_MAX_RESULTS = 10;
 export const DEFAULT_MIN_RERANK = 0;
 export const DEFAULT_MIN_AUTHORITY = 0;
 export const DEFAULT_MAX_SUMMARY_CHARS = 1200;
+/**
+ * The per-result budget a need_content page body is clamped to. 1,500 keeps a
+ * default count=10 response (bodies plus metadata ≈ 16 KB) under the tightest
+ * host output cap, Pi's 20 KB MCP-path truncation — see
+ * docs/research/search-inline-content.md.
+ */
+export const DEFAULT_SEARCH_CONTENT_MAX_CHARS = 1500;
+/**
+ * The timeout need_content calls use in place of searchTimeoutMs: DeepSeek
+ * fetches every result page server-side before responding, which the 30 s
+ * search default does not budget for.
+ */
+export const DEFAULT_SEARCH_CONTENT_TIMEOUT_MS = 60000;
 
 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 +72,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.';
 
@@ -29,7 +30,8 @@ export const SEARCH_TOOL_DESCRIPTION =
   `${SEARCH_RANKED_FILTERED} ` +
   `${SEARCH_EMPTY_IS_NORMAL} ` +
   `${SEARCH_QUERY_OPERATORS} ` +
-  "To read a full page, pass a result URL to the deepseek_fetch tool.";
+  "To read one full page in depth, pass a result URL to the deepseek_fetch tool; to carry each result's " +
+  "page body in this response, set need_content to true.";
 
 export const FETCH_TOOL_DESCRIPTION =
   "Fetch one web page as clean Markdown through DeepSeek's Fetch API. " +
@@ -45,3 +47,16 @@ 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.";
+
+export const SEARCH_NEED_CONTENT_PARAMETER =
+  "Optional; set true to attach each result's page body as Markdown — an excerpt clamped to a configured per-result " +
+  "budget, not a full page — in place of its short summary. Slower per call (DeepSeek fetches the result pages) and " +
+  "priced the same per request; for a full page, call deepseek_fetch.";

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";
@@ -14,6 +14,8 @@ const NUMBER_ENV = {
   minAuthority: "DEEPSEEK_SEARCH_MIN_AUTHORITY",
   maxSummaryChars: "DEEPSEEK_SEARCH_MAX_SUMMARY_CHARS",
   searchTimeoutMs: "DEEPSEEK_SEARCH_TIMEOUT_MS",
+  searchContentMaxChars: "DEEPSEEK_SEARCH_CONTENT_MAX_CHARS",
+  searchContentTimeoutMs: "DEEPSEEK_SEARCH_CONTENT_TIMEOUT_MS",
   fetchMaxChars: "DEEPSEEK_FETCH_MAX_CHARS",
   fetchTimeoutMs: "DEEPSEEK_FETCH_TIMEOUT_MS",
   maxRetries: "DEEPSEEK_MAX_RETRIES",
@@ -23,6 +25,7 @@ const NUMBER_ENV = {
 const TEXT_ENV = {
   language: "DEEPSEEK_SEARCH_LANGUAGE",
   searchLocalization: SEARCH_LOCALIZATION_ENV,
+  baseUrl: BASE_URL_ENV,
 } as const;
 
 const DOMAINS_ENV = {
@@ -96,6 +99,8 @@ export function envOptionsReport(env: Env = process.env): EnvOptionsReport {
   putText(options, "searchLocalization", env);
   putNumber(options, "maxSummaryChars", env, warnings);
   putNumber(options, "searchTimeoutMs", env, warnings);
+  putNumber(options, "searchContentMaxChars", env, warnings);
+  putNumber(options, "searchContentTimeoutMs", env, warnings);
 
   putNumber(options, "fetchMaxChars", env, warnings);
   putDomains(options, "fetchAllowedDomains", env, warnings);
@@ -107,6 +112,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,20 +85,49 @@ 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);
       const lines = [`${index + 1}. [${escapeBrackets(title)}](${result.url})${marker ? ` ${marker}` : ""}`];
       if (result.content) {
-        lines.push(`   ${result.content.replaceAll("\n", " ")}`);
+        // Page bodies keep their Markdown line structure, indented into the
+        // list item; digests compact to one line, as summaries always did.
+        lines.push(
+          result.contentKind === "page"
+            ? result.content
+                .split("\n")
+                .map((line) => `   ${line}`)
+                .join("\n")
+            : `   ${result.content.replaceAll("\n", " ")}`,
+        );
       }
       if (result.published !== undefined) {
         lines.push(`   Published: ${formatPublished(result.published)}`);
@@ -106,6 +135,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,
@@ -8,10 +9,13 @@ import {
   DEFAULT_MIN_AUTHORITY,
   DEFAULT_MIN_RERANK,
   DEFAULT_RETRY_BASE_DELAY_MS,
+  DEFAULT_SEARCH_CONTENT_MAX_CHARS,
+  DEFAULT_SEARCH_CONTENT_TIMEOUT_MS,
   DEFAULT_SEARCH_COUNT,
   DEFAULT_TIMEOUT_MS,
   MAX_RETRIES,
   MAX_RETRY_DELAY_MS,
+  MAX_SEARCH_COUNT,
   MAX_TIMEOUT_MS,
   MIN_TIMEOUT_MS,
 } from "./constants";
@@ -32,9 +36,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 {
@@ -52,6 +69,13 @@ export function resolveSearchOptions(input?: PluginOptions): SearchOptions {
     language: optionalText(input?.language),
     localization: localizationValue(input?.searchLocalization),
     maxSummaryChars: clampInt(input?.maxSummaryChars, DEFAULT_MAX_SUMMARY_CHARS, 0, 1_000_000),
+    contentMaxChars: clampInt(input?.searchContentMaxChars, DEFAULT_SEARCH_CONTENT_MAX_CHARS, 0, 1_000_000),
+    contentTimeoutMs: clampInt(
+      input?.searchContentTimeoutMs,
+      DEFAULT_SEARCH_CONTENT_TIMEOUT_MS,
+      MIN_TIMEOUT_MS,
+      MAX_TIMEOUT_MS,
+    ),
     timeoutMs: clampInt(input?.searchTimeoutMs, DEFAULT_TIMEOUT_MS, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS),
     enabled: input?.searchEnabled !== false,
   };
@@ -82,6 +106,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.