deepseek-web-retrieval 0.6.0 → 0.8.0

package/docs/research/result-quality-passthrough.md

@@ -0,0 +1,159 @@
+# Passing result quality fields to the model
+
+This note answers one question: through which channel can DeepSeek's per-result quality fields —
+`rerank_score` (0–3, "≥1.5 优质"), `authority` (0–4, -1 unknown, "≥3 极权威"), `site_name`
+(string|null) — reach the **model** (not the human UI) on each host at its locked version? The
+repo filters on the first two in `src/core/search.ts` (thresholds default to off); at the
+research baseline it dropped all three before returning — the adapters now pass them through
+as a text marker plus a structured mirror (item 1 below is implemented as
+`formatQualityMarker`).
+Related: [ori-question-sourcing.md](ori-question-sourcing.md) (input side),
+[search-inline-content.md](search-inline-content.md) (content volume).
+
+**Research baseline:** 2026-10-23, using the same version locks as
+[hosts.jsonc](../hosts.jsonc) (Cline 0.0.13, Codex 0.163.0, OpenCode 2.0.32, Pi 1.3.0,
+Claude Code 2.1.303, Cursor 2026.10.08, Devin 3000.11.92, GitHub Copilot 1.0.98). Claims are
+cited to primary sources: the MCP specification, the official TypeScript SDK as installed in
+this repo (`@modelcontextprotocol/server` 2.3.1 — the shipped artifact), host source at the
+exact tags or as installed in `node_modules` (the published npm packages are themselves primary
+sources), and official docs/changelogs. Prior findings in
+[mcp-compatibility.md](mcp-compatibility.md) and [control-matrix.md](control-matrix.md) are
+cited rather than re-derived; this note re-verified the load-bearing ones and extends them.
+
+## What the specification says
+
+MCP [`2025-06-18` tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)
+introduced structured output:
+
+- Unstructured content rides in `content` (text/image/audio/resource blocks); structured
+  content is "a JSON object in the `structuredContent` field."
+- Backwards compatibility is a server-side SHOULD, verbatim: *"For backwards compatibility, a
+  tool that returns structured content **SHOULD** also return the serialized JSON in a
+  TextContent block."*
+- With a declared `outputSchema`: *"Servers **MUST** provide structured results that conform to
+  this schema. Clients **SHOULD** validate structured results against this schema."*
+- Content blocks carry optional `annotations.audience` (`"user"` / `"assistant"`) — a spec-level
+  way to mark a block as model-visible or human-visible. No host in the matrix is documented to
+  honor it; treated as unpinned below.
+
+The `2024-11-05` revision (Cline's floor) has neither `structuredContent` nor `outputSchema`.
+
+## What the official TypeScript SDK enforces (v2.3.1, as shipped in this repo)
+
+The server-side validator (`@modelcontextprotocol/server` 2.3.1,
+`dist/mcp-*.mjs`, `validateToolOutput`) makes the outputSchema obligation concrete:
+
+- A tool with an `outputSchema` whose result has no `structuredContent` is **rejected**:
+  `Output validation error: Tool <name> has an output schema but no structured content was
+  provided` (JSON-RPC `InvalidParams`). Text-only results are not allowed for schema'd tools.
+- `structuredContent` is then validated against the schema; a mismatch is rejected the same way.
+- The v2 codec's SEP-2106 §4.3 auto-append (`appendTextFallbackForNonObject`) adds a
+  `JSON.stringify(structuredContent)` TextContent block **only when `structuredContent` is a
+  non-object** (primitive/array/null) and no text block exists. Object-shaped
+  `structuredContent` gets **no** automatic text mirror — the server must mirror it itself to
+  satisfy the spec's SHOULD.
+
+Consequence for this repo: the shipped server declares no `outputSchema` and emits both a text
+summary and (except for Codex, below) a mirrored `structuredContent` — that combination remains
+the spec- and SDK-safe shape. Declaring an `outputSchema` would obligate every successful call
+to return schema-conforming structured content.
+
+## Per host: what actually reaches the model
+
+| Host (lock) | Text `content` reaches model | `structuredContent` reaches model | Output caps at the lock |
+| --- | --- | --- | --- |
+| Codex 0.163.0 | Replaced when `structuredContent` present | Yes — content is **replaced** by serialized JSON | Per-tool `output_token_limit` + "standard 20% serialization allowance" ([mcp_types.rs](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/config/src/mcp_types.rs)); default value not pinned there |
+| Pi 1.3.0 (MCP path) | Yes (content-first) | Only when no content blocks | 20 KB text middle-truncate, full text saved to file; 60 s per-request ([control-matrix](control-matrix.md#pi)) |
+| Pi 1.3.0 (extension path) | Yes — **the only model channel** | **No** — event-layer only (below) | Extension tools bypass the MCP 20 KB truncation ([control-matrix](control-matrix.md#pi)) |
+| OpenCode 2.0.32 (plugin path) | Yes (content wins) | **No** — serialized `output` is a fallback only (below) | 2000 lines / 50 KiB tool-output truncation, full output retained to file for 7 days |
+| Claude Code 2.1.303 | Yes | Spec-level yes (2026-07-28 + TS SDK 2.0 runtime); client-side rendering not pinned by a primary source | 25k tokens default (`MAX_MCP_OUTPUT_TOKENS`), oversized saved to file ([control-matrix](control-matrix.md#claude-code)) |
+| Cline 0.0.13 | Yes | **No** — `2024-11-05` has no `structuredContent` | None documented |
+| Devin 3000.11.92 / Copilot 1.0.98 | Yes | Spec-level yes (both negotiate 2026-07-28); rendering not pinned | Not pinned |
+| Cursor 2026.10.08 | Yes | Revision unpinnable (docs show ≥2025-06-18 features, so the field exists); rendering not pinned | Not pinned |
+
+Codex's replacement behavior and Cline's text-only floor were established at these locks in
+[mcp-compatibility.md](mcp-compatibility.md#what-each-host-supports) and re-checked; the two
+native-adapter findings below are new.
+
+### Pi 1.3.0: the extension `structuredContent` never reaches the model
+
+From the installed `@earendil-works/pi-coding-agent` 1.3.0 (the shipped artifact):
+
+- An extension tool's `execute` returns `{ content, structuredContent?, details? }`. The
+  `structuredContent` field exists only on the extension **event** layer, documented as
+  *"Machine-readable result for tools that declare an `outputSchema`"*
+  (`dist/core/extensions/types.d.ts`, `ToolResultEventBase`) — consumers are other extensions
+  (hooks, nested tool calls), not the model.
+- The model-facing message type (`@earendil-works/pi-ai` `ToolResultMessage`,
+  `dist/types.d.ts`) carries `content` blocks, `isError`, ids — no `structuredContent`, and
+  `details` is session-record only. The Anthropic serializer sends exactly
+  `tool_use_id` + content blocks + `is_error`
+  (`dist/api/anthropic-messages.js`, `convertToolResult`).
+- So this repo's Pi adapter already does the right thing by putting the full result in the text
+  block; its `structuredContent` payload is event-layer data for machine consumers.
+
+### OpenCode 2.0.32: text `content` wins; typed `output` is a JSON-stringified fallback; `metadata` is not model-facing
+
+From the official repo at tag `v2.0.32` (github.com/anomalyco/opencode, where `@opencode/cli`
+2.0.32's npm manifest points) and the installed `@opencode/schema`/`@opencode/plugin`:
+
+- `Tool.Result` is `{ output?, content?, metadata? }` — `output` typed by an optional declared
+  output schema, `content` a string or text/file blocks, `metadata` a free record
+  (`@opencode/schema/dist/tool.d.ts`).
+- The model channel is decided by
+  [`normalizeContent(content, output)`](https://github.com/anomalyco/opencode/blob/v2.0.32/packages/core/src/tool/runtime.ts):
+  a string or non-empty `content` wins; only when `content` is absent/empty is `output`
+  serialized via `JSON.stringify` into a text block. `metadata` never enters this path (it
+  feeds `tool.execute.after` hooks and UI).
+- Every tool result then passes through `ToolOutput.truncate`:
+  **`MAX_LINES = 2000`, `MAX_BYTES = 50 KiB`** (full output retained to a `tool-output/`
+  file for 7 days) — [`packages/core/src/tool-output.ts`](https://github.com/anomalyco/opencode/blob/v2.0.32/packages/core/src/tool-output.ts).
+  These caps were not previously recorded in [control-matrix.md](control-matrix.md).
+
+## What this means for this repo
+
+1. **Text is the only channel verified to reach the model on every host.** Codex is the sole
+   host where `structuredContent` demonstrably reaches the model (as a *replacement*); on the
+   two native adapters it provably does not (Pi: event-layer only; OpenCode: fallback only).
+   Quality fields the model should reason about therefore belong **in the text** — e.g. a
+   compact per-result marker like `[rerank 2.1 · authority 3]` (plus `site_name` where present).
+   At 10 results that is a few hundred characters, negligible against every cap above.
+2. **Mirroring in `structuredContent` stays worth it** for machine consumers (Pi extension
+   events, future hosts, tests) and costs nothing: the shipped dual-emission — text plus
+   structured, with the mirror omitted for the detected `codex-mcp-client` identity — already
+   matches the spec's SHOULD and Codex's replacement. Adding the new fields to both shapes
+   changes no host behavior.
+3. **Keep `outputSchema` undeclared** on the MCP server unless the team is prepared to guarantee
+   schema-conforming `structuredContent` on every successful call (the SDK rejects otherwise).
+   The Pi adapter's extension `outputSchema` is safe as-is — Pi re-declares but does not
+   validate it, and its `structuredContent` is event data.
+4. **New cap facts for the design margin:** OpenCode plugin results truncate at 2000 lines /
+   50 KiB (new), Pi extension tools bypass the MCP 20 KB truncation (already known), Claude
+   Code 25k tokens, Codex per-tool `output_token_limit` (default unpublished). None of these
+   bind at search-result volumes; they matter if [inline content](search-inline-content.md) is
+   ever enabled.
+
+## Sources
+
+- MCP spec: [2025-06-18 tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)
+  (structured content, outputSchema MUST/SHOULD, audience annotations); revision table in
+  [mcp-compatibility.md](mcp-compatibility.md#protocol-revisions).
+- Official TypeScript SDK, **as installed** (`@modelcontextprotocol/server` 2.3.1,
+  `@modelcontextprotocol/client` 2.3.1): `dist/mcp-*.mjs` `validateToolOutput` /
+  `validateToolInput`; `dist/src-*.mjs` `appendTextFallbackForNonObject` /
+  `projectCallToolResult` (SEP-2106 §4.3).
+- Pi, **as installed** (`@earendil-works/pi-coding-agent` 1.3.0, `@earendil-works/pi-ai`):
+  `dist/core/extensions/types.d.ts` (`ToolResultEventBase.structuredContent` doc,
+  `ToolDefinition.outputSchema`), `pi-ai/dist/types.d.ts` (`ToolResultMessage`),
+  `pi-ai/dist/api/anthropic-messages.js` (`convertToolResult`, `convertMessages`).
+- OpenCode at the lock: [`v2.0.32` tool/runtime.ts (`normalizeContent`)](https://github.com/anomalyco/opencode/blob/v2.0.32/packages/core/src/tool/runtime.ts),
+  [`v2.0.32` tool-output.ts (MAX_LINES/MAX_BYTES)](https://github.com/anomalyco/opencode/blob/v2.0.32/packages/core/src/tool-output.ts),
+  [`v2.0.32` core/src/tool.ts (execute.after result shape)](https://github.com/anomalyco/opencode/blob/v2.0.32/packages/core/src/tool.ts),
+  installed `@opencode/schema/dist/tool.d.ts` and `@opencode/plugin/dist/promise/tool.d.ts`.
+- Codex: [`mcp_types.rs` at rust-v0.163.0 (`output_token_limit`, 20% serialization allowance)](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/config/src/mcp_types.rs);
+  replacement behavior per [mcp-compatibility.md](mcp-compatibility.md#what-each-host-supports).
+- Host caps and protocol facts previously verified at these locks:
+  [control-matrix.md](control-matrix.md#per-host-reference) (Pi 20 KB / 60 s, Claude Code
+  `MAX_MCP_OUTPUT_TOKENS` 25k, Cline text-only floor),
+  [mcp-compatibility.md](mcp-compatibility.md) (per-host negotiated revisions; Cursor
+  unpinnable).

package/docs/research/search-api-defaults.md

@@ -255,9 +255,25 @@ quality filtering**. What they do publish, verbatim
 - `rerank_score`: "排序分数，0～3 分，综合考虑相关性、权威性、时效性等维度，**大于等于 1.5 分为优质结果**。"
 - `authority`: "网页权威性，0～4（**-1 表示未知**），**大于等于 3 为极权威结果**。"
 - Request defaults: `count` "否 / 默认值 10 / 返回条数，1～50"; `need_content` "否 / false";
-  `localization` "否 / 空"; `ori_question` optional.
+  `ori_question` optional ("触发搜索的用户原始问题，1～128 个字符").
+- `localization` (checked 2026-10-23): documented as "用于优先返回本地化搜索结果的 IP
+  地址" — an IP address used to prefer geo-localized results, optional, default empty. The
+  docs pin nothing beyond "IP 地址"; this repo accepts exactly what `net.isIP` validates
+  (IPv4 or IPv6) and drops anything else at option resolution.
+- Query operators (checked 2026-10-23): the `query` "会原样传递给搜索服务" and supports
+  `site:` / `-site:` / `lang:` (e.g. `lang:zh,en`) plus the time filters `after:` ("将结果限制在指定日期之后发布的网页")
+  and `before:` ("将结果限制在指定日期之前发布的网页") — each taking a year or a date, with the
+  doc examples "DeepSeek after:2025 或 DeepSeek after:2025-01-01" and
+  "DeepSeek before:2026 或 DeepSeek before:2026-06-01".
 - Response sizing: `snippet` "短摘要 … 通常为 100～200 字符"; `summary` "长摘要 … 通常为 600～800 字符".
 
+Two follow-up notes examine the request parameters this section lists only as defaults:
+[search-inline-content.md](search-inline-content.md) covers `need_content: true` — what
+provably returns, what it costs, how large it can get, and where that collides with
+per-host output caps — and [ori-question-sourcing.md](ori-question-sourcing.md) covers
+`ori_question` — the per-host channels that could supply a value (the MCP and Pi adapters
+now send it; OpenCode's websearch provider path has no input channel at its lock).
+
 ## What this means for this repo's defaults
 
 Fact-by-fact alignment of the repo's client-side defaults
@@ -268,7 +284,7 @@ here; the table only lines up what the industry ships.
 | --- | --- |
 | API `count=10`, client `maxResults=10` (post-dedup cap; `5` before 2026-10-21) | API-level count defaults: Tavily 10, Exa 10, Perplexity Search API 10, Firecrawl 10, You.com 10 (per section), Brave 20. Post-filter caps are uncommon; a fixed 5 exists at Jina (`s.jina.ai` top 5, not configurable) and Perplexity's `image_search` tool (default 5). Linkup's schema example is 5 but no default is published. OpenAI and Anthropic expose no count at all |
 | `minRerank=0`, `minAuthority=0`, `allowUnknownAuthority=true` — no client-side filtering (previously `1.5`/`2`/`false`) | **No surveyed product filters search results client-side by relevance score or authority.** The only published thresholds for DeepSeek's own fields are the docs' quality labels (≥1.5 "优质", ≥3 "极权威") — labels, not filters. The closest shipped analogues are domain allow/block lists (Tavily, Exa, Perplexity, You.com, Anthropic, Brave) and You.com's `safesearch: moderate` default, which is content moderation, not authority |
-| `maxRetries=0` | Official model-API SDKs: OpenAI 2, Anthropic 2 (both languages). Search-API SDKs: firecrawl-js 3 (502 only), tavily-python 0, Linkup SDK 0 |
+| `maxRetries=2` — changed from `0` on 2026-10-23: this package runs as an agent tool, where a transient failure left un-retried falls to the model re-issuing the whole billed tool call, the failure profile of the model-API SDKs in this row (2, both languages) rather than of the split search-API SDKs; the default followed the model-SDK column | Official model-API SDKs: OpenAI 2, Anthropic 2 (both languages). Search-API SDKs: firecrawl-js 3 (502 only), tavily-python 0, Linkup SDK 0 |
 | `timeout=30s` (search and fetch, 1–120 s range, covers body read) | Search/scrape API timeouts: Firecrawl 60 s (scrape max 300 s), Tavily SDK search 60 s (cap 120 s) / extract 30 s, You.com `crawl_timeout` 10 s, Linkup SDK no timeout, Jina `x-timeout` unset by default (max 180 s). Model-API SDKs: OpenAI and Anthropic 10 minutes |
 | Fetch truncation 16,000 chars | Exa: page text **off** by default (`contents.text: false`), opt-in `maxCharacters` with no published default; DeepSeek itself: `need_content: false` by default; Anthropic `web_fetch`: token-based `max_content_tokens`, no published default (example 100000), no char/MiB figure in current docs; You.com highlights budget 8192 tokens; Firecrawl and Jina publish no truncation default |
 | Summary truncation 1,200 chars | DeepSeek's own field doc says `summary` is "通常为 600～800 字符"; no surveyed vendor ships a client-side summary cap (they return snippets/highlights sized server-side: Exa verbosity `compact`, You.com highlights budget) |

package/docs/research/search-inline-content.md

@@ -0,0 +1,244 @@
+# Search with inline content: `need_content` facts
+
+This note answers one question: if DeepSeek's Search API were called with
+`need_content: true` (today the repo hardcodes `false`), what would the response provably
+contain, what would it cost, how large could it get, and where does that collide with
+per-host output caps? It extends
+[search-api-defaults.md](search-api-defaults.md) — which surveyed factory defaults — with the
+one question that survey did not ask: which vendors ship search-with-inline-content as the
+default architecture versus opt-in, and with what per-result content budget. It records facts
+only; the closing section lines the facts up against the current two-tool design (search
+summary-only plus a separate fetch tool) without recommending for or against it.
+
+**Research baseline: 2026-10-23.** Claims are cited to primary sources only: official
+DeepSeek documentation (api-docs.deepseek.com, English and 中文 pages, plus the official FAQ
+bundle), other vendors' official documentation and SDK/API references, and OpenAI Codex
+source at the repo's locked tag. Secondhand blogs are excluded. Where no primary source pins
+a fact — most importantly the size of `content` — that is stated as such: an undocumented
+size is itself a decision-relevant fact.
+
+## What `need_content=true` provably returns
+
+From the official Search & Fetch guide, the parameter and its response field, verbatim:
+
+| Item | 中文 | English |
+| --- | --- | --- |
+| `need_content` (request) | “是否在 content 中返回网页正文，为 false 时 content 恒为空字符串。” | "Whether to return page content in content, which is always an empty string when false." |
+| `content` (search response) | “网页正文，need_content 为 false 或正文缺失时为空字符串。” | "The page content, which is empty when need_content is false or when the content is unavailable." |
+
+([指南](https://api-docs.deepseek.com/zh-cn/guides/search) ·
+[guide](https://api-docs.deepseek.com/guides/search), checked 2026-10-23.)
+
+Three facts follow, all of them absences:
+
+1. **No size bound of any kind is documented for `content`.** The same guide gives "通常"
+   sizing for the other two text fields — `snippet` "通常为 100～200 字符" ("typically 100 to
+   200 characters"), `summary` "通常为 600～800 字符" ("typically 600 to 800 characters") —
+   but has **no analogous statement** for `content`: no "通常" range, no maximum, no
+   truncation rule, no server-side character cap. An undocumented content size is the
+   single most decision-relevant fact in this note.
+2. **No format statement for search `content`.** The Fetch API's `content` field is
+   explicitly Markdown — "The fetched page content as Markdown text." /
+   “抓取后的 Markdown 正文” — but the Search API's `content` field carries no format
+   statement. Whether search-side `content` is the same Markdown rendering the Fetch
+   endpoint returns, or something else, is not documented. “正文缺失时为空字符串”
+   ("or when the content is unavailable") implies per-result content can be missing
+   independently of `need_content`, which matches the Fetch API's own empty-content failure
+   mode; no recovery behavior is specified for search.
+3. **No `need_content` × `count` interaction is documented.** The only sentence linking a
+   request parameter to result shape is about count and price (below); nothing says content
+   is returned for only the top N results, or that `count` behaves differently under
+   `need_content`.
+
+## Billing and rate limits
+
+**Billing is per successful request, and `need_content` is never mentioned in connection
+with price.** Verbatim from the guide and pricing page:
+
+- “Search 和 Fetch 按请求次数计费，不按 token 或返回结果条数计费” — Search and Fetch are
+  billed per request, **not by token or by number of results returned**
+  ([指南](https://api-docs.deepseek.com/zh-cn/guides/search)).
+- "count only controls how many results are returned and does not affect the per-request
+  price." / “count 只控制返回的结果条数，不影响单次请求的价格。” (same guide, both languages.)
+- Price: Search and Fetch are each "Per 1,000 successful requests $0.75"
+  ([pricing](https://api-docs.deepseek.com/quick_start/pricing); the 中文 pages state
+  每 1,000 次成功请求 5 元). A request is billable "only when it returns HTTP 200 and
+  produces a result" (Search must return non-empty `results`; Fetch must return page
+  content); failures, empty results, and timeouts are free.
+- Neither the guide, the pricing page, nor the official FAQ
+  (`static.deepseek.com/faq`, whose embedded question set was inspected — it contains zero
+  entries about the Search/Fetch API) mentions `need_content` as a price modifier. Under
+  the documented model, a `need_content: true` search is one request at the Search
+  per-request price; there is no token-metered billing tier for Search/Fetch to move into.
+
+One dated note on the pricing page (verbatim, EN): "when you use the DeepSeek API through
+DeepSeek Harness, Claude Code, or Codex," server-side tool calls already hit the Search and
+Fetch APIs; "These calls are currently free of charge;" — “这部分 Search/Fetch 接口调用目前未计费，
+并将于北京时间 2026 年 11 月 1 日 00:00 起按次收取调用费用” (per-request billing for those
+server-side-tool calls starts 00:00 Beijing time on 2026-11-01 — nine days after this note's
+baseline). This note concerns the repo's direct `/v1/tools/search` calls, which follow the
+per-request price above, not those chat-completions-internal tool calls.
+
+**Rate limits are per endpoint and independent; `need_content` is not mentioned.** Search
+100 QPS, Fetch 25 QPS per account; “Search 和 Fetch 分别独立限速，互不占用额度” ("traffic to
+one does not consume the other's quota"); “除了账号级限制，Fetch 还针对目标域名有 QPS 限制”
+(Fetch additionally has an unspecified per-domain QPS limit)
+([guide](https://api-docs.deepseek.com/guides/search)). A `need_content: true` call is a
+Search-endpoint call; no page documents it counting against anything but the Search quota.
+
+## Official guidance on `need_content` vs the Fetch endpoint
+
+None exists. The guide gives only the two positioning sentences — Search “按 query 搜索网页，
+返回结构化结果”, Fetch “抓取单个网页，以 Markdown 文本返回页面内容” — with no use-case,
+latency, or cost trade-off statement, in either language. (Checked 2026-10-23; also absent
+from the FAQ.)
+
+## Vendor architectures: who ships content-bearing search by default
+
+Extending [search-api-defaults.md](search-api-defaults.md) (which established the defaults)
+with the architecture reading. "Inline by default" means the caller gets page bodies in the
+search response without setting any parameter.
+
+| Vendor | Content inline by default? | Opt-in mechanism | Per-result content budget knob | Separate fetch tool? |
+| --- | --- | --- | --- | --- |
+| **Tavily** | Partial — default response carries per-result `content` of **relevance chunks**: `chunks_per_source` **3** chunks of ~500 chars (~1,500 chars/result) | Full body via `include_raw_content` (default **false**; accepts `markdown`/`text`/`true`) | Chunk count only (`chunks_per_source` 1–3, sizes `content`, **not** `raw_content`); no knob limits `raw_content` size in `/search` | Yes — `/extract` (up to 20 URLs; `extract_depth` basic/advanced; no per-URL cap; ~800-char chunks only when `query` is given) |
+| **Exa** | No — `contents.text` defaults **false** | `contents.text: true` in the **same** `POST /search` body | **`maxCharacters`** (1–1,000,000, no published default) plus `verbosity` `compact`/`standard`/`full` | Yes — `/contents` endpoint by result ID/URL |
+| **You.com** | No — “Omit `extraction` for a plain search that returns snippets only” | `extraction.full_page` (“crawls each result and returns the page content”) | **None for `full_page`** (only `crawl_timeout`); the `highlights` mode has a response-wide `total_max_tokens` budget of **8192** (1,024–8,192) | No dedicated fetch endpoint documented on `/v1/search` |
+| **Perplexity** | No — Search API results are `title`/`url`/`snippet`/`date` only | Token budgets: `max_tokens` ("Maximum total webpage content tokens to return across all search results") and **`max_tokens_per_page`** ("Maximum webpage content tokens to extract from each result page"), on both the Search API and the Agent API `web_search` tool; **no default published** for either ("the default budgets apply"); on the Search API the extracted text surfaces through `snippet` | **`max_tokens_per_page`** (min 1, max 1,000,000, no default) | Yes — Agent API "Fetch URL Content" tool ("Fetch full content from known URLs") |
+| **Anthropic** | Not caller-visible — `web_search` results carry `url`/`title`/`page_age` plus `encrypted_content` (“Encrypted content that you must pass back in multi-turn conversations”); the model reads content in its context, the caller cannot | `response_inclusion` (`"full"` default / `"excluded"`) only controls whether consumed search blocks are echoed in the response — it is not a content-size knob | **None** (dynamic filtering on `web_search_20260209+` has Claude write code to filter results before they reach context, but no caller-set budget) | Yes — `web_fetch` with token-based `max_content_tokens` (no published default) |
+| **Firecrawl** | No — search returns `title`/`description`/`url` (+ `highlights`, default true) | `scrapeOptions` (default `{}`): "Include `scrapeOptions` with `formats: [{"type": "markdown"}] to get complete markdown content for each search result" | **None** for content size (`onlyMainContent` default true trims boilerplate, not length) | Collapsed into search via `scrapeOptions`; standalone `/scrape` endpoint also exists |
+| **Jina** (`s.jina.ai`) | **Yes — the only default-content architecture surveyed**: "Reader searches the web, fetches the top 5 results, visits each URL, and applies `r.jina.ai` to it"; result count is fixed at 5, not a parameter | None needed (content is the product) | **`x-token-budget`** header, no default (parsed only when sent) — a global budget, not per-result | Same product (`r.jina.ai`) serves plain fetch |
+| **DeepSeek (subject of this note)** | No — `need_content` defaults **false** | `need_content: true` | **None documented** (see above) | Yes — Fetch API, Markdown, no documented size cap |
+
+The split, stated plainly: of the eight architectures surveyed, exactly one (Jina
+`s.jina.ai`) ships content-bearing search as the default, and it pins the result count at 5.
+Every other vendor makes inline content opt-in (Tavily `raw_content`, Exa `contents.text`,
+You.com `extraction`, Firecrawl `scrapeOptions`, Perplexity token budgets) or keeps page
+content out of the caller's hands entirely (Anthropic `encrypted_content`). Where budgets
+exist they are per-result character caps (Exa `maxCharacters`) or per-result token caps
+(Perplexity `max_tokens_per_page`); Tavily and You.com ship full-content modes with **no**
+per-result size knob at all — the two closest analogues to DeepSeek's `need_content`.
+
+Sources: [Tavily /search](https://docs.tavily.com/documentation/api-reference/endpoint/search) ·
+[Tavily /extract](https://docs.tavily.com/documentation/api-reference/endpoint/extract) ·
+[Exa /search](https://exa.ai/docs/reference/search) ·
+[You.com /v1/search](https://you.com/docs/api-reference/search/v1-search) ·
+[Perplexity /search](https://docs.perplexity.ai/api-reference/search-post) ·
+[Perplexity Agent web_search](https://docs.perplexity.ai/docs/agent-api/tools/web-search) ·
+[Anthropic web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) ·
+[Anthropic web fetch tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool) ·
+[Firecrawl /search](https://docs.firecrawl.dev/api-reference/endpoint/search) ·
+[Jina reader README](https://github.com/jina-ai/reader/blob/main/README.md) — all checked
+2026-10-23; Tavily/Exa/You.com/Jina defaults cross-checked against
+[search-api-defaults.md](search-api-defaults.md).
+
+## Volume math against host caps
+
+**Assumptions, labeled as such (not source-backed):** a typical article page body rendered
+to Markdown is ~2,000–10,000 characters (assumption; it is consistent with this repo's own
+calibration that 16,000 chars is a sensible budget for one *fetched* page, but no vendor
+publishes a typical body size); English text ≈ 1 byte and CJK ≈ 3 bytes per UTF-8 char;
+English ≈ 4 chars per token and CJK ≈ 1–1.5 chars per token (rough tokenizer conventions,
+assumptions).
+
+With `count=10` (the repo's default, and DeepSeek's) and `need_content: true`:
+
+- **Response size, order of magnitude:** 10 × 2k–10k chars of body ≈ **20k–100k chars**,
+  plus ~1k chars of metadata per result (title/url/snippet/summary/scores) → roughly
+  **30k–110k chars**, i.e. **~30–110 KB** for English pages and up to **~330 KB** if pages
+  are CJK-heavy. A single malformed huge page (a pasted log, a link farm) can exceed this
+  unboundedly — there is no documented server-side cap (the key fact above).
+- **Pi, MCP path: collides at the low end of the assumption.** Text results over **20 KB**
+  are middle-truncated (full text saved to a file) and the per-request timeout is **60 s**
+  ([control-matrix.md](control-matrix.md)). Even 10 × 2k-char bodies plus metadata (~30 KB)
+  exceeds 20 KB. Staying under 20 KB at count=10 requires ≲**1.8k chars of content per
+  result** after metadata. Caveat from the same note: the *shipped* Pi adapter is the native
+  extension, whose results bypass the MCP layer — "neither the 20 KB truncation nor the 60 s
+  request timeout applies"; the cap binds the MCP fallback path only.
+- **Claude Code: collides at the high end.** Tool output is capped at **25k tokens** by
+  default (`MAX_MCP_OUTPUT_TOKENS`), oversized text saved to a file
+  ([control-matrix.md](control-matrix.md)). 30k–110k English chars ≈ 8k–28k tokens —
+  brushing or overflowing the cap at the top of the assumed range; CJK at 1–1.5 chars/token
+  ≈ 20k–110k tokens — overflowing from the middle of the range up. Staying under 25k tokens
+  at count=10 requires ≲**2.5k tokens (~10k English chars) per result**.
+- **Codex: collides by policy, magnitude unpublished.** Codex truncates tool output by a
+  per-model, server-provided truncation policy (bytes or tokens — "Server-provided
+  truncation policy metadata for a model"), using **middle truncation**, with a 20%
+  serialization allowance added (`with_serialization_allowance` = policy × 1.2); no default
+  number is published in the repo or config reference (the only literal in source,
+  `bytes(10_000)`, is a `#[cfg(test)]` fixture). The per-tool override
+  `mcp_servers.<id>.tools.<tool>.output_token_limit` exists ("Token budget for one MCP
+  tool's output, before the standard 20% serialization allowance")
+  ([config reference](https://learn.chatgpt.com/docs/config-file/config-reference);
+  [mcp_types.rs at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/config/src/mcp_types.rs)).
+  [control-matrix.md](control-matrix.md) records Codex's 300 s MCP tool timeout — latency,
+  not size, is that host's documented ceiling.
+- **The binding constraint is Pi's 20 KB**, roughly an order of magnitude tighter than
+  Claude Code's 25k-token default: a per-result content budget in the **~1k–2k char**
+  range keeps count=10 under every published cap; reusing the repo's fetch budget (16,000
+  chars) *per search result* would reach 160k chars per response — 8× Pi's cap and ~40k
+  tokens on Claude Code.
+- **The repo's own 5 MiB `MAX_RESPONSE_BYTES` is not the binding constraint** at these
+  assumptions (10 results would need to average ~500 KB each to reach it), but note it
+  **rejects** oversized bodies with an error rather than truncating
+  ([transport.ts](../../src/core/transport.ts) `readResponseText`), and with no documented
+  server-side cap, a pathological page could trip it.
+
+## What this means for this repo
+
+Fact-by-fact alignment with the current code. No recommendation is made here; the
+maintainer decides.
+
+- **The toggle point is one hardcoded literal.** `searchWeb` posts `need_content: false`
+  ([client.ts](../../src/core/client.ts)); everything else about a content-bearing mode
+  would be new surface.
+- **Today's pipeline would silently drop the content.** `DeepSeekSearchResult`
+  ([types.ts](../../src/core/types.ts)) has no `content` field, and `processResults`
+  ([search.ts](../../src/core/search.ts)) maps `SearchResult.content` from
+  `summary ?? snippet` only — a `need_content` response's page bodies would be received and
+  discarded, unbilled-for-nothing but also unrendered.
+- **The only per-result clamp in the search path is `maxSummaryChars` (1,200)** — a
+  summary/snippet budget. `fetchMaxChars` (16,000) and `formatFetchedContent`'s
+  truncation-marker logic apply exclusively to the fetch tool path. There is **no per-result
+  page-content budget knob of any kind**; the vendor table above shows the two shapes such
+  a knob takes elsewhere (Exa's per-result `maxCharacters`, Perplexity's per-result
+  `max_tokens_per_page`).
+- **`MAX_RESPONSE_BYTES` (5 MiB) is the only existing guard a need_content response meets**,
+  and it errors rather than truncates — the one host cap it protects against is the
+  undocumented-content-size scenario at its pathological extreme.
+- **Text rendering flattens structure.** `formatSearchResults` ([format.ts](../../src/core/format.ts))
+  renders each result's `content` with newlines replaced by single spaces — sized for a
+  1,200-char summary. Multi-thousand-character Markdown bodies in the text content block
+  would lose heading/list structure; the `structuredContent` mirror preserves it as-is.
+- **The two facts that make this decision unusual:** DeepSeek documents **no size bound and
+  no per-result budget knob** for `need_content` content (unlike Exa/Perplexity, whose
+  opt-in modes ship with budget parameters), and **no vendor but Jina ships
+  content-bearing search by default** — with Jina pinning count at 5, exactly the
+  count-shrinking direction the Pi 20 KB arithmetic above pushes toward.
+
+## Sources
+
+- DeepSeek: [Search & Fetch guide (EN)](https://api-docs.deepseek.com/guides/search) ·
+  [网页搜索与抓取 (ZH)](https://api-docs.deepseek.com/zh-cn/guides/search) ·
+  [Pricing](https://api-docs.deepseek.com/quick_start/pricing) ·
+  [FAQ (static.deepseek.com/faq)](https://static.deepseek.com/faq/index.html?lang=en) —
+  question set inspected from the app bundle, 2026-10-23
+- Tavily: [search endpoint](https://docs.tavily.com/documentation/api-reference/endpoint/search) ·
+  [extract endpoint](https://docs.tavily.com/documentation/api-reference/endpoint/extract)
+- Exa: [search reference](https://exa.ai/docs/reference/search)
+- You.com: [POST /v1/search reference](https://you.com/docs/api-reference/search/v1-search)
+- Perplexity: [Search API reference](https://docs.perplexity.ai/api-reference/search-post) ·
+  [Agent API web_search tool](https://docs.perplexity.ai/docs/agent-api/tools/web-search)
+- Anthropic: [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) ·
+  [web fetch tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool)
+- Firecrawl: [search endpoint](https://docs.firecrawl.dev/api-reference/endpoint/search)
+- Jina: [reader README](https://github.com/jina-ai/reader/blob/main/README.md)
+- Codex: [config reference](https://learn.chatgpt.com/docs/config-file/config-reference) ·
+  [mcp_types.rs at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/config/src/mcp_types.rs) ·
+  [openai_models.rs at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/protocol/src/openai_models.rs) ·
+  [output truncation lib at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/utils/output-truncation/src/lib.rs)
+- Repo: [search-api-defaults.md](search-api-defaults.md) ·
+  [control-matrix.md](control-matrix.md) ·
+  [constants.ts](../../src/core/constants.ts) · [client.ts](../../src/core/client.ts) ·
+  [search.ts](../../src/core/search.ts) · [format.ts](../../src/core/format.ts) ·
+  [transport.ts](../../src/core/transport.ts)

package/examples/opencode.global.jsonc

@@ -1,8 +1,9 @@
 {
   "$schema": "https://opencode.ai/config.json",
 
-  // Global config: ~/.config/opencode/opencode.jsonc
-  // Assumes the repo is cloned to ~/.config/opencode/vendor/deepseek-web-retrieval.
+  // Global config: ~/.config/opencode/opencode.jsonc (%APPDATA%\opencode\opencode.jsonc on Windows)
+  // Assumes the repo is cloned to the vendor/ directory beside the config
+  // (~/.config/opencode/vendor/deepseek-web-retrieval; %APPDATA%\opencode\vendor\... on Windows).
   "plugins": [
     {
       "package": "./vendor/deepseek-web-retrieval",

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "deepseek-web-retrieval",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Token-efficient DeepSeek Search and Fetch for coding agents, starting with OpenCode v2.",
   "type": "module",
   "license": "MIT",
@@ -48,6 +48,7 @@
   ],
   "scripts": {
     "lint": "biome check --error-on-warnings .",
+    "clean": "bun run scripts/clean.ts",
     "lint:ci": "biome ci --error-on-warnings .",
     "lint:fix": "biome check --write --error-on-warnings .",
     "format": "biome format --write .",

package/src/core/auth.ts

@@ -1,5 +1,8 @@
 import { API_KEY_ENV } from "./constants";
 
+/** Shared missing-key guidance; every surface that needs a key prints this one message. */
+export const MISSING_API_KEY_MESSAGE = `DeepSeek API key not found. Set ${API_KEY_ENV} in the MCP server's env configuration.`;
+
 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,6 +1,6 @@
-import { FETCH_ENDPOINT, MAX_QUERY_CHARS, SEARCH_ENDPOINT } from "./constants";
+import { FETCH_ENDPOINT, MAX_ORI_QUESTION_CHARS, MAX_QUERY_CHARS, SEARCH_ENDPOINT } from "./constants";
 import { assertFetchHostPolicy } from "./domains";
-import { formatFetchedContent } from "./format";
+import { formatFetchedContent, truncate } from "./format";
 import { buildQuery, processResults } from "./search";
 import { postJson } from "./transport";
 import type {
@@ -22,6 +22,16 @@ function effectiveTimeout(configuredMs: number, perCallMs: number | undefined):
   return perCallMs === undefined ? configuredMs : Math.min(configuredMs, perCallMs);
 }
 
+/**
+ * The wire value for ori_question: absent/whitespace-only means "not
+ * provided"; longer values are clamped rather than rejected — the field is
+ * auxiliary and a hard error would punish the model for verbosity.
+ */
+function oriQuestionValue(oriQuestion: string | undefined): string | undefined {
+  const trimmed = oriQuestion?.trim();
+  return trimmed ? truncate(trimmed, MAX_ORI_QUESTION_CHARS) : undefined;
+}
+
 interface SearchResponse {
   readonly results?: unknown;
 }
@@ -41,10 +51,19 @@ export interface RequestOptions {
   readonly timeoutMs?: number;
 }
 
+export interface SearchRequest extends RequestOptions {
+  /**
+   * Per-call only — the option-resolution pipeline never populates this. The
+   * user's original question behind the search, sent as DeepSeek's optional
+   * ori_question to sharpen intent; adapters fill it from tool input.
+   */
+  readonly oriQuestion?: string;
+}
+
 export async function searchWeb(
   query: string,
   options: SearchOptions,
-  request: RequestOptions,
+  request: SearchRequest,
 ): Promise<SearchResult[]> {
   const trimmed = query.trim();
   if (!trimmed) throw new Error("DeepSeek search query must not be empty");
@@ -63,12 +82,15 @@ export async function searchWeb(
   }
 
   const timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs);
+  const oriQuestion = oriQuestionValue(request.oriQuestion);
   const payload = await postJson<SearchResponse>(
     SEARCH_ENDPOINT,
     {
       query: builtQuery,
       count: options.count,
       need_content: false,
+      ...(oriQuestion === undefined ? {} : { ori_question: oriQuestion }),
+      ...(options.localization === undefined ? {} : { localization: options.localization }),
     },
     "DeepSeek Search",
     { ...request, timeoutMs: timeout },
@@ -129,7 +151,7 @@ export async function fetchDocument(
 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: string, options: SearchOptions, request: SearchRequest) =>
       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) =>