pi-better-web-search 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,21 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.2
4
+
5
+ - Remove provider/model routing metadata from the model-facing JSON output
6
+ (`search` and `fetched[]`). Routing metadata remains in `details` for UI and
7
+ logs and is not sent to the model.
8
+ - Update the architecture diagram to show all 10 supported provider classes
9
+ plus Anthropic Messages.
10
+ - Refresh the README, Chinese README, design notes, and architecture docs for the
11
+ new output shape.
12
+ - Verification: 116 tests pass, and the package contents pass verification.
13
+
14
+ ## 0.1.1
15
+
16
+ - Align directory structure with Pi extension conventions (`extensions/index.ts` and `lib/`), eliminating the `:src` suffix in Pi's startup banner.
17
+ - Highlight and expand documentation for all 10 supported provider classes: DeepSeek, Google Gemini, Google Antigravity, Ollama Cloud, OpenAI, Azure OpenAI, OpenAI Codex, GitHub Copilot, OpenCode, and xAI Grok (plus Anthropic Messages).
18
+
3
19
  ## 0.1.0
4
20
 
5
21
  Initial release of `pi-better-web-search`.
package/CONTRIBUTING.md CHANGED
@@ -37,8 +37,8 @@ step and no runtime dependency to bundle.
37
37
 
38
38
  ## Provider work
39
39
 
40
- A provider adapter lives in `src/providers/<family>.ts` and follows the
41
- `ProviderAdapter` contract in `src/providers/types.ts`. Return provider data
40
+ A provider adapter lives in `lib/providers/<family>.ts` and follows the
41
+ `ProviderAdapter` contract in `lib/providers/types.ts`. Return provider data
42
42
  unchanged. `search()` should throw when the provider did not perform a search;
43
43
  `fetch()` should return one entry per URL and put per-URL failures in
44
44
  `entry.error`.
package/README.md CHANGED
@@ -8,12 +8,12 @@ provider supports it, automatically falls back across authenticated providers,
8
8
  and returns provider data as-is.
9
9
 
10
10
  [![CI](https://github.com/zhexusun10/pi-better-web-search/actions/workflows/ci.yml/badge.svg)](https://github.com/zhexusun10/pi-better-web-search/actions/workflows/ci.yml)
11
- [![npm](https://img.shields.io/badge/npm-v0.1.0-blue)](https://www.npmjs.com/package/pi-better-web-search)
11
+ [![npm](https://img.shields.io/badge/npm-v0.1.1-blue)](https://www.npmjs.com/package/pi-better-web-search)
12
12
  [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
13
13
  [![Pi 1.3](https://img.shields.io/badge/Pi-1.3-blue.svg)](https://pi.dev)
14
14
  [![Node](https://img.shields.io/badge/node-%3E%3D22.19-339933.svg)](https://nodejs.org)
15
15
 
16
- [简体中文](docs/README.zh-CN.md) · [Architecture](docs/architecture.md) · [Providers](docs/providers.md) · [Testing](docs/testing.md) · [Source](src/index.ts)
16
+ [简体中文](docs/README.zh-CN.md) · [Architecture](docs/architecture.md) · [Providers](docs/providers.md) · [Testing](docs/testing.md) · [Source](extensions/index.ts)
17
17
 
18
18
  ![pi-better-web-search architecture](https://raw.githubusercontent.com/zhexusun10/pi-better-web-search/main/assets/architecture.svg)
19
19
 
@@ -99,14 +99,21 @@ invalid URLs alongside valid work are reported in the `fetched` entries.
99
99
 
100
100
  ## Provider support
101
101
 
102
- | Provider / family | Web search | URL analysis | Native interface |
103
- | --- | --- | --- | --- |
104
- | DeepSeek | Yes | Yes | Native Search and Fetch: `/v1/tools/search`, `/v1/tools/fetch` |
105
- | Ollama Cloud | Yes | Yes | `/api/web_search`, `/api/web_fetch` |
106
- | Google Gemini / Antigravity | Yes | Yes | `google_search` grounding and `url_context` |
107
- | OpenAI / Azure / Codex / Copilot / OpenCode | Yes | No | Responses API `web_search` tool |
108
- | xAI Grok | Yes | No | Responses API `web_search` tool |
109
- | Anthropic Messages | Yes | No | `web_search` server tool |
102
+ `pi-better-web-search` natively supports **10 distinct provider classes** (plus Anthropic Messages), automatically detecting authenticated credentials and routing each call through native provider protocols:
103
+
104
+ | # | Provider Class | Web Search | URL Analysis | Native Protocol & Endpoint |
105
+ |:---:|---|:---:|:---:|---|
106
+ | 1 | **DeepSeek** | Yes | Yes | Native REST `/v1/tools/search` & `/v1/tools/fetch` |
107
+ | 2 | **Google Gemini** | Yes | Yes | `google-generative-ai` SSE `google_search` grounding & `url_context` |
108
+ | 3 | **Google Antigravity** | Yes | Yes | Antigravity enterprise Vertex endpoint & wrapper body |
109
+ | 4 | **Ollama Cloud** | Yes | Yes | Hosted REST `/api/web_search` & `/api/web_fetch` (`ollama.com`) |
110
+ | 5 | **OpenAI** | Yes | No | Official Responses API `web_search` tool (`openai-responses`) |
111
+ | 6 | **Azure OpenAI** | Yes | No | Azure Responses API (`azure-openai-responses`) |
112
+ | 7 | **OpenAI Codex** | Yes | No | Specialized `/codex/responses` with Codex account tokens & headers |
113
+ | 8 | **GitHub Copilot** | Yes | No | Responses routing with Copilot auth tokens & proxy endpoints |
114
+ | 9 | **OpenCode** | Yes | No | Responses routing with Pi session tracking headers |
115
+ | 10 | **xAI (Grok)** | Yes | No | Grok dialect Responses API (`web_search_call.action.sources`) |
116
+ | * | **Anthropic Messages** | Yes | No | Messages API `web_search_20260209` tool & Claude Code OAuth |
110
117
 
111
118
  URL analysis is only exposed when at least one usable interface supports it.
112
119
  For example, a current OpenAI model with only OpenAI credentials gets a
@@ -115,13 +122,12 @@ credentials also gets `urls`.
115
122
 
116
123
  Provider detection follows the authenticated model's provider/API:
117
124
 
118
- 1. `deepseek` provider
119
- 2. Antigravity or Google Generative AI
125
+ 1. `deepseek` provider (DeepSeek native search/fetch)
126
+ 2. Antigravity or Google Generative AI (Google Gemini & Google Antigravity)
120
127
  3. Ollama Cloud (`ollama-cloud` provider or exact `ollama.com` host)
121
- 4. xAI with `openai-responses`
122
- 5. OpenAI-compatible Responses APIs (`openai-responses`,
123
- `azure-openai-responses`, `openai-codex-responses`)
124
- 6. Anthropic Messages
128
+ 4. xAI with `openai-responses` (xAI Grok)
129
+ 5. OpenAI-compatible Responses APIs (OpenAI, Azure OpenAI, OpenAI Codex, GitHub Copilot, OpenCode)
130
+ 6. Anthropic Messages (Claude)
125
131
 
126
132
  See [Providers](docs/providers.md) for request shapes, auth quirks, and URL
127
133
  support per family.
@@ -216,8 +222,6 @@ this:
216
222
  {
217
223
  "query": "the query",
218
224
  "search": {
219
- "provider": "deepseek",
220
- "model": "deepseek-chat",
221
225
  "answer": "provider text when available",
222
226
  "results": "the provider's raw results",
223
227
  "citations": "the provider's raw citations",
@@ -227,8 +231,6 @@ this:
227
231
  "fetched": [
228
232
  {
229
233
  "url": "https://example.com",
230
- "provider": "deepseek",
231
- "model": "deepseek-chat",
232
234
  "data": "the provider's raw fetch payload"
233
235
  }
234
236
  ]
@@ -1,6 +1,6 @@
1
1
  <svg xmlns="http://www.w3.org/2000/svg" width="1200" height="640" viewBox="0 0 1200 640" role="img" aria-labelledby="title desc">
2
2
  <title id="title">pi-better-web-search architecture</title>
3
- <desc id="desc">One web_search tool routes to provider-native search APIs, falls back across authenticated providers, and returns raw provider JSON with a size guard.</desc>
3
+ <desc id="desc">One web_search tool routes across ten provider classes, falls back across authenticated providers, and returns raw provider JSON with a size guard.</desc>
4
4
  <defs>
5
5
  <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
6
6
  <path d="M 0 0 L 10 5 L 0 10 z" fill="#52525b"/>
@@ -16,8 +16,13 @@
16
16
  .h { font: 700 18px Arial, Helvetica, sans-serif; fill: #18181b; }
17
17
  .t { font: 400 15px Arial, Helvetica, sans-serif; fill: #3f3f46; }
18
18
  .muted { font: 400 14px Arial, Helvetica, sans-serif; fill: #71717a; }
19
+ .p { font: 700 13px Arial, Helvetica, sans-serif; fill: #18181b; }
20
+ .d { font: 400 10.5px Arial, Helvetica, sans-serif; fill: #71717a; }
19
21
  .inv-h { font: 700 18px Arial, Helvetica, sans-serif; fill: #ffffff; }
20
22
  .inv-t { font: 400 14px Arial, Helvetica, sans-serif; fill: #e4e4e7; }
23
+ .inv-p { font: 700 13px Arial, Helvetica, sans-serif; fill: #ffffff; }
24
+ .inv-d { font: 400 10.5px Arial, Helvetica, sans-serif; fill: #e4e4e7; }
25
+ .note { font: 400 11px Arial, Helvetica, sans-serif; fill: #71717a; }
21
26
  .arrow { stroke: #52525b; stroke-width: 2; fill: none; marker-end: url(#arrow); }
22
27
  .label { font: 600 13px Arial, Helvetica, sans-serif; fill: #52525b; }
23
28
  .footer { font: 400 14px Arial, Helvetica, sans-serif; fill: #71717a; }
@@ -28,57 +33,80 @@
28
33
  <rect class="panel" x="20" y="20" width="1160" height="600" rx="22"/>
29
34
 
30
35
  <text class="title" x="56" y="82">pi-better-web-search</text>
31
- <text class="subtitle" x="56" y="116">one tool · provider-native search · raw results</text>
36
+ <text class="subtitle" x="56" y="116">one tool · 10 provider classes · raw results</text>
32
37
 
33
- <rect class="box" x="56" y="166" width="226" height="136" rx="16"/>
34
- <text class="h" x="78" y="198">Current pi model</text>
35
- <text class="t" x="78" y="226">supports search?</text>
36
- <text class="muted" x="78" y="252">yes → use it first</text>
37
- <text class="muted" x="78" y="274">no → fallback</text>
38
+ <rect class="box" x="56" y="150" width="220" height="124" rx="16"/>
39
+ <text class="h" x="76" y="180">Current pi model</text>
40
+ <text class="t" x="76" y="208">supports search?</text>
41
+ <text class="muted" x="76" y="234">yes → use it first</text>
42
+ <text class="muted" x="76" y="256">no → fallback</text>
38
43
 
39
- <path class="arrow" d="M 286 234 L 334 234"/>
40
- <text class="label" x="292" y="222">route</text>
44
+ <path class="arrow" d="M 276 212 L 306 212"/>
45
+ <text class="label" x="280" y="200">route</text>
41
46
 
42
- <rect class="box" x="342" y="166" width="248" height="136" rx="16"/>
43
- <text class="h" x="364" y="198">Candidate router</text>
44
- <text class="t" x="364" y="226">current → cached →</text>
45
- <text class="t" x="364" y="248">family priority</text>
46
- <text class="muted" x="364" y="274">fingerprint-aware cache</text>
47
+ <rect class="box" x="312" y="150" width="250" height="124" rx="16"/>
48
+ <text class="h" x="332" y="180">Candidate router</text>
49
+ <text class="t" x="332" y="208">current → cached →</text>
50
+ <text class="t" x="332" y="230">family priority</text>
51
+ <text class="muted" x="332" y="256">fingerprint-aware cache</text>
47
52
 
48
- <path class="arrow" d="M 594 234 L 642 234"/>
49
- <text class="label" x="600" y="222">try in order</text>
53
+ <path class="arrow" d="M 562 212 L 598 212"/>
54
+ <text class="label" x="568" y="200">try in order</text>
50
55
 
51
- <text class="h" x="650" y="126">provider adapters</text>
52
- <rect class="dash" x="642" y="140" width="258" height="318" rx="18"/>
56
+ <rect class="dash" x="604" y="112" width="340" height="350" rx="18"/>
57
+ <text class="h" x="624" y="142">provider adapters</text>
58
+ <text class="muted" x="920" y="142" text-anchor="end">10 classes</text>
53
59
 
54
- <rect class="accent" x="654" y="152" width="234" height="52" rx="12"/>
55
- <text class="inv-h" x="672" y="175">DeepSeek</text>
56
- <text class="inv-t" x="672" y="194">native search + fetch</text>
60
+ <rect class="accent" x="616" y="154" width="152" height="46" rx="10"/>
61
+ <text class="inv-p" x="630" y="172">DeepSeek</text>
62
+ <text class="inv-d" x="630" y="187">native search + fetch</text>
57
63
 
58
- <rect class="box" x="654" y="214" width="234" height="52" rx="12"/>
59
- <text class="h" x="672" y="237">Ollama Cloud</text>
60
- <text class="t" x="672" y="256">search + fetch</text>
64
+ <rect class="box" x="616" y="208" width="152" height="46" rx="10"/>
65
+ <text class="p" x="630" y="226">Google Gemini</text>
66
+ <text class="d" x="630" y="241">search + URL context</text>
61
67
 
62
- <rect class="box" x="654" y="276" width="234" height="52" rx="12"/>
63
- <text class="h" x="672" y="299">Google Gemini</text>
64
- <text class="t" x="672" y="318">search + URL context</text>
68
+ <rect class="box" x="616" y="262" width="152" height="46" rx="10"/>
69
+ <text class="p" x="630" y="280">Google Antigravity</text>
70
+ <text class="d" x="630" y="295">search + URL context</text>
65
71
 
66
- <rect class="box" x="654" y="338" width="234" height="52" rx="12"/>
67
- <text class="h" x="672" y="361">OpenAI / xAI</text>
68
- <text class="t" x="672" y="380">Responses web search</text>
72
+ <rect class="box" x="616" y="316" width="152" height="46" rx="10"/>
73
+ <text class="p" x="630" y="334">Ollama Cloud</text>
74
+ <text class="d" x="630" y="349">search + fetch</text>
69
75
 
70
- <rect class="box" x="654" y="400" width="234" height="52" rx="12"/>
71
- <text class="h" x="672" y="423">Anthropic</text>
72
- <text class="t" x="672" y="442">Messages web search</text>
76
+ <rect class="box" x="616" y="370" width="152" height="46" rx="10"/>
77
+ <text class="p" x="630" y="388">OpenAI</text>
78
+ <text class="d" x="630" y="403">Responses web search</text>
73
79
 
74
- <path class="arrow" d="M 906 234 L 954 234"/>
75
- <text class="label" x="912" y="222">raw</text>
80
+ <rect class="box" x="776" y="154" width="152" height="46" rx="10"/>
81
+ <text class="p" x="790" y="172">Azure OpenAI</text>
82
+ <text class="d" x="790" y="187">Azure Responses</text>
76
83
 
77
- <rect class="box" x="962" y="166" width="178" height="136" rx="16"/>
78
- <text class="h" x="982" y="198">Tool result</text>
79
- <text class="t" x="982" y="226">raw JSON</text>
80
- <text class="muted" x="982" y="252">no cleanup</text>
81
- <text class="muted" x="982" y="274">64k char guard</text>
84
+ <rect class="box" x="776" y="208" width="152" height="46" rx="10"/>
85
+ <text class="p" x="790" y="226">OpenAI Codex</text>
86
+ <text class="d" x="790" y="241">Codex Responses</text>
87
+
88
+ <rect class="box" x="776" y="262" width="152" height="46" rx="10"/>
89
+ <text class="p" x="790" y="280">GitHub Copilot</text>
90
+ <text class="d" x="790" y="295">Copilot Responses</text>
91
+
92
+ <rect class="box" x="776" y="316" width="152" height="46" rx="10"/>
93
+ <text class="p" x="790" y="334">OpenCode</text>
94
+ <text class="d" x="790" y="349">OpenCode Responses</text>
95
+
96
+ <rect class="box" x="776" y="370" width="152" height="46" rx="10"/>
97
+ <text class="p" x="790" y="388">xAI Grok</text>
98
+ <text class="d" x="790" y="403">Grok Responses</text>
99
+
100
+ <text class="note" x="624" y="446">plus Anthropic Messages · native Messages web search</text>
101
+
102
+ <path class="arrow" d="M 944 212 L 974 212"/>
103
+ <text class="label" x="948" y="200">raw</text>
104
+
105
+ <rect class="box" x="980" y="150" width="160" height="124" rx="16"/>
106
+ <text class="h" x="1000" y="180">Tool result</text>
107
+ <text class="t" x="1000" y="208">raw JSON</text>
108
+ <text class="muted" x="1000" y="234">no cleanup</text>
109
+ <text class="muted" x="1000" y="256">64k char guard</text>
82
110
 
83
111
  <rect class="panel" x="56" y="492" width="1084" height="94" rx="16"/>
84
112
  <text class="h" x="78" y="522">Exposure &amp; memory</text>
@@ -6,7 +6,7 @@
6
6
  `web_search`。它使用各家 provider 的原生搜索接口,在可用 provider 支持时
7
7
  分析 URL,自动在已登录的 provider 之间切换,并把 provider 数据原样返回。
8
8
 
9
- [English](../README.md) · [架构说明](architecture.md) · [Provider 细节](providers.md) · [测试](testing.md) · [源码](../src/index.ts)
9
+ [English](../README.md) · [架构说明](architecture.md) · [Provider 细节](providers.md) · [测试](testing.md) · [源码](../extensions/index.ts)
10
10
 
11
11
  ![pi-better-web-search 架构](https://raw.githubusercontent.com/zhexusun10/pi-better-web-search/main/assets/architecture.svg)
12
12
 
@@ -81,28 +81,34 @@ provider 都失败时,工具返回错误(`isError: true`),不会静默
81
81
 
82
82
  ## Provider 支持
83
83
 
84
- | Provider / family | 网页搜索 | URL 分析 | 原生接口 |
85
- | --- | --- | --- | --- |
86
- | DeepSeek | 是 | 是 | 原生 Search/Fetch:`/v1/tools/search`、`/v1/tools/fetch` |
87
- | Ollama Cloud | 是 | 是 | `/api/web_search`、`/api/web_fetch` |
88
- | Google Gemini / Antigravity | 是 | 是 | `google_search` grounding 和 `url_context` |
89
- | OpenAI / Azure / Codex / Copilot / OpenCode | 是 | 否 | Responses API `web_search` |
90
- | xAI Grok | 是 | 否 | Responses API `web_search` |
91
- | Anthropic Messages | 是 | 否 | Messages `web_search` server tool |
84
+ `pi-better-web-search` 原生支持 **10 类主流 Provider**(及 Anthropic Messages),通过各家原生 API 协议接入,兼具最原汁原味的模型能力与极速体验:
85
+
86
+ | # | Provider 类别 | 网页搜索 | URL 分析 | 原生协议与端点接口 |
87
+ |:---:|---|:---:|:---:|---|
88
+ | 1 | **DeepSeek** | 是 | 是 | 原生 REST `/v1/tools/search` 与 `/v1/tools/fetch` |
89
+ | 2 | **Google Gemini** | 是 | 是 | `google-generative-ai` SSE `google_search` 与 `url_context` |
90
+ | 3 | **Google Antigravity** | 是 | 是 | Antigravity 企业级 Vertex 端点与专属包装体 |
91
+ | 4 | **Ollama Cloud** | 是 | 是 | 托管独立 REST `/api/web_search` 与 `/api/web_fetch`(`ollama.com`) |
92
+ | 5 | **OpenAI** | 是 | 否 | 官方 Responses API `web_search` 工具(`openai-responses`) |
93
+ | 6 | **Azure OpenAI** | 是 | 否 | Azure Responses API 专用端点(`azure-openai-responses`) |
94
+ | 7 | **OpenAI Codex** | 是 | 否 | 专有 `/codex/responses` 端点,支持 Codex 账号 Token 与 Originator 协议 |
95
+ | 8 | **GitHub Copilot** | 是 | 否 | Copilot 鉴权凭证路由与兼容代理端点 Responses 搜索 |
96
+ | 9 | **OpenCode** | 是 | 否 | 携带 Pi 会话追踪请求头的 Responses 搜索 |
97
+ | 10 | **xAI (Grok)** | 是 | 否 | 原生 Grok 方言 Responses API(`web_search_call.action.sources`) |
98
+ | * | **Anthropic Messages** | 是 | 否 | Messages API `web_search_20260209` 工具及 Claude Code OAuth 凭据 |
92
99
 
93
100
  只有至少一个可用接口支持 URL 分析时,`urls` 才会暴露。例如:当前模型是
94
101
  OpenAI 且只有 OpenAI 凭据时,schema 只有 `query`;同一会话只要还有
95
- DeepSeek、Ollama Cloud 或 Google 凭据,就会出现 `urls`。
102
+ DeepSeek、Google Gemini、Antigravity 或 Ollama Cloud 凭据,就会出现 `urls`。
96
103
 
97
104
  Provider 识别顺序:
98
105
 
99
- 1. `deepseek` provider
100
- 2. Antigravity 或 Google Generative AI
106
+ 1. `deepseek` provider(DeepSeek 原生 search/fetch)
107
+ 2. Antigravity 或 Google Generative AI(Google Gemini 与 Google Antigravity)
101
108
  3. Ollama Cloud(`ollama-cloud` provider,或 host 精确为 `ollama.com`)
102
- 4. xAI + `openai-responses`
103
- 5. OpenAI-compatible Responses API(`openai-responses`、
104
- `azure-openai-responses`、`openai-codex-responses`)
105
- 6. Anthropic Messages
109
+ 4. xAI + `openai-responses`(xAI Grok)
110
+ 5. OpenAI-compatible Responses API(OpenAI、Azure OpenAI、OpenAI Codex、GitHub Copilot、OpenCode)
111
+ 6. Anthropic Messages(Claude)
106
112
 
107
113
  各 provider 的请求形状、鉴权细节和 URL 支持见 [Provider 细节](providers.md)。
108
114
 
@@ -183,8 +189,6 @@ Provider 数据放在 JSON 外层中返回,不做清理。示例:
183
189
  {
184
190
  "query": "the query",
185
191
  "search": {
186
- "provider": "deepseek",
187
- "model": "deepseek-chat",
188
192
  "answer": "provider text when available",
189
193
  "results": "the provider's raw results",
190
194
  "citations": "the provider's raw citations",
@@ -194,8 +198,6 @@ Provider 数据放在 JSON 外层中返回,不做清理。示例:
194
198
  "fetched": [
195
199
  {
196
200
  "url": "https://example.com",
197
- "provider": "deepseek",
198
- "model": "deepseek-chat",
199
201
  "data": "the provider's raw fetch payload"
200
202
  }
201
203
  ]
@@ -136,8 +136,6 @@ The result is a JSON wrapper:
136
136
  {
137
137
  query?: string;
138
138
  search?: {
139
- provider: ProviderFamily;
140
- model: string;
141
139
  answer?: string;
142
140
  results?: unknown;
143
141
  citations?: unknown;
@@ -147,8 +145,6 @@ The result is a JSON wrapper:
147
145
  };
148
146
  fetched?: Array<{
149
147
  url: string;
150
- provider?: ProviderFamily;
151
- model?: string;
152
148
  data?: unknown;
153
149
  error?: string;
154
150
  }>;
@@ -189,21 +185,21 @@ interface ProviderAdapter {
189
185
 
190
186
  `search()` throws when the provider did not perform a search. `fetch()` returns
191
187
  one entry per requested URL; per-URL failures go in `entry.error`. Both honor
192
- the abort signal and resolve credentials through `src/auth.ts`.
188
+ the abort signal and resolve credentials through `lib/auth.ts`.
193
189
 
194
190
  ## File map
195
191
 
196
192
  | Path | Responsibility |
197
193
  | --- | --- |
198
- | `src/index.ts` | Tool registration, exposure sync, lifecycle handlers |
199
- | `src/candidates.ts` | Current/available candidates, ordering, cache resolution |
200
- | `src/search.ts` | Input validation, search/fetch fallback, cache writes, output |
201
- | `src/auth.ts` | Credential resolution, header merging, env fallback |
202
- | `src/cache.ts` | Preference cache and model-set fingerprint |
203
- | `src/families.ts` | Provider family detection |
204
- | `src/schema.ts` | Query-only and query+urls schema variants |
205
- | `src/format.ts` | JSON wrapper, output guard, success/error results |
206
- | `src/providers/` | Provider adapters, SSE reader, HTTP helpers |
194
+ | `extensions/index.ts` | Tool registration, exposure sync, lifecycle handlers |
195
+ | `lib/candidates.ts` | Current/available candidates, ordering, cache resolution |
196
+ | `lib/search.ts` | Input validation, search/fetch fallback, cache writes, output |
197
+ | `lib/auth.ts` | Credential resolution, header merging, env fallback |
198
+ | `lib/cache.ts` | Preference cache and model-set fingerprint |
199
+ | `lib/families.ts` | Provider family detection |
200
+ | `lib/schema.ts` | Query-only and query+urls schema variants |
201
+ | `lib/format.ts` | JSON wrapper, output guard, success/error results |
202
+ | `lib/providers/` | Provider adapters, SSE reader, HTTP helpers |
207
203
 
208
204
  ## Non-goals
209
205
 
package/docs/providers.md CHANGED
@@ -1,17 +1,23 @@
1
1
  # Providers
2
2
 
3
- The extension selects a provider family from the authenticated model's
4
- provider id, API id, and base URL. Each adapter owns one family's request shape,
5
- authentication, stream parsing, and error behavior.
6
-
7
- | Family | Detection | Search | URL analysis | Interface |
8
- | --- | --- | --- | --- | --- |
9
- | DeepSeek | provider `deepseek` | Yes | Yes | Native `/v1/tools/search`, `/v1/tools/fetch` |
10
- | Ollama | provider `ollama-cloud` or host `ollama.com` | Yes | Yes | `/api/web_search`, `/api/web_fetch` |
11
- | Google | api `google-generative-ai`, provider/api `antigravity` | Yes | Yes | `google_search`, `url_context` |
12
- | OpenAI | api `openai-responses`, `azure-openai-responses`, `openai-codex-responses` | Yes | No | Responses `web_search` |
13
- | xAI | provider `xai` with `openai-responses` | Yes | No | Responses `web_search` |
14
- | Anthropic | api `anthropic-messages` | Yes | No | Messages `web_search` |
3
+ The extension selects an adapter from the authenticated model's provider id,
4
+ API id, and base URL. We natively support **10 distinct provider classes** (plus
5
+ Anthropic Messages), each mapped to its native request shape, authentication,
6
+ stream parsing, and error behavior:
7
+
8
+ | # | Provider Class | Detection | Search | URL Analysis | Interface & Endpoint |
9
+ |:---:|---|---|:---:|:---:|---|
10
+ | 1 | **DeepSeek** | provider `deepseek` | Yes | Yes | Native REST `/v1/tools/search`, `/v1/tools/fetch` |
11
+ | 2 | **Google Gemini** | api `google-generative-ai` | Yes | Yes | SSE `google_search`, `url_context` |
12
+ | 3 | **Google Antigravity** | provider/api `antigravity` | Yes | Yes | Antigravity enterprise Vertex endpoint & wrapper |
13
+ | 4 | **Ollama Cloud** | provider `ollama-cloud` or host `ollama.com` | Yes | Yes | Hosted REST `/api/web_search`, `/api/web_fetch` |
14
+ | 5 | **OpenAI** | api `openai-responses` | Yes | No | Responses API `web_search` |
15
+ | 6 | **Azure OpenAI** | api `azure-openai-responses` | Yes | No | Azure Responses API `/responses` |
16
+ | 7 | **OpenAI Codex** | api `openai-codex-responses` | Yes | No | Codex `/codex/responses` & account tokens |
17
+ | 8 | **GitHub Copilot** | Copilot provider/token with Responses | Yes | No | Copilot Responses with token routing & proxy endpoints |
18
+ | 9 | **OpenCode** | OpenCode provider with Responses | Yes | No | Responses API with Pi session tracking headers |
19
+ | 10 | **xAI (Grok)** | provider `xai` or model `grok*` with Responses | Yes | No | Grok dialect Responses (`action.sources`) |
20
+ | * | **Anthropic Messages** | api `anthropic-messages` | Yes | No | Messages API `web_search_20260209` tool & OAuth |
15
21
 
16
22
  A model whose API is `openai-completions` is not search-capable unless it is
17
23
  served by DeepSeek or Ollama Cloud. A local Ollama daemon is not supported;
@@ -207,10 +213,10 @@ a per-URL error.
207
213
 
208
214
  ## Adding a provider
209
215
 
210
- 1. Add a family to `src/providers/types.ts` if it is genuinely new.
211
- 2. Create `src/providers/<family>.ts` exporting a `ProviderAdapter`.
212
- 3. Register it in `src/providers/index.ts`.
213
- 4. Add family detection in `src/families.ts`.
216
+ 1. Add a family to `lib/providers/types.ts` if it is genuinely new.
217
+ 2. Create `lib/providers/<family>.ts` exporting a `ProviderAdapter`.
218
+ 3. Register it in `lib/providers/index.ts`.
219
+ 4. Add family detection in `lib/families.ts`.
214
220
  5. Add tests for request shape, auth/header preservation, raw result
215
221
  preservation, search evidence, errors, aborts, and URL behavior.
216
222
  6. Update this document, `README.md`, and `CHANGELOG.md`.
@@ -30,7 +30,7 @@ local `pi-web-search` reference checkout, `.env` files, and `DESIGN.md`.
30
30
  npm run build
31
31
  ```
32
32
 
33
- This produces `dist/pi-better-web-search-0.1.0.tgz`. The tarball is not
33
+ This produces `dist/pi-better-web-search-0.1.2.tgz`. The tarball is not
34
34
  committed.
35
35
 
36
36
  ## Publish
@@ -42,7 +42,7 @@ npm publish --access public
42
42
  Alternatively, publish the verified tarball directly:
43
43
 
44
44
  ```bash
45
- npm publish dist/pi-better-web-search-0.1.0.tgz --access public
45
+ npm publish dist/pi-better-web-search-0.1.2.tgz --access public
46
46
  ```
47
47
 
48
48
  `prepublishOnly` reruns the checks, tests, and package verification. npm may
@@ -51,10 +51,10 @@ require browser or OTP authentication.
51
51
  ## Tag and release
52
52
 
53
53
  ```bash
54
- git tag -a v0.1.0 -m "v0.1.0"
55
- git push origin v0.1.0
56
- gh release create v0.1.0 dist/pi-better-web-search-0.1.0.tgz \
57
- --title "v0.1.0" \
54
+ git tag -a v0.1.2 -m "v0.1.2"
55
+ git push origin v0.1.2
56
+ gh release create v0.1.2 dist/pi-better-web-search-0.1.2.tgz \
57
+ --title "v0.1.2" \
58
58
  --notes-file /path/to/release-notes.md
59
59
  ```
60
60
 
package/docs/testing.md CHANGED
@@ -80,7 +80,7 @@ search and a real DeepSeek credential:
80
80
  PI_BETTER_WEB_SEARCH_CACHE=/tmp/pi-bws-e2e/cache.json \
81
81
  pi --no-session --print --mode json \
82
82
  --provider mock-chat --model mock-chat/mock-chat-model \
83
- -e ./src/index.ts "please search the web"
83
+ -e ./extensions/index.ts "please search the web"
84
84
  ```
85
85
 
86
86
  5. Inspect the second model request. The tool result must be valid raw JSON with
@@ -4,11 +4,11 @@ import {
4
4
  hasExposedCandidate,
5
5
  hasUrlCandidate,
6
6
  resolveResolutionContext,
7
- } from "./candidates.ts";
8
- import { buildWebSearchSchema, buildWebSearchToolDescription, WEB_SEARCH_TOOL_NAME } from "./schema.ts";
9
- import { runWebSearch } from "./search.ts";
7
+ } from "../lib/candidates.ts";
8
+ import { buildWebSearchSchema, buildWebSearchToolDescription, WEB_SEARCH_TOOL_NAME } from "../lib/schema.ts";
9
+ import { runWebSearch } from "../lib/search.ts";
10
10
 
11
- export { WEB_SEARCH_TOOL_NAME } from "./schema.ts";
11
+ export { WEB_SEARCH_TOOL_NAME } from "../lib/schema.ts";
12
12
 
13
13
  export function createWebSearchToolManager(
14
14
  pi: Pick<ExtensionAPI, "registerTool" | "getActiveTools" | "setActiveTools">,
@@ -1,5 +1,4 @@
1
1
  import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
2
- import type { ProviderFamily } from "./providers/types.ts";
3
2
 
4
3
  const configuredOutputLimit = Number(process.env.PI_BETTER_WEB_SEARCH_MAX_CHARS);
5
4
  export const MAX_OUTPUT_CHARS =
@@ -10,8 +9,6 @@ export const MAX_OUTPUT_CHARS =
10
9
  export interface WebSearchOutput {
11
10
  query?: string;
12
11
  search?: {
13
- provider: ProviderFamily;
14
- model: string;
15
12
  answer?: string;
16
13
  results?: unknown;
17
14
  citations?: unknown;
@@ -21,8 +18,6 @@ export interface WebSearchOutput {
21
18
  };
22
19
  fetched?: Array<{
23
20
  url: string;
24
- provider?: ProviderFamily;
25
- model?: string;
26
21
  data?: unknown;
27
22
  error?: string;
28
23
  }>;
@@ -377,8 +377,6 @@ function fetchOutput(states: FetchState[], urlErrors: UrlValidationError[]): Non
377
377
  if (state.data !== undefined && state.provider) {
378
378
  return {
379
379
  url: state.url,
380
- provider: state.provider.family,
381
- model: state.provider.model.id,
382
380
  data: state.data,
383
381
  };
384
382
  }
@@ -474,11 +472,7 @@ export async function runWebSearch(
474
472
  const output: WebSearchOutput = {};
475
473
  if (query) output.query = query;
476
474
  if (searchSuccess) {
477
- output.search = {
478
- ...searchSuccess.result,
479
- provider: searchSuccess.candidate.family,
480
- model: searchSuccess.candidate.model.id,
481
- };
475
+ output.search = { ...searchSuccess.result };
482
476
  }
483
477
  if (fetchRequested) {
484
478
  output.fetched = fetchOutput(states, urlErrors);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-better-web-search",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "A better provider-native web_search tool for pi: raw results, automatic provider fallback, URL analysis, and native DeepSeek Search/Fetch.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -30,7 +30,8 @@
30
30
  "url-context"
31
31
  ],
32
32
  "files": [
33
- "src/",
33
+ "extensions/",
34
+ "lib/",
34
35
  "docs/",
35
36
  "assets/",
36
37
  "README.md",
@@ -41,7 +42,7 @@
41
42
  ],
42
43
  "pi": {
43
44
  "extensions": [
44
- "./src/index.ts"
45
+ "./extensions/index.ts"
45
46
  ],
46
47
  "image": "https://raw.githubusercontent.com/zhexusun10/pi-better-web-search/main/assets/architecture.svg"
47
48
  },
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes