deepseek-web-retrieval 0.9.0 → 0.10.0

package/docs/research/control-matrix.md

@@ -113,30 +113,31 @@ scopes; keys locked to a single scope are enumerated in the
   `web_search = "disabled"` in `~/.codex/config.toml`. Trap: the `[tools] web_search =
   <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` (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: MCP tool output can be
-  capped per tool via `output_token_limit` ("Token budget for one MCP tool's output,
-  before the standard 20% serialization allowance"; the default cap is not published
-  there)
-  ([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)).
-  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).
+- **MCP registration** — `~/.codex/config.toml` `[mcp_servers.<name>]`:
+  - **Entry keys:** stdio `command`/`args`/`env`/`env_vars`; per-tool approval modes.
+  - **Timeouts:** `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)).
+  - **Tool filtering:** `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.
+  - **Output limits:** MCP tool output can be capped per tool via `output_token_limit`
+    ("Token budget for one MCP tool's output, before the standard 20% serialization
+    allowance"; the default cap is not published there)
+    ([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)).
+  - **Environment:** stdio children do not inherit the parent environment (only `HOME`,
+    `PATH`, and explicit `env`), so `DEEPSEEK_API_KEY` must be passed explicitly.
+  - **Result shape and identity:** 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)).
+  - **Docs drift:** 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`
@@ -184,8 +185,10 @@ scopes; keys locked to a single scope are enumerated in the
   channel: the runtime config surface is the `DEEPSEEK_*` environment (the same pipeline as
   the MCP server), the shared config file
   (`~/.config/deepseek-web-retrieval/config.json`, layered under the environment), plus a
-  `deepseekWebRetrieval` settings namespace the installer writes for
-  the off tier — Pi preserves unknown settings keys on read and on its own rewrites
+  `deepseekWebRetrieval` settings namespace the installer writes for the `off` tier (a
+  capability switched off — the [tier-to-artifact
+  mapping](../design/installer-design.md#tier-to-artifact-mapping) defines it) — 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
@@ -320,11 +323,13 @@ scopes; keys locked to a single scope are enumerated in the
   `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).
-- **Claude Code forward-compat anchors (checked at the 2.1.303 lock):** the headless docs
-  pre-announce `--bare` becoming the default for `-p`, and bare mode never reads
-  `.mcp.json` — the billed e2e scenario and the project-scope install story both need
-  re-checking when that lands. `${VAR}` expansion in the `env` block of a user-scope
-  `~/.claude.json` entry is supported but only indirectly documented (the docs spell out
-  `.mcp.json` and `command`/`args`; the e2e's `hasCompletedOnboarding` flag and the
-  redundant `enableAllProjectMcpServers` belt-and-suspenders are undocumented), so a
-  baseline bump should re-verify all three against the then-current docs.
+- **Claude Code forward-compat anchors (checked at the 2.1.303 lock)** — three facts a
+  baseline bump should re-verify against the then-current docs:
+  1. The headless docs pre-announce `--bare` becoming the default for `-p`, and bare mode
+     never reads `.mcp.json` — the billed `claude-code` e2e scenario in this repo's test
+     suite and the project-scope install story both need re-checking when that lands.
+  2. `${VAR}` expansion in the `env` block of a user-scope `~/.claude.json` entry is
+     supported but only indirectly documented (the docs spell out `.mcp.json` and
+     `command`/`args`).
+  3. The same e2e scenario's `hasCompletedOnboarding` flag and the redundant
+     `enableAllProjectMcpServers` belt-and-suspenders are undocumented.

package/docs/research/mcp-compatibility.md

@@ -127,7 +127,9 @@ differences:
    spec says clients SHOULD support it whenever possible. Legacy SSE is never required —
    Codex and Pi reject it anyway.
 3. **Build on the official SDK v2 dual-era serving.** One build then serves the full range:
-   the `2024-11-05` floor set by Cline (v2 legacy support spans `2024-10-07`–`2025-11-25`)
+   the `2024-11-05` floor set by Cline (v2 legacy support spans `2024-10-07`–`2025-11-25`;
+   `2024-10-07` is the pre-1.0 draft version string the SDK accepts for legacy
+   compatibility — it predates the spec's initial `2024-11-05` revision)
    up to the `2026-07-28` negotiators (Claude Code 2.1.274+, Devin 3000.11.92, Copilot CLI
    1.0.81+). A v1.x-built server still works today — modern clients fall back to the legacy
    handshake — but it can never offer the stateless era; v2 serves both from one entry

package/docs/research/ori-question-sourcing.md

@@ -54,7 +54,7 @@ MCP never carries conversation context to a server. The facts, per revision:
   human-reviewed
   ([sampling](https://modelcontextprotocol.io/specification/2025-11-25/client/sampling)). A server
   could only ask a model to *guess* intent — not obtain the user's question.
-- **Elicititation is interactive, not derivation.** `elicitation/create` asks the user a form/choice
+- **Elicitation is interactive, not derivation.** `elicitation/create` asks the user a form/choice
   question and waits ([2025-06-18+](https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation));
   it requires client capability (only Codex in this matrix has it, per
   [mcp-compatibility.md](mcp-compatibility.md)) and an explicit round trip.
@@ -184,21 +184,11 @@ the declared schema; raw JSON Schema forwarded verbatim) and B feasible
 (`ctx.session.context`). Websearch provider path (the search replacement this repo ships): neither
 — the input schema is host-fixed to `query`, and the provider context has no session handle.**
 
-### Cline 0.0.13
-
-Closed source; the platform binary
-([@cline/cli-linux-x64 0.0.13](https://registry.npmjs.org/@cline/cli-linux-x64/0.0.13), ~119 MB)
-yielded the protocol facts already recorded — custom client negotiating `2024-11-05`,
-text-content-only results ([mcp-compatibility.md](mcp-compatibility.md)). No primary source
-documents whether the client validates tool arguments against `inputSchema` or mangles schemas;
-strings cannot prove a runtime behavior either way, so this is **undeterminable at the lock**. The
-2024-11-05 revision itself puts no validation obligation on clients and defines `arguments` as a
-free-form object, so there is no protocol-level obstacle to channel A — merely no evidence for or
-against host behavior. Channel B: none (MCP only, `paths` in hosts.jsonc).
-
 ## Proprietary hosts
 
-No proprietary host documents a context channel; the question is whether anything documents
+Closed-source hosts, from binary analysis (Cline) and official docs/changelogs (the
+rest). No proprietary host documents a context
+channel; the question is whether anything documents
 input-schema handling that would break an optional parameter.
 
 - **Claude Code 2.1.303.** The [MCP docs](https://code.claude.com/docs/en/mcp) say nothing about
@@ -212,6 +202,16 @@ input-schema handling that would break an optional parameter.
   preventing calling MCP tools that have nested references in their input schemas". Together these
   show the server's `inputSchema` is what the model provider sees and that arguments follow it;
   no host-side validation is ever mentioned. **A feasible by this evidence; B none.**
+- **Cline 0.0.13.** Closed source; the platform binary
+  ([@cline/cli-linux-x64 0.0.13](https://registry.npmjs.org/@cline/cli-linux-x64/0.0.13), ~119 MB)
+  yielded the protocol facts already recorded — custom client negotiating `2024-11-05`,
+  text-content-only results ([mcp-compatibility.md](mcp-compatibility.md)). No primary
+  source documents whether the client validates tool arguments against `inputSchema` or
+  mangles schemas; strings cannot prove a runtime behavior either way, so this is
+  **undeterminable at the lock**. The 2024-11-05 revision itself puts no validation
+  obligation on clients and defines `arguments` as a free-form object, so there is no
+  protocol-level obstacle to channel A — merely no evidence for or against host behavior.
+  Channel B: none (MCP only, `paths` in hosts.jsonc).
 - **Cursor 2026.10.08.** The [MCP docs](https://cursor.com/docs/mcp) describe tools only as
   "Functions for the AI model to execute" and say nothing about input schemas, validation, or
   context — and the protocol revision itself is unpinnable from primary sources
@@ -293,7 +293,7 @@ negotiated revision in the matrix.
   [2025-11-25 tasks (experimental)](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks)
 - [2026-07-28 overview (`_meta`, statelessness)](https://modelcontextprotocol.io/specification/2026-07-28/basic/index)
 
-### Open-source hosts
+### Open-source host sources
 
 - Codex: [rust-v0.163.0 tag](https://github.com/openai/codex/tree/rust-v0.163.0) —
   [mcp_tool_call.rs (argument parsing, no validation)](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/core/src/mcp_tool_call.rs),
@@ -324,15 +324,15 @@ negotiated revision in the matrix.
   (Tool.Context, WebSearch.ProviderInput),
   [@opencode/client](https://registry.npmjs.org/@opencode/client/2.0.32)
   (session.context → SessionMessageInfo[], SessionMessageUser.text)
-- Cline: [@cline/cli-linux-x64 0.0.13](https://registry.npmjs.org/@cline/cli-linux-x64/0.0.13)
-  (manifest only; behavior undeterminable) and prior binary analysis recorded in
-  [mcp-compatibility.md](mcp-compatibility.md)
 
-### Proprietary hosts
+### Proprietary host sources
 
 - Claude Code: [changelog](https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md)
   (entries 2.0.50, 2.1.30, 2.1.246, 2.1.300 — all ≤ the 2.1.303 lock),
   [MCP docs](https://code.claude.com/docs/en/mcp)
+- Cline: [@cline/cli-linux-x64 0.0.13](https://registry.npmjs.org/@cline/cli-linux-x64/0.0.13)
+  (manifest only; behavior undeterminable) and prior binary analysis recorded in
+  [mcp-compatibility.md](mcp-compatibility.md)
 - Cursor: [MCP docs](https://cursor.com/docs/mcp) (silent on the question)
 - Devin: [MCP overview](https://docs.devin.ai/cli/extensibility/mcp/overview),
   [changelog](https://docs.devin.ai/cli/changelog) (silent on the question)

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

@@ -5,8 +5,8 @@ This note answers one question: through which channel can DeepSeek's per-result
 (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`).
+as a text marker plus a structured mirror (the text marker of *What this means for this
+repo*, item 1, 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).
 
@@ -47,7 +47,8 @@ The server-side validator (`@modelcontextprotocol/server` 2.3.1,
   `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
+- The v2 codec's SEP-2106 §4.3 auto-append (so named in the installed SDK's own source;
+  implemented as `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
@@ -108,7 +109,8 @@ From the official repo at tag `v2.0.32` (github.com/anomalyco/opencode, where `@
 - 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).
+  These caps are also recorded in [control-matrix.md](control-matrix.md#opencode)'s
+  OpenCode section.
 
 ## What this means for this repo
 
@@ -128,9 +130,9 @@ From the official repo at tag `v2.0.32` (github.com/anomalyco/opencode, where `@
    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
+   50 KiB, Pi extension tools bypass the MCP 20 KB truncation, Claude Code caps output at
+   25k tokens, and Codex applies its 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

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

@@ -159,7 +159,8 @@ the current official docs** (checked 2026-10-21), nor in the November 2025 snaps
 page on the Internet Archive; the published truncation mechanism is the token-based
 `max_content_tokens` parameter above, with no published default.
 
-SDK layer (official repos, default branch):
+SDK layer (official repos, default branch at the 2026-10-21 check — moving heads, unlike
+the pinned firecrawl 4.50.0 above; re-pin to a tag before citing these constants later):
 
 | SDK | Default timeout | Default max retries | Source |
 | --- | --- | --- | --- |
@@ -180,7 +181,8 @@ From the official guide
 
 No relevance/authority score or filter is exposed on any web-search surface.
 
-SDK layer (official repos, default branch):
+SDK layer (official repos, default branch at the 2026-10-21 check — same moving-head
+caveat as the Anthropic SDK table above):
 
 | SDK | Default timeout | Default max retries | Source |
 | --- | --- | --- | --- |

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

@@ -17,6 +17,12 @@ source at the repo's locked tag. Secondhand blogs are excluded. Where no primary
 a fact — most importantly the size of `content` — that is stated as such: an undocumented
 size is itself a decision-relevant fact.
 
+**Short answer:** DeepSeek documents **no size bound** for `need_content` content and no
+per-result budget knob; of the eight architectures surveyed below, only Jina ships
+content-bearing search as the default; and the binding host cap is Pi's 20 KB MCP-path
+truncation — the volume math below puts a safe per-result budget in the ~1k–2k char
+range.
+
 ## What `need_content=true` provably returns
 
 From the official Search & Fetch guide, the parameter and its response field, verbatim:
@@ -101,15 +107,36 @@ 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) |
+| **Tavily** | Partial — per-result `content` of relevance chunks by default | Full body via `include_raw_content` (default **false**) | Chunk count only (`chunks_per_source` 1–3); no knob limits `raw_content` size in `/search` | Yes — `/extract` (up to 20 URLs) |
 | **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 |
+| **Perplexity** | No — Search API results are `title`/`url`/`snippet`/`date` only | Token budgets on both the Search API and the Agent API `web_search` tool (detail below) | **`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 — content is model-only (`encrypted_content`) | None — `response_inclusion` is not a content-size knob | **None** (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**; 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 |
 
+Detail for the trimmed rows above:
+
+- **Tavily:** the default per-result `content` carries **relevance chunks** —
+  `chunks_per_source` **3** chunks of ~500 chars (~1,500 chars/result); `include_raw_content`
+  accepts `markdown`/`text`/`true`; the chunk sizes apply to `content`, **not**
+  `raw_content`; `/extract` takes up to 20 URLs with `extract_depth` basic/advanced, no
+  per-URL cap, ~800-char chunks only when `query` is given.
+- **Perplexity:** `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”), **no default published** for either (“the default
+  budgets apply”); on the Search API the extracted text surfaces through `snippet`.
+- **Anthropic:** `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; dynamic filtering on `web_search_20260209+`
+  has Claude write code to filter results before they reach context, but no caller-set
+  budget exists.
+- **Jina:** “Reader searches the web, fetches the top 5 results, visits each URL, and
+  applies `r.jina.ai` to it.”
+
 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`,
@@ -119,6 +146,17 @@ exist they are per-result character caps (Exa `maxCharacters`) or per-result tok
 (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`.
 
+One further architecture reading (added 2026-10-24, same sources): **no surveyed vendor
+narrows another parameter's value range when inline content is requested.** Every budget
+knob in the table is static-range, conditional-effect — Exa's `maxCharacters` and
+Perplexity's `max_tokens_per_page` keep their 1–1,000,000 ranges whether or not
+`contents.text`/extraction is engaged, Tavily's `chunks_per_source` and Anthropic's
+`max_content_tokens` are likewise unconditional, and none shrinks `count`/`numResults`
+or any other parameter's domain when content flows (Jina's fixed 5 is its architecture,
+not a conditional rule). The only conditional behavior anywhere in the table is which
+budget *applies*; a content flag that reshaped other parameters' allowed values appears
+in none of the eight.
+
 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) ·
@@ -173,8 +211,9 @@ With `count=10` (the repo's default, and DeepSeek's) and `need_content: true`:
   [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**
+- **The binding constraint is Pi's 20 KB**, roughly 5× tighter than Claude Code's
+  25k-token default (≈100k English chars by the conversions above): 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.
@@ -195,8 +234,9 @@ maintainer decides.
 - **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.
+  `summary ?? snippet` only — a `need_content` response's page bodies would be received
+  and discarded: they cost nothing extra (billing is per request), but they are also
+  never rendered.
 - **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

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "deepseek-web-retrieval",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Token-efficient DeepSeek Search and Fetch for coding agents, starting with OpenCode v2.",
   "type": "module",
   "license": "MIT",

package/src/core/client.ts

@@ -92,6 +92,12 @@ export interface SearchRequest extends RequestOptions {
    * ori_question to sharpen intent; adapters fill it from tool input.
    */
   readonly oriQuestion?: string;
+  /**
+   * Per-call only. The tool input's need_content flag: true asks for each
+   * result's page body, sent as the API's need_content and timed against
+   * contentTimeoutMs instead of timeoutMs.
+   */
+  readonly needContent?: boolean;
 }
 
 /**
@@ -130,14 +136,15 @@ export async function searchWeb(query: string, options: SearchOptions, request:
   const composed = composeSearchQuery(trimmed, options);
   const builtQuery = composed.query;
 
-  const timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs);
+  const needContent = request.needContent === true;
+  const timeout = effectiveTimeout(needContent ? options.contentTimeoutMs : options.timeoutMs, request.timeoutMs);
   const oriQuestion = oriQuestionValue(request.oriQuestion);
   const payload = await postJson<SearchResponse>(
     apiUrl(request.baseUrl, SEARCH_ENDPOINT_PATH),
     {
       query: builtQuery,
       count: options.count,
-      need_content: false,
+      need_content: needContent,
       ...(oriQuestion === undefined ? {} : { ori_question: oriQuestion }),
       ...(options.localization === undefined ? {} : { localization: options.localization }),
     },

package/src/core/config-summary.ts

@@ -19,6 +19,8 @@ const VOCABULARY = [
   { key: "language", read: (o: ResolvedOptions) => o.search.language },
   { key: "searchLocalization", read: (o: ResolvedOptions) => o.search.localization },
   { key: "maxSummaryChars", read: (o: ResolvedOptions) => o.search.maxSummaryChars },
+  { key: "searchContentMaxChars", read: (o: ResolvedOptions) => o.search.contentMaxChars },
+  { key: "searchContentTimeoutMs", read: (o: ResolvedOptions) => o.search.contentTimeoutMs },
   { key: "searchTimeoutMs", read: (o: ResolvedOptions) => o.search.timeoutMs },
   { key: "fetchMaxChars", read: (o: ResolvedOptions) => o.fetch.maxChars },
   { key: "fetchAllowedDomains", read: (o: ResolvedOptions) => o.fetch.allowedDomains },

package/src/core/constants.ts

@@ -27,6 +27,19 @@ 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;
+/**
+ * The per-result budget a need_content page body is clamped to. 1,500 keeps a
+ * default count=10 response (bodies plus metadata ≈ 16 KB) under the tightest
+ * host output cap, Pi's 20 KB MCP-path truncation — see
+ * docs/research/search-inline-content.md.
+ */
+export const DEFAULT_SEARCH_CONTENT_MAX_CHARS = 1500;
+/**
+ * The timeout need_content calls use in place of searchTimeoutMs: DeepSeek
+ * fetches every result page server-side before responding, which the 30 s
+ * search default does not budget for.
+ */
+export const DEFAULT_SEARCH_CONTENT_TIMEOUT_MS = 60000;
 
 export const DEFAULT_FETCH_MAX_CHARS = 16000;
 /** The ceiling for a per-call fetch budget, matching the configured knob's range. */

package/src/core/descriptions.ts

@@ -30,7 +30,8 @@ export const SEARCH_TOOL_DESCRIPTION =
   `${SEARCH_RANKED_FILTERED} ` +
   `${SEARCH_EMPTY_IS_NORMAL} ` +
   `${SEARCH_QUERY_OPERATORS} ` +
-  "To read a full page, pass a result URL to the deepseek_fetch tool.";
+  "To read one full page in depth, pass a result URL to the deepseek_fetch tool; to carry each result's " +
+  "page body in this response, set need_content to true.";
 
 export const FETCH_TOOL_DESCRIPTION =
   "Fetch one web page as clean Markdown through DeepSeek's Fetch API. " +
@@ -54,3 +55,8 @@ export const FETCH_MAX_CHARS_PARAMETER =
 export const SEARCH_COUNT_PARAMETER =
   "Optional number of results for this call, 1-50. Overrides the configured count and result cap for this call; " +
   "billing is per request, not per result.";
+
+export const SEARCH_NEED_CONTENT_PARAMETER =
+  "Optional; set true to attach each result's page body as Markdown — an excerpt clamped to a configured per-result " +
+  "budget, not a full page — in place of its short summary. Slower per call (DeepSeek fetches the result pages) and " +
+  "priced the same per request; for a full page, call deepseek_fetch.";

package/src/core/env.ts

@@ -14,6 +14,8 @@ const NUMBER_ENV = {
   minAuthority: "DEEPSEEK_SEARCH_MIN_AUTHORITY",
   maxSummaryChars: "DEEPSEEK_SEARCH_MAX_SUMMARY_CHARS",
   searchTimeoutMs: "DEEPSEEK_SEARCH_TIMEOUT_MS",
+  searchContentMaxChars: "DEEPSEEK_SEARCH_CONTENT_MAX_CHARS",
+  searchContentTimeoutMs: "DEEPSEEK_SEARCH_CONTENT_TIMEOUT_MS",
   fetchMaxChars: "DEEPSEEK_FETCH_MAX_CHARS",
   fetchTimeoutMs: "DEEPSEEK_FETCH_TIMEOUT_MS",
   maxRetries: "DEEPSEEK_MAX_RETRIES",
@@ -97,6 +99,8 @@ export function envOptionsReport(env: Env = process.env): EnvOptionsReport {
   putText(options, "searchLocalization", env);
   putNumber(options, "maxSummaryChars", env, warnings);
   putNumber(options, "searchTimeoutMs", env, warnings);
+  putNumber(options, "searchContentMaxChars", env, warnings);
+  putNumber(options, "searchContentTimeoutMs", env, warnings);
 
   putNumber(options, "fetchMaxChars", env, warnings);
   putDomains(options, "fetchAllowedDomains", env, warnings);

package/src/core/format.ts

@@ -118,7 +118,16 @@ export function formatSearchResults(results: readonly SearchResult[], context?:
       const marker = formatQualityMarker(result);
       const lines = [`${index + 1}. [${escapeBrackets(title)}](${result.url})${marker ? ` ${marker}` : ""}`];
       if (result.content) {
-        lines.push(`   ${result.content.replaceAll("\n", " ")}`);
+        // Page bodies keep their Markdown line structure, indented into the
+        // list item; digests compact to one line, as summaries always did.
+        lines.push(
+          result.contentKind === "page"
+            ? result.content
+                .split("\n")
+                .map((line) => `   ${line}`)
+                .join("\n")
+            : `   ${result.content.replaceAll("\n", " ")}`,
+        );
       }
       if (result.published !== undefined) {
         lines.push(`   Published: ${formatPublished(result.published)}`);

package/src/core/options.ts

@@ -9,6 +9,8 @@ import {
   DEFAULT_MIN_AUTHORITY,
   DEFAULT_MIN_RERANK,
   DEFAULT_RETRY_BASE_DELAY_MS,
+  DEFAULT_SEARCH_CONTENT_MAX_CHARS,
+  DEFAULT_SEARCH_CONTENT_TIMEOUT_MS,
   DEFAULT_SEARCH_COUNT,
   DEFAULT_TIMEOUT_MS,
   MAX_RETRIES,
@@ -67,6 +69,13 @@ export function resolveSearchOptions(input?: PluginOptions): SearchOptions {
     language: optionalText(input?.language),
     localization: localizationValue(input?.searchLocalization),
     maxSummaryChars: clampInt(input?.maxSummaryChars, DEFAULT_MAX_SUMMARY_CHARS, 0, 1_000_000),
+    contentMaxChars: clampInt(input?.searchContentMaxChars, DEFAULT_SEARCH_CONTENT_MAX_CHARS, 0, 1_000_000),
+    contentTimeoutMs: clampInt(
+      input?.searchContentTimeoutMs,
+      DEFAULT_SEARCH_CONTENT_TIMEOUT_MS,
+      MIN_TIMEOUT_MS,
+      MAX_TIMEOUT_MS,
+    ),
     timeoutMs: clampInt(input?.searchTimeoutMs, DEFAULT_TIMEOUT_MS, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS),
     enabled: input?.searchEnabled !== false,
   };

package/src/core/search.ts

@@ -142,12 +142,20 @@ export function processResults(raw: readonly DeepSeekSearchResult[], options: Se
     }
 
     seen.add(url);
-    const rawContent = optionalText(item.summary) ?? optionalText(item.snippet) ?? "";
-    const cutContent = truncate(rawContent, options.maxSummaryChars);
+    // A need_content page body outranks the digest — the summary is only ever
+    // a proxy for the body it compresses. A zero budget drops the body so the
+    // digest renders instead.
+    const body = optionalText(item.content);
+    const digest = optionalText(item.summary) ?? optionalText(item.snippet) ?? "";
+    const fromPage = body !== undefined && options.contentMaxChars > 0;
+    const rawContent: string = fromPage && body !== undefined ? body : digest;
+    const contentBudget = fromPage ? options.contentMaxChars : options.maxSummaryChars;
+    const cutContent = truncate(rawContent, contentBudget);
     // The ellipsis marks a summary the cap actually shortened; official
     // summaries are typically 600-800 characters, so the 1,200 default
     // rarely triggers it.
-    const content = cutContent && charCount(rawContent) > options.maxSummaryChars ? `${cutContent}…` : cutContent;
+    const content = cutContent && charCount(rawContent) > contentBudget ? `${cutContent}…` : cutContent;
+    const contentKind = fromPage ? "page" : "digest";
     const published = parsePublished(item.date);
     const title = optionalText(item.title);
     const rerankScore = typeof rerank === "number" && Number.isFinite(rerank) ? rerank : undefined;
@@ -156,7 +164,7 @@ export function processResults(raw: readonly DeepSeekSearchResult[], options: Se
     results.push({
       url,
       ...(title ? { title } : {}),
-      ...(content ? { content } : {}),
+      ...(content ? { content, contentKind } : {}),
       ...(published !== undefined ? { published } : {}),
       ...(rerankScore !== undefined ? { rerankScore } : {}),
       ...(authorityScore !== undefined ? { authority: authorityScore } : {}),

package/src/core/types.ts

@@ -20,6 +20,14 @@ export interface SearchOptions {
    */
   readonly localization?: string;
   readonly maxSummaryChars: number;
+  /**
+   * Deployment-level only — never a per-call tool parameter. The budget a
+   * need_content page body is clamped to per result; the per-call boolean is
+   * `SearchRequest.needContent`.
+   */
+  readonly contentMaxChars: number;
+  /** Deployment-level only; the timeout a need_content call uses instead of `timeoutMs`. */
+  readonly contentTimeoutMs: number;
   readonly timeoutMs: number;
   readonly enabled: boolean;
 }
@@ -63,6 +71,8 @@ export interface DeepSeekSearchResult {
   readonly url?: string | null;
   readonly snippet?: string | null;
   readonly summary?: string | null;
+  /** The need_content page body; an empty string when need_content is false or the content is unavailable. */
+  readonly content?: string | null;
   readonly date?: string | null;
 }
 
@@ -71,6 +81,8 @@ export interface SearchResult {
   readonly url: string;
   readonly title?: string;
   readonly content?: string;
+  /** Which wire field `content` came from: a need_content page body or the summary/snippet digest. */
+  readonly contentKind?: "page" | "digest";
   readonly published?: number;
   readonly rerankScore?: number;
   /** Faithful to the wire: -1 means unknown authority. */

package/src/mcp/server.ts

@@ -11,6 +11,7 @@ import {
   FETCH_TOOL_DESCRIPTION,
   FETCH_URL_PARAMETER,
   SEARCH_COUNT_PARAMETER,
+  SEARCH_NEED_CONTENT_PARAMETER,
   SEARCH_ORI_QUESTION_PARAMETER,
   SEARCH_QUERY_PARAMETER,
   SEARCH_TOOL_DESCRIPTION,
@@ -27,6 +28,7 @@ const SEARCH_INPUT = z.object({
   query: z.string().min(1).describe(SEARCH_QUERY_PARAMETER),
   original_question: z.string().optional().describe(SEARCH_ORI_QUESTION_PARAMETER),
   count: z.number().int().min(1).max(MAX_SEARCH_COUNT).optional().describe(SEARCH_COUNT_PARAMETER),
+  need_content: z.boolean().optional().describe(SEARCH_NEED_CONTENT_PARAMETER),
 });
 
 const FETCH_INPUT = z.object({
@@ -54,12 +56,13 @@ export function createDeepSeekServer(
         inputSchema: SEARCH_INPUT,
         annotations: { readOnlyHint: true },
       },
-      async ({ query, original_question, count }, ctx) => {
+      async ({ query, original_question, count, need_content }, ctx) => {
         try {
           const request = requestContext(config, requireApiKey(env), ctx.mcpReq.signal);
           const outcome = await client.searchWeb(query, withPerCallCount(config.search, count), {
             ...request,
             oriQuestion: original_question,
+            needContent: need_content === true,
           });
           return callResult(server, ctx, formatSearchResults(outcome.results, outcome), {
             results: outcome.results.map(toStructuredResult),