deepseek-web-retrieval 0.2.0 → 0.3.0

package/src/core/client.ts

@@ -1,24 +1,27 @@
-import {
-  FETCH_ENDPOINT,
-  MAX_ERROR_BODY_CHARS,
-  MAX_QUERY_CHARS,
-  MAX_RESPONSE_BYTES,
-  MAX_RETRY_DELAY_MS,
-  SEARCH_ENDPOINT,
-} from "./constants"
+import { FETCH_ENDPOINT, MAX_QUERY_CHARS, SEARCH_ENDPOINT } from "./constants"
 import { assertFetchHostPolicy } from "./domains"
-import { formatApiError, formatTimeoutError, redactSecrets, truncate } from "./format"
+import { formatFetchedContent } from "./format"
 import { buildQuery, processResults } from "./search"
+import { postJson } from "./transport"
+import { parseFetchUrl } from "./url"
 import type {
   DeepSeekSearchResult,
+  FetchedDocument,
   FetchedPage,
   FetchOptions,
   RequestAuth,
-  RetryConfig,
+  RetryOptions,
   SearchOptions,
-  WebSearchResult,
+  SearchResult,
 } from "./types"
 
+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)
+}
+
 interface SearchResponse {
   readonly results?: unknown
 }
@@ -31,42 +34,16 @@ interface FetchResponse {
 export interface RequestOptions {
   readonly signal: AbortSignal
   readonly auth: RequestAuth
-  readonly retry: RetryConfig
-}
-
-export class DeepSeekApiError extends Error {
-  readonly operation: string
-  readonly status: number
-  readonly body: string
-  readonly retryable: boolean
-  readonly retryAfterMs?: number
-
-  constructor(input: {
-    operation: string
-    status: number
-    body: string
-    retryAfterMs?: number
-  }) {
-    const body = redactSecrets(input.body)
-    super(formatApiError(input.operation, input.status, body))
-    this.name = "DeepSeekApiError"
-    this.operation = input.operation
-    this.status = input.status
-    this.body = body
-    this.retryable =
-      input.status === 408 ||
-      input.status === 425 ||
-      input.status === 429 ||
-      (input.status >= 500 && input.status <= 599)
-    this.retryAfterMs = input.retryAfterMs
-  }
+  readonly retry: RetryOptions
+  /** Per-call cap in milliseconds; the shorter of this and the configured timeout wins. */
+  readonly timeoutMs?: number
 }
 
 export async function searchWeb(
   query: string,
   options: SearchOptions,
   request: RequestOptions,
-): Promise<WebSearchResult[]> {
+): Promise<SearchResult[]> {
   const trimmed = query.trim()
   if (!trimmed) throw new Error("DeepSeek search query must not be empty")
   if (Array.from(trimmed).length > MAX_QUERY_CHARS) {
@@ -83,6 +60,7 @@ export async function searchWeb(
     )
   }
 
+  const timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs)
   const payload = await postJson<SearchResponse>(
     SEARCH_ENDPOINT,
     {
@@ -91,8 +69,7 @@ export async function searchWeb(
       need_content: false,
     },
     "DeepSeek Search",
-    request,
-    options.timeoutMs,
+    { signal: request.signal, auth: request.auth, retry: request.retry, timeoutMs: timeout },
   )
 
   if (!Array.isArray(payload.results)) {
@@ -109,12 +86,12 @@ export async function fetchPage(
   // 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",
-    request,
-    options.timeoutMs,
+    { 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 : ""
@@ -124,213 +101,29 @@ export async function fetchPage(
   return { url: url.href, title, content }
 }
 
-async function postJson<T>(
-  endpoint: string,
-  body: unknown,
-  operation: string,
-  options: RequestOptions,
-  timeoutMs: number,
-): Promise<T> {
-  const attempts = options.retry.maxRetries + 1
-  let lastError: unknown
-
-  for (let attempt = 0; attempt < attempts; attempt++) {
-    try {
-      return await requestOnce<T>(endpoint, body, operation, options, timeoutMs)
-    } catch (error) {
-      lastError = error
-      if (!(error instanceof DeepSeekApiError) || !error.retryable || attempt === attempts - 1) {
-        throw error
-      }
-      await sleep(retryDelay(error.retryAfterMs, options.retry.baseDelayMs, attempt), options.signal)
-    }
-  }
-
-  throw lastError
-}
-
-async function requestOnce<T>(
-  endpoint: string,
-  body: unknown,
-  operation: string,
-  options: RequestOptions,
-  timeoutMs: number,
-): Promise<T> {
-  return fetchWithTimeout(
-    endpoint,
-    {
-      method: "POST",
-      headers: {
-        Authorization: `Bearer ${options.auth.apiKey}`,
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify(body),
-    },
-    options.signal,
-    timeoutMs,
-    operation,
-    async (response) => {
-      if (!response.ok) {
-        const text = await readBoundedText(response, MAX_ERROR_BODY_CHARS)
-        throw new DeepSeekApiError({
-          operation,
-          status: response.status,
-          body: text,
-          retryAfterMs: parseRetryAfter(response.headers.get("retry-after")),
-        })
-      }
-
-      const text = await readResponseText(response, MAX_RESPONSE_BYTES, operation)
-      if (!text.trim()) throw new Error(`${operation} returned an empty response body`)
-
-      try {
-        return JSON.parse(text) as T
-      } catch {
-        throw new Error(`${operation} returned invalid JSON: ${truncate(redactSecrets(text), 500)}`)
-      }
-    },
-  )
+/** 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
 }
 
 /**
- * Runs the request and the callback that consumes its body inside one
- * timeout/abort scope. The timer must stay active while the response body is
- * read, otherwise a slow or stalled body can outlive the configured timeout.
+ * The full fetch pipeline adapters share: fetch the page (a URL skips
+ * re-parsing) and format it for the model within its budget.
  */
-async function fetchWithTimeout<T>(
-  endpoint: string,
-  init: RequestInit,
-  signal: AbortSignal,
-  timeoutMs: number,
-  operation: string,
-  handleResponse: (response: Response) => Promise<T>,
-): Promise<T> {
-  const controller = new AbortController()
-  let timedOut = false
-  const forwardAbort = () => controller.abort(signal.reason)
-  if (signal.aborted) forwardAbort()
-  else signal.addEventListener("abort", forwardAbort, { once: true })
-
-  const timer = signal.aborted
-    ? undefined
-    : setTimeout(() => {
-        timedOut = true
-        controller.abort(new Error("timeout"))
-      }, timeoutMs)
-
-  try {
-    const response = await fetch(endpoint, { ...init, signal: controller.signal })
-    return await handleResponse(response)
-  } catch (error) {
-    if (timedOut) throw new Error(formatTimeoutError(operation, timeoutMs))
-    if (signal.aborted) throw abortReason(signal, operation)
-    throw error
-  } finally {
-    if (timer !== undefined) clearTimeout(timer)
-    signal.removeEventListener("abort", forwardAbort)
-  }
-}
-
-function parseRetryAfter(value: string | null): number | undefined {
-  if (!value) return undefined
-  const trimmed = value.trim()
-  if (!trimmed) return undefined
-
-  if (/^\d+$/.test(trimmed)) {
-    return Math.min(MAX_RETRY_DELAY_MS, Number(trimmed) * 1000)
-  }
-
-  const timestamp = Date.parse(trimmed)
-  if (!Number.isFinite(timestamp)) return undefined
-  return Math.min(MAX_RETRY_DELAY_MS, Math.max(0, timestamp - Date.now()))
-}
-
-function retryDelay(retryAfterMs: number | undefined, baseDelayMs: number, attempt: number): number {
-  if (retryAfterMs !== undefined) return retryAfterMs
-  return Math.min(MAX_RETRY_DELAY_MS, baseDelayMs * 2 ** attempt)
-}
-
-function sleep(ms: number, signal: AbortSignal): Promise<void> {
-  if (ms <= 0) return Promise.resolve()
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => {
-      signal.removeEventListener("abort", onAbort)
-      resolve()
-    }, ms)
-    const onAbort = () => {
-      clearTimeout(timer)
-      reject(abortReason(signal, "DeepSeek request"))
-    }
-    if (signal.aborted) {
-      clearTimeout(timer)
-      reject(abortReason(signal, "DeepSeek request"))
-      return
-    }
-    signal.addEventListener("abort", onAbort, { once: true })
-  })
-}
-
-function abortReason(signal: AbortSignal, operation: string): unknown {
-  return signal.reason instanceof Error ? signal.reason : new Error(`${operation} request aborted`)
-}
-
-/** Reads at most `maxChars + 1` characters, enough for formatApiError to add its marker. */
-async function readBoundedText(response: Response, maxChars: number): Promise<string> {
-  if (!response.body) return truncate(await response.text(), maxChars + 1)
-
-  const reader = response.body.getReader()
-  const decoder = new TextDecoder()
-  const limit = maxChars + 1
-  let text = ""
-  let chars = 0
-  try {
-    while (chars < limit) {
-      const { done, value } = await reader.read()
-      if (done) break
-      const chunk = decoder.decode(value, { stream: true })
-      text += chunk
-      chars += Array.from(chunk).length
-    }
-    text += decoder.decode()
-  } finally {
-    await reader.cancel().catch(() => undefined)
-    reader.releaseLock()
-  }
-  return truncate(text, limit)
-}
-
-/** Reads a successful response body, rejecting payloads above `maxBytes`. */
-async function readResponseText(
-  response: Response,
-  maxBytes: number,
-  operation: string,
-): Promise<string> {
-  if (!response.body) {
-    const text = await response.text()
-    if (new TextEncoder().encode(text).byteLength > maxBytes) {
-      throw new Error(`${operation} response exceeded ${maxBytes} bytes`)
-    }
-    return text
-  }
-
-  const reader = response.body.getReader()
-  const decoder = new TextDecoder()
-  let text = ""
-  let bytes = 0
-  try {
-    while (true) {
-      const { done, value } = await reader.read()
-      if (done) break
-      bytes += value.byteLength
-      if (bytes > maxBytes) {
-        throw new Error(`${operation} response exceeded ${maxBytes} bytes`)
-      }
-      text += decoder.decode(value, { stream: true })
-    }
-    text += decoder.decode()
-  } finally {
-    await reader.cancel().catch(() => undefined)
-    reader.releaseLock()
+export async function fetchDocument(
+  url: string | URL,
+  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)
+  return {
+    url: page.url,
+    title: page.title,
+    content: formatted.content,
+    truncated: formatted.truncated,
   }
-  return text
 }

package/src/core/constants.ts

@@ -23,3 +23,8 @@ 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"

package/src/core/descriptions.ts

@@ -0,0 +1,19 @@
+/**
+ * Capability fact fragments shared by every host's tool descriptions. Hosts
+ * compose these with their own framing; the facts must never drift per host.
+ */
+
+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_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."
+
+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."

package/src/core/format.ts

@@ -2,7 +2,7 @@ import {
   FETCH_TRUNCATION_MARKER,
   MAX_ERROR_BODY_CHARS,
 } from "./constants"
-import type { FormattedFetchContent } from "./types"
+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 {
@@ -95,3 +95,33 @@ export function formatApiError(operation: string, status: number, body: string):
 export function formatTimeoutError(operation: string, timeoutMs: number): string {
   return `${operation} timed out after ${timeoutMs} ms`
 }
+
+/**
+ * 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
+    .map((result, index) => {
+      const title = result.title?.trim() || result.url
+      const lines = [`${index + 1}. [${escapeBrackets(title)}](${result.url})`]
+      if (result.content) {
+        lines.push(`   ${result.content.replaceAll("\n", " ")}`)
+      }
+      if (result.published !== undefined) {
+        lines.push(`   Published: ${formatPublished(result.published)}`)
+      }
+      return lines.join("\n")
+    })
+    .join("\n\n")
+}
+
+function escapeBrackets(value: string): string {
+  return value.replaceAll("[", "\\[").replaceAll("]", "\\]")
+}
+
+function formatPublished(epochMs: number): string {
+  return new Date(epochMs).toISOString().slice(0, 10)
+}

package/src/core/jsonc.ts

@@ -0,0 +1,16 @@
+import { parse } from "jsonc-parser/lib/esm/main.js"
+
+/**
+ * Parses JSONC (JSON with comments and trailing commas) via jsonc-parser,
+ * the library behind VS Code's JSON support. Throws a SyntaxError when the
+ * 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 })
+  if (errors.length > 0) {
+    const first = errors[0]
+    throw new SyntaxError(`JSONC parse error at offset ${first.offset} (code ${first.error})`)
+  }
+  return value
+}

package/src/core/options.ts

@@ -46,7 +46,7 @@ export function resolveSearchOptions(input?: PluginOptions): SearchOptions {
     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),
-    setDefault: input?.setDefaultWebsearch === true,
+    enabled: input?.searchEnabled !== false,
   }
 }
 
@@ -56,9 +56,8 @@ export function resolveFetchOptions(input?: PluginOptions): FetchOptions {
     allowedDomains: normalizeDomains(input?.fetchAllowedDomains),
     blockedDomains: normalizeDomains(input?.fetchBlockedDomains),
     timeoutMs: clampInt(input?.fetchTimeoutMs, DEFAULT_TIMEOUT_MS, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS),
-    overrideWebfetch: input?.fetchOverrideWebfetch === true,
-    registerTool: input?.fetchRegisterTool !== false,
     blockPrivateHosts: input?.fetchBlockPrivateHosts !== false,
+    enabled: input?.fetchEnabled !== false,
   }
 }
 

package/src/core/search.ts

@@ -1,6 +1,6 @@
 import { normalizeDomains } from "./domains"
 import { truncate } from "./format"
-import type { DeepSeekSearchResult, SearchOptions, WebSearchResult } from "./types"
+import type { DeepSeekSearchResult, SearchOptions, SearchResult } from "./types"
 import { normalizeResultUrl } from "./url"
 
 /**
@@ -29,15 +29,15 @@ export function parsePublished(value: unknown): number | undefined {
 }
 
 /**
- * Filters and maps DeepSeek results to OpenCode's WebSearch.Result shape.
+ * Filters and maps DeepSeek results into the neutral SearchResult shape.
  * Missing/non-finite rerank_score never passes. Authority -1/missing is
  * "unknown" and only passes when allowUnknownAuthority is enabled.
  */
 export function processResults(
   raw: readonly DeepSeekSearchResult[],
   options: SearchOptions,
-): WebSearchResult[] {
-  const results: WebSearchResult[] = []
+): SearchResult[] {
+  const results: SearchResult[] = []
   const seen = new Set<string>()
 
   for (const item of raw) {
@@ -64,15 +64,13 @@ export function processResults(
       optionalText(item.summary) ?? optionalText(item.snippet) ?? "",
       options.maxSummaryChars,
     )
-    const time: { published?: number } = {}
     const published = parsePublished(item.date)
-    if (published !== undefined) time.published = published
     const title = optionalText(item.title)
     results.push({
       url,
       ...(title ? { title } : {}),
       ...(content ? { content } : {}),
-      time,
+      ...(published !== undefined ? { published } : {}),
     })
   }