deepseek-web-retrieval 0.8.0 → 0.9.0

package/dist/cli.js

@@ -16,10 +16,12 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
 // src/core/constants.ts
-var SEARCH_ENDPOINT = "https://api.deepseek.com/v1/tools/search", FETCH_ENDPOINT = "https://api.deepseek.com/v1/tools/fetch", DEFAULT_SEARCH_COUNT = 10, DEFAULT_MAX_RESULTS = 10, DEFAULT_MIN_RERANK = 0, DEFAULT_MIN_AUTHORITY = 0, DEFAULT_MAX_SUMMARY_CHARS = 1200, DEFAULT_FETCH_MAX_CHARS = 16000, DEFAULT_TIMEOUT_MS = 30000, MIN_TIMEOUT_MS = 1000, MAX_TIMEOUT_MS = 120000, MAX_QUERY_CHARS = 128, MAX_ORI_QUESTION_CHARS = 128, MAX_URL_CHARS = 8192, MAX_ERROR_BODY_CHARS = 2000, MAX_RESPONSE_BYTES, FETCH_TRUNCATION_MARKER = `
+var DEFAULT_API_BASE_URL = "https://api.deepseek.com", SEARCH_ENDPOINT_PATH = "/v1/tools/search", FETCH_ENDPOINT_PATH = "/v1/tools/fetch", SEARCH_ENDPOINT, FETCH_ENDPOINT, DEFAULT_SEARCH_COUNT = 10, DEFAULT_MAX_RESULTS = 10, DEFAULT_MIN_RERANK = 0, DEFAULT_MIN_AUTHORITY = 0, DEFAULT_MAX_SUMMARY_CHARS = 1200, DEFAULT_FETCH_MAX_CHARS = 16000, MAX_FETCH_CHARS = 1e6, MAX_SEARCH_COUNT = 50, DEFAULT_TIMEOUT_MS = 30000, MIN_TIMEOUT_MS = 1000, MAX_TIMEOUT_MS = 120000, MAX_QUERY_CHARS = 128, MAX_ORI_QUESTION_CHARS = 128, MAX_URL_CHARS = 8192, MAX_ERROR_BODY_CHARS = 2000, MAX_RESPONSE_BYTES, FETCH_TRUNCATION_MARKER = `
 
-[content truncated]`, DEFAULT_API_KEY_SOURCE = "auto", DEFAULT_MAX_RETRIES = 2, MAX_RETRIES = 5, DEFAULT_RETRY_BASE_DELAY_MS = 250, MAX_RETRY_DELAY_MS = 1e4, API_KEY_ENV = "DEEPSEEK_API_KEY", ENABLE_SEARCH_ENV = "DEEPSEEK_ENABLE_SEARCH", ENABLE_FETCH_ENV = "DEEPSEEK_ENABLE_FETCH", SEARCH_LOCALIZATION_ENV = "DEEPSEEK_SEARCH_LOCALIZATION";
+[content truncated]`, DEFAULT_API_KEY_SOURCE = "auto", DEFAULT_MAX_RETRIES = 2, MAX_RETRIES = 5, DEFAULT_RETRY_BASE_DELAY_MS = 250, MAX_RETRY_DELAY_MS = 1e4, API_KEY_ENV = "DEEPSEEK_API_KEY", BASE_URL_ENV = "DEEPSEEK_BASE_URL", ENABLE_SEARCH_ENV = "DEEPSEEK_ENABLE_SEARCH", ENABLE_FETCH_ENV = "DEEPSEEK_ENABLE_FETCH", SEARCH_LOCALIZATION_ENV = "DEEPSEEK_SEARCH_LOCALIZATION";
 var init_constants = __esm(() => {
+  SEARCH_ENDPOINT = `${DEFAULT_API_BASE_URL}${SEARCH_ENDPOINT_PATH}`;
+  FETCH_ENDPOINT = `${DEFAULT_API_BASE_URL}${FETCH_ENDPOINT_PATH}`;
   MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
 });
 
@@ -138,9 +140,15 @@ function resolvePluginOptions(input) {
     search: resolveSearchOptions(input),
     fetch: resolveFetchOptions(input),
     auth: resolveAuthOptions(input),
-    retry: resolveRetryOptions(input)
+    retry: resolveRetryOptions(input),
+    baseUrl: resolveBaseUrl(input?.baseUrl)
   };
 }
+function bothDisabledPrecheck(config, reason) {
+  if (config.search.enabled || config.fetch.enabled)
+    return;
+  return `Both tools are disabled (${reason}); at least one must stay enabled.`;
+}
 function resolveSearchOptions(input) {
   const count = clampInt(input?.count, DEFAULT_SEARCH_COUNT, 1, 50);
   return {
@@ -180,6 +188,28 @@ function resolveRetryOptions(input) {
     baseDelayMs: clampInt(input?.retryBaseDelayMs, DEFAULT_RETRY_BASE_DELAY_MS, 0, MAX_RETRY_DELAY_MS)
   };
 }
+function resolveBaseUrl(value) {
+  if (typeof value !== "string")
+    return DEFAULT_API_BASE_URL;
+  const trimmed = value.trim();
+  if (!trimmed)
+    return DEFAULT_API_BASE_URL;
+  let parsed;
+  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(/\/+$/, "");
+}
+function withPerCallCount(options, count) {
+  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 };
+}
 function optionalText(value) {
   if (typeof value !== "string")
     return;
@@ -256,7 +286,8 @@ var init_config_summary = __esm(() => {
     { key: "fetchTimeoutMs", read: (o) => o.fetch.timeoutMs },
     { key: "fetchBlockPrivateHosts", read: (o) => o.fetch.blockPrivateHosts },
     { key: "maxRetries", read: (o) => o.retry.maxRetries },
-    { key: "retryBaseDelayMs", read: (o) => o.retry.baseDelayMs }
+    { key: "retryBaseDelayMs", read: (o) => o.retry.baseDelayMs },
+    { key: "baseUrl", read: (o) => o.baseUrl }
   ];
   CONFIG_KEYS = VOCABULARY.map((entry) => entry.key);
 });
@@ -3415,55 +3446,6 @@ var init_formats = __esm(() => {
   init_toml();
 });
 
-// src/installer/revert.ts
-import { existsSync as existsSync4, readFileSync as readFileSync7, rmdirSync, unlinkSync } from "node:fs";
-import { dirname as dirname2 } from "node:path";
-function pruneEmptyDir(dir) {
-  try {
-    rmdirSync(dir);
-  } catch {}
-}
-function revertRecordedFile(file, host, opts) {
-  const lines = [];
-  if (!existsSync4(file.file)) {
-    lines.push(`already absent: ${file.file}${opts.label}`);
-    return lines;
-  }
-  const codec = codecFor(file.format, host);
-  const text = readFileSync7(file.file, "utf8");
-  if (file.format === "rules") {
-    const edit2 = { file: file.file, format: "rules", block: file.blockApplied ?? "" };
-    if (!codec.verify(text, edit2)) {
-      lines.push(`no rules block${opts.label} in ${file.file}; left untouched`);
-      return lines;
-    }
-    const updated = codec.revert(text, file).text;
-    if (opts.whole && codec.isEffectivelyEmpty(updated)) {
-      unlinkSync(file.file);
-      pruneEmptyDir(dirname2(file.file));
-      lines.push(`deleted ${file.file} (installer-created, now empty)`);
-    } else {
-      writeConfig(file.file, updated);
-      lines.push(`removed rules block${opts.label} from ${file.file}`);
-    }
-    return lines;
-  }
-  const reverted = codec.revert(text, file);
-  if (opts.whole && file.created && codec.isEffectivelyEmpty(reverted.text)) {
-    unlinkSync(file.file);
-    pruneEmptyDir(dirname2(file.file));
-    lines.push(`deleted ${file.file} (installer-created, now empty)`);
-  } else {
-    writeConfig(file.file, reverted.text);
-    lines.push(`reverted artifacts${opts.label} in ${file.file}`);
-  }
-  lines.push(...reverted.notes.map((note) => `  note: ${note}`));
-  return lines;
-}
-var init_revert = __esm(() => {
-  init_formats();
-});
-
 // src/installer/paths.ts
 import { join as pathJoin } from "node:path";
 function join2(...parts) {
@@ -3473,35 +3455,35 @@ function join2(...parts) {
 function configHome(roots) {
   return roots.configHome ?? join2(roots.home, ".config");
 }
-function stateDir(roots, scope) {
+function recordDir(roots, scope) {
   return scope === "global" ? join2(configHome(roots), "deepseek-web-retrieval") : join2(roots.cwd, ".deepseek-web-retrieval");
 }
 var init_paths = () => {};
 
-// src/installer/state.ts
-import { existsSync as existsSync5, lstatSync as lstatSync2, readdirSync, readFileSync as readFileSync8, rmSync as rmSync2 } from "node:fs";
+// src/installer/record.ts
+import { existsSync as existsSync4, lstatSync as lstatSync2, readdirSync, readFileSync as readFileSync7, rmSync as rmSync2 } from "node:fs";
 import { isAbsolute, join as join3 } from "node:path";
 import { z } from "zod/v4";
-function statePathFor(input) {
-  return join3(stateDir(input, input.scope), `install.${input.host}.json`);
+function recordPathFor(input) {
+  return join3(recordDir(input, input.scope), `install.${input.host}.json`);
 }
 function platformOf(roots) {
   return roots.platform ?? process.platform;
 }
-function legacyGlobalStateDir(roots) {
+function legacyGlobalRecordDir(roots) {
   return join3(roots.home, ".config", "deepseek-web-retrieval");
 }
 function recordReadPath(input, platform = platformOf(input)) {
-  const canonical = statePathFor(input);
-  if (platform !== "win32" || input.scope !== "global" || existsSync5(canonical))
+  const canonical = recordPathFor(input);
+  if (platform !== "win32" || input.scope !== "global" || existsSync4(canonical))
     return canonical;
-  const legacy = join3(legacyGlobalStateDir(input), `install.${input.host}.json`);
-  return existsSync5(legacy) ? legacy : canonical;
+  const legacy = join3(legacyGlobalRecordDir(input), `install.${input.host}.json`);
+  return existsSync4(legacy) ? legacy : canonical;
 }
 function readRecordFile(file, host, scope) {
   let text;
   try {
-    text = readFileSync8(file, "utf8");
+    text = readFileSync7(file, "utf8");
   } catch (error) {
     if (error.code === "ENOENT") {
       try {
@@ -3539,7 +3521,7 @@ function claimedByOtherScope(input, files) {
   return files.filter((file) => record.files.some((candidate) => candidate.file === file));
 }
 function writeRecord(input, record) {
-  const file = statePathFor(input);
+  const file = recordPathFor(input);
   atomicWrite(file, `${JSON.stringify(record, null, 2)}
 `, 384);
 }
@@ -3559,7 +3541,7 @@ function appendedByPrevious(record, path) {
 }
 function deleteRecord(input) {
   const file = recordReadPath(input);
-  if (existsSync5(file))
+  if (existsSync4(file))
     rmSync2(file);
 }
 function readRecordsFromDir(dir, scope) {
@@ -3591,18 +3573,18 @@ function hasRecordFiles(dir) {
 function readingLegacyGlobalRecords(roots) {
   if (platformOf(roots) !== "win32")
     return false;
-  if (hasRecordFiles(stateDir(roots, "global")))
+  if (hasRecordFiles(recordDir(roots, "global")))
     return false;
-  return hasRecordFiles(legacyGlobalStateDir(roots));
+  return hasRecordFiles(legacyGlobalRecordDir(roots));
 }
 function listRecords(roots) {
-  const global = readRecordsFromDir(stateDir(roots, "global"), "global");
-  const project = readRecordsFromDir(stateDir(roots, "project"), "project");
-  const legacy = readingLegacyGlobalRecords(roots) ? readRecordsFromDir(legacyGlobalStateDir(roots), "global") : [];
+  const global = readRecordsFromDir(recordDir(roots, "global"), "global");
+  const project = readRecordsFromDir(recordDir(roots, "project"), "project");
+  const legacy = readingLegacyGlobalRecords(roots) ? readRecordsFromDir(legacyGlobalRecordDir(roots), "global") : [];
   return [...global, ...legacy, ...project];
 }
 var keyPath, tier, operation, recordSchema, InstallRecordError;
-var init_state = __esm(() => {
+var init_record = __esm(() => {
   init_paths();
   init_persistence();
   keyPath = z.array(z.string().min(1)).min(1);
@@ -3637,7 +3619,7 @@ var init_state = __esm(() => {
     file;
     kind;
     constructor(file, kind, detail) {
-      super(`${kind === "invalid" ? "Invalid install record" : "Cannot read install record"} at ${file} (${detail}). ` + "Restore a valid record from backup or repair its permissions before retrying; configuration was not changed. Do not delete undo state to bypass this check.");
+      super(`${kind === "invalid" ? "Invalid install record" : "Cannot read install record"} at ${file} (${detail}). ` + "Restore a valid install record from your own copy or repair its permissions before retrying; configuration was not changed. Do not delete the install record to bypass this check.");
       this.file = file;
       this.kind = kind;
       this.name = "InstallRecordError";
@@ -3645,6 +3627,55 @@ var init_state = __esm(() => {
   };
 });
 
+// src/installer/revert.ts
+import { existsSync as existsSync5, readFileSync as readFileSync8, rmdirSync, unlinkSync } from "node:fs";
+import { dirname as dirname2 } from "node:path";
+function pruneEmptyDir(dir) {
+  try {
+    rmdirSync(dir);
+  } catch {}
+}
+function revertRecordedFile(file, host, opts) {
+  const lines = [];
+  if (!existsSync5(file.file)) {
+    lines.push(`already absent: ${file.file}${opts.label}`);
+    return lines;
+  }
+  const codec = codecFor(file.format, host);
+  const text = readFileSync8(file.file, "utf8");
+  if (file.format === "rules") {
+    const edit2 = { file: file.file, format: "rules", block: file.blockApplied ?? "" };
+    if (!codec.verify(text, edit2)) {
+      lines.push(`no rules block${opts.label} in ${file.file}; left untouched`);
+      return lines;
+    }
+    const updated = codec.revert(text, file).text;
+    if (opts.whole && codec.isEffectivelyEmpty(updated)) {
+      unlinkSync(file.file);
+      pruneEmptyDir(dirname2(file.file));
+      lines.push(`deleted ${file.file} (installer-created, now empty)`);
+    } else {
+      writeConfig(file.file, updated);
+      lines.push(`removed rules block${opts.label} from ${file.file}`);
+    }
+    return lines;
+  }
+  const reverted = codec.revert(text, file);
+  if (opts.whole && file.created && codec.isEffectivelyEmpty(reverted.text)) {
+    unlinkSync(file.file);
+    pruneEmptyDir(dirname2(file.file));
+    lines.push(`deleted ${file.file} (installer-created, now empty)`);
+  } else {
+    writeConfig(file.file, reverted.text);
+    lines.push(`reverted artifacts${opts.label} in ${file.file}`);
+  }
+  lines.push(...reverted.notes.map((note) => `  note: ${note}`));
+  return lines;
+}
+var init_revert = __esm(() => {
+  init_formats();
+});
+
 // src/installer/ownership.ts
 import { existsSync as existsSync6, mkdirSync as mkdirSync2, readFileSync as readFileSync9, realpathSync as realpathSync2, rmSync as rmSync3, writeFileSync as writeFileSync2 } from "node:fs";
 import { basename as basename2, dirname as dirname3, join as join4, resolve } from "node:path";
@@ -3672,7 +3703,7 @@ function canonicalPath(file) {
   return join4(canonicalPath(dirname3(absolute)), basename2(absolute));
 }
 function ownerOf(input) {
-  return { recordPath: canonicalPath(statePathFor(input)), scope: input.scope, cwd: canonicalPath(input.cwd) };
+  return { recordPath: canonicalPath(recordPathFor(input)), scope: input.scope, cwd: canonicalPath(input.cwd) };
 }
 function claimPaths(input, files) {
   return [
@@ -3748,8 +3779,8 @@ function releaseFileOwnership(input, files) {
     releaseClaim(input, claim);
 }
 var init_ownership = __esm(() => {
+  init_record();
   init_revert();
-  init_state();
 });
 
 // src/installer/operation-lock.ts
@@ -3808,7 +3839,7 @@ function applyPlan(plan, input) {
   if (plan.errors.length > 0) {
     throw new Error(`refusing to apply a plan with errors: ${plan.errors.map((error) => error.message).join("; ")}`);
   }
-  return withOperationLock([statePathFor(input)], () => withOperationLock([...plan.edits, ...plan.reverts ?? []].map((file) => file.file), () => applyLocked(plan, input)));
+  return withOperationLock([recordPathFor(input)], () => withOperationLock([...plan.edits, ...plan.reverts ?? []].map((file) => file.file), () => applyLocked(plan, input)));
 }
 function applyLocked(plan, input) {
   const touched = [...plan.edits, ...plan.reverts ?? []];
@@ -3934,7 +3965,7 @@ function rollbackApply(input, previous, snapshots) {
       writeRecord(input, previous);
     else
       deleteRecord(input);
-    if (previous === undefined ? existsSync7(statePathFor(input)) : !deepEqual(readRecord(input), previous)) {
+    if (previous === undefined ? existsSync7(recordPathFor(input)) : !deepEqual(readRecord(input), previous)) {
       throw new Error("restored install record differs from its previous state");
     }
   } catch (restoreError) {
@@ -4033,8 +4064,8 @@ var init_apply = __esm(() => {
   init_value();
   init_operation_lock();
   init_ownership();
+  init_record();
   init_revert();
-  init_state();
   ApplyError = class ApplyError extends Error {
     status;
     constructor(status, message, cause) {
@@ -4050,6 +4081,12 @@ function apiKeyFromEnv(env = process.env) {
   const key = env[API_KEY_ENV]?.trim();
   return key ? key : undefined;
 }
+function requireApiKey(env) {
+  const apiKey = apiKeyFromEnv(env);
+  if (!apiKey)
+    throw new Error(MISSING_API_KEY_MESSAGE);
+  return apiKey;
+}
 var MISSING_API_KEY_MESSAGE;
 var init_auth = __esm(() => {
   init_constants();
@@ -4113,10 +4150,22 @@ function formatApiError(operation2, status, body) {
 function formatTimeoutError(operation2, timeoutMs) {
   return `${operation2} timed out after ${timeoutMs} ms`;
 }
-function formatSearchResults(results) {
-  if (results.length === 0)
-    return "No results found.";
-  return results.map((result, index) => {
+function searchHeader(context) {
+  if (!context)
+    return;
+  if (context.effectiveQuery === context.inputQuery && context.notes.length === 0)
+    return;
+  const header = `Searched for: ${context.effectiveQuery}`;
+  return context.notes.length > 0 ? `${header} — ${context.notes.join("; ")}` : header;
+}
+function formatSearchResults(results, context) {
+  const header = searchHeader(context);
+  if (results.length === 0) {
+    return header ? `${header}
+
+No 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}` : ""}`];
@@ -4132,6 +4181,9 @@ function formatSearchResults(results) {
   }).join(`
 
 `);
+  return header ? `${header}
+
+${body}` : body;
 }
 function formatQualityMarker(result) {
   const parts = [];
@@ -4212,17 +4264,62 @@ var init_url = __esm(() => {
 });
 
 // src/core/search.ts
-function buildQuery(query, options) {
-  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 "));
+function charCount(value) {
+  return Array.from(value).length;
+}
+function operatorParts(options) {
+  const blocked = normalizeDomains(options.blockedDomains).map((domain) => `-site:${domain}`);
+  const include = normalizeDomains(options.includeDomains).map((domain) => `site:${domain}`);
   const language = options.language?.trim().replace(/^lang:/i, "");
-  if (language)
-    parts.push(`lang:${language}`);
-  return parts.filter((part) => part.length > 0).join(" ");
+  return {
+    blocked,
+    include: include.length ? include.join(" OR ") : undefined,
+    language: language ? `lang:${language}` : undefined
+  };
+}
+function assemble(body, parts, withInclude, withLang) {
+  const segments = [body, ...parts.blocked];
+  if (withInclude && parts.include)
+    segments.push(parts.include);
+  if (withLang && parts.language)
+    segments.push(parts.language);
+  return segments.filter((segment) => segment.length > 0).join(" ");
+}
+function bodyBudget(parts, withInclude, withLang, maxChars) {
+  const fixed = [
+    ...parts.blocked,
+    ...withInclude && parts.include ? [parts.include] : [],
+    ...withLang && parts.language ? [parts.language] : []
+  ].join(" ");
+  return maxChars - (fixed ? charCount(fixed) + 1 : 0);
+}
+function composeSearchQuery(query, options, maxChars = MAX_QUERY_CHARS) {
+  const parts = operatorParts(options);
+  const body = query.trim();
+  const notes = [];
+  const attempt = (withInclude, withLang) => {
+    const budget = bodyBudget(parts, withInclude, withLang, maxChars);
+    if (charCount(body) <= budget)
+      return assemble(body, parts, withInclude, withLang);
+    if (budget >= MIN_BODY_CHARS) {
+      notes.push(`query truncated to ${budget} characters (query length limit)`);
+      return assemble(truncate(body, budget), parts, withInclude, withLang);
+    }
+    return;
+  };
+  let assembled = attempt(true, true);
+  if (assembled === undefined && parts.language) {
+    notes.push("language filter dropped (query length limit)");
+    assembled = attempt(true, false);
+  }
+  if (assembled === undefined && parts.include) {
+    notes.push("includeDomains filter dropped (query length limit)");
+    assembled = attempt(false, false);
+  }
+  if (assembled === undefined) {
+    throw new Error(`DeepSeek search query cannot fit ${maxChars} characters: the blockedDomains -site: ` + `operators alone occupy ${charCount(parts.blocked.join(" "))} characters`);
+  }
+  return { query: assembled, notes };
 }
 function parsePublished(value) {
   if (typeof value !== "string" || !value.trim())
@@ -4257,7 +4354,9 @@ function processResults(raw, options) {
       continue;
     }
     seen.add(url);
-    const content = truncate(optionalText2(item.summary) ?? optionalText2(item.snippet) ?? "", options.maxSummaryChars);
+    const rawContent = optionalText2(item.summary) ?? optionalText2(item.snippet) ?? "";
+    const cutContent = truncate(rawContent, options.maxSummaryChars);
+    const content = cutContent && charCount(rawContent) > options.maxSummaryChars ? `${cutContent}…` : cutContent;
     const published = parsePublished(item.date);
     const title = optionalText2(item.title);
     const rerankScore = typeof rerank === "number" && Number.isFinite(rerank) ? rerank : undefined;
@@ -4281,7 +4380,9 @@ function optionalText2(value) {
   const trimmed = value.trim();
   return trimmed ? trimmed : undefined;
 }
+var MIN_BODY_CHARS = 8;
 var init_search = __esm(() => {
+  init_constants();
   init_domains();
   init_format2();
   init_url();
@@ -4487,25 +4588,41 @@ var init_transport = __esm(() => {
 function effectiveTimeout(configuredMs, perCallMs) {
   return perCallMs === undefined ? configuredMs : Math.min(configuredMs, perCallMs);
 }
+function effectiveMaxChars(configured, perCall) {
+  if (perCall === undefined || !Number.isFinite(perCall))
+    return configured;
+  return Math.min(MAX_FETCH_CHARS, Math.max(0, Math.trunc(perCall)));
+}
+function apiUrl(baseUrl, path) {
+  return `${baseUrl ?? DEFAULT_API_BASE_URL}${path}`;
+}
 function oriQuestionValue(oriQuestion) {
   const trimmed = oriQuestion?.trim();
   return trimmed ? truncate(trimmed, MAX_ORI_QUESTION_CHARS) : undefined;
 }
+function requestContext(config, apiKey, signal, perCall) {
+  return {
+    signal,
+    auth: { apiKey },
+    retry: config.retry,
+    baseUrl: config.baseUrl,
+    ...perCall?.timeoutMs === undefined ? {} : { timeoutMs: perCall.timeoutMs },
+    ...perCall?.maxChars === undefined ? {} : { maxChars: perCall.maxChars }
+  };
+}
 async function searchWeb(query, options, request) {
   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) {
-    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 trimmedLength = Array.from(trimmed).length;
+  if (trimmedLength > MAX_QUERY_CHARS) {
+    throw new Error(`DeepSeek search query must be ${MAX_QUERY_CHARS} characters or fewer ` + `(got ${trimmedLength}: ${JSON.stringify(truncate(trimmed, 64))})`);
   }
+  const composed = composeSearchQuery(trimmed, options);
+  const builtQuery = composed.query;
   const timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs);
   const oriQuestion = oriQuestionValue(request.oriQuestion);
-  const payload = await postJson(SEARCH_ENDPOINT, {
+  const payload = await postJson(apiUrl(request.baseUrl, SEARCH_ENDPOINT_PATH), {
     query: builtQuery,
     count: options.count,
     need_content: false,
@@ -4515,13 +4632,19 @@ async function searchWeb(query, options, request) {
   if (!Array.isArray(payload.results)) {
     throw new Error("DeepSeek Search returned a response without a results array");
   }
-  return processResults(payload.results, options);
+  const results = processResults(payload.results, options);
+  return {
+    results,
+    inputQuery: trimmed,
+    effectiveQuery: builtQuery,
+    notes: composed.notes
+  };
 }
 async function fetchPage(url, options, request) {
   const target = parseFetchUrl(url.href);
   assertFetchHostPolicy(target, options);
   const timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs);
-  const payload = await postJson(FETCH_ENDPOINT, { url: target.href }, "DeepSeek Fetch", {
+  const payload = await postJson(apiUrl(request.baseUrl, FETCH_ENDPOINT_PATH), { url: target.href }, "DeepSeek Fetch", {
     ...request,
     timeoutMs: timeout
   });
@@ -4536,7 +4659,7 @@ async function fetchDocument(url, options, request) {
   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,
@@ -4591,6 +4714,7 @@ function envOptionsReport(env = process.env) {
   putFalseOnly(options, "fetchEnabled", env, warnings);
   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)) {
     if (!key.startsWith("DEEPSEEK_") || key === API_KEY_ENV || known.has(key))
@@ -4675,7 +4799,8 @@ var init_env = __esm(() => {
   };
   TEXT_ENV = {
     language: "DEEPSEEK_SEARCH_LANGUAGE",
-    searchLocalization: SEARCH_LOCALIZATION_ENV
+    searchLocalization: SEARCH_LOCALIZATION_ENV,
+    baseUrl: BASE_URL_ENV
   };
   DOMAINS_ENV = {
     blockedDomains: "DEEPSEEK_SEARCH_BLOCKED_DOMAINS",
@@ -4725,15 +4850,16 @@ async function runConfigCommand(query, io, deps = {}) {
   const client = deps.client ?? createRetrievalClient();
   const startedAt = Date.now();
   try {
-    const results = await client.searchWeb(query, resolved.search, {
+    const outcome = await client.searchWeb(query, resolved.search, {
       signal: new AbortController().signal,
       auth: { apiKey },
-      retry: resolved.retry
+      retry: resolved.retry,
+      baseUrl: resolved.baseUrl
     });
     const elapsedMs = Date.now() - startedAt;
-    io.out(`search "${query.trim()}" — ${results.length} ${results.length === 1 ? "result" : "results"} in ${elapsedMs} ms`);
+    io.out(`search "${query.trim()}" — ${outcome.results.length} ${outcome.results.length === 1 ? "result" : "results"} in ${elapsedMs} ms`);
     io.out("");
-    for (const line of formatSearchResults(results).split(`
+    for (const line of formatSearchResults(outcome.results, outcome).split(`
 `))
       io.out(line);
     return 0;
@@ -4846,6 +4972,7 @@ var init_rulesContent = __esm(() => {
 });
 
 // src/installer/hosts/shared.ts
+import { spawnSync } from "node:child_process";
 function planHeader(input, paths, loaded, dialect) {
   const notes = [];
   const errors = [];
@@ -4866,24 +4993,26 @@ function planHeader(input, paths, loaded, dialect) {
     notes.push(competitorSteeringNote(paths.rules, steering));
   return { notes, errors, abort: false };
 }
+function probeHostVersion(command, parse4, err) {
+  const result = spawnSync(command, ["--version"], { timeout: 5000, encoding: "utf8", env: process.env, shell: true });
+  const version = result.status === 0 ? parse4(result.stdout ?? "") : undefined;
+  if (version === undefined) {
+    err(`note: ${command} was not found on PATH or printed no version; the version-drift check was skipped`);
+  }
+  return version;
+}
 var init_shared = __esm(() => {
   init_detect();
   init_formats();
 });
 
 // src/installer/hosts/claude-code.ts
-import { spawnSync } from "node:child_process";
 import { existsSync as existsSync9 } from "node:fs";
 function valueKind(value) {
   return Array.isArray(value) ? "an array" : `a ${typeof value}`;
 }
 function probeClaudeCodeVersion(err) {
-  const result = spawnSync("claude", ["--version"], { timeout: 5000, encoding: "utf8", env: process.env, shell: true });
-  const version = result.status === 0 ? parseClaudeCodeVersion(result.stdout ?? "") : undefined;
-  if (version === undefined) {
-    err("note: claude was not found on PATH or printed no version; the version-drift check was skipped");
-  }
-  return version;
+  return probeHostVersion("claude", parseClaudeCodeVersion, err);
 }
 function parseClaudeCodeVersion(output) {
   return [...output.matchAll(/\b\d+\.\d+\.\d+\b/g)].map((match) => match[0]).at(-1);
@@ -5089,14 +5218,8 @@ var init_claude_code = __esm(() => {
 });
 
 // src/installer/hosts/codex.ts
-import { spawnSync as spawnSync2 } from "node:child_process";
 function probeCodexVersion(err) {
-  const result = spawnSync2("codex", ["--version"], { timeout: 5000, encoding: "utf8", env: process.env, shell: true });
-  const version = result.status === 0 ? parseCodexVersion(result.stdout ?? "") : undefined;
-  if (version === undefined) {
-    err("note: codex was not found on PATH or printed no version; the version-drift check was skipped");
-  }
-  return version;
+  return probeHostVersion("codex", parseCodexVersion, err);
 }
 function parseCodexVersion(output) {
   return /\bcodex(?:-cli)?\s+(\d+\.\d+\.\d+)\b/.exec(output)?.[1];
@@ -5299,8 +5422,8 @@ var init_opencode = __esm(() => {
   init_value();
   init_ownership();
   init_paths();
+  init_record();
   init_rulesContent();
-  init_state();
   init_shared();
   OPENCODE_TOOL_IDS = { search: "websearch (provider deepseek)", fetch: "deepseek_fetch" };
 });
@@ -5405,10 +5528,10 @@ function planPiExtension(input, previous) {
       format: "rules",
       block: buildRulesBlock(input.host, rulesLines(RAW_MCP_TOOL_IDS, input.search, input.fetch))
     });
-    notes.push(`Rules block upserted in ${paths.rules}; Pi loads AGENTS.md context files from the working directory and its parents.`);
+    notes.push(rulesUpsertNote(paths.rules));
   }
   if (forced) {
-    notes.push("Forced tier: Pi 1.3.0 ships no built-in web tool, so the registered tools are the only web path (de-facto). " + FORCED_COST_NOTE);
+    notes.push(FORCED_NO_BUILTIN_NOTE);
   }
   return { host: "pi", scope: input.scope, tiers, edits, notes, errors };
 }
@@ -5515,16 +5638,17 @@ function planPiMcp(input) {
       format: "rules",
       block: buildRulesBlock(input.host, rulesLines(MCP_TOOL_IDS, input.search, input.fetch))
     });
-    notes.push(`Rules block upserted in ${paths.rules}; Pi loads AGENTS.md context files from the working directory and its parents.`);
+    notes.push(rulesUpsertNote(paths.rules));
   }
   if (input.search === "forced" || input.fetch === "forced") {
-    notes.push("Forced tier: Pi 1.3.0 ships no built-in web tool, so the registered tools are the only web path (de-facto). " + FORCED_COST_NOTE);
+    notes.push(FORCED_NO_BUILTIN_NOTE);
   }
   return { host: "pi", scope: input.scope, tiers, edits, notes, errors };
 }
 function collectSources(value) {
   return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
 }
+var rulesUpsertNote = (rules) => `Rules block upserted in ${rules}; Pi loads AGENTS.md context files from the working directory and its parents.`, FORCED_NO_BUILTIN_NOTE;
 var init_pi = __esm(() => {
   init_constants();
   init_settings();
@@ -5534,9 +5658,10 @@ var init_pi = __esm(() => {
   init_value();
   init_ownership();
   init_paths();
+  init_record();
   init_rulesContent();
-  init_state();
   init_shared();
+  FORCED_NO_BUILTIN_NOTE = "Forced tier: Pi 1.3.0 ships no built-in web tool, so the registered tools are the only web path (de-facto). " + FORCED_COST_NOTE;
 });
 
 // src/installer/hosts/index.ts
@@ -5623,7 +5748,7 @@ function withSecretGuard(plan) {
           reverts: undefined,
           errors: [
             {
-              message: `${edit2.file}: the existing value at ${op.path.join(".")} contains a credential-looking key ` + `(${offender}). The installer refuses to snapshot secrets into its state file. Move the key to ` + `environment indirection ("\${${API_KEY_ENV}}" expansion or env_vars) and re-run.`
+              message: `${edit2.file}: the existing value at ${op.path.join(".")} contains a credential-looking key ` + `(${offender}). The installer refuses to snapshot secrets into its install record. Move the key to ` + `environment indirection ("\${${API_KEY_ENV}}" expansion or env_vars) and re-run.`
             }
           ]
         };
@@ -5680,7 +5805,7 @@ var init_hosts = __esm(() => {
   init_constants();
   init_value();
   init_ownership();
-  init_state();
+  init_record();
   init_claude_code();
   init_codex();
   init_opencode();
@@ -5758,7 +5883,7 @@ function preview(value) {
 
 // src/installer/uninstall.ts
 function uninstall(input) {
-  return withOperationLock([statePathFor(input)], () => {
+  return withOperationLock([recordPathFor(input)], () => {
     const record = readRecord(input);
     if (record === undefined) {
       throw new Error(`No ${input.host} install is recorded for the ${input.scope} scope.`);
@@ -5786,7 +5911,7 @@ function uninstallLocked(input, record) {
   }
   releaseFileOwnership(input, record.files);
   deleteRecord(input);
-  pruneEmptyDir(stateDir(input, input.scope));
+  pruneEmptyDir(recordDir(input, input.scope));
   lines.push(`removed install record (${input.host}, ${input.scope})`);
   return lines;
 }
@@ -5795,8 +5920,8 @@ var init_uninstall = __esm(() => {
   init_operation_lock();
   init_ownership();
   init_paths();
+  init_record();
   init_revert();
-  init_state();
 });
 
 // src/installer/cli.ts
@@ -5896,7 +6021,7 @@ ${USAGE}`);
       return 0;
     }
     if (readingLegacyGlobalRecords({ ...roots, configHome: configHome2 })) {
-      out(`Global install records are being read from the legacy ${legacyGlobalStateDir(roots)} ` + "(written before the Windows config home moved to %APPDATA%).");
+      out(`Global install records are being read from the legacy ${legacyGlobalRecordDir(roots)} ` + "(written before the Windows config home moved to %APPDATA%).");
     }
     for (const record of records) {
       const by = record.installerVersion ? ` by v${record.installerVersion}` : "";
@@ -6030,7 +6155,7 @@ var init_cli = __esm(() => {
   init_config_command();
   init_hosts();
   init_ownership();
-  init_state();
+  init_record();
   init_uninstall();
   HOSTS = Object.keys(HOST_PLANNERS);
   HOST_CHOICES = `<${HOSTS.join("|")}>`;
@@ -6070,17 +6195,6 @@ re-running.`;
   PATH_CHOICES = ["extension", "mcp"];
 });
 
-// src/mcp/auth.ts
-function requireApiKey(env) {
-  const apiKey = apiKeyFromEnv(env);
-  if (!apiKey)
-    throw new Error(MISSING_API_KEY_MESSAGE);
-  return apiKey;
-}
-var init_auth2 = __esm(() => {
-  init_auth();
-});
-
 // src/mcp/client.ts
 import { CLIENT_INFO_META_KEY } from "@modelcontextprotocol/server";
 function clientNameOf(server, ctx) {
@@ -6108,7 +6222,7 @@ var init_package = __esm(() => {
   package_default = {
     $schema: "https://json.schemastore.org/package.json",
     name: "deepseek-web-retrieval",
-    version: "0.8.0",
+    version: "0.9.0",
     description: "Token-efficient DeepSeek Search and Fetch for coding agents, starting with OpenCode v2.",
     type: "module",
     license: "MIT",
@@ -6164,7 +6278,8 @@ var init_package = __esm(() => {
       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",
@@ -6211,11 +6326,13 @@ var init_package = __esm(() => {
 });
 
 // src/core/descriptions.ts
-var FETCH_SERVICE_LIMITS = "DeepSeek does not render JavaScript and cannot reach private networks; PDFs, images, and other binary files are unsupported.", FETCH_OUTPUT_TRUNCATED = "Output is truncated to the configured size.", SEARCH_RANKED_FILTERED = "Results are ranked by relevance and source authority, deduplicated by URL, and capped at the configured maximum.", SEARCH_EMPTY_IS_NORMAL = "An empty result list is normal, not an error.", SEARCH_QUERY_OPERATORS = "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.", SEARCH_TOOL_DESCRIPTION, FETCH_TOOL_DESCRIPTION, SEARCH_QUERY_PARAMETER = "Search query, 128 characters or fewer including operators (site:, -site:, quoted phrases, lang:, after:, before:).", SEARCH_ORI_QUESTION_PARAMETER, FETCH_URL_PARAMETER = "Absolute http:// or https:// URL to fetch. Credentials are rejected.";
+var FETCH_SERVICE_LIMITS = "DeepSeek does not render JavaScript and cannot reach private networks; PDFs, images, and other binary files are unsupported.", FETCH_OUTPUT_TRUNCATED = "Output is truncated to the configured size; the optional maxChars parameter raises or lowers that size for one call.", SEARCH_RANKED_FILTERED = "Results are ranked by relevance and source authority, deduplicated by URL, and capped at the configured maximum.", SEARCH_EMPTY_IS_NORMAL = "An empty result list is normal, not an error.", SEARCH_QUERY_OPERATORS = "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.", SEARCH_TOOL_DESCRIPTION, FETCH_TOOL_DESCRIPTION, SEARCH_QUERY_PARAMETER = "Search query, 128 characters or fewer including operators (site:, -site:, quoted phrases, lang:, after:, before:).", SEARCH_ORI_QUESTION_PARAMETER, FETCH_URL_PARAMETER = "Absolute http:// or https:// URL to fetch. Credentials are rejected.", FETCH_MAX_CHARS_PARAMETER, SEARCH_COUNT_PARAMETER;
 var init_descriptions = __esm(() => {
   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.";
   FETCH_TOOL_DESCRIPTION = "Fetch one web page as clean Markdown through DeepSeek's Fetch API. " + `${FETCH_SERVICE_LIMITS} ` + `${FETCH_OUTPUT_TRUNCATED}`;
   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.";
+  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.";
+  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.";
 });
 
 // src/mcp/server.ts
@@ -6229,15 +6346,15 @@ function createDeepSeekServer(config, env = process.env, client = retrievalClien
       description: SEARCH_TOOL_DESCRIPTION,
       inputSchema: SEARCH_INPUT,
       annotations: { readOnlyHint: true }
-    }, async ({ query, original_question }, ctx) => {
+    }, async ({ query, original_question, count }, ctx) => {
       try {
-        const request = requestContext(config, env, ctx.mcpReq.signal);
-        const results = await client.searchWeb(query, config.search, {
+        const request = requestContext(config, requireApiKey(env), ctx.mcpReq.signal);
+        const outcome = await client.searchWeb(query, withPerCallCount(config.search, count), {
           ...request,
           oriQuestion: original_question
         });
-        return callResult(server, ctx, formatSearchResults(results), {
-          results: results.map(toStructuredResult)
+        return callResult(server, ctx, formatSearchResults(outcome.results, outcome), {
+          results: outcome.results.map(toStructuredResult)
         });
       } catch (error) {
         return toErrorResult(error);
@@ -6250,9 +6367,9 @@ function createDeepSeekServer(config, env = process.env, client = retrievalClien
       description: FETCH_TOOL_DESCRIPTION,
       inputSchema: FETCH_INPUT,
       annotations: { readOnlyHint: true }
-    }, async ({ url }, ctx) => {
+    }, async ({ url, maxChars }, ctx) => {
       try {
-        const request = requestContext(config, env, ctx.mcpReq.signal);
+        const request = requestContext(config, requireApiKey(env), ctx.mcpReq.signal, { maxChars });
         const page = await client.fetchDocument(url, config.fetch, request);
         return callResult(server, ctx, page.content, {
           url: page.url,
@@ -6267,18 +6384,13 @@ function createDeepSeekServer(config, env = process.env, client = retrievalClien
   }
   return server;
 }
-function requestContext(config, env, signal) {
-  return { signal, auth: { apiKey: requireApiKey(env) }, retry: config.retry };
-}
 function callResult(server, ctx, text, structured) {
   if (omitStructuredContent(server, ctx))
     return { content: [{ type: "text", text }] };
   return { content: [{ type: "text", text }], structuredContent: structured };
 }
 function servePrecheck(config) {
-  if (config.search.enabled || config.fetch.enabled)
-    return;
-  return `Both tools are disabled (${ENABLE_SEARCH_ENV} and ${ENABLE_FETCH_ENV} are false); ` + "at least one must stay enabled.";
+  return bothDisabledPrecheck(config, `${ENABLE_SEARCH_ENV} and ${ENABLE_FETCH_ENV} are false`);
 }
 function toErrorResult(error) {
   const message = error instanceof Error ? error.message : String(error);
@@ -6287,18 +6399,21 @@ function toErrorResult(error) {
 var MCP_SERVER_NAME = "deepseek-web-retrieval", SEARCH_INPUT, FETCH_INPUT;
 var init_server = __esm(() => {
   init_package();
+  init_auth();
   init_client();
   init_constants();
   init_descriptions();
   init_format2();
-  init_auth2();
+  init_options();
   init_client2();
   SEARCH_INPUT = z2.object({
     query: z2.string().min(1).describe(SEARCH_QUERY_PARAMETER),
-    original_question: z2.string().optional().describe(SEARCH_ORI_QUESTION_PARAMETER)
+    original_question: z2.string().optional().describe(SEARCH_ORI_QUESTION_PARAMETER),
+    count: z2.number().int().min(1).max(MAX_SEARCH_COUNT).optional().describe(SEARCH_COUNT_PARAMETER)
   });
   FETCH_INPUT = z2.object({
-    url: z2.string().min(1).describe(FETCH_URL_PARAMETER)
+    url: z2.string().min(1).describe(FETCH_URL_PARAMETER),
+    maxChars: z2.number().int().min(0).max(MAX_FETCH_CHARS).optional().describe(FETCH_MAX_CHARS_PARAMETER)
   });
 });
 
@@ -6346,7 +6461,6 @@ var init_serve = __esm(() => {
   init_config_file();
   init_config_summary();
   init_env();
-  init_auth2();
   init_client2();
   init_server();
 });