deepseek-web-retrieval 0.4.0 → 0.5.0

package/docs/research/control-matrix.md

@@ -79,14 +79,19 @@ paths imply the available scopes; keys locked to a single scope are enumerated i
 
 - **Positioning** — VSCode-extension agent with an experimental lightweight CLI (`clite`,
   built on the Cline SDKs). Apache-2.0. MCP plus CLI/SDK custom tools; neither replaces the
-  built-in `fetch_web_content`. Current docs.cline.bot describes the newer 3.x `cline`
-  binary — the lock is 0.0.13 `clite`, and everything here is verified against that binary.
+  built-in `fetch_web_content`. `@cline/cli` is frozen at 0.0.13 (last publish 2026-05-11);
+  the next day the unscoped `cline` package superseded it (3.0.0 on 2026-05-12; 3.0.73 at
+  2026-10-21; binary renamed `clite` → `cline`), and docs.cline.bot now describes only the
+  `cline` binary (re-verified 2026-10-21). The lock stays 0.0.13 `clite` and everything
+  here is verified against that binary; adopting 3.x means re-verifying this whole row.
 - **Built-in web tools** — `fetch_web_content` (fetch a URL and analyze it with a prompt);
   no built-in web search (the binary's `web_search` strings are Bedrock provider tool
   versions). Kill switch: `"disabledTools": ["fetch_web_content"]` in
   `~/.cline/data/settings/global-settings.json` (path overridable via
   `CLINE_GLOBAL_SETTINGS_PATH`); a disabled tool is dropped from the available set.
-  `--yolo` mode also deactivates web fetch.
+  `--yolo` mode also deactivates web fetch. Current docs.cline.bot documents the SDK's
+  `toolPolicies: { enabled: false }` as the disable mechanism and no longer mentions the
+  `disabledTools` key, which still exists in the settings file (re-verified 2026-10-21).
 - **MCP registration** — `~/.cline/settings/cline_mcp_settings.json`
   (`CLINE_MCP_SETTINGS_PATH`), written by the `clite mcp` wizard in a nested form:
   `mcpServers.<name>.transport` with `type` (`stdio` | `sse` | `streamableHttp`) plus
@@ -108,11 +113,25 @@ paths imply the available scopes; keys locked to a single scope are enumerated i
   <bool>` form parses but discards the value at 0.163.0 — a silent no-op
   ([config source at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/config/src/config_toml.rs)).
 - **MCP registration** — `~/.codex/config.toml` `[mcp_servers.<name>]`: stdio
-  `command`/`args`/`env`/`env_vars`; `startup_timeout_sec` (10 s), `tool_timeout_sec`
-  (60 s); `enabled_tools`/`disabled_tools`, per-tool approval modes, and output limits.
+  `command`/`args`/`env`/`env_vars`; `startup_timeout_sec` (30 s) and `tool_timeout_sec`
+  (300 s) defaults — the `DEFAULT_STARTUP_TIMEOUT`/`DEFAULT_TOOL_TIMEOUT` constants
+  ([rmcp_client.rs at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/codex-mcp/src/rmcp_client.rs));
+  `enabled_tools`/`disabled_tools` (verbatim raw tool-name match, filtered before
+  registration so the model never sees a disabled tool; an empty `enabled_tools` allow-list
+  exposes nothing), per-tool approval modes, and output limits.
   stdio children do not inherit the parent environment (only `HOME`, `PATH`, and explicit
   `env`), so `DEEPSEEK_API_KEY` must be passed explicitly. When a tool result has
   `structuredContent`, Codex replaces the content blocks with the serialized JSON. No SSE.
+  Codex identifies itself in the initialize handshake as clientInfo name `codex-mcp-client`
+  with title `Codex`
+  ([rmcp_client.rs at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/codex-mcp/src/rmcp_client.rs)).
+  The official docs moved to learn.chatgpt.com
+  ([MCP](https://learn.chatgpt.com/docs/extend/mcp),
+  [config reference](https://learn.chatgpt.com/docs/config-file/config-reference); the old
+  developers.openai.com URLs 308-redirect there) and now document every key above — but
+  state 10 s/60 s timeout defaults, which describe an older release line; the 30 s/300 s
+  constants above are the facts at the locked 0.163.0 (docs discrepancy re-verified
+  2026-10-21).
 - **Rules** — `~/.codex/AGENTS.md` (with `AGENTS.override.md` preferred) at user scope;
   every `AGENTS.md` from the project root down to the cwd, concatenated root→cwd.
   Extensible via `project_doc_fallback_filenames` and `developer_instructions`
@@ -136,12 +155,25 @@ paths imply the available scopes; keys locked to a single scope are enumerated i
 
 ### Pi
 
-- **Positioning** — minimal, fully customizable agent (earendil-works). MIT. MCP server
-  plus a TypeScript extension API. See [Pi](../agents/pi.md).
+- **Positioning** — minimal, fully customizable agent (earendil-works). MIT. A TypeScript
+  extension API plus MCP. See [Pi](../agents/pi.md); the shipped adapter is the native
+  extension (`src/pi/`), with the MCP server as the fallback path.
 - **Built-in web tools** — none at 1.3.0. The built-in set is exactly `bash, edit, find,
   grep, ls, powershell, read, write` (default-active: `read, bash, edit, write`); web
   search/fetch arrive via MCP or extensions
   ([tools index at v1.3.0](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/src/core/tools/index.ts)).
+- **Extension registration** — `packages` in settings.json (`~/.pi/agent/settings.json` or
+  `.pi/settings.json`): source strings (`npm:<pkg>`, `git:…`, local paths) resolved at
+  session start; `pi install <source>` appends them, and a package's `pi` manifest field
+  names its entry files (loaded via jiti, TypeScript directly). Extension tools default to
+  `exposure: "direct"` — no codemode trap — and run in-process: the key is read from
+  `process.env` (no forwarding), and results bypass the MCP layer entirely, so neither the
+  20 KB truncation nor the 60 s request timeout applies. There is no per-extension options
+  channel: the runtime config surface is the `DEEPSEEK_*` environment (the same pipeline as
+  the MCP server) plus a `deepseekWebRetrieval` settings namespace the installer writes for
+  the off tier — Pi preserves unknown settings keys on read and on its own rewrites
+  (`pi install`), verified at 1.3.0. Action methods such as `getSettings()` cannot be
+  called during extension loading, so the adapter reads the settings files itself.
 - **MCP registration** — `~/.pi/agent/mcp.json` or `.pi/mcp.json`: stdio
   `command`/`args`/`env`/`cwd`, HTTP `url`/`headers`, plus `timeout`, `enabled`,
   `exposure`. MCP tools are hidden from the model by default
@@ -237,7 +269,9 @@ paths imply the available scopes; keys locked to a single scope are enumerated i
 - **Rules** — `~/.copilot/copilot-instructions.md` (user),
   `.github/copilot-instructions.md` (repo) and `.github/instructions/**/*.instructions.md`
   (path-scoped via `applyTo` globs); `AGENTS.md`/`CLAUDE.md` discovery (changelog-dated
-  ≤1.0.86; `GEMINI.md` could not be dated to the lock);
+  ≤1.0.86); `GEMINI.md` is never named in the changelog but the official docs have listed
+  it since the page's creation on 2026-02-16 (docs-history-dated, 0.0.41x era — comfortably
+  ≤1.0.98; re-verified 2026-10-21); `.claude/rules` support is changelog-dated 1.0.89;
   `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` adds directories
   ([custom instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions)).
 
@@ -250,8 +284,9 @@ paths imply the available scopes; keys locked to a single scope are enumerated i
 - **Replacement is exclusive to native extension points** — only OpenCode. Exclusion is
   the general forced path on MCP hosts. The two structural limits: OpenCode search has no
   middle tier, and Cursor search cannot be forced at all.
-- **Version drift to re-verify on the next baseline pass:** Cline's docs describe the 3.x
-  `cline` binary while the lock is 0.0.13 `clite`; Codex's config docs have moved and
-  describe a newer release; Copilot's `GEMINI.md` support could not be changelog-dated to
-  ≤1.0.98. Protocol-revision evidence for every host lives in
-  [mcp-compatibility.md](mcp-compatibility.md).
+- **Version drift to re-verify on the next baseline pass:** Cline's `cline` 3.x package
+  (3.0.73 at 2026-10-21) has superseded the locked 0.0.13 `clite`; adopting it means
+  re-verifying that host's whole row (the documented kill switch already differs: SDK
+  `toolPolicies`). Codex's docs location and Copilot's `GEMINI.md` dating were re-verified
+  2026-10-21 and are settled in their sections above. Protocol-revision evidence for every
+  host lives in [mcp-compatibility.md](mcp-compatibility.md).

package/docs/research/mcp-compatibility.md

@@ -107,12 +107,17 @@ differences:
    capability; do not rely on resources, prompts, sampling, elicitation, or roots — the
    hosts' client capabilities are inconsistent (Codex has elicitation only; Pi serves
    roots). Always return readable
-   text in `content` blocks, and mirror the same data in `structuredContent` for
-   `2025-06-18`+ clients — the spec's own backwards-compat SHOULD. This split matters in
-   practice: Codex *replaces* content with `structuredContent` when present; Cline reads
+   text in `content` blocks, and mirror the same data in `structuredContent` — the
+   spec's own backwards-compat SHOULD — except for clients that would replace the text
+   with its serialized JSON: Codex *replaces* content with `structuredContent` when
+   present, so the shipped server detects its `codex-mcp-client` identity (the
+   initialize `clientInfo` on handshake-era connections, the per-request envelope on
+   `2026-07-28`) and omits the mirror for it. Cline reads
    text content only; Pi is
    content-first, falling back to `structuredContent` only when a result has no content
-   blocks (verified in `tools.ts` at v1.3.0).
+   blocks (verified in `tools.ts` at v1.3.0). No `outputSchema` is declared: the SDK
+   rejects text-only results for a tool with a declared schema, and no host in the
+   matrix validates the schema anyway.
 2. **stdio is the universal transport.** Every host in the matrix launches stdio servers
    with the same conceptual JSON (`mcpServers` → `command`/`args`/`env`), differing only in
    file location and cosmetic field names. stdio needs no OAuth and no URL config, and the

package/examples/pi.settings.jsonc

@@ -0,0 +1,17 @@
+{
+  // Pi extension config: ~/.pi/agent/settings.json (user) or .pi/settings.json (project).
+  // "packages" sources resolve at session start; the first launch fetches
+  // npm:deepseek-web-retrieval from the registry (pi update --extensions refreshes it).
+  // The key never enters this file: the extension reads DEEPSEEK_API_KEY from the
+  // environment of the Pi process itself.
+  "packages": [
+    "npm:deepseek-web-retrieval"
+  ],
+  // Optional: the off switches the installer writes; they outrank the
+  // DEEPSEEK_ENABLE_* environment variables. Pi preserves unknown keys like
+  // this namespace on read and on its own rewrites.
+  "deepseekWebRetrieval": {
+    // "enableSearch": false,
+    // "enableFetch": false
+  }
+}

package/index.ts

@@ -1,2 +1,2 @@
-export { default } from "./src/opencode/plugin"
-export * from "./src/core/index"
+export * from "./src/core/index";
+export { default } from "./src/opencode/plugin";

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "deepseek-web-retrieval",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Token-efficient DeepSeek Search and Fetch for coding agents, starting with OpenCode v2.",
   "type": "module",
   "license": "MIT",
@@ -14,6 +14,8 @@
   "keywords": [
     "opencode",
     "opencode-plugin",
+    "pi",
+    "pi-extension",
     "deepseek",
     "websearch",
     "webfetch",
@@ -23,7 +25,13 @@
   "exports": {
     ".": "./index.ts",
     "./core": "./src/core/index.ts",
-    "./mcp": "./src/mcp/server.ts"
+    "./mcp": "./src/mcp/server.ts",
+    "./pi": "./src/pi/extension.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./src/pi/extension.ts"
+    ]
   },
   "bin": {
     "deepseek-web-retrieval": "dist/cli.js"
@@ -39,19 +47,42 @@
     "examples"
   ],
   "scripts": {
+    "lint": "biome check --error-on-warnings .",
+    "lint:ci": "biome ci --error-on-warnings .",
+    "lint:fix": "biome check --write --error-on-warnings .",
+    "format": "biome format --write .",
     "typecheck": "tsc --noEmit",
     "build": "bun build src/mcp/cli.ts --target=node --format=esm --outdir=dist --external @modelcontextprotocol/server --external @modelcontextprotocol/server/stdio --external zod --external zod/v4",
-    "prepublishOnly": "bun run typecheck && bun run build",
+    "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",
+    "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",
     "test:coverage": "bun test --coverage",
-    "check": "bun run typecheck && bun run docs:matrix --check && bun run build && bun test"
+    "check": "bun run lint && bun run typecheck && bun run docs:matrix --check && bun run build && bun test"
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "^1.3.0",
+    "@earendil-works/pi-coding-agent": "^1.3.0",
     "@opencode/plugin": "^2.0.32"
   },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@opencode/plugin": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "@earendil-works/pi-ai": "1.3.0",
+    "@earendil-works/pi-coding-agent": "1.3.0",
     "@modelcontextprotocol/client": "^2.3.1",
     "@opencode/plugin": "2.0.32",
     "@types/bun": "1.4.0",

package/src/core/auth.ts

@@ -1,8 +1,6 @@
-import { API_KEY_ENV } from "./constants"
+import { API_KEY_ENV } from "./constants";
 
-export function apiKeyFromEnv(
-  env: Readonly<Record<string, string | undefined>> = process.env,
-): string | undefined {
-  const key = env[API_KEY_ENV]?.trim()
-  return key ? key : undefined
+export function apiKeyFromEnv(env: Readonly<Record<string, string | undefined>> = process.env): string | undefined {
+  const key = env[API_KEY_ENV]?.trim();
+  return key ? key : undefined;
 }

package/src/core/client.ts

@@ -1,9 +1,8 @@
-import { FETCH_ENDPOINT, MAX_QUERY_CHARS, SEARCH_ENDPOINT } from "./constants"
-import { assertFetchHostPolicy } from "./domains"
-import { formatFetchedContent } from "./format"
-import { buildQuery, processResults } from "./search"
-import { postJson } from "./transport"
-import { parseFetchUrl } from "./url"
+import { FETCH_ENDPOINT, MAX_QUERY_CHARS, SEARCH_ENDPOINT } from "./constants";
+import { assertFetchHostPolicy } from "./domains";
+import { formatFetchedContent } from "./format";
+import { buildQuery, processResults } from "./search";
+import { postJson } from "./transport";
 import type {
   DeepSeekSearchResult,
   FetchedDocument,
@@ -13,30 +12,33 @@ import type {
   RetryOptions,
   SearchOptions,
   SearchResult,
-} from "./types"
+} from "./types";
+import { parseFetchUrl } from "./url";
 
-export { DeepSeekApiError } from "./transport"
+export { DeepSeekApiError } from "./transport";
 
 /** The shorter of the configured and per-call timeout always wins. */
 function effectiveTimeout(configuredMs: number, perCallMs: number | undefined): number {
-  return perCallMs === undefined ? configuredMs : Math.min(configuredMs, perCallMs)
+  return perCallMs === undefined ? configuredMs : Math.min(configuredMs, perCallMs);
 }
 
 interface SearchResponse {
-  readonly results?: unknown
+  readonly results?: unknown;
 }
 
 interface FetchResponse {
-  readonly title?: unknown
-  readonly content?: unknown
+  readonly title?: unknown;
+  readonly content?: unknown;
 }
 
 export interface RequestOptions {
-  readonly signal: AbortSignal
-  readonly auth: RequestAuth
-  readonly retry: RetryOptions
+  /** Optional per-request HTTP dependency; factories bind this once for an adapter. */
+  readonly fetchImpl?: typeof fetch;
+  readonly signal: AbortSignal;
+  readonly auth: RequestAuth;
+  readonly retry: RetryOptions;
   /** Per-call cap in milliseconds; the shorter of this and the configured timeout wins. */
-  readonly timeoutMs?: number
+  readonly timeoutMs?: number;
 }
 
 export async function searchWeb(
@@ -44,23 +46,23 @@ export async function searchWeb(
   options: SearchOptions,
   request: RequestOptions,
 ): Promise<SearchResult[]> {
-  const trimmed = query.trim()
-  if (!trimmed) throw new Error("DeepSeek search query must not be empty")
+  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`)
+    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
+  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 timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs)
+  const timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs);
   const payload = await postJson<SearchResponse>(
     SEARCH_ENDPOINT,
     {
@@ -69,43 +71,38 @@ export async function searchWeb(
       need_content: false,
     },
     "DeepSeek Search",
-    { signal: request.signal, auth: request.auth, retry: request.retry, timeoutMs: timeout },
-  )
+    { ...request, timeoutMs: timeout },
+  );
 
   if (!Array.isArray(payload.results)) {
-    throw new Error("DeepSeek Search returned a response without a results array")
+    throw new Error("DeepSeek Search returned a response without a results array");
   }
-  return processResults(payload.results as DeepSeekSearchResult[], options)
+  return processResults(payload.results as DeepSeekSearchResult[], options);
 }
 
-export async function fetchPage(
-  url: URL,
-  options: FetchOptions,
-  request: RequestOptions,
-): Promise<FetchedPage> {
-  // Enforced here so direct core consumers cannot bypass the policy. Adapters
-  // may also pre-check to reject before a permission prompt.
-  assertFetchHostPolicy(url, options)
-  const timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs)
-  const payload = await postJson<FetchResponse>(
-    FETCH_ENDPOINT,
-    { url: url.href },
-    "DeepSeek Fetch",
-    { signal: request.signal, auth: request.auth, retry: request.retry, timeoutMs: timeout },
-  )
-  const title = typeof payload.title === "string" ? payload.title.trim() : ""
-  const content = typeof payload.content === "string" ? payload.content : ""
+export async function fetchPage(url: URL, options: FetchOptions, request: RequestOptions): Promise<FetchedPage> {
+  // A URL object is parsed, not necessarily safe: direct core callers must pass
+  // the same protocol, credentials, length and host checks as string callers.
+  const target = parseFetchUrl(url.href);
+  assertFetchHostPolicy(target, options);
+  const timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs);
+  const payload = await postJson<FetchResponse>(FETCH_ENDPOINT, { url: target.href }, "DeepSeek Fetch", {
+    ...request,
+    timeoutMs: timeout,
+  });
+  const title = typeof payload.title === "string" ? payload.title.trim() : "";
+  const content = typeof payload.content === "string" ? payload.content : "";
   if (!content.trim()) {
-    throw new Error("DeepSeek Fetch returned no page content (the page may be empty or unavailable)")
+    throw new Error("DeepSeek Fetch returned no page content (the page may be empty or unavailable)");
   }
-  return { url: url.href, title, content }
+  return { url: target.href, title, content };
 }
 
 /** Parses the URL and enforces the host policy in one call, returning the fetch target. */
 export function inspectFetchTarget(url: string, options: FetchOptions): URL {
-  const target = parseFetchUrl(url)
-  assertFetchHostPolicy(target, options)
-  return target
+  const target = parseFetchUrl(url);
+  assertFetchHostPolicy(target, options);
+  return target;
 }
 
 /**
@@ -117,13 +114,28 @@ export async function fetchDocument(
   options: FetchOptions,
   request: RequestOptions,
 ): Promise<FetchedDocument> {
-  if (typeof url !== "string" && !(url instanceof URL)) throw new Error('"url" must be a string or URL')
-  const page = await fetchPage(url instanceof URL ? url : parseFetchUrl(url), options, request)
-  const formatted = formatFetchedContent(page.title, page.content, options.maxChars)
+  if (typeof url !== "string" && !(url instanceof URL)) throw new Error('"url" must be a string or URL');
+  const page = await fetchPage(url instanceof URL ? url : parseFetchUrl(url), options, request);
+  const formatted = formatFetchedContent(page.title, page.content, options.maxChars);
   return {
     url: page.url,
     title: page.title,
     content: formatted.content,
     truncated: formatted.truncated,
-  }
+  };
 }
+
+/** One client per adapter/test; transport overrides never mutate process globals. */
+export function createRetrievalClient(dependencies: { readonly fetchImpl?: typeof fetch } = {}) {
+  const bind = (request: RequestOptions): RequestOptions => ({ ...request, ...dependencies });
+  return {
+    searchWeb: (query: string, options: SearchOptions, request: RequestOptions) =>
+      searchWeb(query, options, bind(request)),
+    fetchPage: (url: URL, options: FetchOptions, request: RequestOptions) => fetchPage(url, options, bind(request)),
+    fetchDocument: (url: string | URL, options: FetchOptions, request: RequestOptions) =>
+      fetchDocument(url, options, bind(request)),
+  };
+}
+
+export type RetrievalClient = ReturnType<typeof createRetrievalClient>;
+export const retrievalClient = createRetrievalClient();

package/src/core/constants.ts

@@ -1,5 +1,5 @@
-export const SEARCH_ENDPOINT = "https://api.deepseek.com/v1/tools/search"
-export const FETCH_ENDPOINT = "https://api.deepseek.com/v1/tools/fetch"
+export const SEARCH_ENDPOINT = "https://api.deepseek.com/v1/tools/search";
+export const FETCH_ENDPOINT = "https://api.deepseek.com/v1/tools/fetch";
 
 /**
  * Search defaults are benchmarked against surveyed AI-native search APIs and
@@ -7,30 +7,30 @@ export const FETCH_ENDPOINT = "https://api.deepseek.com/v1/tools/fetch"
  * Result caps cluster at 10 across vendors, and no surveyed vendor filters
  * results client-side by score or authority — thresholds stay opt-in.
  */
-export const DEFAULT_SEARCH_COUNT = 10
-export const DEFAULT_MAX_RESULTS = 10
-export const DEFAULT_MIN_RERANK = 0
-export const DEFAULT_MIN_AUTHORITY = 0
-export const DEFAULT_MAX_SUMMARY_CHARS = 1200
+export const DEFAULT_SEARCH_COUNT = 10;
+export const DEFAULT_MAX_RESULTS = 10;
+export const DEFAULT_MIN_RERANK = 0;
+export const DEFAULT_MIN_AUTHORITY = 0;
+export const DEFAULT_MAX_SUMMARY_CHARS = 1200;
 
-export const DEFAULT_FETCH_MAX_CHARS = 16000
-export const DEFAULT_TIMEOUT_MS = 30000
-export const MIN_TIMEOUT_MS = 1000
-export const MAX_TIMEOUT_MS = 120000
+export const DEFAULT_FETCH_MAX_CHARS = 16000;
+export const DEFAULT_TIMEOUT_MS = 30000;
+export const MIN_TIMEOUT_MS = 1000;
+export const MAX_TIMEOUT_MS = 120000;
 
-export const MAX_QUERY_CHARS = 128
-export const MAX_URL_CHARS = 8192
-export const MAX_ERROR_BODY_CHARS = 2000
-export const MAX_RESPONSE_BYTES = 5 * 1024 * 1024
-export const FETCH_TRUNCATION_MARKER = "\n\n[content truncated]"
+export const MAX_QUERY_CHARS = 128;
+export const MAX_URL_CHARS = 8192;
+export const MAX_ERROR_BODY_CHARS = 2000;
+export const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+export const FETCH_TRUNCATION_MARKER = "\n\n[content truncated]";
 
-export const DEFAULT_API_KEY_SOURCE = "auto"
-export const DEFAULT_MAX_RETRIES = 0
-export const MAX_RETRIES = 5
-export const DEFAULT_RETRY_BASE_DELAY_MS = 250
-export const MAX_RETRY_DELAY_MS = 10000
+export const DEFAULT_API_KEY_SOURCE = "auto";
+export const DEFAULT_MAX_RETRIES = 0;
+export const MAX_RETRIES = 5;
+export const DEFAULT_RETRY_BASE_DELAY_MS = 250;
+export const MAX_RETRY_DELAY_MS = 10000;
 
 /** The single source for every DEEPSEEK_* environment variable name. */
-export const API_KEY_ENV = "DEEPSEEK_API_KEY"
-export const ENABLE_SEARCH_ENV = "DEEPSEEK_ENABLE_SEARCH"
-export const ENABLE_FETCH_ENV = "DEEPSEEK_ENABLE_FETCH"
+export const API_KEY_ENV = "DEEPSEEK_API_KEY";
+export const ENABLE_SEARCH_ENV = "DEEPSEEK_ENABLE_SEARCH";
+export const ENABLE_FETCH_ENV = "DEEPSEEK_ENABLE_FETCH";

package/src/core/descriptions.ts

@@ -4,16 +4,40 @@
  */
 
 export const FETCH_SERVICE_LIMITS =
-  "DeepSeek does not render JavaScript and cannot reach private networks; PDFs, images, and other binary files are unsupported."
+  "DeepSeek does not render JavaScript and cannot reach private networks; PDFs, images, and other binary files are unsupported.";
 
-export const FETCH_OUTPUT_TRUNCATED = "Output is truncated to the configured size."
+export const FETCH_OUTPUT_TRUNCATED = "Output is truncated to the configured size.";
 
-export const FETCH_MARKDOWN_ONLY = 'Only format "markdown" is supported.'
+export const FETCH_MARKDOWN_ONLY = 'Only format "markdown" is supported.';
 
 export const SEARCH_RANKED_FILTERED =
-  "Results are ranked by relevance and source authority, deduplicated by URL, and capped at the configured maximum."
+  "Results are ranked by relevance and source authority, deduplicated by URL, and capped at the configured maximum.";
 
-export const SEARCH_EMPTY_IS_NORMAL = "An empty result list is normal, not an error."
+export const SEARCH_EMPTY_IS_NORMAL = "An empty result list is normal, not an error.";
 
 export const SEARCH_QUERY_OPERATORS =
-  "Use site:/-site: operators in the query to include or exclude domains; the full query must stay within 128 characters."
+  "Use site:/-site: operators in the query to include or exclude domains; the full query must stay within 128 characters.";
+
+/**
+ * The full tool descriptions, composed from the fact fragments. Every host
+ * adapter registers its tools with these verbatim — the MCP server and the Pi
+ * extension must never drift on what a tool does.
+ */
+export const 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.";
+
+export const FETCH_TOOL_DESCRIPTION =
+  "Fetch one web page as clean Markdown through DeepSeek's Fetch API. " +
+  `${FETCH_SERVICE_LIMITS} ` +
+  `${FETCH_OUTPUT_TRUNCATED}`;
+
+/** Parameter descriptions shared by every adapter's input schema for the two tools. */
+export const SEARCH_QUERY_PARAMETER =
+  "Search query, 128 characters or fewer including operators (site:, -site:, quoted phrases, lang:).";
+
+export const FETCH_URL_PARAMETER = "Absolute http:// or https:// URL to fetch. Credentials are rejected.";