deepseek-web-retrieval 0.6.0 → 0.7.0

package/src/installer/hosts/opencode.ts

@@ -2,6 +2,7 @@ import { FORCED_COST_NOTE, looksLikeOwnPackage } from "../detect";
 import { codecFor } from "../formats";
 import { buildRulesBlock } from "../formats/rules";
 import { isPlainObject } from "../formats/value";
+import { lineageMatcher } from "../ownership";
 import { configHome, join } from "../paths";
 import { rulesLines } from "../rulesContent";
 import { appendedByPrevious } from "../state";
@@ -44,8 +45,10 @@ export function planOpenCode(input: InstallerInput, previous: InstallRecord | un
 
   const plugins = Array.isArray(loaded.value.plugins) ? loaded.value.plugins : [];
   // Precisely ours: plugin packages a tracked init appended, plus this init's ref.
-  // Without a record nothing is excused — an untracked same-name plugin (a fork
-  // registers the same tool ids and would collide) must be removed first.
+  // Refs compare by package name (samePackageName), so a pinned ref excuses the
+  // unpinned lineage a previous init wrote and vice versa. Without a record
+  // nothing is excused — an untracked same-name plugin (a fork registers the
+  // same tool ids and would collide) must be removed first.
   const trackedPackages = new Set(
     appendedByPrevious(previous, ["plugins"])
       .filter((entry): entry is { package: string } => isPlainObject(entry) && typeof entry.package === "string")
@@ -54,9 +57,10 @@ export function planOpenCode(input: InstallerInput, previous: InstallRecord | un
   const pluginPackages = plugins.filter(
     (entry): entry is { package: string } => isPlainObject(entry) && typeof entry.package === "string",
   );
-  const excused = previous === undefined ? new Set<string>() : new Set<string>([...trackedPackages, input.packageRef]);
+  const excusedRefs = previous === undefined ? [] : [...trackedPackages, input.packageRef];
+  const isExcusedRef = lineageMatcher(excusedRefs);
   const foreignOwn = pluginPackages.filter(
-    (entry) => looksLikeOwnPackage(entry.package) && !excused.has(entry.package),
+    (entry) => looksLikeOwnPackage(entry.package) && !isExcusedRef(entry.package),
   );
   if (foreignOwn.length > 0) {
     errors.push({
@@ -65,7 +69,7 @@ export function planOpenCode(input: InstallerInput, previous: InstallRecord | un
         "write. Remove it (or run uninstall if it came from a previous init), then retry.",
     });
   }
-  if (previous !== undefined && pluginPackages.some((entry) => excused.has(entry.package))) {
+  if (previous !== undefined && pluginPackages.some((entry) => isExcusedRef(entry.package))) {
     notes.push(
       "A previous init wrote the plugins entry; re-applying keeps it the only entry (a changed package ref or tier " +
         "options replace it, an unchanged one is a no-op) and the original snapshots carry over.",

package/src/installer/hosts/pi.ts

@@ -11,6 +11,7 @@ import {
 import { codecFor } from "../formats";
 import { buildRulesBlock } from "../formats/rules";
 import { isPlainObject } from "../formats/value";
+import { lineageMatcher } from "../ownership";
 import { join } from "../paths";
 import { MCP_TOOL_IDS, RAW_MCP_TOOL_IDS, rulesLines } from "../rulesContent";
 import { appendedByPrevious } from "../state";
@@ -60,14 +61,17 @@ function planPiExtension(input: InstallerInput, previous: InstallRecord | undefi
   const packages = Array.isArray(loaded.value.packages) ? loaded.value.packages : [];
   const source = piSourceRef(input.packageRef);
   // Precisely ours: what a tracked init appended, plus what this init would write.
-  // Only a tracked init can excuse a same-name source — without a record, even an
+  // Sources compare by package name (samePackageName), so a pinned source
+  // excuses the unpinned lineage a previous init wrote and vice versa. Only a
+  // tracked init can excuse a same-name source — without a record, even an
   // exact match is an untracked install this installer must not adopt silently.
   const trackedSources = appendedByPrevious(previous, ["packages"]).filter(
     (entry): entry is string => typeof entry === "string",
   );
-  const excused = previous === undefined ? new Set<string>() : new Set<string>([...trackedSources, source]);
   const sources = packages.filter((entry): entry is string => typeof entry === "string");
-  const foreignOwn = sources.filter((entry) => looksLikeOwnPackage(entry) && !excused.has(entry));
+  const excusedSources = previous === undefined ? [] : [...trackedSources, source];
+  const isExcusedSource = lineageMatcher(excusedSources);
+  const foreignOwn = sources.filter((entry) => looksLikeOwnPackage(entry) && !isExcusedSource(entry));
   if (foreignOwn.length > 0) {
     errors.push({
       message:
@@ -75,7 +79,7 @@ function planPiExtension(input: InstallerInput, previous: InstallRecord | undefi
         "write. Remove it (pi remove <source>, or uninstall if it came from a previous init), then retry.",
     });
   }
-  if (previous !== undefined && sources.some((entry) => excused.has(entry))) {
+  if (previous !== undefined && sources.some((entry) => isExcusedSource(entry))) {
     notes.push(
       "A previous init wrote the packages entry; re-applying reuses it (an unchanged source deduplicates, a changed " +
         "--package ref replaces the old source) and the original snapshots carry over.",
@@ -87,9 +91,9 @@ function planPiExtension(input: InstallerInput, previous: InstallRecord | undefi
     // Pi has no per-package kill switch in settings.json, so a web-capable
     // package or extension source cannot be excluded from the plan — refuse the
     // tier instead of promising routing that is not actually forced.
-    const ownSources = new Set<string>([...trackedSources, source]);
+    const isOwnSource = lineageMatcher([...trackedSources, source]);
     const unexcludable = [...collectSources(loaded.value.packages), ...collectSources(loaded.value.extensions)].filter(
-      (entry) => !ownSources.has(entry) && looksWebCapable(entry, undefined),
+      (entry) => !isOwnSource(entry) && looksWebCapable(entry, undefined),
     );
     if (unexcludable.length > 0) {
       errors.push({

package/src/installer/ownership.ts

@@ -2,11 +2,60 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSyn
 import { basename, dirname, join, resolve } from "node:path";
 import { isPlainObject } from "../core/object";
 import { pruneEmptyDir } from "./revert";
-import { statePathFor } from "./state";
+import { recordReadPath, statePathFor } from "./state";
 import type { InstallerInput, RecordedFile, Scope } from "./types";
 
 type ClaimedFile = Pick<RecordedFile, "file" | "format" | "shared">;
 
+/**
+ * True when a ref's final `@` segment is a version spec — it starts with a digit
+ * (`name@<version>`, `npm:name@<version>`) — and not an npm scope
+ * (`@scope/name`, whose only `@` leads the string) or a dist-tag (`name@canary`).
+ */
+function hasVersionSuffix(ref: string): boolean {
+  const at = ref.lastIndexOf("@");
+  return at > 0 && /^[0-9]/.test(ref.slice(at + 1));
+}
+
+function stripVersionSuffix(ref: string): string {
+  const at = ref.lastIndexOf("@");
+  return hasVersionSuffix(ref) ? ref.slice(0, at) : ref;
+}
+
+/**
+ * Package-ref identity, the one comparison for "is this entry our package":
+ * two refs are the same package when they are equal after stripping a trailing
+ * `@version` suffix, so a pinned ref (`deepseek-web-retrieval@<version>`,
+ * `npm:deepseek-web-retrieval@<version>`) still matches its lineage
+ * (`deepseek-web-retrieval`). Forks, dist-tags, and lookalike names compare
+ * unequal. Everywhere a recorded or configured ref is matched against this
+ * install's ref — orphan detection, upgrade detection — goes through this
+ * helper instead of exact string equality.
+ */
+export function samePackageName(a: string, b: string): boolean {
+  return stripVersionSuffix(a) === stripVersionSuffix(b);
+}
+
+/**
+ * A lineage-membership predicate over an excused/own ref set: the candidate
+ * matches when it is the same package as any listed ref (version suffixes
+ * stripped via samePackageName — a pinned or hand-edited ref still matches its
+ * lineage). Both host modules build their set (previous init's tracked entries
+ * plus this run's ref) and ask the same two questions with this one predicate.
+ */
+export function lineageMatcher(refs: readonly string[]): (candidate: string) => boolean {
+  return (candidate: string) => refs.some((ref) => samePackageName(ref, candidate));
+}
+
+/**
+ * The `--pin` rule: append the running CLI's version to the ref unless its
+ * final `@` segment already is a version (`name` → `name@<version>`; a ref
+ * already ending in a version keeps it).
+ */
+export function pinPackageRef(ref: string, version: string): string {
+  return hasVersionSuffix(ref) ? ref : `${ref}@${version}`;
+}
+
 interface FileOwner {
   readonly recordPath: string;
   readonly scope: Scope;
@@ -63,6 +112,10 @@ function readOwner(file: string): FileOwner | undefined {
 function assertOwner(input: InstallerInput, claim: string): void {
   const owner = readOwner(claim);
   if (owner === undefined || owner.recordPath === ownerOf(input).recordPath) return;
+  // A win32 sidecar written before the config home moved to %APPDATA% names the
+  // legacy record location; when that is where this input's record is read
+  // from (see recordReadPath), it still identifies this same install lineage.
+  if (owner.recordPath === canonicalPath(recordReadPath(input))) return;
   throw new Error(
     `A ${input.host} install is already recorded at the ${owner.scope} scope (${owner.recordPath}) and claims the same config file. ` +
       `Uninstall it first: deepseek-web-retrieval uninstall --host ${input.host} --scope ${owner.scope} --cwd ${JSON.stringify(owner.cwd)}. ` +

package/src/installer/paths.ts

@@ -7,7 +7,13 @@ export function join(...parts: readonly string[]): string {
   return nonEmpty.length === 0 ? "" : pathJoin(...nonEmpty);
 }
 
-/** Config home: an explicit root wins; otherwise ~/.config. The CLI resolves XDG at the edge. */
+/**
+ * Config home: an explicit root wins; otherwise `~/.config`. The CLI edge now
+ * supplies the platform-aware explicit root (see userConfigHome in
+ * core/config-file: an honored XDG on every platform, `%APPDATA%` or
+ * `<home>\AppData\Roaming` on win32), so the `.config` fallback applies only to
+ * callers that construct roots directly without going through the CLI.
+ */
 export function configHome(roots: FsRoots): string {
   return roots.configHome ?? join(roots.home, ".config");
 }

package/src/installer/state.ts

@@ -3,12 +3,38 @@ import { isAbsolute, join } from "node:path";
 import { z } from "zod/v4";
 import { stateDir } from "./paths";
 import { atomicWrite } from "./persistence";
-import type { FsRoots, InstallerInput, InstallRecord } from "./types";
+import type { FsRoots, InstallerInput, InstallRecord, Scope } from "./types";
 
 export function statePathFor(input: InstallerInput): string {
   return join(stateDir(input, input.scope), `install.${input.host}.json`);
 }
 
+/** The platform a read resolves for: injected at the CLI edge, process.platform otherwise. */
+function platformOf(roots: FsRoots): NodeJS.Platform {
+  return roots.platform ?? process.platform;
+}
+
+/**
+ * Windows-only read compatibility: global records written before the config
+ * home moved to %APPDATA% live under `~/.config`. Kept readable so `list` and
+ * `uninstall` keep tracking installs made by older releases.
+ */
+export function legacyGlobalStateDir(roots: FsRoots): string {
+  return join(roots.home, ".config", "deepseek-web-retrieval");
+}
+
+/**
+ * The file a record is read from: the canonical state path, except that a
+ * missing win32 global record falls back to the legacy `~/.config` location
+ * (see legacyGlobalStateDir). Writes always target the canonical path.
+ */
+export function recordReadPath(input: InstallerInput, platform: NodeJS.Platform = platformOf(input)): string {
+  const canonical = statePathFor(input);
+  if (platform !== "win32" || input.scope !== "global" || existsSync(canonical)) return canonical;
+  const legacy = join(legacyGlobalStateDir(input), `install.${input.host}.json`);
+  return existsSync(legacy) ? legacy : canonical;
+}
+
 const keyPath = z.array(z.string().min(1)).min(1);
 const tier = z.enum(["optional", "preferred", "forced", "off"]);
 const operation = z.discriminatedUnion("op", [
@@ -86,7 +112,7 @@ function readRecordFile(file: string, host: string, scope: string): InstallRecor
 }
 
 export function readRecord(input: InstallerInput): InstallRecord | undefined {
-  return readRecordFile(statePathFor(input), input.host, input.scope);
+  return readRecordFile(recordReadPath(input), input.host, input.scope);
 }
 
 /**
@@ -123,27 +149,54 @@ export function appendedByPrevious(record: InstallRecord | undefined, path: read
 }
 
 export function deleteRecord(input: InstallerInput): void {
-  const file = statePathFor(input);
+  // Win32 legacy records are removed where they were found, so uninstalling a
+  // pre-APPDATA install clears its tracking instead of a canonical file that
+  // was never written.
+  const file = recordReadPath(input);
   if (existsSync(file)) rmSync(file);
 }
 
-/** Lists install records found in both scope locations for the given roots. */
-export function listRecords(roots: FsRoots): InstallRecord[] {
+/** Reads every valid record in one scope's directory; an absent directory is empty. */
+function readRecordsFromDir(dir: string, scope: Scope): InstallRecord[] {
   const records: InstallRecord[] = [];
-  for (const scope of ["global", "project"] as const) {
-    const dir = stateDir(roots, scope);
-    let names: string[];
-    try {
-      names = readdirSync(dir);
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
-      throw new InstallRecordError(dir, "unreadable", (error as NodeJS.ErrnoException).code ?? "list failed");
-    }
-    for (const name of names) {
-      if (!name.startsWith("install.") || !name.endsWith(".json")) continue;
-      const record = readRecordFile(join(dir, name), name.slice("install.".length, -".json".length), scope);
-      if (record !== undefined) records.push(record);
-    }
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return records;
+    throw new InstallRecordError(dir, "unreadable", (error as NodeJS.ErrnoException).code ?? "list failed");
+  }
+  for (const name of names) {
+    if (!name.startsWith("install.") || !name.endsWith(".json")) continue;
+    const record = readRecordFile(join(dir, name), name.slice("install.".length, -".json".length), scope);
+    if (record !== undefined) records.push(record);
   }
   return records;
 }
+
+function hasRecordFiles(dir: string): boolean {
+  try {
+    return readdirSync(dir).some((name) => name.startsWith("install.") && name.endsWith(".json"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when the global records must be read from the legacy win32 `~/.config`
+ * location: win32, nothing recorded under the canonical config home, and
+ * pre-%APPDATA% records still present there. `list` says so when this holds.
+ */
+export function readingLegacyGlobalRecords(roots: FsRoots): boolean {
+  if (platformOf(roots) !== "win32") return false;
+  if (hasRecordFiles(stateDir(roots, "global"))) return false;
+  return hasRecordFiles(legacyGlobalStateDir(roots));
+}
+
+/** Lists install records found in both scope locations for the given roots. */
+export function listRecords(roots: FsRoots): InstallRecord[] {
+  const global = readRecordsFromDir(stateDir(roots, "global"), "global");
+  const project = readRecordsFromDir(stateDir(roots, "project"), "project");
+  const legacy = readingLegacyGlobalRecords(roots) ? readRecordsFromDir(legacyGlobalStateDir(roots), "global") : [];
+  return [...global, ...legacy, ...project];
+}

package/src/installer/types.ts

@@ -13,6 +13,11 @@ export interface FsRoots {
   readonly cwd: string;
   /** Explicit config home; the CLI edge resolves XDG once and passes it down. */
   readonly configHome?: string;
+  /**
+   * Platform for the win32-aware reads (legacy record fallback); the CLI edge
+   * passes it down like configHome. Readers default to process.platform.
+   */
+  readonly platform?: NodeJS.Platform;
 }
 
 /** The files a host edit touches for a given scope. */
@@ -37,6 +42,11 @@ export interface InstallerInput {
   readonly home: string;
   readonly cwd: string;
   readonly configHome?: string;
+  /**
+   * Platform for the win32-aware reads (legacy record fallback); see FsRoots.
+   * Injected at the CLI edge, absent when callers construct inputs directly.
+   */
+  readonly platform?: NodeJS.Platform;
   /**
    * Integration mechanism for hosts with more than one (Pi: the native
    * extension, or the MCP server). Undefined means the host's default path.

package/src/mcp/auth.ts

@@ -1,8 +1,7 @@
-import { apiKeyFromEnv } from "../core/auth";
-import { API_KEY_ENV } from "../core/constants";
+import { apiKeyFromEnv, MISSING_API_KEY_MESSAGE } from "../core/auth";
 import type { Env } from "../core/env";
 
-export const MISSING_API_KEY_MESSAGE = `DeepSeek API key not found. Set ${API_KEY_ENV} in the MCP server's env configuration.`;
+export { MISSING_API_KEY_MESSAGE };
 
 /** Resolves the API key from the environment or fails with shared guidance. */
 export function requireApiKey(env: Env): string {

package/src/mcp/cli.ts

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 // Any argument means a human ran the CLI; MCP clients spawn this bin with no
-// arguments for the stdio server. The installer is imported statically and the
-// MCP server dynamically, so init/uninstall never load — or depend on — the
-// server's dependency graph, including when recovering from a bad server setup.
+// arguments for the stdio server. Each side is imported dynamically, and only
+// the side being routed to, so init/uninstall never load — or depend on — the
+// server's dependency graph (and the server never loads the installer),
+// including when recovering from a bad server setup.
 if (process.argv.length > 2) {
   const { runInstallerCli } = await import("../installer/cli");
   process.exit(await runInstallerCli(process.argv.slice(2)));

package/src/mcp/serve.ts

@@ -1,5 +1,7 @@
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { apiKeyFromEnv } from "../core/auth";
+import { sharedFileOptions } from "../core/config-file";
+import { configDeviations } from "../core/config-summary";
 import { resolveEnvOptions } from "../core/env";
 import { MISSING_API_KEY_MESSAGE } from "./auth";
 import { isJsonReplacingClient } from "./client";
@@ -14,7 +16,9 @@ export function serveMcp(): void {
     process.exit(1);
   }
 
-  const config = resolveEnvOptions(env);
+  // Defaults < shared config file < environment: the server reads the file
+  // itself, so hosts that forward only DEEPSEEK_API_KEY still honor it.
+  const config = resolveEnvOptions(env, sharedFileOptions({ env }));
   const precheck = servePrecheck(config);
   if (precheck) {
     console.error(precheck);
@@ -45,6 +49,11 @@ export function serveMcp(): void {
     .filter(Boolean)
     .join(", ");
   console.error(`deepseek-web-retrieval MCP server on stdio (${tools})`);
+  // Deviations only, so the line stays short while still showing every
+  // non-default knob the layered resolution produced; nothing deviating
+  // means no line at all.
+  const deviations = configDeviations(config);
+  if (deviations) console.error(`config: ${deviations}`);
 
   process.on("SIGINT", () => void handle.close());
   process.on("SIGTERM", () => void handle.close());

package/src/mcp/server.ts

@@ -8,6 +8,7 @@ import { ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV } from "../core/constants";
 import {
   FETCH_TOOL_DESCRIPTION,
   FETCH_URL_PARAMETER,
+  SEARCH_ORI_QUESTION_PARAMETER,
   SEARCH_QUERY_PARAMETER,
   SEARCH_TOOL_DESCRIPTION,
 } from "../core/descriptions";
@@ -21,6 +22,7 @@ export const MCP_SERVER_NAME = "deepseek-web-retrieval";
 
 const SEARCH_INPUT = z.object({
   query: z.string().min(1).describe(SEARCH_QUERY_PARAMETER),
+  original_question: z.string().optional().describe(SEARCH_ORI_QUESTION_PARAMETER),
 });
 
 const FETCH_INPUT = z.object({
@@ -47,10 +49,13 @@ export function createDeepSeekServer(
         inputSchema: SEARCH_INPUT,
         annotations: { readOnlyHint: true },
       },
-      async ({ query }, ctx) => {
+      async ({ query, original_question }, ctx) => {
         try {
           const request = requestContext(config, env, ctx.mcpReq.signal);
-          const results = await client.searchWeb(query, config.search, request);
+          const results = await client.searchWeb(query, config.search, {
+            ...request,
+            oriQuestion: original_question,
+          });
           return callResult(server, ctx, formatSearchResults(results), {
             results: results.map(toStructuredResult),
           });

package/src/opencode/plugin.ts

@@ -3,7 +3,11 @@ import type { Context } from "@opencode/plugin/promise/plugin";
 import type { ToolContext } from "@opencode/plugin/promise/tool";
 import type { RetrievalClient } from "../core/client";
 import { inspectFetchTarget, retrievalClient } from "../core/client";
+import { sharedFileOptions } from "../core/config-file";
+import { configDeviations } from "../core/config-summary";
 import { FETCH_MARKDOWN_ONLY, FETCH_OUTPUT_TRUNCATED } from "../core/descriptions";
+import { pluginOptionsFromEnv } from "../core/env";
+import { formatQualityMarker } from "../core/format";
 import { resolveFetchTimeoutMs, resolvePluginOptions } from "../core/options";
 import type { PluginOptions, ResolvedOptions, SearchResult } from "../core/types";
 import { resolveApiKey } from "./auth";
@@ -58,10 +62,14 @@ interface OpenCodeSearchResult {
 
 /** Maps the core's neutral SearchResult onto the shape OpenCode expects. */
 function toOpenCodeResult(result: SearchResult): OpenCodeSearchResult {
+  // OpenCode's result shape is closed and only `content` reaches the model,
+  // so the quality marker rides at the end of the content string.
+  const marker = formatQualityMarker(result);
+  const content = marker ? (result.content ? `${result.content} ${marker}` : marker) : result.content;
   return {
     url: result.url,
     ...(result.title ? { title: result.title } : {}),
-    ...(result.content ? { content: result.content } : {}),
+    ...(content ? { content } : {}),
     ...(result.published !== undefined ? { time: { published: result.published } } : { time: {} }),
   };
 }
@@ -143,8 +151,20 @@ export function createOpenCodePlugin(client: RetrievalClient = retrievalClient)
   return Plugin.define({
     id: "deepseek-web-retrieval",
     async setup(ctx) {
-      const config = resolvePluginOptions(ctx.options);
+      // Defaults < shared config file < DEEPSEEK_* environment < opencode.json
+      // options: the host layer keeps winning exactly as before — the change
+      // is that the file and the environment now configure this host too.
+      const config = resolvePluginOptions({
+        ...sharedFileOptions(),
+        ...pluginOptionsFromEnv(process.env),
+        ...ctx.options,
+      });
       const registration = resolveRegistration(ctx.options);
+      // Deviations only, printed once at setup: one stderr line so a
+      // multi-layer resolution is visible; nothing deviating means no line at
+      // all (same contract as the MCP server).
+      const deviations = configDeviations(config);
+      if (deviations) console.error(`deepseek-web-retrieval config: ${deviations}`);
 
       if (config.search.enabled) {
         await ctx.websearch.transform((editor) => {

package/src/pi/extension.ts

@@ -1,14 +1,17 @@
 import { homedir } from "node:os";
 import { Type } from "@earendil-works/pi-ai";
-import type { AgentToolResult, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult, ExtensionAPI, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { apiKeyFromEnv } from "../core/auth";
 import type { RequestOptions, RetrievalClient } from "../core/client";
 import { inspectFetchTarget, retrievalClient } from "../core/client";
+import { sharedFileOptions } from "../core/config-file";
+import { configDeviations } from "../core/config-summary";
 import { API_KEY_ENV, ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV } from "../core/constants";
 import {
   FETCH_TOOL_DESCRIPTION,
   FETCH_URL_PARAMETER,
+  SEARCH_ORI_QUESTION_PARAMETER,
   SEARCH_QUERY_PARAMETER,
   SEARCH_TOOL_DESCRIPTION,
 } from "../core/descriptions";
@@ -22,6 +25,11 @@ import { readExtensionSettings, SETTINGS_NAMESPACE } from "./settings";
 
 const SEARCH_PARAMETERS = Type.Object({
   query: Type.String({ minLength: 1, description: SEARCH_QUERY_PARAMETER }),
+  original_question: Type.Optional(
+    Type.String({
+      description: `${SEARCH_ORI_QUESTION_PARAMETER} When left blank, the most recent user message in the session is sent instead, truncated to fit.`,
+    }),
+  ),
 });
 
 const SEARCH_OUTPUT = Type.Object({
@@ -31,6 +39,9 @@ const SEARCH_OUTPUT = Type.Object({
       title: Type.Optional(Type.String()),
       content: Type.Optional(Type.String()),
       published: Type.Optional(Type.Number()),
+      rerankScore: Type.Optional(Type.Number()),
+      authority: Type.Optional(Type.Number()),
+      siteName: Type.Optional(Type.String()),
     }),
   ),
 });
@@ -50,14 +61,15 @@ const FETCH_OUTPUT = Type.Object({
 const NEVER_ABORTS = new AbortController().signal;
 
 /**
- * Resolves the extension's options: the shared DEEPSEEK_* environment
- * pipeline, with the settings namespace layered on top. Settings outrank the
- * environment because the installer wrote them as the explicit install-time
- * intent (the off tier lands there — the installer cannot write the shell
- * environment).
+ * Resolves the extension's options: defaults < shared config file < the shared
+ * DEEPSEEK_* environment pipeline < the settings namespace. The file's path
+ * follows the passed environment (XDG_CONFIG_HOME), so the function stays
+ * injectable. Settings outrank both lower layers because the installer wrote
+ * them as the explicit install-time intent (the off tier lands there — the
+ * installer cannot write the shell environment).
  */
 export function resolveExtensionOptions(env: Env = process.env, settings: ExtensionSettings = {}): ResolvedOptions {
-  const options: Record<string, unknown> = { ...pluginOptionsFromEnv(env) };
+  const options: Record<string, unknown> = { ...sharedFileOptions({ env }), ...pluginOptionsFromEnv(env) };
   if (settings.enableSearch === false) options.searchEnabled = false;
   if (settings.enableFetch === false) options.fetchEnabled = false;
   return resolvePluginOptions(options);
@@ -83,9 +95,15 @@ export function searchTool(config: ResolvedOptions, client: RetrievalClient = re
     outputSchema: SEARCH_OUTPUT,
     annotations: { readOnlyHint: true, openWorldHint: true },
     exposure: "direct",
-    async execute(_toolCallId, params, signal): Promise<AgentToolResult> {
+    async execute(_toolCallId, params, signal, _onUpdate, ctx): Promise<AgentToolResult> {
       try {
-        const results = await client.searchWeb(params.query, config.search, requestContext(config, signal));
+        // The explicit parameter wins; only when the model left it blank does
+        // the session fallback get a say.
+        const explicit = params.original_question?.trim() ? params.original_question : undefined;
+        const results = await client.searchWeb(params.query, config.search, {
+          ...requestContext(config, signal),
+          oriQuestion: explicit ?? sessionOriQuestion(ctx),
+        });
         return {
           content: [{ type: "text", text: formatSearchResults(results) }],
           structuredContent: { results: results.map(toStructuredResult) },
@@ -141,6 +159,11 @@ export default function deepSeekWebRetrieval(pi: ExtensionAPI): void {
   const config = resolveExtensionOptions(process.env, readExtensionSettings(homedir(), process.cwd()));
   const precheck = extensionPrecheck(config);
   if (precheck) throw new Error(precheck);
+  // Deviations only, printed once at registration: one stderr line so a
+  // multi-layer resolution is visible where Pi surfaces extension output;
+  // nothing deviating means no line at all (same contract as the MCP server).
+  const deviations = configDeviations(config);
+  if (deviations) console.error(`deepseek-web-retrieval config: ${deviations}`);
   if (config.search.enabled) pi.registerTool(searchTool(config));
   if (config.fetch.enabled) pi.registerTool(fetchTool(config));
 }
@@ -149,6 +172,52 @@ function requestContext(config: ResolvedOptions, signal: AbortSignal | undefined
   return { signal: signal ?? NEVER_ABORTS, auth: { apiKey: requireApiKey() }, retry: config.retry };
 }
 
+/**
+ * Best-effort `ori_question` fallback for when the model left the tool input
+ * blank: the most recent user message text in the session projection, readable
+ * synchronously at call time. Best-effort is the contract — Pi's runtime may
+ * call `execute` without a context (the fifth argument is typed non-optional
+ * but `wrapToolDefinition` passes `ctx ?? ctxFactory?.()`), and any surprise
+ * (missing manager, thrown error, odd shape) must degrade to "no fallback"
+ * rather than fail the search itself. Length handling stays in the core
+ * client, which trims and clamps to the API's 128-char budget.
+ */
+function sessionOriQuestion(ctx: ExtensionToolContext | undefined): string | undefined {
+  try {
+    const messages = ctx?.sessionManager?.buildSessionProjection()?.messages;
+    if (!Array.isArray(messages)) return undefined;
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const text = userMessageText(messages[i]);
+      if (text !== undefined) return text;
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The trimmed text of a user message's string or `text`-block content, if any. */
+function userMessageText(message: unknown): string | undefined {
+  if (typeof message !== "object" || message === null) return undefined;
+  const { role, content } = message as { role?: unknown; content?: unknown };
+  if (role !== "user") return undefined;
+  const text =
+    typeof content === "string"
+      ? content
+      : Array.isArray(content)
+        ? content
+            .map((part) =>
+              typeof part === "object" && part !== null && (part as { type?: unknown }).type === "text"
+                ? (part as { text?: unknown }).text
+                : undefined,
+            )
+            .filter((part): part is string => typeof part === "string")
+            .join(" ")
+        : undefined;
+  const trimmed = text?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
 function requireApiKey(): string {
   const key = apiKeyFromEnv();
   if (key) return key;