deepseek-web-retrieval 0.6.0 → 0.8.0

package/src/core/config-file.ts

@@ -0,0 +1,168 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+import { CONFIG_KEYS } from "./config-summary";
+import type { Env } from "./env";
+import { isPlainObject } from "./object";
+import type { PluginOptions } from "./types";
+
+/** The user-scope shared config file: one file, under the user config home (userConfigHome). */
+export const SHARED_CONFIG_DIR = "deepseek-web-retrieval";
+export const SHARED_CONFIG_FILE = "config.json";
+
+/**
+ * The shared file's vocabulary: API-behavior and host-sensitive plugin option
+ * keys only, derived from the ordered config vocabulary (CONFIG_KEYS) so the
+ * file, the startup summary, and the config command can never drift apart.
+ * Values pass through raw — validation and clamping stay in
+ * resolvePluginOptions so every channel feeds one pipeline. Host-integration
+ * keys are deliberately absent (see HOST_INTEGRATION_KEYS).
+ */
+export const SHARED_CONFIG_KEYS = CONFIG_KEYS;
+
+const SHARED_KEY_SET = new Set<string>(SHARED_CONFIG_KEYS);
+
+/**
+ * Host-integration keys describe the host's tool landscape, not the DeepSeek
+ * call, so they stay in host-native config; the shared file rejects them.
+ */
+const HOST_INTEGRATION_KEYS = new Set<string>([
+  "searchEnabled",
+  "fetchEnabled",
+  "setDefaultWebsearch",
+  "fetchOverrideWebfetch",
+  "fetchRegisterTool",
+  "apiKeySource",
+]);
+
+/**
+ * Joins with the separators of the platform being resolved, not the host's —
+ * identical to `join` in production (the platform is process.platform), but
+ * deterministic when tests inject win32 on another host.
+ */
+function joinFor(platform: NodeJS.Platform, ...parts: readonly string[]): string {
+  return (platform === "win32" ? win32 : posix).join(...parts);
+}
+
+/**
+ * The inputs every config-location resolution shares, bundled so they travel
+ * as one (the installer's FsRoots is the precedent for this shape). Every
+ * function below accepts a partial and fills the machine's real values for
+ * anything omitted.
+ */
+export interface UserConfigContext {
+  readonly env: Env;
+  readonly home: string;
+  readonly platform: NodeJS.Platform;
+}
+
+function resolveContext(context: Partial<UserConfigContext> = {}): UserConfigContext {
+  return {
+    env: context.env ?? process.env,
+    home: context.home ?? homedir(),
+    platform: context.platform ?? process.platform,
+  };
+}
+
+/**
+ * The canonical user config home — the one resolution every consumer of the
+ * per-user config location shares (the shared config file, the installer's
+ * global state records, and the OpenCode global config).
+ *
+ * A non-empty XDG_CONFIG_HOME wins on every platform: power users and CI pin it
+ * deliberately, Windows included. Otherwise win32 uses the conventional Roaming
+ * root — %APPDATA% from the environment, `<home>\AppData\Roaming` when unset —
+ * and every other platform keeps the XDG default `<home>/.config`. Pure so
+ * tests inject env, home, and platform directly.
+ */
+export function userConfigHome(context: Partial<UserConfigContext>): string {
+  const { env, home, platform } = resolveContext(context);
+  const xdg = env.XDG_CONFIG_HOME;
+  if (xdg) return xdg;
+  if (platform === "win32") return env.APPDATA || joinFor(platform, home, "AppData", "Roaming");
+  return joinFor(platform, home, ".config");
+}
+
+/** The directory this tool owns inside the user config home (see userConfigHome). */
+export function userConfigDir(context: Partial<UserConfigContext>): string {
+  const { env, home, platform } = resolveContext(context);
+  return joinFor(platform, userConfigHome({ env, home, platform }), SHARED_CONFIG_DIR);
+}
+
+/** The shared file's location on this machine; see userConfigHome for the rules. */
+export function configFilePath(context: Partial<UserConfigContext>): string {
+  const { env, home, platform } = resolveContext(context);
+  return joinFor(platform, userConfigDir({ env, home, platform }), SHARED_CONFIG_FILE);
+}
+
+/**
+ * What reading the shared config file produced: the accepted options plus the
+ * problems as structured data. `readFileOptions` prints the warnings; other
+ * consumers (the config command) replay them through their own channel.
+ */
+export interface FileOptionsReport {
+  readonly options: PluginOptions;
+  /** One entry per problem the runtime would warn about on stderr. */
+  readonly warnings: readonly string[];
+  /** False only when the file is absent — the normal, silent case. */
+  readonly exists: boolean;
+}
+
+/**
+ * Reads the shared config file synchronously (the Pi settings reader's
+ * convention — adapters resolve once at startup) and reports what happened.
+ * Absence is normal and silent; an unreadable or unparseable file and every
+ * rejected key produce one warning each and are otherwise dropped, so a bad
+ * file never blocks startup.
+ */
+export function readFileOptionsReport(file: string): FileOptionsReport {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { options: {}, warnings: [], exists: false };
+    }
+    return { options: {}, warnings: [`cannot read ${file} — file ignored`], exists: true };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { options: {}, warnings: [`${file} is not valid JSON — file ignored`], exists: true };
+  }
+  if (!isPlainObject(parsed)) {
+    return { options: {}, warnings: [`${file} is not a JSON object — file ignored`], exists: true };
+  }
+
+  const options: Record<string, unknown> = {};
+  const warnings: string[] = [];
+  for (const [key, value] of Object.entries(parsed)) {
+    if (SHARED_KEY_SET.has(key)) options[key] = value;
+    else if (HOST_INTEGRATION_KEYS.has(key))
+      warnings.push(`"${key}" is a host-integration key (host config only) — ignored`);
+    else warnings.push(`unknown key "${key}" — ignored`);
+  }
+  return { options, warnings, exists: true };
+}
+
+/**
+ * Reads the shared config file and warns about problems on stderr (stdout is
+ * the MCP server's JSON-RPC channel). See readFileOptionsReport for the
+ * structured shape; this is the production entry adapters use.
+ */
+export function readFileOptions(file: string): PluginOptions {
+  const report = readFileOptionsReport(file);
+  for (const warning of report.warnings) warn(warning);
+  return report.options;
+}
+
+/** The production entry point: compute the path for this machine and read it. */
+export function sharedFileOptions(context: Partial<UserConfigContext> = {}): PluginOptions {
+  return readFileOptions(configFilePath(context));
+}
+
+function warn(line: string): void {
+  console.error(`deepseek-web-retrieval config: ${line}`);
+}

package/src/core/config-summary.ts

@@ -0,0 +1,82 @@
+import { resolvePluginOptions } from "./options";
+import type { ResolvedOptions } from "./types";
+
+/**
+ * The ordered config vocabulary: every diffable knob's config key and where it
+ * lives in ResolvedOptions. The single source three surfaces share — the
+ * startup deviation line's key order (via configSummaryValues), the config
+ * command's listing, and the shared file's accepted keys (SHARED_CONFIG_KEYS
+ * derives from it) — so adding a knob is one edit here.
+ */
+const VOCABULARY = [
+  { key: "count", read: (o: ResolvedOptions) => o.search.count },
+  { key: "maxResults", read: (o: ResolvedOptions) => o.search.maxResults },
+  { key: "minRerank", read: (o: ResolvedOptions) => o.search.minRerank },
+  { key: "minAuthority", read: (o: ResolvedOptions) => o.search.minAuthority },
+  { key: "allowUnknownAuthority", read: (o: ResolvedOptions) => o.search.allowUnknownAuthority },
+  { key: "blockedDomains", read: (o: ResolvedOptions) => o.search.blockedDomains },
+  { key: "includeDomains", read: (o: ResolvedOptions) => o.search.includeDomains },
+  { 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: "searchTimeoutMs", read: (o: ResolvedOptions) => o.search.timeoutMs },
+  { key: "fetchMaxChars", read: (o: ResolvedOptions) => o.fetch.maxChars },
+  { key: "fetchAllowedDomains", read: (o: ResolvedOptions) => o.fetch.allowedDomains },
+  { key: "fetchBlockedDomains", read: (o: ResolvedOptions) => o.fetch.blockedDomains },
+  { key: "fetchTimeoutMs", read: (o: ResolvedOptions) => o.fetch.timeoutMs },
+  { key: "fetchBlockPrivateHosts", read: (o: ResolvedOptions) => o.fetch.blockPrivateHosts },
+  { key: "maxRetries", read: (o: ResolvedOptions) => o.retry.maxRetries },
+  { key: "retryBaseDelayMs", read: (o: ResolvedOptions) => o.retry.baseDelayMs },
+] as const;
+
+/** The config keys in vocabulary order; the shared config file accepts exactly these. */
+export const CONFIG_KEYS: readonly string[] = VOCABULARY.map((entry) => entry.key);
+
+/**
+ * Renders only the knobs whose effective value differs from the built-in
+ * defaults, as space-separated `key=value` tokens in the config vocabulary.
+ * Host-integration fields (the tool `enabled` flags, `apiKeySource`) are
+ * excluded — they are not in the vocabulary; tool visibility is the startup
+ * tools line's job and the key source is host-native config. Empty diff means
+ * empty string.
+ */
+export function configDeviations(resolved: ResolvedOptions): string {
+  const defaults = configSummaryValues(resolvePluginOptions({}));
+  const effective = configSummaryValues(resolved);
+  const tokens: string[] = [];
+  for (const key of Object.keys(effective)) {
+    const value = effective[key];
+    if (sameValue(value, defaults[key])) continue;
+    tokens.push(`${key}=${formatConfigValue(value, "length")}`);
+  }
+  return tokens.join(" ");
+}
+
+/**
+ * Flattens the diffable resolved fields onto their config-vocabulary names,
+ * in vocabulary order (Object key insertion order preserves it).
+ */
+export function configSummaryValues(options: ResolvedOptions): Record<string, unknown> {
+  const values: Record<string, unknown> = {};
+  for (const entry of VOCABULARY) values[entry.key] = entry.read(options);
+  return values;
+}
+
+/** How arrays render: lengths for the noise-constrained startup line, entries for the human CLI. */
+export type ConfigArrayStyle = "length" | "join";
+
+/** One value renderer for both surfaces; `undefined` renders as "unset". */
+export function formatConfigValue(value: unknown, arrays: ConfigArrayStyle): string {
+  if (Array.isArray(value)) {
+    if (arrays === "length") return String(value.length);
+    return value.length > 0 ? value.join(", ") : "[]";
+  }
+  return value === undefined ? "unset" : String(value);
+}
+
+function sameValue(value: unknown, fallback: unknown): boolean {
+  if (Array.isArray(value) && Array.isArray(fallback)) {
+    return value.length === fallback.length && value.every((entry, index) => entry === fallback[index]);
+  }
+  return value === fallback;
+}

package/src/core/constants.ts

@@ -8,6 +8,11 @@ export const FETCH_ENDPOINT = "https://api.deepseek.com/v1/tools/fetch";
  * results client-side by score or authority — thresholds stay opt-in.
  */
 export const DEFAULT_SEARCH_COUNT = 10;
+/**
+ * The fallback only when neither knob is set; whenever `count` is explicitly
+ * configured, an unset `maxResults` follows the effective count instead (see
+ * resolveSearchOptions) — the two are coupled in one direction, not independent.
+ */
 export const DEFAULT_MAX_RESULTS = 10;
 export const DEFAULT_MIN_RERANK = 0;
 export const DEFAULT_MIN_AUTHORITY = 0;
@@ -19,13 +24,21 @@ export const MIN_TIMEOUT_MS = 1000;
 export const MAX_TIMEOUT_MS = 120000;
 
 export const MAX_QUERY_CHARS = 128;
+/** DeepSeek documents ori_question as 1-128 characters; longer values are clamped, not rejected. */
+export const MAX_ORI_QUESTION_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;
+/**
+ * 2, not 0: a transient failure inside a tool call is cheaper to retry here than
+ * to leave to the model, whose only fallback is re-issuing the whole billed tool
+ * call — the same trade-off behind OpenAI/Anthropic SDKs defaulting to 2; see
+ * docs/research/search-api-defaults.md.
+ */
+export const DEFAULT_MAX_RETRIES = 2;
 export const MAX_RETRIES = 5;
 export const DEFAULT_RETRY_BASE_DELAY_MS = 250;
 export const MAX_RETRY_DELAY_MS = 10000;
@@ -34,3 +47,4 @@ export const MAX_RETRY_DELAY_MS = 10000;
 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 SEARCH_LOCALIZATION_ENV = "DEEPSEEK_SEARCH_LOCALIZATION";

package/src/core/descriptions.ts

@@ -16,7 +16,7 @@ export const SEARCH_RANKED_FILTERED =
 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, and after:/before: with a year or date (e.g. after:2025-06-01) to filter by publish time; the full query must stay within 128 characters.";
 
 /**
  * The full tool descriptions, composed from the fact fragments. Every host
@@ -38,6 +38,10 @@ export const FETCH_TOOL_DESCRIPTION =
 
 /** 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:).";
+  "Search query, 128 characters or fewer including operators (site:, -site:, quoted phrases, lang:, after:, before:).";
+
+export const SEARCH_ORI_QUESTION_PARAMETER =
+  "The user's original question or task that triggered this search, in the user's own words rather than a " +
+  "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.";

package/src/core/env.ts

@@ -1,4 +1,5 @@
-import { ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV } from "./constants";
+import { API_KEY_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";
 
@@ -21,6 +22,7 @@ const NUMBER_ENV = {
 
 const TEXT_ENV = {
   language: "DEEPSEEK_SEARCH_LANGUAGE",
+  searchLocalization: SEARCH_LOCALIZATION_ENV,
 } as const;
 
 const DOMAINS_ENV = {
@@ -38,51 +40,95 @@ const FALSE_ONLY_ENV = {
   fetchEnabled: ENABLE_FETCH_ENV,
 } as const;
 
+/** Every option key mapped onto its `DEEPSEEK_*` variable — the inverse view of the maps above. */
+export const OPTION_ENV_BY_KEY: Readonly<Record<string, string>> = {
+  ...NUMBER_ENV,
+  ...TEXT_ENV,
+  ...DOMAINS_ENV,
+  ...FALSE_ONLY_ENV,
+};
+
+/**
+ * Every option's `DEEPSEEK_*` variable name, in map order — the names a host that
+ * isolates its children from the parent environment (Codex) must forward for
+ * shell-set options to reach the server. `DEEPSEEK_API_KEY` is deliberately
+ * absent: it is not an option variable, and installers compose it separately.
+ */
+export const OPTION_ENV_VARS: readonly string[] = Object.values(OPTION_ENV_BY_KEY);
+
 /**
  * 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.
+ * default applies; `envOptionsReport` is where those drops become visible.
+ * `fileOptions` (the shared config file) layer beneath the environment: for
+ * the same key the environment wins.
  */
-export function resolveEnvOptions(env: Env = process.env): ResolvedOptions {
-  return resolvePluginOptions(pluginOptionsFromEnv(env));
+export function resolveEnvOptions(env: Env = process.env, fileOptions?: PluginOptions): ResolvedOptions {
+  return resolvePluginOptions({ ...fileOptions, ...pluginOptionsFromEnv(env) });
 }
 
-export function pluginOptionsFromEnv(env: Env): PluginOptions {
-  const options: Record<string, unknown> = {};
+/**
+ * What reading the `DEEPSEEK_*` environment produced, plus the problems as
+ * structured data. Startup paths stay silent (they use pluginOptionsFromEnv);
+ * surfaces whose job is visibility — the config command — replay these
+ * warnings through their own channel.
+ */
+export interface EnvOptionsReport {
+  readonly options: PluginOptions;
+  /** One entry per set-but-unusable `DEEPSEEK_*` variable: unknown names and values that had to be dropped. */
+  readonly warnings: readonly string[];
+}
 
-  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);
+/** The options layer of the environment, with every drop reported instead of silent. */
+export function envOptionsReport(env: Env = process.env): EnvOptionsReport {
+  const options: Record<string, unknown> = {};
+  const warnings: string[] = [];
+
+  putNumber(options, "count", env, warnings);
+  putNumber(options, "maxResults", env, warnings);
+  putNumber(options, "minRerank", env, warnings);
+  putNumber(options, "minAuthority", env, warnings);
+  putFalseOnly(options, "allowUnknownAuthority", env, warnings);
+  putDomains(options, "blockedDomains", env, warnings);
+  putDomains(options, "includeDomains", env, warnings);
   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);
+  putText(options, "searchLocalization", env);
+  putNumber(options, "maxSummaryChars", env, warnings);
+  putNumber(options, "searchTimeoutMs", env, warnings);
+
+  putNumber(options, "fetchMaxChars", env, warnings);
+  putDomains(options, "fetchAllowedDomains", env, warnings);
+  putDomains(options, "fetchBlockedDomains", env, warnings);
+  putNumber(options, "fetchTimeoutMs", env, warnings);
+  putFalseOnly(options, "fetchBlockPrivateHosts", env, warnings);
+  putFalseOnly(options, "searchEnabled", env, warnings);
+  putFalseOnly(options, "fetchEnabled", env, warnings);
+
+  putNumber(options, "maxRetries", env, warnings);
+  putNumber(options, "retryBaseDelayMs", env, warnings);
+
+  const known = new Set(OPTION_ENV_VARS);
+  for (const key of Object.keys(env)) {
+    if (!key.startsWith("DEEPSEEK_") || key === API_KEY_ENV || known.has(key)) continue;
+    if (!(env[key] ?? "").trim()) continue;
+    warnings.push(`unknown DEEPSEEK_* variable ${key} — ignored`);
+  }
+  return { options, warnings };
+}
 
-  return options;
+export function pluginOptionsFromEnv(env: Env): PluginOptions {
+  return envOptionsReport(env).options;
 }
 
-function putNumber(target: Record<string, unknown>, key: keyof typeof NUMBER_ENV, env: Env): void {
+function putNumber(target: Record<string, unknown>, key: keyof typeof NUMBER_ENV, env: Env, warnings: string[]): 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;
+  else warnings.push(`${NUMBER_ENV[key]} is not a number ("${trimmed}") — ignored`);
 }
 
 function putText(target: Record<string, unknown>, key: keyof typeof TEXT_ENV, env: Env): void {
@@ -92,18 +138,42 @@ function putText(target: Record<string, unknown>, key: keyof typeof TEXT_ENV, en
   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 putFalseOnly(
+  target: Record<string, unknown>,
+  key: keyof typeof FALSE_ONLY_ENV,
+  env: Env,
+  warnings: string[],
+): void {
+  const name = FALSE_ONLY_ENV[key];
+  const value = env[name];
+  if (value === undefined || !value.trim()) return;
+  if (isFalseValue(value)) {
+    target[key] = false;
+    return;
+  }
+  warnings.push(`${name}="${value.trim()}" changes nothing — only false/0/no/off turns the switch off`);
 }
 
-function putDomains(target: Record<string, unknown>, key: keyof typeof DOMAINS_ENV, env: Env): void {
-  const value = env[DOMAINS_ENV[key]];
+function putDomains(
+  target: Record<string, unknown>,
+  key: keyof typeof DOMAINS_ENV,
+  env: Env,
+  warnings: string[],
+): void {
+  const name = DOMAINS_ENV[key];
+  const value = env[name];
   if (value === undefined || !value.trim()) return;
   const domains = value
     .split(",")
     .map((domain) => domain.trim())
     .filter((domain) => domain.length > 0);
+  for (const domain of domains) {
+    if (normalizeDomain(domain) === undefined) {
+      warnings.push(`${name} entry "${domain}" is not a domain — ignored`);
+    }
+  }
   if (domains.length > 0) target[key] = domains;
+  else warnings.push(`${name} contains no domains — ignored`);
 }
 
 function isFalseValue(value: string | undefined): boolean {

package/src/core/format.ts

@@ -95,7 +95,8 @@ export function formatSearchResults(results: readonly SearchResult[]): string {
   return results
     .map((result, index) => {
       const title = result.title?.trim() || result.url;
-      const lines = [`${index + 1}. [${escapeBrackets(title)}](${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", " ")}`);
       }
@@ -107,6 +108,20 @@ export function formatSearchResults(results: readonly SearchResult[]): string {
     .join("\n\n");
 }
 
+/**
+ * Renders the quality fields DeepSeek reports as one bracketed token on the
+ * result's heading line; the text channel is the only one every host delivers
+ * to the model. Authority -1 means unknown and stays in the structured shape
+ * only, so it never wastes text.
+ */
+export function formatQualityMarker(result: SearchResult): string {
+  const parts: string[] = [];
+  if (result.rerankScore !== undefined) parts.push(`rerank ${result.rerankScore}`);
+  if (result.authority !== undefined && result.authority >= 0) parts.push(`authority ${result.authority}`);
+  if (result.siteName) parts.push(result.siteName);
+  return parts.length > 0 ? `[${parts.join(" · ")}]` : "";
+}
+
 /**
  * Renders one search result as the structured mirror of its text form; hosts
  * that read structuredContent (every JSON-replacing client excepted) get this
@@ -118,6 +133,9 @@ export function toStructuredResult(result: SearchResult) {
     ...(result.title ? { title: result.title } : {}),
     ...(result.content ? { content: result.content } : {}),
     ...(result.published !== undefined ? { published: result.published } : {}),
+    ...(result.rerankScore !== undefined ? { rerankScore: result.rerankScore } : {}),
+    ...(result.authority !== undefined ? { authority: result.authority } : {}),
+    ...(result.siteName ? { siteName: result.siteName } : {}),
   };
 }
 

package/src/core/options.ts

@@ -1,3 +1,4 @@
+import { isIP } from "node:net";
 import {
   DEFAULT_API_KEY_SOURCE,
   DEFAULT_FETCH_MAX_CHARS,
@@ -35,15 +36,21 @@ export function resolvePluginOptions(input?: PluginOptions): ResolvedOptions {
 }
 
 export function resolveSearchOptions(input?: PluginOptions): SearchOptions {
+  const count = clampInt(input?.count, DEFAULT_SEARCH_COUNT, 1, 50);
   return {
-    count: clampInt(input?.count, DEFAULT_SEARCH_COUNT, 1, 50),
-    maxResults: clampInt(input?.maxResults, DEFAULT_MAX_RESULTS, 0, 50),
+    count,
+    // Constraint: maxResults follows count only when the user left it alone —
+    // an explicit maxResults still caps as before. count never follows
+    // maxResults: fetching more than the cap returns wastes nothing visible,
+    // while returning fewer than were fetched silently discards results.
+    maxResults: clampInt(input?.maxResults, Number.isFinite(input?.count) ? count : DEFAULT_MAX_RESULTS, 0, 50),
     minRerank: finiteNumber(input?.minRerank, DEFAULT_MIN_RERANK),
     minAuthority: finiteNumber(input?.minAuthority, DEFAULT_MIN_AUTHORITY),
     allowUnknownAuthority: input?.allowUnknownAuthority !== false,
     blockedDomains: normalizeDomains(input?.blockedDomains),
     includeDomains: normalizeDomains(input?.includeDomains),
     language: optionalText(input?.language),
+    localization: localizationValue(input?.searchLocalization),
     maxSummaryChars: clampInt(input?.maxSummaryChars, DEFAULT_MAX_SUMMARY_CHARS, 0, 1_000_000),
     timeoutMs: clampInt(input?.searchTimeoutMs, DEFAULT_TIMEOUT_MS, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS),
     enabled: input?.searchEnabled !== false,
@@ -93,6 +100,19 @@ function optionalText(value: unknown): string | undefined {
   return trimmed ? trimmed : undefined;
 }
 
+/**
+ * Constraint: only a valid IPv4 dotted-quad (four 0-255 octets) or IPv6
+ * address (including "::" compression) survives; anything else drops to
+ * undefined so the request omits `localization` entirely. This is the
+ * enforcement point no matter which config channel delivered the value.
+ */
+function localizationValue(value: unknown): string | undefined {
+  const text = optionalText(value);
+  // isIP is the platform's strict parser; its one lax spot is IPv6 zone IDs
+  // ("%eth0"), which name a local link, not a geolocation — reject those.
+  return text !== undefined && !text.includes("%") && isIP(text) !== 0 ? text : undefined;
+}
+
 function finiteNumber(value: unknown, fallback: number): number {
   return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }

package/src/core/search.ts

@@ -67,11 +67,17 @@ export function processResults(raw: readonly DeepSeekSearchResult[], options: Se
     const content = truncate(optionalText(item.summary) ?? optionalText(item.snippet) ?? "", options.maxSummaryChars);
     const published = parsePublished(item.date);
     const title = optionalText(item.title);
+    const rerankScore = typeof rerank === "number" && Number.isFinite(rerank) ? rerank : undefined;
+    const authorityScore = typeof authority === "number" && Number.isFinite(authority) ? authority : undefined;
+    const siteName = optionalText(item.site_name);
     results.push({
       url,
       ...(title ? { title } : {}),
       ...(content ? { content } : {}),
       ...(published !== undefined ? { published } : {}),
+      ...(rerankScore !== undefined ? { rerankScore } : {}),
+      ...(authorityScore !== undefined ? { authority: authorityScore } : {}),
+      ...(siteName ? { siteName } : {}),
     });
   }
 

package/src/core/types.ts

@@ -13,6 +13,12 @@ export interface SearchOptions {
   readonly blockedDomains: readonly string[];
   readonly includeDomains: readonly string[];
   readonly language?: string;
+  /**
+   * Deployment-level only — never a per-call tool parameter. A valid IPv4 or
+   * IPv6 address sent as DeepSeek's optional `localization` to prefer
+   * geo-localized results; invalid values are dropped at option resolution.
+   */
+  readonly localization?: string;
   readonly maxSummaryChars: number;
   readonly timeoutMs: number;
   readonly enabled: boolean;
@@ -46,6 +52,7 @@ export interface ResolvedOptions {
 export interface DeepSeekSearchResult {
   readonly rerank_score?: number;
   readonly authority?: number;
+  readonly site_name?: string | null;
   readonly title?: string | null;
   readonly url?: string | null;
   readonly snippet?: string | null;
@@ -59,6 +66,10 @@ export interface SearchResult {
   readonly title?: string;
   readonly content?: string;
   readonly published?: number;
+  readonly rerankScore?: number;
+  /** Faithful to the wire: -1 means unknown authority. */
+  readonly authority?: number;
+  readonly siteName?: string;
 }
 
 export interface FetchedPage {