deepseek-web-retrieval 0.3.0 → 0.5.0

package/src/pi/extension.ts

@@ -0,0 +1,164 @@
+import { homedir } from "node:os";
+import { Type } from "@earendil-works/pi-ai";
+import type { AgentToolResult, ExtensionAPI } 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 { API_KEY_ENV, ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV } from "../core/constants";
+import {
+  FETCH_TOOL_DESCRIPTION,
+  FETCH_URL_PARAMETER,
+  SEARCH_QUERY_PARAMETER,
+  SEARCH_TOOL_DESCRIPTION,
+} from "../core/descriptions";
+import type { Env } from "../core/env";
+import { pluginOptionsFromEnv } from "../core/env";
+import { formatSearchResults, toStructuredResult } from "../core/format";
+import { resolvePluginOptions } from "../core/options";
+import type { ResolvedOptions } from "../core/types";
+import type { ExtensionSettings } from "./settings";
+import { readExtensionSettings, SETTINGS_NAMESPACE } from "./settings";
+
+const SEARCH_PARAMETERS = Type.Object({
+  query: Type.String({ minLength: 1, description: SEARCH_QUERY_PARAMETER }),
+});
+
+const SEARCH_OUTPUT = Type.Object({
+  results: Type.Array(
+    Type.Object({
+      url: Type.String(),
+      title: Type.Optional(Type.String()),
+      content: Type.Optional(Type.String()),
+      published: Type.Optional(Type.Number()),
+    }),
+  ),
+});
+
+const FETCH_PARAMETERS = Type.Object({
+  url: Type.String({ minLength: 1, description: FETCH_URL_PARAMETER }),
+});
+
+const FETCH_OUTPUT = Type.Object({
+  url: Type.String(),
+  title: Type.String(),
+  content: Type.String(),
+  truncated: Type.Boolean(),
+});
+
+/** Pi may execute a tool without an abort signal; the core requires one. */
+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).
+ */
+export function resolveExtensionOptions(env: Env = process.env, settings: ExtensionSettings = {}): ResolvedOptions {
+  const options: Record<string, unknown> = { ...pluginOptionsFromEnv(env) };
+  if (settings.enableSearch === false) options.searchEnabled = false;
+  if (settings.enableFetch === false) options.fetchEnabled = false;
+  return resolvePluginOptions(options);
+}
+
+/** Returns the both-disabled message, or undefined when a tool stays enabled. */
+export function extensionPrecheck(config: ResolvedOptions): string | undefined {
+  if (config.search.enabled || config.fetch.enabled) return undefined;
+  return (
+    `Both tools are disabled (${ENABLE_SEARCH_ENV} and ${ENABLE_FETCH_ENV} are false, or the ` +
+    `${SETTINGS_NAMESPACE} settings namespace disabled them); at least one must stay enabled.`
+  );
+}
+
+/** The search tool as Pi registers it; exported for tests. */
+export function searchTool(config: ResolvedOptions, client: RetrievalClient = retrievalClient) {
+  return defineTool({
+    name: "deepseek_web_search",
+    label: "DeepSeek Web Search",
+    description: SEARCH_TOOL_DESCRIPTION,
+    promptSnippet: "Search the web with DeepSeek and return ranked results with summaries.",
+    parameters: SEARCH_PARAMETERS,
+    outputSchema: SEARCH_OUTPUT,
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    exposure: "direct",
+    async execute(_toolCallId, params, signal): Promise<AgentToolResult> {
+      try {
+        const results = await client.searchWeb(params.query, config.search, requestContext(config, signal));
+        return {
+          content: [{ type: "text", text: formatSearchResults(results) }],
+          structuredContent: { results: results.map(toStructuredResult) },
+          details: undefined,
+        };
+      } catch (error) {
+        return toErrorResult(error);
+      }
+    },
+  });
+}
+
+/** The fetch tool as Pi registers it; exported for tests. */
+export function fetchTool(config: ResolvedOptions, client: RetrievalClient = retrievalClient) {
+  return defineTool({
+    name: "deepseek_fetch",
+    label: "DeepSeek Fetch",
+    description: FETCH_TOOL_DESCRIPTION,
+    promptSnippet: "Fetch one web page as clean Markdown with DeepSeek.",
+    parameters: FETCH_PARAMETERS,
+    outputSchema: FETCH_OUTPUT,
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    exposure: "direct",
+    async execute(_toolCallId, params, signal): Promise<AgentToolResult> {
+      try {
+        const target = inspectFetchTarget(params.url, config.fetch);
+        const page = await client.fetchDocument(target, config.fetch, requestContext(config, signal));
+        return {
+          content: [{ type: "text", text: page.content }],
+          structuredContent: {
+            url: page.url,
+            title: page.title,
+            content: page.content,
+            truncated: page.truncated,
+          },
+          details: undefined,
+        };
+      } catch (error) {
+        return toErrorResult(error);
+      }
+    },
+  });
+}
+
+/**
+ * The Pi extension entry. Pi loads this file through the package's `pi`
+ * manifest and calls the default export inside its own process: the tools run
+ * without MCP's 20 KB result truncation and 60 s request timeout, exposure is
+ * `direct` by Pi's own default (no codemode trap), and the key is read
+ * straight from the Pi process environment.
+ */
+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);
+  if (config.search.enabled) pi.registerTool(searchTool(config));
+  if (config.fetch.enabled) pi.registerTool(fetchTool(config));
+}
+
+function requestContext(config: ResolvedOptions, signal: AbortSignal | undefined): RequestOptions {
+  return { signal: signal ?? NEVER_ABORTS, auth: { apiKey: requireApiKey() }, retry: config.retry };
+}
+
+function requireApiKey(): string {
+  const key = apiKeyFromEnv();
+  if (key) return key;
+  throw new Error(
+    `${API_KEY_ENV} is not set. The DeepSeek extension reads it from the environment of the Pi ` +
+      "process; set it in the shell that launches Pi.",
+  );
+}
+
+function toErrorResult(error: unknown): AgentToolResult {
+  const message = error instanceof Error ? error.message : String(error);
+  return { content: [{ type: "text", text: message }], details: undefined, isError: true };
+}

package/src/pi/settings.ts

@@ -0,0 +1,49 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isPlainObject } from "../core/object";
+
+/** The settings.json namespace the installer writes capability switches into. */
+export const SETTINGS_NAMESPACE = "deepseekWebRetrieval";
+
+/** The namespace shape. Only an explicit false is meaningful, mirroring the env switches. */
+export interface ExtensionSettings {
+  readonly enableSearch?: boolean;
+  readonly enableFetch?: boolean;
+}
+
+/**
+ * Reads the namespace from Pi's settings files, project over global (Pi's own
+ * merge order — a project key overrides a global one, so a project can
+ * re-enable against a global off). Pi 1.3.0 tolerates unknown keys in
+ * settings.json — reads ignore them and Pi's own rewrites preserve them
+ * (verified against 1.3.0: `pi install` rewriting the file kept the namespace
+ * intact), so the installer can sit its keys next to Pi's own. Missing or
+ * unparseable files contribute nothing.
+ */
+export function readExtensionSettings(home: string, cwd: string): ExtensionSettings {
+  const merged: Record<string, unknown> = {
+    ...readNamespace(join(home, ".pi", "agent", "settings.json")),
+    ...readNamespace(join(cwd, ".pi", "settings.json")),
+  };
+  return {
+    ...(merged.enableSearch === false ? { enableSearch: false } : {}),
+    ...(merged.enableFetch === false ? { enableFetch: false } : {}),
+  };
+}
+
+function readNamespace(file: string): Record<string, unknown> {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    if (!isPlainObject(parsed)) return {};
+    const namespace = parsed[SETTINGS_NAMESPACE];
+    return isPlainObject(namespace) ? namespace : {};
+  } catch {
+    return {};
+  }
+}

package/src/mcp/config.ts

@@ -1,124 +0,0 @@
-import { ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV } from "../core/constants"
-import { resolvePluginOptions } from "../core/options"
-import type { PluginOptions, ResolvedOptions } from "../core/types"
-
-/** The environment an MCP server reads its key and options from. */
-export type Env = Readonly<Record<string, string | undefined>>
-
-/** Each supported option mapped onto its DEEPSEEK_* variable, grouped by value type. */
-const NUMBER_ENV = {
-  count: "DEEPSEEK_SEARCH_COUNT",
-  maxResults: "DEEPSEEK_SEARCH_MAX_RESULTS",
-  minRerank: "DEEPSEEK_SEARCH_MIN_RERANK",
-  minAuthority: "DEEPSEEK_SEARCH_MIN_AUTHORITY",
-  maxSummaryChars: "DEEPSEEK_SEARCH_MAX_SUMMARY_CHARS",
-  searchTimeoutMs: "DEEPSEEK_SEARCH_TIMEOUT_MS",
-  fetchMaxChars: "DEEPSEEK_FETCH_MAX_CHARS",
-  fetchTimeoutMs: "DEEPSEEK_FETCH_TIMEOUT_MS",
-  maxRetries: "DEEPSEEK_MAX_RETRIES",
-  retryBaseDelayMs: "DEEPSEEK_RETRY_BASE_DELAY_MS",
-} as const
-
-const TEXT_ENV = {
-  language: "DEEPSEEK_SEARCH_LANGUAGE",
-} as const
-
-const DOMAINS_ENV = {
-  blockedDomains: "DEEPSEEK_SEARCH_BLOCKED_DOMAINS",
-  includeDomains: "DEEPSEEK_SEARCH_INCLUDE_DOMAINS",
-  fetchAllowedDomains: "DEEPSEEK_FETCH_ALLOWED_DOMAINS",
-  fetchBlockedDomains: "DEEPSEEK_FETCH_BLOCKED_DOMAINS",
-} as const
-
-const FLAG_ENV = {
-  allowUnknownAuthority: "DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY",
-} as const
-
-/** Shared defaults are true; only an explicit false value disables them. */
-const FALSE_ONLY_ENV = {
-  fetchBlockPrivateHosts: "DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS",
-  searchEnabled: ENABLE_SEARCH_ENV,
-  fetchEnabled: ENABLE_FETCH_ENV,
-} as const
-
-/**
- * Maps `DEEPSEEK_*` environment variables onto the shared plugin option keys and
- * resolves them through the same pipeline as the OpenCode adapter, so defaults
- * and clamping stay identical across hosts. Invalid values are dropped and the
- * shared default applies.
- */
-export function resolveEnvOptions(env: Env = process.env): ResolvedOptions {
-  return resolvePluginOptions(pluginOptionsFromEnv(env))
-}
-
-export function pluginOptionsFromEnv(env: Env): PluginOptions {
-  const options: Record<string, unknown> = {}
-
-  putNumber(options, "count", env)
-  putNumber(options, "maxResults", env)
-  putNumber(options, "minRerank", env)
-  putNumber(options, "minAuthority", env)
-  putBoolean(options, "allowUnknownAuthority", env)
-  putDomains(options, "blockedDomains", env)
-  putDomains(options, "includeDomains", env)
-  putText(options, "language", env)
-  putNumber(options, "maxSummaryChars", env)
-  putNumber(options, "searchTimeoutMs", env)
-
-  putNumber(options, "fetchMaxChars", env)
-  putDomains(options, "fetchAllowedDomains", env)
-  putDomains(options, "fetchBlockedDomains", env)
-  putNumber(options, "fetchTimeoutMs", env)
-  putFalseOnly(options, "fetchBlockPrivateHosts", env)
-  putFalseOnly(options, "searchEnabled", env)
-  putFalseOnly(options, "fetchEnabled", env)
-
-  putNumber(options, "maxRetries", env)
-  putNumber(options, "retryBaseDelayMs", env)
-
-  return options
-}
-
-function putNumber(target: Record<string, unknown>, key: keyof typeof NUMBER_ENV, env: Env): void {
-  const value = env[NUMBER_ENV[key]]
-  if (value === undefined) return
-  const trimmed = value.trim()
-  if (!trimmed) return
-  const parsed = Number(trimmed)
-  if (Number.isFinite(parsed)) target[key] = parsed
-}
-
-function putText(target: Record<string, unknown>, key: keyof typeof TEXT_ENV, env: Env): void {
-  const value = env[TEXT_ENV[key]]
-  if (value === undefined) return
-  const trimmed = value.trim()
-  if (trimmed) target[key] = trimmed
-}
-
-function putBoolean(target: Record<string, unknown>, key: keyof typeof FLAG_ENV, env: Env): void {
-  if (isTrueValue(env[FLAG_ENV[key]])) target[key] = true
-}
-
-function putFalseOnly(target: Record<string, unknown>, key: keyof typeof FALSE_ONLY_ENV, env: Env): void {
-  if (isFalseValue(env[FALSE_ONLY_ENV[key]])) target[key] = false
-}
-
-function putDomains(target: Record<string, unknown>, key: keyof typeof DOMAINS_ENV, env: Env): void {
-  const value = env[DOMAINS_ENV[key]]
-  if (value === undefined || !value.trim()) return
-  const domains = value
-    .split(",")
-    .map((domain) => domain.trim())
-    .filter((domain) => domain.length > 0)
-  if (domains.length > 0) target[key] = domains
-}
-
-function isTrueValue(value: string | undefined): boolean {
-  const trimmed = value?.trim().toLowerCase()
-  return trimmed === "true" || trimmed === "1" || trimmed === "yes" || trimmed === "on"
-}
-
-function isFalseValue(value: string | undefined): boolean {
-  const trimmed = value?.trim().toLowerCase()
-  return trimmed === "false" || trimmed === "0" || trimmed === "no" || trimmed === "off"
-}