deepseek-web-retrieval 0.3.0 → 0.5.0

package/docs/agents/codex.md

@@ -16,6 +16,12 @@ The tools appear in Codex as `mcp__deepseek__deepseek_web_search` and
 `mcp__deepseek__deepseek_fetch`. Codex's built-in `web_search` tool is not replaced; see
 [Control tiers](#control-tiers) for routing it away.
 
+The server recognizes Codex's MCP client identity (`codex-mcp-client`, declared in the
+initialize handshake) and returns text-only tool results: Codex replaces the content
+blocks with the serialized `structuredContent` JSON when it is present, so for Codex the
+structured mirror is omitted and the model reads clean Markdown. Other clients receive
+both the text and `structuredContent`.
+
 For shared search/fetch limits, retries, and privacy behavior, see
 [General behavior](../../README.md#general-behavior).
 
@@ -40,7 +46,13 @@ It prints the full plan — every file, old value → new value, and notes about
 MCP servers — and writes nothing until you pass `--apply`. `uninstall` restores exactly
 what the plan applied (snapshots, merged entries, created files). Codex's config lives in
 `~/.codex/config.toml` at the user level only, so the server registration and kill switch
-are written there even for `--scope project`; the rules file follows the scope.
+are written there even for `--scope project`; the rules file follows the scope. An `off`
+capability is written as the tool's name in the server entry's `disabled_tools` array —
+Codex's own mechanism — merging with any entries you put there yourself. When `codex` is
+on PATH, `init` also probes `codex --version` and adds a plan note when the installed
+release differs from the tested lock (see
+[hosts.jsonc](../hosts.jsonc)) — version-anchored behavior such as the kill switch may
+have drifted between the two.
 
 ### Manual install
 
@@ -59,13 +71,22 @@ env_vars = ["DEEPSEEK_API_KEY"]
 > forwarded explicitly and set in the shell that launches Codex. Literal values can go
 > in an `env` table instead if you prefer them in the file.
 
-To disable one capability, set it in the `env` table:
+To disable one capability, add its raw tool name to the server's `disabled_tools` —
+Codex removes the tool from the model's context while the server keeps running:
 
 ```toml
-[mcp_servers.deepseek.env]
-DEEPSEEK_ENABLE_SEARCH = "false"   # or DEEPSEEK_ENABLE_FETCH; at least one must stay on
+[mcp_servers.deepseek]
+command = "npx"
+args = ["-y", "deepseek-web-retrieval"]
+env_vars = ["DEEPSEEK_API_KEY"]
+disabled_tools = ["deepseek_web_search"]   # or deepseek_fetch; at least one must stay on
 ```
 
+The names match verbatim what the server declares (`deepseek_web_search`,
+`deepseek_fetch`). The server also honors `DEEPSEEK_ENABLE_SEARCH`/`DEEPSEEK_ENABLE_FETCH`
+in the `env` table if you prefer switching the tools off at the source; the installer uses
+`disabled_tools`.
+
 ### Local checkout
 
 ```bash
@@ -111,7 +132,7 @@ Ask naturally:
 
 ```text
 Search the web for the latest Codex MCP config changes and cite the sources.
-Fetch https://developers.openai.com/codex/mcp and summarize the config keys.
+Fetch https://learn.chatgpt.com/docs/extend/mcp and summarize the config keys.
 ```
 
 The model calls `mcp__deepseek__deepseek_web_search` or `mcp__deepseek__deepseek_fetch`.
@@ -127,10 +148,10 @@ defaults and clamping match the other adapters. `DEEPSEEK_API_KEY` goes in `env_
 | --- | --- | --- |
 | `DEEPSEEK_ENABLE_SEARCH` | `true` | Register the search tool. Only an explicit `false`/`0`/`no`/`off` disables it; at least one tool must stay enabled. |
 | `DEEPSEEK_SEARCH_COUNT` | `10` | Results requested from DeepSeek, 1–50. Billing is per request, not per result. |
-| `DEEPSEEK_SEARCH_MAX_RESULTS` | `5` | Results returned to the model after filtering, 0–50. `0` returns no results. |
-| `DEEPSEEK_SEARCH_MIN_RERANK` | `1.5` | Drop results below this relevance score. DeepSeek scores are 0–3. |
-| `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `2` | Drop known authorities below this tier. Authority is 0–4. |
-| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `false` | Keep results whose authority is missing or unknown. |
+| `DEEPSEEK_SEARCH_MAX_RESULTS` | `10` | Results returned to the model after filtering, 0–50. `0` returns no results. |
+| `DEEPSEEK_SEARCH_MIN_RERANK` | `0` | Drop results below this relevance score. DeepSeek scores are 0–3. |
+| `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `0` | Drop known authorities below this tier. Authority is 0–4. |
+| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `true` | Keep results whose authority is missing or unknown. Set `false`/`0` to drop them. |
 | `DEEPSEEK_SEARCH_BLOCKED_DOMAINS` | unset | Comma-separated; adds `-site:` operators to the query. |
 | `DEEPSEEK_SEARCH_INCLUDE_DOMAINS` | unset | Comma-separated; restricts results with `site:` operators. |
 | `DEEPSEEK_SEARCH_LANGUAGE` | unset | Adds a `lang:` operator, for example `zh,en`. |
@@ -163,8 +184,8 @@ defaults and clamping match the other adapters. `DEEPSEEK_API_KEY` goes in `env_
 | Server fails to start or `HTTP 401` from the tools | `DEEPSEEK_API_KEY` must be set in the shell that launches Codex and forwarded via `env_vars`; stdio children do not inherit the environment. |
 | Both tools missing after startup | At least one of `DEEPSEEK_ENABLE_SEARCH`/`DEEPSEEK_ENABLE_FETCH` must stay enabled; the server exits when both are false. |
 | Search still uses the built-in tool under the forced tier | The kill switch is the top-level `web_search = "disabled"` key; the `[tools] web_search` form is a no-op at 0.163.0. |
-| Tool results look like raw JSON | When a result has `structuredContent`, Codex replaces the content blocks with the serialized JSON — expected behavior. |
-| Tools time out around 60 s | Raise `tool_timeout_sec` for the server entry if you raise `DEEPSEEK_*_TIMEOUT_MS` beyond it. |
+| Tool results look like raw JSON | The server omits `structuredContent` for Codex's `codex-mcp-client` client identity so the model reads Markdown; if JSON still appears, a newer Codex renamed the identity — report it. |
+| Tools time out before the configured DeepSeek timeout | Codex's per-server `tool_timeout_sec` defaults to 300 s — above the 120 s `DEEPSEEK_*_TIMEOUT_MS` maximum — so this only happens if you lowered it; raise it back above the DeepSeek timeout. |
 | Routing not exclusive | Other `[mcp_servers.*]` entries stay registered and are noted in the plan. Under a forced tier, an entry that looks web-capable makes `init` refuse — Codex has no per-server kill switch, so remove the server or restrict its tools via `disabled_tools` by hand. |
 | `HTTP 402`, `HTTP 429` | Top up the DeepSeek account; wait, reduce concurrency, or set `DEEPSEEK_MAX_RETRIES`. |
 | Fetch fails on localhost or an internal URL | Use a local fetch tool; DeepSeek cannot reach private networks. |

package/docs/agents/opencode-v2.md

@@ -100,7 +100,7 @@ A complete global config:
 Use the bare package name (optionally pinned) as the `package` value:
 
 ```jsonc
-"plugins": [{ "package": "deepseek-web-retrieval@0.3.0" }]
+"plugins": [{ "package": "deepseek-web-retrieval@0.4.0" }]
 ```
 
 **Global checkout**
@@ -173,10 +173,10 @@ Set these in the plugin's `options` object.
 | --- | --- | --- |
 | `searchEnabled` | `true` | Register the DeepSeek search provider at all. Only an explicit `false` disables it. |
 | `count` | `10` | Results requested from DeepSeek, 1–50. Billing is per request, not per result. |
-| `maxResults` | `5` | Results returned to the model after filtering, 0–50. `0` returns no results. |
-| `minRerank` | `1.5` | Drop results below this relevance score. DeepSeek scores are 0–3. |
-| `minAuthority` | `2` | Drop known authorities below this tier. Authority is 0–4. |
-| `allowUnknownAuthority` | `false` | Keep results whose authority is missing or unknown. |
+| `maxResults` | `10` | Results returned to the model after filtering, 0–50. `0` returns no results. |
+| `minRerank` | `0` | Drop results below this relevance score. DeepSeek scores are 0–3. A result without a finite score passes while the threshold is `0` and is dropped once it is positive. |
+| `minAuthority` | `0` | Drop known authorities below this tier. Authority is 0–4. |
+| `allowUnknownAuthority` | `true` | Keep results whose authority is missing or unknown. Only an explicit `false` disables it. |
 | `blockedDomains` | `[]` | Add `-site:` operators to the search query. |
 | `includeDomains` | `[]` | Restrict results with `site:` operators. |
 | `language` | unset | Add a `lang:` operator, for example `zh,en`. |

package/docs/agents/pi.md

@@ -2,29 +2,33 @@
 
 Pi adapter for [DeepSeek Web Retrieval](../../README.md).
 
-Integration mechanism: MCP server over stdio, launched from Pi's `mcp.json`. Pi 1.3.0
-negotiates MCP revision `2025-11-25`; the server also accepts clients from `2024-11-05`
-through `2026-07-28`, so the same build works for other MCP hosts (see
-[the compatibility research](../research/mcp-compatibility.md)).
+Integration mechanism: Pi's native extension API — the package's `pi` manifest names
+`src/pi/extension.ts`, and Pi loads it in-process (via jiti, TypeScript directly) at session
+start. The same build also ships an MCP server over stdio as the fallback path
+([below](#the-mcp-fallback-path)); the extension is the recommended one:
 
-When registered, it adds:
+- The tools are declared to the model like built-ins (`exposure: "direct"` is Pi's own
+  default for extension tools — the MCP path's codemode trap does not exist here).
+- Results bypass Pi's MCP layer entirely: no 20 KB middle truncation and no 60 s
+  per-request timeout; the adapter's own output cap is the only limit.
+- The key is read from the Pi process environment — no `env` forwarding, no `${VAR}`
+  indirection in any config file.
+
+When loaded, it adds:
 
 - A `deepseek_web_search` tool backed by DeepSeek Search
 - A `deepseek_fetch` tool backed by DeepSeek Fetch
 
-The tools appear in Pi as `mcp__deepseek__deepseek_web_search` and
-`mcp__deepseek__deepseek_fetch`. Pi's built-in tools are not replaced.
-
-For shared search/fetch limits, retries, and privacy behavior, see
+Pi 1.3.0 ships no built-in web tool, so the registered tools are the only web path. For
+shared search/fetch limits, retries, and privacy behavior, see
 [General behavior](../../README.md#general-behavior).
 
 ## Requirements
 
 - Pi 1.3.0 or newer
-- Node.js 20 or newer (`npx` runs the server)
 - A DeepSeek account with access to `/v1/tools/search` and `/v1/tools/fetch`
 - A funded DeepSeek account; Search and Fetch are billed per successful request
-- `DEEPSEEK_API_KEY` set in the server's `env` block
+- `DEEPSEEK_API_KEY` set in the shell that launches Pi
 
 ## Install
 
@@ -36,79 +40,49 @@ npx deepseek-web-retrieval init --host pi --scope <project|global> \
 ```
 
 It prints the full plan — every file, old value → new value, and notes about existing
-MCP servers and the `exposure` requirement — and writes nothing until you pass `--apply`.
-JSON edits preserve comments. `uninstall` restores exactly what the plan applied. Under a
-forced tier, other registered MCP servers that look web-capable are disabled
-(`enabled: false`, prior value snapshotted) so DeepSeek routing is exclusive, and
-`uninstall` restores them. The
-tiers follow the [control matrix](../research/control-matrix.md): Pi ships no built-in web
-tool, so forced is de-facto for both capabilities and `off` writes
-`DEEPSEEK_ENABLE_SEARCH`/`DEEPSEEK_ENABLE_FETCH` into the server's env block.
+packages and MCP servers — and writes nothing until you pass `--apply`. The default path is
+the extension: the plan appends `npm:deepseek-web-retrieval` to the `packages` array in
+`~/.pi/agent/settings.json` (global) or `.pi/settings.json` (project), and Pi resolves the
+source at the next session start (the first launch fetches the package from npm;
+`pi update --extensions` refreshes it later). An off capability is written into the
+`deepseekWebRetrieval` settings namespace the extension reads at load. Pass `--path mcp`
+to install the [MCP fallback path](#the-mcp-fallback-path) instead. `uninstall` restores
+exactly what the plan applied.
 
 ### Manual install
 
-Add the server to `~/.pi/agent/mcp.json` (user) or `.pi/mcp.json` (project):
-
-```jsonc
-{
-  "mcpServers": {
-    "deepseek": {
-      "command": "npx",
-      "args": ["-y", "deepseek-web-retrieval"],
-      "env": { "DEEPSEEK_API_KEY": "${DEEPSEEK_API_KEY}" },
-      "exposure": "direct"
-    }
-  }
-}
-```
-
-`${DEEPSEEK_API_KEY}` expands from the shell that launches Pi, so the key itself stays out
-of the config file. Set it in your shell profile:
+Use Pi's own installer:
 
 ```bash
-export DEEPSEEK_API_KEY="sk-***"
+pi install npm:deepseek-web-retrieval           # ~/.pi/agent/settings.json (user)
+pi install --local npm:deepseek-web-retrieval   # .pi/settings.json (project)
 ```
 
-> [!NOTE]
-> `exposure` matters. Pi 1.3.0 defaults MCP tools to `codemode`, which does not declare
-> them to the model. `"exposure": "direct"` registers the two tools like built-ins so the
-> model can call them. Without it the server connects but the tools are never used.
-
-Verify the registration with `pi mcp list` (or the `/mcp` panel inside a session); Pi
-shows the server's tools when the handshake succeeds. Config changes load with `/reload`
-or a new session.
+Pi reads the package's `pi` manifest and loads `src/pi/extension.ts` at session start. No
+build step and no config entry beyond the `packages` source are needed.
 
 ### Local checkout
 
-To run the server from a checkout instead of the published package (for
-development):
-
 ```bash
 git clone https://github.com/gwokhou/deepseek-web-retrieval.git
-cd deepseek-web-retrieval
-bun install && bun run build
 ```
 
-Then point Pi at the built entry:
+Then point Pi at the checkout (it is itself a valid package):
 
-```jsonc
-{
-  "mcpServers": {
-    "deepseek": {
-      "command": "node",
-      "args": ["/absolute/path/to/deepseek-web-retrieval/dist/cli.js"],
-      "env": { "DEEPSEEK_API_KEY": "${DEEPSEEK_API_KEY}" },
-      "exposure": "direct"
-    }
-  }
-}
+```bash
+pi install /absolute/path/to/deepseek-web-retrieval
 ```
 
+The extension entry imports only host-supplied modules (`@earendil-works/pi-coding-agent`,
+`@earendil-works/pi-ai`) and the package's own `src/core/`, so a plain clone works.
+
 ## Authentication
 
-`DEEPSEEK_API_KEY` is the only source; MCP has no host credential store. The key is read
-per request and sent only to `api.deepseek.com` as a Bearer token. It is not written to
-tool output or logs. Without a key the server exits at startup with a message on stderr.
+`DEEPSEEK_API_KEY` is the only source: the extension runs inside the Pi process and reads
+the environment directly, so the key must be set in the shell that launches Pi (MCP's env
+forwarding does not apply). It is read per request and sent only to `api.deepseek.com` as a
+Bearer token. It is not written to tool output or logs. Without it, the first tool call
+returns an error naming the missing variable.
 
 ## Usage
 
@@ -119,12 +93,15 @@ Search the web for the latest Pi extension API changes and cite the sources.
 Fetch https://pi.dev/docs/latest/extensions and summarize the extension lifecycle.
 ```
 
-The model calls `mcp__deepseek__deepseek_web_search` or `mcp__deepseek__deepseek_fetch`.
+The model calls `deepseek_web_search` or `deepseek_fetch` — the same names over both paths;
+only the MCP fallback prefixes them with `mcp__deepseek__`.
 
 ## Configuration
 
-Set these in the server's `env` block. Values map onto the shared option pipeline, so
-defaults and clamping match the OpenCode adapter.
+The runtime config surface is the same `DEEPSEEK_*` environment the MCP server reads
+(identical defaults and clamping), set in the shell that launches Pi, plus the
+`deepseekWebRetrieval` settings namespace for the off switches (written by the installer;
+it outranks the environment and is preserved by Pi's own settings rewrites).
 
 ### Search
 
@@ -132,23 +109,23 @@ defaults and clamping match the OpenCode adapter.
 | --- | --- | --- |
 | `DEEPSEEK_ENABLE_SEARCH` | `true` | Register the search tool. Only an explicit `false`/`0`/`no`/`off` disables it; at least one tool must stay enabled. |
 | `DEEPSEEK_SEARCH_COUNT` | `10` | Results requested from DeepSeek, 1–50. Billing is per request, not per result. |
-| `DEEPSEEK_SEARCH_MAX_RESULTS` | `5` | Results returned to the model after filtering, 0–50. `0` returns no results. |
-| `DEEPSEEK_SEARCH_MIN_RERANK` | `1.5` | Drop results below this relevance score. DeepSeek scores are 0–3. |
-| `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `2` | Drop known authorities below this tier. Authority is 0–4. |
-| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `false` | Keep results whose authority is missing or unknown. Set `true`/`1`. |
+| `DEEPSEEK_SEARCH_MAX_RESULTS` | `10` | Results returned to the model after filtering, 0–50. `0` returns no results. |
+| `DEEPSEEK_SEARCH_MIN_RERANK` | `0` | Drop results below this relevance score. DeepSeek scores are 0–3. |
+| `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `0` | Drop known authorities below this tier. Authority is 0–4. |
+| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `true` | Keep results whose authority is missing or unknown. Set `false`/`0` to drop them. |
 | `DEEPSEEK_SEARCH_BLOCKED_DOMAINS` | unset | Comma-separated; adds `-site:` operators to the query. |
 | `DEEPSEEK_SEARCH_INCLUDE_DOMAINS` | unset | Comma-separated; restricts results with `site:` operators. |
 | `DEEPSEEK_SEARCH_LANGUAGE` | unset | Adds a `lang:` operator, for example `zh,en`. |
 | `DEEPSEEK_SEARCH_MAX_SUMMARY_CHARS` | `1200` | Per-result summary cap, 0–1,000,000. |
-| `DEEPSEEK_SEARCH_TIMEOUT_MS` | `30000` | Search timeout, 1,000–120,000 ms. |
+| `DEEPSEEK_SEARCH_TIMEOUT_MS` | `30000` | Search timeout, 1,000–120,000 ms. No host-side cap applies on the extension path. |
 
 ### Fetch
 
 | Env variable | Default | Description |
-| --- | --- |
+| --- | --- | --- |
 | `DEEPSEEK_ENABLE_FETCH` | `true` | Register the fetch tool. Same false-only semantics as `DEEPSEEK_ENABLE_SEARCH`. |
-| `DEEPSEEK_FETCH_MAX_CHARS` | `16000` | Maximum characters returned, including the title, 0–1,000,000. |
-| `DEEPSEEK_FETCH_TIMEOUT_MS` | `30000` | Fetch timeout, 1,000–120,000 ms. |
+| `DEEPSEEK_FETCH_MAX_CHARS` | `16000` | Maximum characters returned, including the title, 0–1,000,000. The only output cap on this path. |
+| `DEEPSEEK_FETCH_TIMEOUT_MS` | `30000` | Fetch timeout, 1,000–120,000 ms. No host-side cap applies on the extension path. |
 | `DEEPSEEK_FETCH_ALLOWED_DOMAINS` | unset | If set, only these hosts and subdomains may be fetched. |
 | `DEEPSEEK_FETCH_BLOCKED_DOMAINS` | unset | Always block these hosts and subdomains. Blocked wins over allowed. |
 | `DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS` | `true` | Reject localhost, private IPs, `.local`, `.internal`, and similar hosts. Set `false`/`0` to disable. |
@@ -157,7 +134,7 @@ defaults and clamping match the OpenCode adapter.
 
 | Env variable | Default | Description |
 | --- | --- | --- |
-| `DEEPSEEK_API_KEY` | required | DeepSeek API key. The server refuses to start without it. |
+| `DEEPSEEK_API_KEY` | required | DeepSeek API key, read from the Pi process environment. |
 | `DEEPSEEK_MAX_RETRIES` | `0` | Retries for 408, 425, 429, and 5xx responses, 0–5. |
 | `DEEPSEEK_RETRY_BASE_DELAY_MS` | `250` | Base delay for exponential backoff. `Retry-After` is honored up to 10 seconds. |
 
@@ -167,30 +144,28 @@ Invalid values fall back to the shared default.
 
 | Error or symptom | What to do |
 | --- | --- |
-| Server connects but the model never calls the tools | Set `"exposure": "direct"`; Pi 1.3.0 defaults to `codemode`, which hides MCP tools from the model. |
-| Server fails to start (`pi mcp list`) | Check `DEEPSEEK_API_KEY`; without it the process exits with a stderr message. |
+| `Failed to load extension ... at least one must stay enabled` | Both capabilities are off (env or the `deepseekWebRetrieval` namespace); keep at least one on. |
+| Tools never appear | Check that the `packages` entry is present (`pi list`) and that the first launch after install could reach npm; `pi update --extensions` re-fetches. |
+| First tool call errors on the key | `DEEPSEEK_API_KEY` must be set in the shell that launches Pi; the extension reads only the process environment. |
 | `HTTP 401, invalid API key` | Check the key and its access to the tools endpoints. |
 | `HTTP 402, insufficient balance` | Top up the DeepSeek account. |
 | `HTTP 429, rate limited` | Wait, reduce concurrency, or set `DEEPSEEK_MAX_RETRIES`. |
 | Search query too long | Shorten the query or reduce configured domain/language operators. |
 | Fetch fails on localhost or an internal URL | Use a local fetch tool; DeepSeek cannot reach private networks. |
-| Long fetch results look cut in the middle | Pi truncates text results over 20 KB (full text is saved to a file). Keep `DEEPSEEK_FETCH_MAX_CHARS` at or below 20000 to truncate deterministically. |
-| Request fails around 60 seconds | Pi's per-request default timeout is 60 s; raise the server's `timeout` if you raise `DEEPSEEK_*_TIMEOUT_MS` beyond it. |
-| Config change does not take effect | Run `/reload` in the session or start a new one. |
+| Project-scope install does not load | Pi gates project-local files behind project trust; approve the project when prompted (or launch with `--approve`). |
 
 ## Compatibility
 
 | Component | Version |
 | --- | --- |
 | Pi | locked in [`docs/hosts.jsonc`](../hosts.jsonc) |
-| MCP revision | `2025-11-25` negotiated; server accepts `2024-11-05`–`2026-07-28` |
-| MCP SDK | `@modelcontextprotocol/server` 2.3.1 |
-| Runtime | Node.js 20+ (stdio) |
+| Extension entry | `src/pi/extension.ts` via the package's `pi` manifest (jiti, no build step) |
+| Runtime | Inside the Pi process (Node, host-provided) |
 | DeepSeek API | `/v1/tools/search`, `/v1/tools/fetch` |
 
-Pi 1.3.0 supports stdio and Streamable HTTP servers; this guide uses stdio. Tested with
-Pi 1.3.0 on Linux over stdio; the dual-era protocol behavior is covered by the SDK client
-test personas (`2024-11-05`, `2025-06-18`, `2025-11-25`, `2026-07-28`).
+Tested with Pi 1.3.0 on Linux. The extension API is version-locked research surface: the
+`ToolDefinition` shape and the settings `packages` key are verified at the locked version
+(see [the per-host reference](../research/control-matrix.md#pi)).
 
 ## Uninstall
 
@@ -200,10 +175,37 @@ With the installer CLI:
 npx deepseek-web-retrieval uninstall --host pi --scope <project|global>
 ```
 
-Or remove the `deepseek` entry from `~/.pi/agent/mcp.json` or `.pi/mcp.json`, or run:
+Or remove the source with Pi itself:
 
 ```bash
-pi mcp remove deepseek
+pi remove npm:deepseek-web-retrieval
 ```
 
 For a local-checkout install, also delete the cloned directory.
+
+## The MCP fallback path
+
+The same package ships a stdio MCP server (`npx deepseek-web-retrieval`). It works on Pi
+through `~/.pi/agent/mcp.json` or `.pi/mcp.json`:
+
+```jsonc
+{
+  "mcpServers": {
+    "deepseek": {
+      "command": "npx",
+      "args": ["-y", "deepseek-web-retrieval"],
+      "env": { "DEEPSEEK_API_KEY": "${DEEPSEEK_API_KEY}" },
+      "exposure": "direct"
+    }
+  }
+}
+```
+
+The tools appear as `mcp__deepseek__deepseek_web_search` and `mcp__deepseek__deepseek_fetch`,
+and the MCP layer's limits apply instead: text results over 20 KB are middle-truncated with
+the full text saved to a file (keep `DEEPSEEK_FETCH_MAX_CHARS` at or below 20000 to truncate
+deterministically), and the per-request default timeout is 60 s (raise the entry's `timeout`
+if you raise `DEEPSEEK_*_TIMEOUT_MS` beyond it). `pi mcp list` verifies the handshake, and
+config changes load with `/reload` or a new session. `npx deepseek-web-retrieval init
+--host pi --path mcp ...` installs this shape with plan-then-apply semantics; see
+[`examples/pi.mcp.jsonc`](../../examples/pi.mcp.jsonc).

package/docs/design/installer-design.md

@@ -116,6 +116,21 @@ scope choice would overlap the other scope's record — Codex's project-scope fa
 onto `~/.codex/config.toml` beside a global install — the plan refuses with guidance,
 and uninstall runs the same check defensively before touching anything.
 
+Shared config files also carry an owner-only sidecar beside the actual file
+(`.config.toml.deepseek-web-retrieval.codex.owner.json` for Codex). It points to the
+owning install record and project directory, so two different project directories
+cannot both claim the same global config, even with different `XDG_CONFIG_HOME`
+values. Planning reports this metadata write; apply acquires the claim before
+writing config and rechecks ownership, and uninstall releases it. A failed first
+apply releases its new claim; a failed re-init retains the previous owner's claim.
+Project-local configs and shared rules blocks do not need these sidecars.
+
+For installs created before this ownership metadata existed, re-run init from the
+original project and scope to establish the claim. An installer-style registration
+without a record at the requested location is refused rather than adopted as a new
+snapshot. If an identical registration was created manually, remove it before init.
+Do not delete an ownership sidecar while its install is still active.
+
 ## Rollback
 
 Uninstall reverses exactly what the plan applied: overwritten values restore their
@@ -127,14 +142,17 @@ pointing at the removed plugin, and the user must clean up by hand.
 
 ## Tier-to-artifact mapping
 
+Pi has two integration paths (`--path extension` by default, `--path mcp` as the fallback);
+the artifacts below name the path where they differ.
+
 | Choice | Artifacts |
 | --- | --- |
-| Optional | Host config registering the server, plus host-side per-tool filtering where supported (Copilot `tools` whitelist, Codex `enabled_tools`); Pi needs `"exposure": "direct"` |
-| Preferred | The above plus a rules file for the host (file names per host in the [per-host reference](../research/control-matrix.md#per-host-reference)) |
+| Optional | Host config registering the integration: Pi's extension path appends an `npm:<package>` source to `packages` in settings.json; the MCP paths register the server (Pi's MCP entry needs `"exposure": "direct"`; the extension path needs nothing — extension tools are `direct` by Pi's own default) |
+| Preferred | The above plus a rules file for the host (file names per host in the [per-host reference](../research/control-matrix.md#per-host-reference)); the rules name the path's tool ids (`deepseek_web_search` for the extension, `mcp__deepseek__deepseek_web_search` for MCP) |
 | Forced (replacement) | OpenCode plugin options (`setDefaultWebsearch` / `fetchOverrideWebfetch`) |
-| Forced (exclusion) | The built-in competitor's kill switch (per-host keys in the per-host reference), plus the exclusion of any other web-capable MCP servers the detect phase found — Pi sets their `enabled` key to `false`; Codex, lacking a per-server kill switch, refuses the tier instead |
+| Forced (exclusion) | The built-in competitor's kill switch (per-host keys in the per-host reference), plus the exclusion of any other web-capable MCP servers the detect phase found — Pi sets their `enabled` key to `false`; Codex, lacking a per-server kill switch, refuses the tier instead; Pi's extension path additionally refuses when a web-capable `packages`/`extensions` source is listed in settings.json (no per-package kill switch exists) |
 | Forced (de-facto) | Nothing beyond the Optional artifacts — no competitor exists |
-| Off | The MCP entry with the capability's false-only server-side switch instead of that tool (`DEEPSEEK_ENABLE_SEARCH` / `DEEPSEEK_ENABLE_FETCH`); both capabilities off refuses to install |
+| Off | Codex writes the capability's raw tool name into the server entry's `disabled_tools` (host-native: the tool leaves the model's context; the user's own entries in that array are kept); the other MCP entry writes the capability's false-only server-side switch instead (`DEEPSEEK_ENABLE_SEARCH` / `DEEPSEEK_ENABLE_FETCH`); Pi's extension path writes the same switches into the `deepseekWebRetrieval` settings namespace the extension reads at load; both capabilities off refuses to install |
 
 OpenCode additionally appends `permissions` allow entries for exactly the tools it
 registers (`websearch`, `deepseek_fetch`, and `webfetch` when fetch is forced), merged
@@ -146,10 +164,13 @@ into any existing `permissions` array rather than replacing it.
   request; deterministic routing removes both the model's discretion and its restraint as
   a cost brake. Every forced-tier plan carries a note naming the README's "Privacy and
   cost" section.
-- **Rules content.** Name the full tool ids (`mcp__deepseek__deepseek_web_search`), state
-  trigger conditions rather than unconditional preference, and list exclusions
-  (localhost/private-network URLs go to local fetch tools; the server blocks them by
-  default).
+- **Rules content.** Name the full tool ids the host will see (`mcp__deepseek__deepseek_web_search`
+  over MCP, `deepseek_web_search` over Pi's extension), state trigger conditions rather than
+  unconditional preference, and list exclusions (localhost/private-network URLs go to local
+  fetch tools; the server blocks them by default). Emit routing guidance only for the
+  capability selected as preferred; an optional capability stays optional even when the
+  other capability is preferred. Missing, reversed, or duplicate block markers refuse
+  planning, apply, and uninstall without deleting the ambiguous surrounding text.
 
 ## Implementation notes
 
@@ -162,11 +183,22 @@ into any existing `permissions` array rather than replacing it.
   records snapshots, appended entries, created files, and created path prefixes — never
   full file contents, so other servers' secrets stay out of the state file.
 - Re-applying over a previous init inherits the original snapshots instead of recording
-  the installer's own output as the "previous" value.
+  the installer's own output as the "previous" value. Pi forced re-inits keep their
+  competitor-disable ops even when those servers are already disabled, so orphan
+  reverts cannot re-enable a still-excluded competitor.
 - Verify is file-level: after apply it re-reads each written file and asserts every op
   holds (set values in place, appended entries present, rules block present). Higher
   layers would be a plan-time detect concern, and none of the three shipped hosts
   documents a layer above user config, so there is nothing to check there yet.
+- Only a bare `--apply` enables writes; assigning a value such as `--apply=false`
+  is a usage error and writes nothing.
+- File verification precedes the install-record commit. A write or verification
+  failure restores the pre-apply files and record and checks the restored values.
+  `ApplyError.status` is `rolled_back` only after recovery and new-claim cleanup
+  succeed. Otherwise it is `recovery_required`, with the original cause and a
+  recovery report; new claims remain while file or record recovery is incomplete.
+  Obsolete claims are released after commit. If that cleanup fails, the verified
+  install and new record are retained and reported explicitly for recovery.
 
 ## Server-side gap (resolved)
 
@@ -182,3 +214,34 @@ Claude Code, Cursor, Devin, GitHub Copilot, and Cline still have no
 host module; their artifacts (from the tier-to-artifact mapping) remain hand-edited
 config until a module lands here. OpenCode's `opencode plugin add` remains available but
 cannot pass options or manage snapshots; `init` supersedes it for tiered installs.
+
+
+### Persistence and concurrent operations
+
+Install records distinguish absent files from invalid or unreadable files. The
+reader validates version, host/scope identity, tiers, file metadata, and recorded
+operations before an install or uninstall can use undo state. `list` reports a
+bad record instead of silently omitting it. Restore the record from backup or
+repair access before retrying; deleting it can discard the original snapshots.
+
+Config and record writes use private temporary files in the target directory,
+verify the temporary contents, flush the file, then rename and flush the directory
+(on POSIX). Existing config permissions and valid symbolic links are preserved;
+records are always mode 0600. A failed write before rename leaves the old file
+intact. This makes each file replacement atomic, not the entire multi-file install.
+The apply rollback remains responsible for caught errors; power-loss recovery is
+not an automatic transaction replay.
+
+Apply and uninstall acquire a record operation lock before reading undo state,
+then locks for every config/rules path they may mutate, including orphan reverts.
+Locks follow canonical paths, so another project or symlink alias cannot bypass a
+shared-file lock. A plan whose prior record changed is refused, even if its only
+edits append arrays. Preview generation is read-only and does not reserve locks.
+
+Operation locks are directories ending in `.deepseek-web-retrieval.lock`, with
+owner PID and start time inside. Ordinary success or failure releases them. A
+killed process may leave a lock: after confirming no installer is running, inspect
+config, install record, and persistent ownership claims, restore any inconsistent
+state, then remove the reported lock directory and generate a new plan. Locks are
+never stolen based only on age or PID. Persistent `.owner.json` claims remain a
+separate safeguard against two installations owning one shared config.

package/docs/hosts.jsonc

@@ -82,13 +82,13 @@
       "npm": "@earendil-works/pi-coding-agent",
       "nativeSearchProvider": false,
       "nativeFetchOverride": false,
-      "paths": ["mcp", "extension"],
+      "paths": ["extension", "mcp"],
       "status": "supported",
       "control": {
         "search": { "optional": "yes", "preferred": "yes", "forced": "de-facto", "key": "no built-in web tool at 1.3.0 (source-verified)" },
         "fetch": { "optional": "yes", "preferred": "yes", "forced": "de-facto", "key": "no built-in web tool at 1.3.0 (source-verified)" }
       },
-      "adapter": "src/mcp",
+      "adapter": "src/pi",
       "installer": "src/installer/hosts/pi",
       "guide": "docs/agents/pi.md",
       "e2eScenario": "pi"

package/docs/integration.md

@@ -16,8 +16,8 @@ ship built-in web tools. MCP tools can add equivalent tools, but do not replace
 | Native websearch provider | Yes | No | Host plugin API | OpenCode v2 adapter |
 | Native tool / fetch override | No | Yes | Host tool API | OpenCode v2 adapter |
 | Custom tool plugin | Yes | Yes | Host plugin API | Cline CLI/SDK; no adapter yet |
-| Extension API | Yes | Yes | Host extension API | Pi; no adapter yet |
-| MCP server | Yes | Yes | Host MCP client | Shipped (`src/mcp/`; Pi guide first) |
+| Extension API | Yes | Yes | Host extension API | Pi adapter (`src/pi/`) |
+| MCP server | Yes | Yes | Host MCP client | Shipped (`src/mcp/`; Pi and Codex guides) |
 | CLI/HTTP wrapper | Yes | Yes | Host can call external tools | Not shipped |
 
 MCP is a protocol, not an agent. It is one possible transport for hosts that support MCP
@@ -34,7 +34,7 @@ Rows are sorted with open-source hosts first, then by host name alphabetically.
 | Cline | 0.0.13 | Yes (Apache-2.0) | No | No | MCP server or custom tool plugin | No adapter yet |
 | Codex | 0.163.0 | Yes (Apache-2.0) | No | No | MCP server | Supported |
 | OpenCode | 2.0.32 | Yes (MIT) | Yes | Yes | native websearch provider or native tool/fetch override | Supported |
-| Pi | 1.3.0 | Yes (MIT) | No | No | MCP server or extension API | Supported |
+| Pi | 1.3.0 | Yes (MIT) | No | No | extension API or MCP server | Supported |
 | Claude Code | 2.1.303 | No | No | No | MCP server | No adapter yet |
 | Cursor | 2026.10.08 | No | No | No | MCP server | No adapter yet |
 | Devin | 3000.11.92 | No | No | No | MCP server | No adapter yet |
@@ -78,14 +78,18 @@ the details: built-in web tools and their kill switches, MCP registration, and r
   [Cline](research/control-matrix.md#cline).
 - **Devin** — Ships built-in `web_search` and `webfetch` tools. See
   [Devin](research/control-matrix.md#devin).
-- **Pi** — No built-in web tools; MCP plus a TypeScript extension API. Supported through
-  the MCP server; see [Pi](agents/pi.md) and [Pi in the per-host reference](research/control-matrix.md#pi).
+- **Pi** — No built-in web tools; a TypeScript extension API plus MCP. Supported through
+  the native extension adapter (the recommended path), with the MCP server as the fallback;
+  see [Pi](agents/pi.md) and [Pi in the per-host reference](research/control-matrix.md#pi).
 
 ## Roadmap
 
-- **MCP server** — shipped in `src/mcp/` with the [Pi](agents/pi.md) guide; the broadest path for
-  hosts that support MCP tools. Protocol compatibility across these hosts is researched in
+- **MCP server** — shipped in `src/mcp/` (the fallback path in the [Pi](agents/pi.md) guide
+  and the path in the [Codex](agents/codex.md) guide); the broadest route for hosts that
+  support MCP tools. Protocol compatibility across these hosts is researched in
   [mcp-compatibility.md](research/mcp-compatibility.md).
+- **Native extension adapters** — the Pi extension adapter ships in `src/pi/`; a host whose
+  extension point can register tools directly gets a native path alongside MCP.
 - **Host-specific guides** — added as requests and testing land; the server itself is
   host-agnostic.
 
@@ -94,8 +98,9 @@ the details: built-in web tools and their kill switches, MCP registration, and r
 - OpenCode: [plugin API](https://opencode.ai/v2/docs/build/plugins)
 - Claude Code: [MCP](https://code.claude.com/docs/en/mcp),
   [tools reference](https://code.claude.com/docs/en/tools-reference)
-- Codex: [MCP](https://developers.openai.com/codex/mcp),
-  [CLI](https://developers.openai.com/codex/cli)
+- Codex: [MCP](https://learn.chatgpt.com/docs/extend/mcp),
+  [CLI](https://learn.chatgpt.com/docs/codex/cli),
+  [config reference](https://learn.chatgpt.com/docs/config-file/config-reference)
 - Cursor: [MCP](https://cursor.com/docs/mcp),
   [CLI changelog](https://cursor.com/docs/cli/changelog)
 - Copilot CLI: [repository](https://github.com/github/copilot-cli),