deepseek-web-retrieval 0.3.0 → 0.5.0

package/src/core/client.ts

@@ -1,9 +1,8 @@
-import { FETCH_ENDPOINT, MAX_QUERY_CHARS, SEARCH_ENDPOINT } from "./constants"
-import { assertFetchHostPolicy } from "./domains"
-import { formatFetchedContent } from "./format"
-import { buildQuery, processResults } from "./search"
-import { postJson } from "./transport"
-import { parseFetchUrl } from "./url"
+import { FETCH_ENDPOINT, MAX_QUERY_CHARS, SEARCH_ENDPOINT } from "./constants";
+import { assertFetchHostPolicy } from "./domains";
+import { formatFetchedContent } from "./format";
+import { buildQuery, processResults } from "./search";
+import { postJson } from "./transport";
 import type {
   DeepSeekSearchResult,
   FetchedDocument,
@@ -13,30 +12,33 @@ import type {
   RetryOptions,
   SearchOptions,
   SearchResult,
-} from "./types"
+} from "./types";
+import { parseFetchUrl } from "./url";
 
-export { DeepSeekApiError } from "./transport"
+export { DeepSeekApiError } from "./transport";
 
 /** The shorter of the configured and per-call timeout always wins. */
 function effectiveTimeout(configuredMs: number, perCallMs: number | undefined): number {
-  return perCallMs === undefined ? configuredMs : Math.min(configuredMs, perCallMs)
+  return perCallMs === undefined ? configuredMs : Math.min(configuredMs, perCallMs);
 }
 
 interface SearchResponse {
-  readonly results?: unknown
+  readonly results?: unknown;
 }
 
 interface FetchResponse {
-  readonly title?: unknown
-  readonly content?: unknown
+  readonly title?: unknown;
+  readonly content?: unknown;
 }
 
 export interface RequestOptions {
-  readonly signal: AbortSignal
-  readonly auth: RequestAuth
-  readonly retry: RetryOptions
+  /** Optional per-request HTTP dependency; factories bind this once for an adapter. */
+  readonly fetchImpl?: typeof fetch;
+  readonly signal: AbortSignal;
+  readonly auth: RequestAuth;
+  readonly retry: RetryOptions;
   /** Per-call cap in milliseconds; the shorter of this and the configured timeout wins. */
-  readonly timeoutMs?: number
+  readonly timeoutMs?: number;
 }
 
 export async function searchWeb(
@@ -44,23 +46,23 @@ export async function searchWeb(
   options: SearchOptions,
   request: RequestOptions,
 ): Promise<SearchResult[]> {
-  const trimmed = query.trim()
-  if (!trimmed) throw new Error("DeepSeek search query must not be empty")
+  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`)
+    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
+  const builtQuery = buildQuery(trimmed, options);
+  const builtQueryLength = Array.from(builtQuery).length;
   if (builtQueryLength > MAX_QUERY_CHARS) {
     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)`,
-    )
+    );
   }
 
-  const timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs)
+  const timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs);
   const payload = await postJson<SearchResponse>(
     SEARCH_ENDPOINT,
     {
@@ -69,43 +71,38 @@ export async function searchWeb(
       need_content: false,
     },
     "DeepSeek Search",
-    { signal: request.signal, auth: request.auth, retry: request.retry, timeoutMs: timeout },
-  )
+    { ...request, timeoutMs: timeout },
+  );
 
   if (!Array.isArray(payload.results)) {
-    throw new Error("DeepSeek Search returned a response without a results array")
+    throw new Error("DeepSeek Search returned a response without a results array");
   }
-  return processResults(payload.results as DeepSeekSearchResult[], options)
+  return processResults(payload.results as DeepSeekSearchResult[], options);
 }
 
-export async function fetchPage(
-  url: URL,
-  options: FetchOptions,
-  request: RequestOptions,
-): Promise<FetchedPage> {
-  // Enforced here so direct core consumers cannot bypass the policy. Adapters
-  // may also pre-check to reject before a permission prompt.
-  assertFetchHostPolicy(url, options)
-  const timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs)
-  const payload = await postJson<FetchResponse>(
-    FETCH_ENDPOINT,
-    { url: url.href },
-    "DeepSeek Fetch",
-    { signal: request.signal, auth: request.auth, retry: request.retry, timeoutMs: timeout },
-  )
-  const title = typeof payload.title === "string" ? payload.title.trim() : ""
-  const content = typeof payload.content === "string" ? payload.content : ""
+export async function fetchPage(url: URL, options: FetchOptions, request: RequestOptions): Promise<FetchedPage> {
+  // A URL object is parsed, not necessarily safe: direct core callers must pass
+  // the same protocol, credentials, length and host checks as string callers.
+  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 title = typeof payload.title === "string" ? payload.title.trim() : "";
+  const content = typeof payload.content === "string" ? payload.content : "";
   if (!content.trim()) {
-    throw new Error("DeepSeek Fetch returned no page content (the page may be empty or unavailable)")
+    throw new Error("DeepSeek Fetch returned no page content (the page may be empty or unavailable)");
   }
-  return { url: url.href, title, content }
+  return { url: target.href, title, content };
 }
 
 /** Parses the URL and enforces the host policy in one call, returning the fetch target. */
 export function inspectFetchTarget(url: string, options: FetchOptions): URL {
-  const target = parseFetchUrl(url)
-  assertFetchHostPolicy(target, options)
-  return target
+  const target = parseFetchUrl(url);
+  assertFetchHostPolicy(target, options);
+  return target;
 }
 
 /**
@@ -117,13 +114,28 @@ export async function fetchDocument(
   options: FetchOptions,
   request: RequestOptions,
 ): 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)
+  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);
   return {
     url: page.url,
     title: page.title,
     content: formatted.content,
     truncated: formatted.truncated,
-  }
+  };
 }
+
+/** One client per adapter/test; transport overrides never mutate process globals. */
+export function createRetrievalClient(dependencies: { readonly fetchImpl?: typeof fetch } = {}) {
+  const bind = (request: RequestOptions): RequestOptions => ({ ...request, ...dependencies });
+  return {
+    searchWeb: (query: string, options: SearchOptions, request: RequestOptions) =>
+      searchWeb(query, options, bind(request)),
+    fetchPage: (url: URL, options: FetchOptions, request: RequestOptions) => fetchPage(url, options, bind(request)),
+    fetchDocument: (url: string | URL, options: FetchOptions, request: RequestOptions) =>
+      fetchDocument(url, options, bind(request)),
+  };
+}
+
+export type RetrievalClient = ReturnType<typeof createRetrievalClient>;
+export const retrievalClient = createRetrievalClient();

package/src/core/constants.ts

@@ -1,30 +1,36 @@
-export const SEARCH_ENDPOINT = "https://api.deepseek.com/v1/tools/search"
-export const FETCH_ENDPOINT = "https://api.deepseek.com/v1/tools/fetch"
+export const SEARCH_ENDPOINT = "https://api.deepseek.com/v1/tools/search";
+export const FETCH_ENDPOINT = "https://api.deepseek.com/v1/tools/fetch";
 
-export const DEFAULT_SEARCH_COUNT = 10
-export const DEFAULT_MAX_RESULTS = 5
-export const DEFAULT_MIN_RERANK = 1.5
-export const DEFAULT_MIN_AUTHORITY = 2
-export const DEFAULT_MAX_SUMMARY_CHARS = 1200
+/**
+ * Search defaults are benchmarked against surveyed AI-native search APIs and
+ * DeepSeek's own factory defaults; see docs/research/search-api-defaults.md.
+ * Result caps cluster at 10 across vendors, and no surveyed vendor filters
+ * results client-side by score or authority — thresholds stay opt-in.
+ */
+export const DEFAULT_SEARCH_COUNT = 10;
+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;
 
-export const DEFAULT_FETCH_MAX_CHARS = 16000
-export const DEFAULT_TIMEOUT_MS = 30000
-export const MIN_TIMEOUT_MS = 1000
-export const MAX_TIMEOUT_MS = 120000
+export const DEFAULT_FETCH_MAX_CHARS = 16000;
+export const DEFAULT_TIMEOUT_MS = 30000;
+export const MIN_TIMEOUT_MS = 1000;
+export const MAX_TIMEOUT_MS = 120000;
 
-export const MAX_QUERY_CHARS = 128
-export const MAX_URL_CHARS = 8192
-export const MAX_ERROR_BODY_CHARS = 2000
-export const MAX_RESPONSE_BYTES = 5 * 1024 * 1024
-export const FETCH_TRUNCATION_MARKER = "\n\n[content truncated]"
+export const MAX_QUERY_CHARS = 128;
+export const MAX_URL_CHARS = 8192;
+export const MAX_ERROR_BODY_CHARS = 2000;
+export const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+export const FETCH_TRUNCATION_MARKER = "\n\n[content truncated]";
 
-export const DEFAULT_API_KEY_SOURCE = "auto"
-export const DEFAULT_MAX_RETRIES = 0
-export const MAX_RETRIES = 5
-export const DEFAULT_RETRY_BASE_DELAY_MS = 250
-export const MAX_RETRY_DELAY_MS = 10000
+export const DEFAULT_API_KEY_SOURCE = "auto";
+export const DEFAULT_MAX_RETRIES = 0;
+export const MAX_RETRIES = 5;
+export const DEFAULT_RETRY_BASE_DELAY_MS = 250;
+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 ENABLE_SEARCH_ENV = "DEEPSEEK_ENABLE_SEARCH"
-export const ENABLE_FETCH_ENV = "DEEPSEEK_ENABLE_FETCH"
+export const API_KEY_ENV = "DEEPSEEK_API_KEY";
+export const ENABLE_SEARCH_ENV = "DEEPSEEK_ENABLE_SEARCH";
+export const ENABLE_FETCH_ENV = "DEEPSEEK_ENABLE_FETCH";

package/src/core/descriptions.ts

@@ -4,16 +4,40 @@
  */
 
 export const FETCH_SERVICE_LIMITS =
-  "DeepSeek does not render JavaScript and cannot reach private networks; PDFs, images, and other binary files are unsupported."
+  "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.";
 
-export const FETCH_MARKDOWN_ONLY = 'Only format "markdown" is supported.'
+export const FETCH_MARKDOWN_ONLY = 'Only format "markdown" is supported.';
 
 export const SEARCH_RANKED_FILTERED =
-  "Results are ranked by relevance and source authority, deduplicated by URL, and capped at the configured maximum."
+  "Results are ranked by relevance and source authority, deduplicated by URL, and capped at the configured maximum.";
 
-export const SEARCH_EMPTY_IS_NORMAL = "An empty result list is normal, not an error."
+export const SEARCH_EMPTY_IS_NORMAL = "An empty result list is normal, not an error.";
 
 export const SEARCH_QUERY_OPERATORS =
-  "Use site:/-site: operators in the query to include or exclude domains; the full query must stay within 128 characters."
+  "Use site:/-site: operators in the query to include or exclude domains; the full query must stay within 128 characters.";
+
+/**
+ * The full tool descriptions, composed from the fact fragments. Every host
+ * adapter registers its tools with these verbatim — the MCP server and the Pi
+ * extension must never drift on what a tool does.
+ */
+export const SEARCH_TOOL_DESCRIPTION =
+  "Search the web with DeepSeek's in-house search engine and return a short, filtered result " +
+  "list (title, URL, summary). " +
+  `${SEARCH_RANKED_FILTERED} ` +
+  `${SEARCH_EMPTY_IS_NORMAL} ` +
+  `${SEARCH_QUERY_OPERATORS} ` +
+  "To read a full page, pass a result URL to the deepseek_fetch tool.";
+
+export const FETCH_TOOL_DESCRIPTION =
+  "Fetch one web page as clean Markdown through DeepSeek's Fetch API. " +
+  `${FETCH_SERVICE_LIMITS} ` +
+  `${FETCH_OUTPUT_TRUNCATED}`;
+
+/** Parameter descriptions shared by every adapter's input schema for the two tools. */
+export const SEARCH_QUERY_PARAMETER =
+  "Search query, 128 characters or fewer including operators (site:, -site:, quoted phrases, lang:).";
+
+export const FETCH_URL_PARAMETER = "Absolute http:// or https:// URL to fetch. Credentials are rejected.";

package/src/core/domains.ts

@@ -1,30 +1,25 @@
-import { isIP } from "node:net"
-import type { FetchOptions } from "./types"
+import { isIP } from "node:net";
+import type { FetchOptions } from "./types";
 
 export function normalizeDomain(value: string): string | undefined {
-  const trimmed = value.trim()
-  if (!trimmed || /\s/.test(trimmed)) return undefined
-  const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed)
-  if (hasScheme && !/^https?:\/\//i.test(trimmed)) return undefined
+  const trimmed = value.trim();
+  if (!trimmed || /\s/.test(trimmed)) return undefined;
+  const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed);
+  if (hasScheme && !/^https?:\/\//i.test(trimmed)) return undefined;
 
-  let hostname: string
+  let hostname: string;
   try {
     // Parsing with a synthetic scheme also strips paths, ports, and userinfo.
-    hostname = new URL(hasScheme ? trimmed : `http://${trimmed}`).hostname
+    hostname = new URL(hasScheme ? trimmed : `http://${trimmed}`).hostname;
   } catch {
-    return undefined
+    return undefined;
   }
-  return normalizeHostname(hostname)
+  return normalizeHostname(hostname);
 }
 
 /** Lowercases a URL hostname and removes brackets and trailing root-label dots. */
 export function normalizeHostname(value: string): string {
-  return value
-    .trim()
-    .toLowerCase()
-    .replace(/^\[/, "")
-    .replace(/\]$/, "")
-    .replace(/\.+$/, "")
+  return value.trim().toLowerCase().replace(/^\[/, "").replace(/\]$/, "").replace(/\.+$/, "");
 }
 
 /**
@@ -32,21 +27,21 @@ export function normalizeHostname(value: string): string {
  * but not `notexample.com` or `example.com.evil.test`.
  */
 export function domainMatches(hostname: string, domain: string): boolean {
-  const host = normalizeHostname(hostname)
-  const target = normalizeHostname(domain)
-  if (!host || !target) return false
-  return host === target || host.endsWith(`.${target}`)
+  const host = normalizeHostname(hostname);
+  const target = normalizeHostname(domain);
+  if (!host || !target) return false;
+  return host === target || host.endsWith(`.${target}`);
 }
 
 export function normalizeDomains(values: unknown): string[] {
-  if (!Array.isArray(values)) return []
-  const domains = new Set<string>()
+  if (!Array.isArray(values)) return [];
+  const domains = new Set<string>();
   for (const value of values) {
-    if (typeof value !== "string") continue
-    const domain = normalizeDomain(value)
-    if (domain) domains.add(domain)
+    if (typeof value !== "string") continue;
+    const domain = normalizeDomain(value);
+    if (domain) domains.add(domain);
   }
-  return [...domains]
+  return [...domains];
 }
 
 /**
@@ -55,9 +50,9 @@ export function normalizeDomains(values: unknown): string[] {
  * to a remote service and fails early instead of producing a confusing 404.
  */
 export function isPrivateHostname(value: string): boolean {
-  const host = normalizeHostname(value)
-  if (!host) return true
-  if (host === "localhost" || host === "local") return true
+  const host = normalizeHostname(value);
+  if (!host) return true;
+  if (host === "localhost" || host === "local") return true;
   if (
     host.endsWith(".localhost") ||
     host.endsWith(".local") ||
@@ -65,48 +60,43 @@ export function isPrivateHostname(value: string): boolean {
     host.endsWith(".lan") ||
     host.endsWith(".home.arpa")
   ) {
-    return true
+    return true;
   }
 
-  const version = isIP(host)
-  if (version === 4) return isPrivateIpv4(host)
-  if (version === 6) return isPrivateIpv6(host)
-  return false
+  const version = isIP(host);
+  if (version === 4) return isPrivateIpv4(host);
+  if (version === 6) return isPrivateIpv6(host);
+  return false;
 }
 
 export function assertFetchHostPolicy(
   url: URL,
   options: Pick<FetchOptions, "allowedDomains" | "blockedDomains" | "blockPrivateHosts">,
 ): void {
-  const host = normalizeHostname(url.hostname)
+  const host = normalizeHostname(url.hostname);
 
   if (options.blockPrivateHosts && isPrivateHostname(host)) {
     throw new Error(
       `Fetch blocked for ${host}: local/private addresses are not reachable by DeepSeek. ` +
         "Set fetchBlockPrivateHosts=false only if you really need to send the URL.",
-    )
+    );
   }
 
-  const blocked = options.blockedDomains.find((domain) => domainMatches(host, domain))
+  const blocked = options.blockedDomains.find((domain) => domainMatches(host, domain));
   if (blocked) {
-    throw new Error(`Fetch blocked for ${host}: matched fetchBlockedDomains entry "${blocked}"`)
+    throw new Error(`Fetch blocked for ${host}: matched fetchBlockedDomains entry "${blocked}"`);
   }
-  if (
-    options.allowedDomains.length > 0 &&
-    !options.allowedDomains.some((domain) => domainMatches(host, domain))
-  ) {
-    throw new Error(
-      `Fetch not allowed for ${host}: add it to fetchAllowedDomains (exact host or subdomain)`,
-    )
+  if (options.allowedDomains.length > 0 && !options.allowedDomains.some((domain) => domainMatches(host, domain))) {
+    throw new Error(`Fetch not allowed for ${host}: add it to fetchAllowedDomains (exact host or subdomain)`);
   }
 }
 
 function isPrivateIpv4(host: string): boolean {
-  const parts = host.split(".").map((part) => Number(part))
+  const parts = host.split(".").map((part) => Number(part));
   if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
-    return true
+    return true;
   }
-  const [a, b] = parts
+  const [a, b] = parts;
   return (
     a === 0 ||
     a === 10 ||
@@ -117,37 +107,36 @@ function isPrivateIpv4(host: string): boolean {
     (a === 192 && b === 168) ||
     (a === 198 && (b === 18 || b === 19)) ||
     a >= 224
-  )
+  );
 }
 
 function isPrivateIpv6(host: string): boolean {
-  const value = host.toLowerCase()
-  if (value === "::" || value === "::1") return true
-  if (value.startsWith("fc") || value.startsWith("fd")) return true
-  if (/^fe[89ab]/.test(value)) return true
+  const value = host.toLowerCase();
+  if (value === "::" || value === "::1") return true;
+  if (value.startsWith("fc") || value.startsWith("fd")) return true;
+  if (/^fe[89ab]/.test(value)) return true;
 
   // IPv4-mapped IPv6, e.g. ::ffff:127.0.0.1. URL parsers normalize the dotted
   // form to hex (`::ffff:7f00:1`), so both representations must be handled.
-  const dottedMapped = value.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/)?.[1]
-  if (dottedMapped) return isPrivateIpv4(dottedMapped)
+  const dottedMapped = value.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/)?.[1];
+  if (dottedMapped) return isPrivateIpv4(dottedMapped);
 
-  const mapped = ipv4FromIpv6Hextets(value, /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/)
-  if (mapped) return isPrivateIpv4(mapped)
+  const mapped = ipv4FromIpv6Hextets(value, /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (mapped) return isPrivateIpv4(mapped);
 
   // IPv4-compatible IPv6, e.g. ::127.0.0.1, which URL parsers normalize to
   // ::7f00:1.
-  const compatible = ipv4FromIpv6Hextets(value, /^::([0-9a-f]{1,4}):([0-9a-f]{1,4})$/)
-  if (compatible) return isPrivateIpv4(compatible)
+  const compatible = ipv4FromIpv6Hextets(value, /^::([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (compatible) return isPrivateIpv4(compatible);
 
-  return false
+  return false;
 }
 
 function ipv4FromIpv6Hextets(value: string, pattern: RegExp): string | undefined {
-  const match = value.match(pattern)
-  if (!match) return undefined
-  const high = Number.parseInt(match[1], 16)
-  const low = Number.parseInt(match[2], 16)
-  if (!Number.isFinite(high) || !Number.isFinite(low)) return undefined
-  return `${high >> 8}.${high & 0xff}.${low >> 8}.${low & 0xff}`
+  const match = value.match(pattern);
+  if (!match) return undefined;
+  const high = Number.parseInt(match[1], 16);
+  const low = Number.parseInt(match[2], 16);
+  if (!Number.isFinite(high) || !Number.isFinite(low)) return undefined;
+  return `${high >> 8}.${high & 0xff}.${low >> 8}.${low & 0xff}`;
 }
-

package/src/core/env.ts

@@ -0,0 +1,112 @@
+import { ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV } from "./constants";
+import { resolvePluginOptions } from "./options";
+import type { PluginOptions, ResolvedOptions } from "./types";
+
+/** The environment an adapter reads its key and options from. */
+export type Env = Readonly<Record<string, string | undefined>>;
+
+/** Each supported option mapped onto its DEEPSEEK_* variable, grouped by value type. */
+const NUMBER_ENV = {
+  count: "DEEPSEEK_SEARCH_COUNT",
+  maxResults: "DEEPSEEK_SEARCH_MAX_RESULTS",
+  minRerank: "DEEPSEEK_SEARCH_MIN_RERANK",
+  minAuthority: "DEEPSEEK_SEARCH_MIN_AUTHORITY",
+  maxSummaryChars: "DEEPSEEK_SEARCH_MAX_SUMMARY_CHARS",
+  searchTimeoutMs: "DEEPSEEK_SEARCH_TIMEOUT_MS",
+  fetchMaxChars: "DEEPSEEK_FETCH_MAX_CHARS",
+  fetchTimeoutMs: "DEEPSEEK_FETCH_TIMEOUT_MS",
+  maxRetries: "DEEPSEEK_MAX_RETRIES",
+  retryBaseDelayMs: "DEEPSEEK_RETRY_BASE_DELAY_MS",
+} as const;
+
+const TEXT_ENV = {
+  language: "DEEPSEEK_SEARCH_LANGUAGE",
+} as const;
+
+const DOMAINS_ENV = {
+  blockedDomains: "DEEPSEEK_SEARCH_BLOCKED_DOMAINS",
+  includeDomains: "DEEPSEEK_SEARCH_INCLUDE_DOMAINS",
+  fetchAllowedDomains: "DEEPSEEK_FETCH_ALLOWED_DOMAINS",
+  fetchBlockedDomains: "DEEPSEEK_FETCH_BLOCKED_DOMAINS",
+} as const;
+
+/** Shared defaults are true; only an explicit false value disables them. */
+const FALSE_ONLY_ENV = {
+  allowUnknownAuthority: "DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY",
+  fetchBlockPrivateHosts: "DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS",
+  searchEnabled: ENABLE_SEARCH_ENV,
+  fetchEnabled: ENABLE_FETCH_ENV,
+} as const;
+
+/**
+ * Maps `DEEPSEEK_*` environment variables onto the shared plugin option keys and
+ * resolves them through the shared pipeline, so defaults and clamping stay
+ * identical across every adapter. Invalid values are dropped and the shared
+ * default applies.
+ */
+export function resolveEnvOptions(env: Env = process.env): ResolvedOptions {
+  return resolvePluginOptions(pluginOptionsFromEnv(env));
+}
+
+export function pluginOptionsFromEnv(env: Env): PluginOptions {
+  const options: Record<string, unknown> = {};
+
+  putNumber(options, "count", env);
+  putNumber(options, "maxResults", env);
+  putNumber(options, "minRerank", env);
+  putNumber(options, "minAuthority", env);
+  putFalseOnly(options, "allowUnknownAuthority", env);
+  putDomains(options, "blockedDomains", env);
+  putDomains(options, "includeDomains", env);
+  putText(options, "language", env);
+  putNumber(options, "maxSummaryChars", env);
+  putNumber(options, "searchTimeoutMs", env);
+
+  putNumber(options, "fetchMaxChars", env);
+  putDomains(options, "fetchAllowedDomains", env);
+  putDomains(options, "fetchBlockedDomains", env);
+  putNumber(options, "fetchTimeoutMs", env);
+  putFalseOnly(options, "fetchBlockPrivateHosts", env);
+  putFalseOnly(options, "searchEnabled", env);
+  putFalseOnly(options, "fetchEnabled", env);
+
+  putNumber(options, "maxRetries", env);
+  putNumber(options, "retryBaseDelayMs", env);
+
+  return options;
+}
+
+function putNumber(target: Record<string, unknown>, key: keyof typeof NUMBER_ENV, env: Env): void {
+  const value = env[NUMBER_ENV[key]];
+  if (value === undefined) return;
+  const trimmed = value.trim();
+  if (!trimmed) return;
+  const parsed = Number(trimmed);
+  if (Number.isFinite(parsed)) target[key] = parsed;
+}
+
+function putText(target: Record<string, unknown>, key: keyof typeof TEXT_ENV, env: Env): void {
+  const value = env[TEXT_ENV[key]];
+  if (value === undefined) return;
+  const trimmed = value.trim();
+  if (trimmed) target[key] = trimmed;
+}
+
+function putFalseOnly(target: Record<string, unknown>, key: keyof typeof FALSE_ONLY_ENV, env: Env): void {
+  if (isFalseValue(env[FALSE_ONLY_ENV[key]])) target[key] = false;
+}
+
+function putDomains(target: Record<string, unknown>, key: keyof typeof DOMAINS_ENV, env: Env): void {
+  const value = env[DOMAINS_ENV[key]];
+  if (value === undefined || !value.trim()) return;
+  const domains = value
+    .split(",")
+    .map((domain) => domain.trim())
+    .filter((domain) => domain.length > 0);
+  if (domains.length > 0) target[key] = domains;
+}
+
+function isFalseValue(value: string | undefined): boolean {
+  const trimmed = value?.trim().toLowerCase();
+  return trimmed === "false" || trimmed === "0" || trimmed === "no" || trimmed === "off";
+}