deepseek-web-retrieval 0.5.1 → 0.7.0

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;

package/src/version.ts

@@ -0,0 +1,12 @@
+import { readFileSync } from "node:fs";
+
+/**
+ * The published package version, read once at startup. Resolves to the repo
+ * root when run from source and to the package root when run from the bundled
+ * dist/ output; npm always ships package.json alongside it.
+ */
+export const TOOL_VERSION: string = (
+  JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as {
+    version: string;
+  }
+).version;