deepseek-web-retrieval 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -2,9 +2,26 @@
 
 All notable changes to this project are documented here, one sentence per item.
 
+## 0.10.0
+
+- Add `need_content` as an optional per-call boolean on the MCP and Pi search tools: `true` attaches each result's page body as Markdown (structure-preserving, indented into the result list) in place of its summary, and a missing body falls back to the summary; OpenCode's fixed provider input keeps that path summary-only.
+- Add the `searchContentMaxChars` (1,500 characters) and `searchContentTimeoutMs` (60,000 ms) deployment knobs — the content envelope every `need_content` call runs inside, never tool parameters, recorded in ADR-0003 and the search content design note.
+- State the `need_content` facts — excerpt length, latency, price, and the fetch alternative — in the tool and parameter descriptions, with both full-page routes named side by side, and no usage policy: when content is worth it stays the model's per-call judgment.
+- Extend the inline-content research note with the vendor reading that no surveyed architecture couples a content flag to another parameter's value range: budgets are static-range, conditional-effect.
+- Add a keyless `pi-mock` e2e leg that drives a real Pi session search with `need_content: true` against the mock upstream and asserts the flag reached the wire and the page body reached the model, with the digest legs now also asserting `need_content: false` by default.
+
+## 0.9.0
+
+- Accept an optional per-call `count` (1–50) on the MCP and Pi search tools and an optional per-call `maxChars` (0–1,000,000) on every adapter's fetch, each overriding the configured value for that one call.
+- Open the search result text with `Searched for: <effective query>` whenever domain or language operators — or fitting the query-length limit — changed what was actually searched, so the model can attribute what it sees.
+- Degrade gracefully instead of failing when search operators push a combined query past the API's 128-character limit: the query body truncates first, the language filter drops next, the include list last, and blocked domains never drop.
+- Align user-facing installer wording with the domain glossary: the secrets refusal and record-repair guidance now say "install record" instead of "state file" or "undo state".
+- Add the `baseUrl` knob (`DEEPSEEK_BASE_URL` environment variable or shared-file key) so every retrieval request can be routed through a proxy, enterprise gateway, or mock upstream; only an http(s) URL is accepted and anything else drops back to `https://api.deepseek.com`.
+- Add keyless `pi-mock` and `opencode-mock` Docker e2e scenarios that run real host session loops (pi via a custom `models.json` provider, OpenCode via a custom provider) against an in-container mock upstream, invoking both retrieval tools and asserting the tool results reached the model — closing CI's tool-execution blind spot without a billed key — and document the keyless (CI) versus billed (local, real API) e2e responsibilities with a `test:e2e:billed` script.
+
 ## 0.8.0
 
-- Add Claude Code as a supported host: an MCP-only integration registered in `.mcp.json` (project scope) or `~/.claude.json` (user scope), with a full installer host module (plan/apply/uninstall, both scopes), a `docs/agents/claude-code.md` guide, a version probe with drift note, and managed-policy detection that reports a `managed-settings.json` layer outranking the install.
+- Add Claude Code as a supported host: an MCP-only integration registered in `.mcp.json` (project scope) or `~/.claude.json` (Claude Code's user scope — global scope in this repo's vocabulary), with a full installer host module (plan/apply/uninstall, both scopes), a `docs/agents/claude-code.md` guide, a version probe with drift note, and managed-policy detection that reports a `managed-settings.json` layer outranking the install.
 - Route Claude Code tiers through its own settings files: forced capabilities deny the built-in `WebSearch`/`WebFetch` via `permissions.deny` in `.claude/settings.json` or `~/.claude/settings.json` (merged with the user's entries), off capabilities deny the full `mcp__deepseek__*` tool ids, and preferred writes a rules block into `CLAUDE.md`; web-capable competitor servers are excluded under forced via server-level `mcp__<server>` deny rules instead of refusing the tier.
 - Add a billed `claude-code` Docker e2e scenario that runs headless `claude -p` prompts with DeepSeek as the LLM over its Anthropic-compatible endpoint (single key for both legs) and asserts the deny-based kill switch keeps the built-in tools out of the session, plus installer/reinit coverage of the new host in the keyless scenarios.
 - Guard Pi's global config files with the shared-file ownership sidecar, and release claims before deleting the install record on uninstall, so two installs under different config homes can no longer claim the same `~/.pi/agent` file.

package/README.md

@@ -4,8 +4,9 @@
 
 Search the web and fetch pages as Markdown through
 [DeepSeek's APIs](https://api-docs.deepseek.com/guides/search), using a **native OpenCode
-plugin**, a **native Pi extension**, or **MCP for Codex and Claude Code**. All four share
-the same retrieval core, with results formatted for each host.
+plugin**, a **native [Pi](https://pi.dev/) extension** (Pi, the open-source coding agent),
+or **MCP for Codex and Claude Code**. All four share the same retrieval core, with results
+formatted for each host.
 
 This is an unofficial community project, not affiliated with DeepSeek or the supported
 host projects.
@@ -16,8 +17,9 @@ Jump to: [Features](#features) · [Quickstart](#quickstart) · [Usage](#usage)
 
 ## Features
 
-- **One package, four hosts** — a native OpenCode v2 plugin, a native Pi extension,
-  and a stdio MCP server for Codex and Claude Code, all sharing one retrieval core
+- **One package, four hosts** — a native plugin for OpenCode v2 (the 2.x series), a
+  native Pi extension, and a stdio MCP server for Codex and Claude Code, all sharing one
+  retrieval core
 - **Routing control per tool** — search and fetch are set independently to optional,
   preferred, forced, or off; the tier table in Usage explains each
 - **Review before anything is written** — `init` prints the full plan and writes only
@@ -59,8 +61,9 @@ Choose your host:
 | Claude Code | MCP server over stdio in `.mcp.json` or `~/.claude.json` | [Claude Code guide](docs/agents/claude-code.md) |
 
 Set `DEEPSEEK_API_KEY` in the environment that launches your host; OpenCode can also
-use its stored DeepSeek key. Run `init` for your host to preview a configuration — the
-command shape is the quickstart's; each host guide shows its recommended tiers.
+use its stored DeepSeek key. Run `init` for your host to preview a configuration — take
+the quickstart command and swap `--host` and `--scope` for your host's values; each host
+guide shows its recommended tiers.
 
 `--search` and `--fetch` each pick a tier — how strongly the host steers toward the
 DeepSeek tool, chosen independently per capability:
@@ -87,7 +90,8 @@ Files:
     upsert marked rules block
 
 Notes:
-  - Codex stdio children do not inherit the parent environment, so the entry forwards DEEPSEEK_API_KEY and every DEEPSEEK_* option variable explicitly via env_vars; shell-set knobs reach the server without hand-editing config.toml (the shared config file works without any forwarding).
+  - Codex stdio children do not inherit the parent environment, so the entry forwards DEEPSEEK_API_KEY and every DEEPSEEK_* option variable explicitly via env_vars; shell-set knobs reach the server without hand-editing config.toml.
+  - The shared config file needs no forwarding at all: the server reads it itself.
   - Rules block upserted in ~/.codex/AGENTS.md; Codex reads ~/.codex/AGENTS.md plus every AGENTS.md from the project root to the cwd.
   - Shared config ownership is recorded in ~/.codex/.config.toml.deepseek-web-retrieval.codex.owner.json; uninstall releases it. Keep this local metadata with the config.
 
@@ -116,21 +120,28 @@ What this adapter layer adds on top of the
 own capabilities (Markdown-only output, no JavaScript rendering, no private networks or
 binary files, per-request billing) are documented there.
 
-| Default | Value | Knob |
+| Setting | Default | Knob |
 | --- | --- | --- |
 | Results per search | 10 | `count` |
 | Fetch output cap | 16,000 characters | `fetchMaxChars` |
 | Search summary cap | 1,200 characters | `maxSummaryChars` |
-| Request timeout, body read included | 30 s | `searchTimeoutMs` / `fetchTimeoutMs` |
+| Inline content cap, per result (when requested) | 1,500 characters | `searchContentMaxChars` |
+| Request timeout, body read included | 30 s (60 s for `need_content` calls) | `searchTimeoutMs` / `fetchTimeoutMs` / `searchContentTimeoutMs` |
 | Transient retries | 2 (range 0–5) | `maxRetries` |
 
 ### Search
 
-- Requests summaries only (`need_content: false`, falling back from `summary` to
-  `snippet`); full page content never enters the results.
+- Requests summaries by default (`need_content: false`, falling back from `summary` to
+  `snippet`); a summary the cap shortens ends with an ellipsis. When a call sets
+  `need_content: true`, each result instead carries its page body as Markdown, clamped
+  to `searchContentMaxChars` per result — a missing body falls back to the summary.
 - Deduplicates URLs; an empty result set is normal, not an error.
-- Builds `blockedDomains`, `includeDomains`, and `language` into query operators, and
-  rejects the final query locally when it exceeds the API's 128-character limit.
+- Builds `blockedDomains`, `includeDomains`, and `language` into query operators (part of
+  DeepSeek's documented search syntax). A combined query over the API's 128-character limit
+  degrades instead of failing — the query body truncates first, the language filter drops
+  next, the include list last, and blocked domains never drop — and whenever operators or
+  degradation changed the query, the result text opens with `Searched for: <effective query>`
+  so the model can attribute what it sees.
 - Optional `rerank_score` and `authority` thresholds are off by default — the default
   returns exactly what DeepSeek ranked. A positive threshold drops results below it.
   A missing `rerank_score` is dropped too; an unknown `authority` stays unless
@@ -140,11 +151,17 @@ binary files, per-request billing) are documented there.
   question in their own words. It is forwarded as DeepSeek's `ori_question`, trimmed
   and truncated to 128 characters; on the Pi extension, a blank input falls back to the
   most recent user message in the session.
+- The same paths also take an optional per-call `count` (1–50), overriding the
+  configured result count for that one call, and an optional per-call `need_content`
+  boolean requesting page bodies in the results (see
+  [search content design](docs/design/search-content-design.md)).
 
 ### Fetch
 
 - Output is capped per the table above, title included; a `[content truncated]` marker
-  is added when the limit leaves room for it.
+  is added when the limit leaves room for it. An optional per-call `maxChars` parameter
+  (0–1,000,000) on every adapter overrides the configured cap for one call — a model that
+  sees the marker can widen the budget and re-fetch.
 - A page that already opens with its title as a top-level heading does not get a
   duplicate title.
 - URLs must be absolute `http://` or `https://`, credential-free, and at most 8,192
@@ -220,8 +237,8 @@ bun run check
 ```
 
 Use `bun run lint:fix` to apply Biome's safe lint fixes and formatting. See
-[CONTRIBUTING.md](CONTRIBUTING.md) for development checks, e2e scenarios, and
-[automated tag releases](CONTRIBUTING.md#automated-releases).
+[CONTRIBUTING.md](CONTRIBUTING.md) for development checks and e2e scenarios, and
+[automated tag releases](CONTRIBUTING.md#automated-releases-maintainers).
 
 The test suite mocks the DeepSeek API and the OpenCode and Pi host APIs; real API calls
 require a funded DeepSeek account. Shared retrieval logic lives in `src/core/`; adapters