deepseek-web-retrieval 0.3.0 → 0.5.0

package/src/core/format.ts

@@ -1,18 +1,11 @@
-import {
-  FETCH_TRUNCATION_MARKER,
-  MAX_ERROR_BODY_CHARS,
-} from "./constants"
-import type { FormattedFetchContent, SearchResult } from "./types"
+import { FETCH_TRUNCATION_MARKER, MAX_ERROR_BODY_CHARS } from "./constants";
+import type { FormattedFetchContent, SearchResult } from "./types";
 
 /** Truncates by Unicode code points so emoji and surrogate pairs are not split. */
 export function truncate(value: string, maxChars: number): string {
-  if (maxChars <= 0) return ""
-  if (value.length <= maxChars) return value
-  return Array.from(value).slice(0, maxChars).join("")
-}
-
-export function formatFetchContent(title: string, content: string, maxChars: number): string {
-  return truncate(withTitle(title, content), maxChars)
+  if (maxChars <= 0) return "";
+  if (value.length <= maxChars) return value;
+  return Array.from(value).slice(0, maxChars).join("");
 }
 
 /**
@@ -20,40 +13,36 @@ export function formatFetchContent(title: string, content: string, maxChars: num
  * truncation marker counts toward `maxChars`, so the returned content never
  * exceeds the configured budget.
  */
-export function formatFetchedContent(
-  title: string,
-  content: string,
-  maxChars: number,
-): FormattedFetchContent {
-  const document = withTitle(title, content)
-  const length = Array.from(document).length
-  if (maxChars <= 0) return { content: "", truncated: length > 0 }
-  if (length <= maxChars) return { content: document, truncated: false }
+export function formatFetchedContent(title: string, content: string, maxChars: number): FormattedFetchContent {
+  const document = withTitle(title, content);
+  const length = Array.from(document).length;
+  if (maxChars <= 0) return { content: "", truncated: length > 0 };
+  if (length <= maxChars) return { content: document, truncated: false };
 
-  const markerLength = Array.from(FETCH_TRUNCATION_MARKER).length
+  const markerLength = Array.from(FETCH_TRUNCATION_MARKER).length;
   if (maxChars <= markerLength) {
-    return { content: truncate(document, maxChars), truncated: true }
+    return { content: truncate(document, maxChars), truncated: true };
   }
   return {
     content: `${truncate(document, maxChars - markerLength)}${FETCH_TRUNCATION_MARKER}`,
     truncated: true,
-  }
+  };
 }
 
 function withTitle(title: string, content: string): string {
-  const heading = title.trim()
-  if (!heading) return content
+  const heading = title.trim();
+  if (!heading) return content;
 
-  const body = content.trimStart()
-  const lines = body.split(/\r?\n/)
-  const firstHeading = lines[0]?.match(/^\\?#\s+(.+?)\s*$/)?.[1]
+  const body = content.trimStart();
+  const lines = body.split(/\r?\n/);
+  const firstHeading = lines[0]?.match(/^\\?#\s+(.+?)\s*$/)?.[1];
   if (firstHeading && normalizeHeading(firstHeading) === normalizeHeading(heading)) {
     // DeepSeek sometimes escapes the leading "#" as "\#"; normalize it so the
     // result is a real Markdown heading instead of a duplicated literal line.
-    lines[0] = `# ${heading}`
-    return lines.join("\n")
+    lines[0] = `# ${heading}`;
+    return lines.join("\n");
   }
-  return `# ${heading}\n\n${content}`
+  return `# ${heading}\n\n${content}`;
 }
 
 function normalizeHeading(value: string): string {
@@ -61,23 +50,23 @@ function normalizeHeading(value: string): string {
     .trim()
     .replace(/\s+/g, " ")
     .replace(/\s+#+\s*$/, "")
-    .toLowerCase()
+    .toLowerCase();
 }
 
 export function redactSecrets(value: string): string {
   return value
     .replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, "sk-***")
-    .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, "Bearer ***")
+    .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, "Bearer ***");
 }
 
 export function formatApiError(operation: string, status: number, body: string): string {
-  const detail = redactSecrets(body.trim())
-  const detailChars = Array.from(detail)
+  const detail = redactSecrets(body.trim());
+  const detailChars = Array.from(detail);
   const text = detail
     ? detailChars.length > MAX_ERROR_BODY_CHARS
       ? `${detailChars.slice(0, MAX_ERROR_BODY_CHARS).join("")}…`
       : detail
-    : "empty response body"
+    : "empty response body";
   const hint =
     status === 401
       ? "invalid API key"
@@ -87,13 +76,13 @@ export function formatApiError(operation: string, status: number, body: string):
           ? "permission denied"
           : status === 429
             ? "rate limited"
-            : undefined
-  const label = hint ? `${operation} failed (HTTP ${status}, ${hint})` : `${operation} failed (HTTP ${status})`
-  return `${label}: ${text}`
+            : undefined;
+  const label = hint ? `${operation} failed (HTTP ${status}, ${hint})` : `${operation} failed (HTTP ${status})`;
+  return `${label}: ${text}`;
 }
 
 export function formatTimeoutError(operation: string, timeoutMs: number): string {
-  return `${operation} timed out after ${timeoutMs} ms`
+  return `${operation} timed out after ${timeoutMs} ms`;
 }
 
 /**
@@ -101,27 +90,41 @@ export function formatTimeoutError(operation: string, timeoutMs: number): string
  * Hosts that ignore structured output read this text.
  */
 export function formatSearchResults(results: readonly SearchResult[]): string {
-  if (results.length === 0) return "No results found."
+  if (results.length === 0) return "No results found.";
 
   return results
     .map((result, index) => {
-      const title = result.title?.trim() || result.url
-      const lines = [`${index + 1}. [${escapeBrackets(title)}](${result.url})`]
+      const title = result.title?.trim() || result.url;
+      const lines = [`${index + 1}. [${escapeBrackets(title)}](${result.url})`];
       if (result.content) {
-        lines.push(`   ${result.content.replaceAll("\n", " ")}`)
+        lines.push(`   ${result.content.replaceAll("\n", " ")}`);
       }
       if (result.published !== undefined) {
-        lines.push(`   Published: ${formatPublished(result.published)}`)
+        lines.push(`   Published: ${formatPublished(result.published)}`);
       }
-      return lines.join("\n")
+      return lines.join("\n");
     })
-    .join("\n\n")
+    .join("\n\n");
+}
+
+/**
+ * Renders one search result as the structured mirror of its text form; hosts
+ * that read structuredContent (every JSON-replacing client excepted) get this
+ * shape from both adapters.
+ */
+export function toStructuredResult(result: SearchResult) {
+  return {
+    url: result.url,
+    ...(result.title ? { title: result.title } : {}),
+    ...(result.content ? { content: result.content } : {}),
+    ...(result.published !== undefined ? { published: result.published } : {}),
+  };
 }
 
 function escapeBrackets(value: string): string {
-  return value.replaceAll("[", "\\[").replaceAll("]", "\\]")
+  return value.replaceAll("[", "\\[").replaceAll("]", "\\]");
 }
 
 function formatPublished(epochMs: number): string {
-  return new Date(epochMs).toISOString().slice(0, 10)
+  return new Date(epochMs).toISOString().slice(0, 10);
 }

package/src/core/index.ts

@@ -1,9 +1,9 @@
-export * from "./auth"
-export * from "./client"
-export * from "./constants"
-export * from "./domains"
-export * from "./format"
-export * from "./options"
-export * from "./search"
-export * from "./types"
-export * from "./url"
+export * from "./auth";
+export * from "./client";
+export * from "./constants";
+export * from "./domains";
+export * from "./format";
+export * from "./options";
+export * from "./search";
+export * from "./types";
+export * from "./url";

package/src/core/jsonc.ts

@@ -1,4 +1,4 @@
-import { parse } from "jsonc-parser/lib/esm/main.js"
+import { parse } from "jsonc-parser/lib/esm/main.js";
 
 /**
  * Parses JSONC (JSON with comments and trailing commas) via jsonc-parser,
@@ -6,11 +6,11 @@ import { parse } from "jsonc-parser/lib/esm/main.js"
  * text has errors beyond tolerated comments and trailing commas.
  */
 export function parseJsonc(text: string): unknown {
-  const errors: { error: number; offset: number; length: number }[] = []
-  const value = parse(text, errors, { allowTrailingComma: true })
+  const errors: { error: number; offset: number; length: number }[] = [];
+  const value = parse(text, errors, { allowTrailingComma: true });
   if (errors.length > 0) {
-    const first = errors[0]
-    throw new SyntaxError(`JSONC parse error at offset ${first.offset} (code ${first.error})`)
+    const first = errors[0];
+    throw new SyntaxError(`JSONC parse error at offset ${first.offset} (code ${first.error})`);
   }
-  return value
+  return value;
 }

package/src/core/object.ts

@@ -0,0 +1,4 @@
+/** Shared plain-object guard: core modules and the installer's value helpers agree on one. */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/core/options.ts

@@ -2,8 +2,8 @@ import {
   DEFAULT_API_KEY_SOURCE,
   DEFAULT_FETCH_MAX_CHARS,
   DEFAULT_MAX_RESULTS,
-  DEFAULT_MAX_SUMMARY_CHARS,
   DEFAULT_MAX_RETRIES,
+  DEFAULT_MAX_SUMMARY_CHARS,
   DEFAULT_MIN_AUTHORITY,
   DEFAULT_MIN_RERANK,
   DEFAULT_RETRY_BASE_DELAY_MS,
@@ -13,8 +13,8 @@ import {
   MAX_RETRY_DELAY_MS,
   MAX_TIMEOUT_MS,
   MIN_TIMEOUT_MS,
-} from "./constants"
-import { normalizeDomains } from "./domains"
+} from "./constants";
+import { normalizeDomains } from "./domains";
 import type {
   ApiKeySource,
   AuthOptions,
@@ -23,7 +23,7 @@ import type {
   ResolvedOptions,
   RetryOptions,
   SearchOptions,
-} from "./types"
+} from "./types";
 
 export function resolvePluginOptions(input?: PluginOptions): ResolvedOptions {
   return {
@@ -31,7 +31,7 @@ export function resolvePluginOptions(input?: PluginOptions): ResolvedOptions {
     fetch: resolveFetchOptions(input),
     auth: resolveAuthOptions(input),
     retry: resolveRetryOptions(input),
-  }
+  };
 }
 
 export function resolveSearchOptions(input?: PluginOptions): SearchOptions {
@@ -40,14 +40,14 @@ export function resolveSearchOptions(input?: PluginOptions): SearchOptions {
     maxResults: clampInt(input?.maxResults, DEFAULT_MAX_RESULTS, 0, 50),
     minRerank: finiteNumber(input?.minRerank, DEFAULT_MIN_RERANK),
     minAuthority: finiteNumber(input?.minAuthority, DEFAULT_MIN_AUTHORITY),
-    allowUnknownAuthority: input?.allowUnknownAuthority === true,
+    allowUnknownAuthority: input?.allowUnknownAuthority !== false,
     blockedDomains: normalizeDomains(input?.blockedDomains),
     includeDomains: normalizeDomains(input?.includeDomains),
     language: optionalText(input?.language),
     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,
-  }
+  };
 }
 
 export function resolveFetchOptions(input?: PluginOptions): FetchOptions {
@@ -58,26 +58,21 @@ export function resolveFetchOptions(input?: PluginOptions): FetchOptions {
     timeoutMs: clampInt(input?.fetchTimeoutMs, DEFAULT_TIMEOUT_MS, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS),
     blockPrivateHosts: input?.fetchBlockPrivateHosts !== false,
     enabled: input?.fetchEnabled !== false,
-  }
+  };
 }
 
 export function resolveAuthOptions(input?: PluginOptions): AuthOptions {
-  const value = input?.apiKeySource
+  const value = input?.apiKeySource;
   return {
     source: value === "opencode" || value === "env" ? value : (DEFAULT_API_KEY_SOURCE as ApiKeySource),
-  }
+  };
 }
 
 export function resolveRetryOptions(input?: PluginOptions): RetryOptions {
   return {
     maxRetries: clampInt(input?.maxRetries, DEFAULT_MAX_RETRIES, 0, MAX_RETRIES),
-    baseDelayMs: clampInt(
-      input?.retryBaseDelayMs,
-      DEFAULT_RETRY_BASE_DELAY_MS,
-      0,
-      MAX_RETRY_DELAY_MS,
-    ),
-  }
+    baseDelayMs: clampInt(input?.retryBaseDelayMs, DEFAULT_RETRY_BASE_DELAY_MS, 0, MAX_RETRY_DELAY_MS),
+  };
 }
 
 /**
@@ -86,23 +81,23 @@ export function resolveRetryOptions(input?: PluginOptions): RetryOptions {
  */
 export function resolveFetchTimeoutMs(configuredMs: number, inputSeconds?: unknown): number {
   if (typeof inputSeconds !== "number" || !Number.isFinite(inputSeconds) || inputSeconds <= 0) {
-    return configuredMs
+    return configuredMs;
   }
-  const inputMs = Math.min(MAX_TIMEOUT_MS, Math.max(1, Math.round(inputSeconds * 1000)))
-  return Math.min(configuredMs, inputMs)
+  const inputMs = Math.min(MAX_TIMEOUT_MS, Math.max(1, Math.round(inputSeconds * 1000)));
+  return Math.min(configuredMs, inputMs);
 }
 
 function optionalText(value: unknown): string | undefined {
-  if (typeof value !== "string") return undefined
-  const trimmed = value.trim()
-  return trimmed ? trimmed : undefined
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
 }
 
 function finiteNumber(value: unknown, fallback: number): number {
-  return typeof value === "number" && Number.isFinite(value) ? value : fallback
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
 
 function clampInt(value: unknown, fallback: number, min: number, max: number): number {
-  const number = typeof value === "number" && Number.isFinite(value) ? Math.trunc(value) : fallback
-  return Math.min(max, Math.max(min, number))
+  const number = typeof value === "number" && Number.isFinite(value) ? Math.trunc(value) : fallback;
+  return Math.min(max, Math.max(min, number));
 }

package/src/core/search.ts

@@ -1,7 +1,7 @@
-import { normalizeDomains } from "./domains"
-import { truncate } from "./format"
-import type { DeepSeekSearchResult, SearchOptions, SearchResult } from "./types"
-import { normalizeResultUrl } from "./url"
+import { normalizeDomains } from "./domains";
+import { truncate } from "./format";
+import type { DeepSeekSearchResult, SearchOptions, SearchResult } from "./types";
+import { normalizeResultUrl } from "./url";
 
 /**
  * Appends DeepSeek search operators:
@@ -13,72 +13,73 @@ export function buildQuery(
   query: string,
   options: Pick<SearchOptions, "blockedDomains" | "includeDomains" | "language">,
 ): string {
-  const parts = [query.trim()]
-  for (const domain of normalizeDomains(options.blockedDomains)) parts.push(`-site:${domain}`)
-  const include = normalizeDomains(options.includeDomains)
-  if (include.length) parts.push(include.map((domain) => `site:${domain}`).join(" OR "))
-  const language = options.language?.trim().replace(/^lang:/i, "")
-  if (language) parts.push(`lang:${language}`)
-  return parts.filter((part) => part.length > 0).join(" ")
+  const parts = [query.trim()];
+  for (const domain of normalizeDomains(options.blockedDomains)) parts.push(`-site:${domain}`);
+  const include = normalizeDomains(options.includeDomains);
+  if (include.length) parts.push(include.map((domain) => `site:${domain}`).join(" OR "));
+  const language = options.language?.trim().replace(/^lang:/i, "");
+  if (language) parts.push(`lang:${language}`);
+  return parts.filter((part) => part.length > 0).join(" ");
 }
 
 export function parsePublished(value: unknown): number | undefined {
-  if (typeof value !== "string" || !value.trim()) return undefined
-  const timestamp = Date.parse(value)
-  return Number.isFinite(timestamp) ? timestamp : undefined
+  if (typeof value !== "string" || !value.trim()) return undefined;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? timestamp : undefined;
 }
 
 /**
  * Filters and maps DeepSeek results into the neutral SearchResult shape.
- * Missing/non-finite rerank_score never passes. Authority -1/missing is
+ * A present rerank_score always compares against minRerank; a missing or
+ * non-finite score passes only while no positive threshold is set, so the
+ * default returns exactly what DeepSeek ranked. Authority -1/missing is
  * "unknown" and only passes when allowUnknownAuthority is enabled.
  */
-export function processResults(
-  raw: readonly DeepSeekSearchResult[],
-  options: SearchOptions,
-): SearchResult[] {
-  const results: SearchResult[] = []
-  const seen = new Set<string>()
+export function processResults(raw: readonly DeepSeekSearchResult[], options: SearchOptions): SearchResult[] {
+  const results: SearchResult[] = [];
+  const seen = new Set<string>();
 
   for (const item of raw) {
-    if (results.length >= options.maxResults) break
-    if (!item || typeof item !== "object") continue
+    if (results.length >= options.maxResults) break;
+    if (!item || typeof item !== "object") continue;
 
-    const url = normalizeResultUrl(item.url)
-    if (!url || seen.has(url)) continue
+    const url = normalizeResultUrl(item.url);
+    if (!url || seen.has(url)) continue;
 
-    const rerank = item.rerank_score
-    if (typeof rerank !== "number" || !Number.isFinite(rerank) || rerank < options.minRerank) continue
+    const rerank = item.rerank_score;
+    if (typeof rerank === "number" && Number.isFinite(rerank)) {
+      if (rerank < options.minRerank) continue;
+    } else if (options.minRerank > 0) {
+      // A threshold was explicitly raised, so a result that cannot be scored
+      // against it must not slip through.
+      continue;
+    }
 
-    const authority = item.authority
-    const knownAuthority =
-      typeof authority === "number" && Number.isFinite(authority) && authority >= 0
+    const authority = item.authority;
+    const knownAuthority = typeof authority === "number" && Number.isFinite(authority) && authority >= 0;
     if (knownAuthority) {
-      if (authority < options.minAuthority) continue
+      if (authority < options.minAuthority) continue;
     } else if (!options.allowUnknownAuthority) {
-      continue
+      continue;
     }
 
-    seen.add(url)
-    const content = truncate(
-      optionalText(item.summary) ?? optionalText(item.snippet) ?? "",
-      options.maxSummaryChars,
-    )
-    const published = parsePublished(item.date)
-    const title = optionalText(item.title)
+    seen.add(url);
+    const content = truncate(optionalText(item.summary) ?? optionalText(item.snippet) ?? "", options.maxSummaryChars);
+    const published = parsePublished(item.date);
+    const title = optionalText(item.title);
     results.push({
       url,
       ...(title ? { title } : {}),
       ...(content ? { content } : {}),
       ...(published !== undefined ? { published } : {}),
-    })
+    });
   }
 
-  return results
+  return results;
 }
 
 function optionalText(value: unknown): string | undefined {
-  if (typeof value !== "string") return undefined
-  const trimmed = value.trim()
-  return trimmed ? trimmed : undefined
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
 }