pi-better-web-search 0.1.7 → 0.1.9

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,51 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.9
4
+
5
+ - Preserve provider diversity and apply cooldowns before limiting actual search
6
+ and fetch attempts, so skipped siblings cannot crowd out healthy providers.
7
+ - Reject DeepSeek search queries over 128 Unicode characters with a generic,
8
+ actionable `Search query is too long` error instead of silently shortening
9
+ them or trying a fallback.
10
+ - Distinguish model-access 403 errors from provider-wide failures, and track
11
+ URL-fetch transport failures while preserving partial successes.
12
+ - Count concurrent failures during one cooldown as a single outage; increase
13
+ backoff only when a subsequent attempt after expiry also fails.
14
+ - Bound HTTP error bodies, individual attempt messages, and model-facing error
15
+ text. Fix Claude version parsing when a date follows the major version.
16
+ - Clarify that brand ranking only covers supported APIs, and test OpenCode Go
17
+ against the actual pi model catalog rather than a fabricated API assignment.
18
+
19
+ ## 0.1.8
20
+
21
+ - Shorten overlong DeepSeek search queries at a word boundary before sending
22
+ them to the provider. DeepSeek rejects queries above 128 Unicode characters,
23
+ so concurrent agent search batches with long queries previously failed with
24
+ the generic unavailable error while shorter sibling calls succeeded. The
25
+ original query remains in the model-facing output.
26
+ - Return the provider errors when every search attempt fails, instead of
27
+ replacing them with the generic unavailable message. For example, an OpenAI
28
+ timeout and a DeepSeek validation error are now both visible to the model.
29
+ - Remember provider-wide and model-specific failures per search/fetch phase and
30
+ move the failed provider or model behind healthy candidates on later calls.
31
+ The cooldown is exponential (60s to 10 minutes) and is cleared by a
32
+ successful call. Configure with `PI_BETTER_WEB_SEARCH_FAILURE_COOLDOWN_MS`;
33
+ set it to `0` to disable.
34
+ - Surface provider error text without prepending provider/model labels to the
35
+ model-facing message.
36
+ - Rank GPT and Claude models by version number first, newest first; capability
37
+ tier is now only a tiebreaker for the same version. Add the
38
+ OpenAI `terra` tier between `luna` and `sol`. This prevents an older
39
+ `gpt-5.6-luna` from outranking newer `gpt-6.1-sol`/`gpt-6.1-terra` models.
40
+ `gpt-6-luna` now outranks `gpt-5.6-luna`.
41
+ - Order model brands inside a provider family as DeepSeek, OpenAI, Claude,
42
+ Gemini/Gemma, then other gateway brands. For non-tiered brands, order model
43
+ variants as `flash → base → pro` before comparing versions.
44
+ - Alternate fallback now includes sibling models from the current model's
45
+ provider id. A provider-wide failure still skips that provider, while a
46
+ model-specific failure can use a newer sibling instead of jumping to another
47
+ provider.
48
+
3
49
  ## 0.1.7
4
50
 
5
51
  - Keep recognized URL/URI/link and title/name/ID fields intact when truncating;
package/README.md CHANGED
@@ -17,6 +17,9 @@ and returns provider data as-is.
17
17
 
18
18
  ![pi-better-web-search architecture](https://raw.githubusercontent.com/zhexusun10/pi-better-web-search/main/assets/architecture.svg)
19
19
 
20
+ > The npm registry may lag GitHub releases. If the version you want is not yet
21
+ > published to npm, install the tagged GitHub release below instead.
22
+
20
23
  ```bash
21
24
  pi install npm:pi-better-web-search
22
25
  ```
@@ -26,7 +29,7 @@ Then start a new pi process, or run `/reload` in an existing session.
26
29
  GitHub and local installations also work:
27
30
 
28
31
  ```bash
29
- pi install git:github.com/zhexusun10/pi-better-web-search
32
+ pi install git:github.com/zhexusun10/pi-better-web-search@v0.1.9
30
33
  pi install ./path/to/pi-better-web-search
31
34
  ```
32
35
 
@@ -79,9 +82,11 @@ The runtime schema is logically:
79
82
  }
80
83
  ```
81
84
 
82
- - `query` searches the web. Search operators such as `site:`, quotes, `AND`,
83
- `OR`, and `-term` are passed through unchanged (only outer whitespace is
84
- trimmed).
85
+ - `query` searches the web. Outer whitespace is trimmed; search operators are
86
+ otherwise passed through unchanged. If DeepSeek is selected and the query
87
+ exceeds 128 Unicode characters, the tool returns an error with the actual
88
+ length and limit, asking the model to shorten the query and retry. It does not
89
+ send the query or silently truncate it. Other providers may accept longer queries.
85
90
  - `urls` analyzes the listed pages. URLs can be used **alone** or together with
86
91
  `query`. A query plus URLs performs a search and then analyzes the URLs.
87
92
  - At most **20** URLs may be supplied.
@@ -137,36 +142,54 @@ support per family.
137
142
  For a search:
138
143
 
139
144
  1. The current conversation model is tried first when its provider family
140
- supports web search.
145
+ supports web search and neither the provider nor that model is cooling down
146
+ after a recent failure.
141
147
  2. A remembered successful provider from the preference cache is tried next
142
148
  when the cache fingerprint is current.
143
149
  3. The remaining provider families are tried in this fixed order:
144
150
  **DeepSeek → Ollama → Google → OpenAI → xAI → Anthropic**.
145
- 4. Within a family, models are ordered by capability tier first (cheapest
146
- available tier wins) and then by version number, newest first. OpenAI tiers
147
- are `luna → sol → astra` and Claude tiers are
148
- `haiku → sonnet → opus → fable`; other families have no named tiers and are
149
- ordered purely by version. Ties are deterministic.
150
- 5. Alternate models from other providers are tried round-robin, so a provider
151
- that rejects one specific model can still serve a sibling. Only the current
152
- model's provider id is excluded; a different provider id in the same family
153
- is still tried. A provider-wide failure (auth, balance, network, timeout,
154
- malformed request) skips the rest of that provider; a model-specific
155
- failure keeps trying sibling models.
156
-
157
- URL fetching uses the same idea, but considers only providers that implement
158
- URL fetching.
159
-
160
- The current model is always tried first when it supports search. The cache does
161
- not replace a supported current model; it mainly lets an unsupported current
162
- model use a remembered compatible provider immediately on later calls.
151
+ 4. Within a family, brand order comes first: DeepSeek models, then OpenAI,
152
+ then Claude, then Gemini/Gemma, then other gateway brands. For brands
153
+ without named tiers, variants order `flash → base → pro`; within a variant,
154
+ newer versions come first. GPT and Claude keep version-first ordering, with
155
+ their capability tier as a tiebreaker: OpenAI tiers are
156
+ `luna → terra → sol → astra` and Claude tiers are
157
+ `haiku → sonnet → opus → fable`. Ties are deterministic.
158
+ 5. Alternate providers are considered before additional models of an already
159
+ represented provider; siblings are then tried round-robin across families.
160
+ A provider-wide failure skips that provider, while a model-specific failure
161
+ (including a model-specific 403) can fall back to a sibling.
162
+
163
+ The search limit is 12 actual attempts; skipped candidates do not consume it.
164
+ URL fetching follows the same idea with a separate limit of 6 actual attempts.
165
+ Model ranking applies only to supported APIs: for example, the built-in
166
+ `opencode-go` DeepSeek models use `openai-completions`, which this extension
167
+ cannot search through and does not reinterpret as Responses.
168
+
169
+ The current model is normally tried first when it supports search, unless its
170
+ provider or model is in a failure cooldown. The cache does not replace a
171
+ supported current model; it mainly lets an unsupported current model use a
172
+ remembered compatible provider immediately on later calls.
163
173
 
164
174
  If a provider errors, the extension records the attempt and moves to the next
165
- interface. Aborts stop immediately. Each attempt has a timeout (60 seconds by
175
+ interface. An overlong query rejected by DeepSeek instead returns immediately
176
+ without trying another provider or updating its health state. Aborts stop immediately. Each attempt has a timeout (60 seconds by
166
177
  default, configurable with `PI_BETTER_WEB_SEARCH_TIMEOUT_MS`). If every attempt
167
- fails, the tool returns an error whose message lists the attempted
168
- provider/model pairs and their errors. For a URL-only call, the error also
169
- reports the per-URL failures.
178
+ fails, the tool returns an error whose message contains the provider errors.
179
+ Provider/model routing remains in `details.attempts`. For a URL-only call, the
180
+ error also reports the per-URL failures. Provider error bodies and model-facing
181
+ error text are bounded to prevent an oversized error from filling the context.
182
+
183
+ Provider-wide failures (auth, balance, network, timeout, malformed request) and
184
+ model-specific failures are remembered for the life of the extension process.
185
+ On later calls the failed provider or model is moved behind healthy candidates
186
+ for search and fetch independently. The cooldown starts at 60 seconds, doubles
187
+ when a subsequent attempt after expiry fails, and is capped at 10 minutes.
188
+ Concurrent failures during the same cooldown do not extend it; a successful
189
+ search or a fetch with at least one successful URL and no provider transport
190
+ error clears it. Set
191
+ `PI_BETTER_WEB_SEARCH_FAILURE_COOLDOWN_MS=0` to disable this behavior. Calls
192
+ already in flight may still try the same candidate at the same time.
170
193
 
171
194
  ### Cache fingerprint invalidation
172
195
 
@@ -252,7 +275,7 @@ this:
252
275
  - Redirects are not resolved and sources are not derived.
253
276
  - Unknown provider fields are preserved when the result fits the size guard.
254
277
 
255
- A final output-size guard limits successful model-facing results to **96,000
278
+ A final output-size guard limits model-facing results and errors to **96,000
256
279
  Unicode code points** by default. Normal-sized results retain their original
257
280
  fields and formatting. If indentation alone exceeds the limit, compact JSON is
258
281
  returned without dropping data or setting the truncation flag.
@@ -268,7 +291,7 @@ links or bare domains in unrecognized fields cannot always be identified. Other
268
291
  entries omitted; results are not re-ranked or summarized.
269
292
 
270
293
  The JSON portion remains valid, followed by a single `[truncated]` line. No
271
- truncation metadata or per-string markers are added to the model-facing JSON.
294
+ output-size truncation metadata or per-string markers are added to the JSON.
272
295
  Because of the trailing line, the complete text is not itself valid JSON.
273
296
  `details.truncated` is also set to `true` when data is actually removed.
274
297
 
@@ -316,8 +339,13 @@ Authorization: Bearer <DeepSeek API Key>
316
339
  Content-Type: application/json
317
340
  ```
318
341
 
319
- Search uses `query`, `count: 10`, and `need_content: true`. The raw `results`
320
- array is returned unchanged, including `rerank_score`, `title`, `url`,
342
+ Search uses `query`, `count: 10`, and `need_content: true`. DeepSeek limits
343
+ `query` to 128 Unicode characters. Longer queries return an error before any
344
+ DeepSeek request is sent; the model should shorten the query and retry. For
345
+ example: `Search query is too long (129 Unicode characters). The maximum is
346
+ 128 Unicode characters. Shorten the query and retry.` The raw `results` array
347
+ is returned unchanged,
348
+ including `rerank_score`, `title`, `url`,
321
349
  `snippet`, `summary`, `content`, `site_name`, `site_icon`, `date`, `authority`,
322
350
  and any unknown fields.
323
351
 
@@ -348,7 +376,7 @@ See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
348
376
 
349
377
  ## Verified
350
378
 
351
- - **116 unit and integration tests** covering exposure, schema variants,
379
+ - **Unit and integration tests** covering exposure, schema variants,
352
380
  provider request shapes, SSE parsing, raw-result preservation, fallback,
353
381
  cache invalidation, URL handling, truncation, and abort behavior.
354
382
  - **Real DeepSeek Search/Fetch run** with a real API key: 10 raw search results,
@@ -390,7 +418,7 @@ npm run build
390
418
  ```
391
419
 
392
420
  `npm run build` runs the checks and tests, verifies the npm file list, and packs
393
- `dist/pi-better-web-search-0.1.7.tgz`. Nothing is published automatically.
421
+ `dist/pi-better-web-search-0.1.9.tgz`. Nothing is published automatically.
394
422
 
395
423
  The test suite uses plain `.mjs` files that import the `.ts` sources directly.
396
424
  It mocks `globalThis.fetch`, uses a temporary cache file, and exercises
@@ -10,6 +10,9 @@
10
10
 
11
11
  ![pi-better-web-search 架构](https://raw.githubusercontent.com/zhexusun10/pi-better-web-search/main/assets/architecture.svg)
12
12
 
13
+ > npm 版本可能落后于 GitHub Release。如果所需版本尚未发布到 npm,可使用
14
+ > 下方指定标签的 GitHub 安装方式。
15
+
13
16
  ```bash
14
17
  pi install npm:pi-better-web-search
15
18
  ```
@@ -19,7 +22,7 @@ pi install npm:pi-better-web-search
19
22
  也可以从 GitHub 或本地安装:
20
23
 
21
24
  ```bash
22
- pi install git:github.com/zhexusun10/pi-better-web-search
25
+ pi install git:github.com/zhexusun10/pi-better-web-search@v0.1.9
23
26
  pi install ./path/to/pi-better-web-search
24
27
  ```
25
28
 
@@ -65,8 +68,9 @@ pi install ./path/to/pi-better-web-search
65
68
  }
66
69
  ```
67
70
 
68
- - `query` 搜索网页。`site:`、引号、`AND`、`OR`、`-term` 等搜索语法原样传给
69
- provider,只去掉首尾空白。
71
+ - `query` 搜索网页,只去掉首尾空白,搜索语法其余部分原样保留。如果选中
72
+ DeepSeek 且 query 超过 128 个 Unicode 字符,工具会直接返回实际长度和上限,
73
+ 提示模型缩短后重试;不会发送请求或静默截断。其他 provider 可以接受更长的查询。
70
74
  - `urls` 分析指定页面。可以**单独使用**,也可以和 `query` 一起使用。两者同时
71
75
  提供时,先搜索,再分析 URL。
72
76
  - 最多 **20** 个 URL。
@@ -116,28 +120,41 @@ Provider 识别顺序:
116
120
 
117
121
  搜索顺序:
118
122
 
119
- 1. 当前模型支持搜索时,优先当前模型。
123
+ 1. 当前模型支持搜索,且对应 provider 和该模型都不在失败冷却期时,优先当前模型。
120
124
  2. 缓存指纹有效时,使用记住的搜索 provider。
121
125
  3. 其余 provider family 按固定顺序尝试:
122
126
  **DeepSeek → Ollama → Google → OpenAI → xAI → Anthropic**。
123
- 4. 同一 family 内先按能力等级排序(便宜的等级优先,未知等级排最后):
124
- OpenAI 为 `luna → sol → astra`,Claude 为 `haiku → sonnet → opus → fable`;
125
- 其他 family 没有命名等级,直接按版本号从新到旧排序。同级内版本号大的优先。
126
- 5. 除当前模型的 provider id 外,其他 provider 的备用模型会按 round-robin 继续尝试,
127
- 这样即使某个账号拒绝某个具体模型,也能换用同 provider 的其他模型。
128
- 同一 family 下不同 provider id(如 `openai` 与 `openai-codex`)仍会尝试。
129
- provider 级失败(鉴权、余额、网络、超时、请求头异常)会跳过该 provider 的
130
- 其余模型;模型级失败则继续尝试同 provider 的其他模型。
131
-
132
- URL 抓取使用同样的思路,但只考虑实现了 URL 抓取的 provider。
133
-
134
- 当前模型支持搜索时始终优先当前模型;缓存不会覆盖它。缓存主要用于当前模型
135
- 不支持搜索时,让下一次调用直接使用之前成功的兼容 provider。
136
-
137
- Provider 报错时记录 attempt 并继续下一个接口。取消会立即停止。每次尝试有
127
+ 4. 同一 family 内先按品牌排序:DeepSeek 模型、OpenAI、Claude、Gemini/Gemma,
128
+ 然后其他网关品牌。没有命名等级的品牌按变体 `flash → base → pro` 排序,同一变体
129
+ 内版本号从新到旧;GPT 和 Claude 仍按版本优先,版本相同时才按能力等级排序
130
+ (便宜的等级优先,未知等级排最后):OpenAI 为 `luna → terra → sol → astra`,
131
+ Claude 为 `haiku → sonnet → opus → fable`。
132
+ 5. 优先尝试尚未覆盖的 provider,再按 family 的 round-robin 尝试各 provider
133
+ 的备用模型。provider 级失败会跳过该 provider;模型级失败(包括模型权限 403)
134
+ 则可继续尝试同 provider 的其他模型。
135
+
136
+ 搜索最多发起 12 次实际尝试;URL 抓取采用同样的思路,最多发起 6 次。跳过的候选
137
+ 不占用次数。排序只适用于支持的 API:例如内置的 `opencode-go` DeepSeek 模型
138
+ 使用 `openai-completions`,本扩展不会将它们当作 Responses 搜索接口。
139
+
140
+ 当前模型支持搜索时通常优先当前模型,除非该 provider 或该模型正处于失败冷却期。
141
+ 缓存不会覆盖它。缓存主要用于当前模型不支持搜索时,让下一次调用直接使用之前成功
142
+ 的兼容 provider。
143
+
144
+ Provider 报错时记录 attempt 并继续下一个接口。DeepSeek 查询超长则直接返回错误,
145
+ 不继续尝试其他 provider,也不记录为 provider 健康故障。取消会立即停止。每次尝试有
138
146
  超时(默认 60 秒,`PI_BETTER_WEB_SEARCH_TIMEOUT_MS` 可调)。所有尝试都失败时,
139
- 工具返回错误,列出尝试过的 provider/model 和错误。URL-only 调用还会报告每个
140
- URL 的失败原因。
147
+ 工具返回错误,消息中包含 provider 返回的错误;provider/model 路由信息保留在
148
+ `details.attempts` 中。URL-only 调用还会报告每个 URL 的失败原因。provider 错误
149
+ 响应体与发给模型的错误文本都有大小限制,避免错误内容占满上下文。
150
+
151
+ Provider 级失败(鉴权、余额、网络、超时、请求头异常)和单个模型失败都会在扩展进程内
152
+ 记住。后续调用会把失败的 provider 或模型排到健康候选之后,搜索和 URL 抓取分别记录。
153
+ 冷却时间从 60 秒开始,冷却结束后的再次尝试失败时翻倍,最多 10 分钟;同一冷却期内
154
+ 的并发失败不会延长时间。搜索成功,或至少一个 URL 抓取成功且没有 provider
155
+ 网络错误时,清除对应冷却。设置
156
+ `PI_BETTER_WEB_SEARCH_FAILURE_COOLDOWN_MS=0` 可禁用。已经在途的并发调用仍可能同时
157
+ 尝试同一个候选。
141
158
 
142
159
  ### 缓存指纹失效
143
160
 
@@ -217,7 +234,7 @@ Provider 数据放在 JSON 外层中返回,不做清理。示例:
217
234
  - 不解析 redirect,不派生 sources。
218
235
  - 未超出大小限制时,provider 的未知字段也会保留。
219
236
 
220
- 最终大小保护默认限制成功结果不超过 **96,000 个 Unicode code point**。
237
+ 最终大小保护默认限制结果及错误文本不超过 **96,000 个 Unicode code point**。
221
238
  未超限时保留原始字段及格式;如果只是缩进导致超限,会先压缩 JSON,
222
239
  不丢失数据,也不标记为截断。
223
240
 
@@ -230,8 +247,8 @@ Provider 数据放在 JSON 外层中返回,不做清理。示例:
230
247
  其他长字符串可能被缩短,字段或数组末尾的条目可能被省略;
231
248
  不对结果重排或总结。
232
249
 
233
- JSON 部分仍然合法,末尾仅追加一行 `[truncated]`。不会向模型可见的 JSON
234
- 中添加截断元数据,也不会逐个标记缩短的字符串。由于末尾追加了这一行,
250
+ 成功结果的 JSON 部分仍然合法,末尾仅追加一行 `[truncated]`。输出大小截断不会在
251
+ JSON 中添加元数据,也不会逐个标记字符串。由于末尾追加了这一行,
235
252
  整个文本不再是合法 JSON。确实丢失数据时,`details.truncated` 也会设为
236
253
  `true`。
237
254
 
@@ -268,8 +285,9 @@ Authorization: Bearer <DeepSeek API Key>
268
285
  Content-Type: application/json
269
286
  ```
270
287
 
271
- 搜索使用 `query`、`count: 10`、`need_content: true`。原始 `results` 数组原样
272
- 返回,包括 `rerank_score`、`title`、`url`、`snippet`、`summary`、`content`、
288
+ 搜索使用 `query`、`count: 10`、`need_content: true`。DeepSeek 的 `query` 上限为
289
+ 128 个 Unicode 字符,超长时会在发送请求前直接返回错误,提示缩短后重试。
290
+ 原始 `results` 数组原样返回,包括 `rerank_score`、`title`、`url`、`snippet`、`summary`、`content`、
273
291
  `site_name`、`site_icon`、`date`、`authority` 和未知字段。
274
292
 
275
293
  Fetch 发送 `{ "url": "..." }`,原样保存 `{ title, content }`。URL 最长 8192
@@ -294,7 +312,7 @@ provider;`403`/`404` 作为单个 URL 的错误上报,orchestrator 只重试
294
312
 
295
313
  ## 已验证
296
314
 
297
- - **116 个单元/集成测试**:暴露规则、schema 变体、provider 请求形状、SSE 解析、
315
+ - **单元/集成测试**:暴露规则、schema 变体、provider 请求形状、SSE 解析、
298
316
  原始结果保留、fallback、缓存失效、URL 处理、截断和取消。
299
317
  - **真实 DeepSeek Search/Fetch**:使用真实 API key,返回 10 条原始搜索结果、
300
318
  summary/content、合法 fetch 页面,以及文档中的 404/非法 URL 错误。
@@ -329,7 +347,7 @@ npm run build
329
347
  ```
330
348
 
331
349
  `npm run build` 会运行检查、测试、包内容验证,并生成
332
- `dist/pi-better-web-search-0.1.7.tgz`。不会自动发布。
350
+ `dist/pi-better-web-search-0.1.9.tgz`。不会自动发布。
333
351
 
334
352
  测试是 `.mjs` 文件,直接导入 `.ts` 源码,mock `globalThis.fetch`,使用临时缓存
335
353
  目录。详见 [测试](testing.md) 和 [发布](publishing.md)。
@@ -14,8 +14,9 @@ output guard. It does not own provider result cleanup.
14
14
  4. **Use provider-native interfaces.** Each family keeps its request shape,
15
15
  authentication quirks, and stream format.
16
16
  5. **Prefer the current model, remember fallbacks.** A supported current model
17
- is tried first. An unsupported current model uses the remembered compatible
18
- provider first.
17
+ is tried first unless its provider is cooling down after a recent
18
+ provider-wide failure. An unsupported current model uses the remembered
19
+ compatible provider first.
19
20
  6. **Do not touch pi's system prompt.** No prompt snippets, guidelines, loadout
20
21
  hooks, commands, or extra tools.
21
22
 
@@ -72,26 +73,40 @@ Search candidates:
72
73
  2. The remembered search provider when the cache fingerprint is current.
73
74
  3. One candidate per remaining family in this order:
74
75
  **DeepSeek → Ollama → Google → OpenAI → xAI → Anthropic**.
75
- 4. Alternate models from every provider except the current model's provider
76
- id, round-robin across families, up to 12 attempts. A different provider id
77
- in the same family (for example `openai` vs `openai-codex`) is still tried.
76
+ 4. Prefer previously unrepresented provider ids, then try remaining sibling
77
+ models round-robin across families. Provider-wide failures skip that
78
+ provider; model-specific failures, including model-access 403s, can use a
79
+ sibling model. The cap is 12 actual search attempts, not skipped candidates.
78
80
 
79
81
  Fetch candidates use the same shape but include only adapters with
80
- `supportsUrls` and a `fetch` implementation. The fetch cap is 6 attempts.
81
-
82
- Within a family, models are ordered by capability tier first and version
83
- second. Named tiers rank cheapest first and unknown ids rank last: OpenAI uses
84
- `luna → sol → astra` and Claude uses `haiku → sonnet → opus → fable`. Other
85
- families have no named tiers. Version numbers are compared as tuples with the
86
- newest first (`gpt-7.0` before `gpt-6.1` before `gpt-4.1`, `gemini-3.8` before
87
- `gemini-2.5`). Ties fall back to the deterministic `provider/id@baseUrl` order.
82
+ `supportsUrls` and a `fetch` implementation. The fetch cap is 6 actual attempts.
83
+ Cooldowns are applied to the full discovery set before either cap.
84
+
85
+ Within a family, models are ordered by brand first: DeepSeek, OpenAI, Claude,
86
+ Gemini/Gemma, then other gateway brands. Brands without named tiers use variant
87
+ order `flash → base → pro`, then version number, newest first. GPT and Claude
88
+ use version number first, newest first, with capability tier as a tiebreaker:
89
+ OpenAI uses `luna → terra → sol → astra` and Claude uses
90
+ `haiku → sonnet → opus → fable`. Ties fall back to the deterministic
91
+ `provider/id@baseUrl` order. Ranking only applies to models whose API is already
92
+ supported. For example, built-in `opencode-go` DeepSeek models use
93
+ `openai-completions` and are not eligible for Responses search.
88
94
  A provider id is only retried with another model when the first failure was
89
95
  model-specific; provider-wide failures (auth, balance, network, timeout,
90
- malformed request) skip the rest of that provider.
91
-
92
- The current model is preferred when it supports search. The cache is a fallback,
93
- not an override. When the current model is unsupported, the cached provider is
94
- tried first, which avoids repeating discovery on every call.
96
+ malformed request) skip the rest of that provider. Provider failures and
97
+ model-specific failures are remembered per phase (search/fetch) for the life of
98
+ the process. On later calls the failed provider or model is moved behind healthy
99
+ candidates for a 60-second to 10-minute exponential cooldown. Concurrent
100
+ failures during an active cooldown count as one outage; a failed probe after
101
+ expiry increases the cooldown. A successful search or fetch with at least one
102
+ successful URL and no provider transport error clears it. Calls already in
103
+ flight are not cancelled or reordered.
104
+
105
+ The current model is preferred when it supports search and neither its provider
106
+ nor that model is cooling down. The cache is a fallback, not an override. When
107
+ the current model
108
+ is unsupported, the cached provider is tried first, which avoids repeating
109
+ discovery on every call.
95
110
 
96
111
  ## Cache and fingerprint
97
112
 
@@ -124,7 +139,10 @@ be used. A cached provider that is no longer available is ignored.
124
139
 
125
140
  ## Input validation
126
141
 
127
- - `query` is trimmed; search operators are otherwise passed through unchanged.
142
+ - `query` is trimmed. When DeepSeek is selected, queries over 128 Unicode
143
+ characters produce an actionable error before any DeepSeek request; no
144
+ automatic truncation, fallback, or health cooldown occurs. Other providers
145
+ are not subject to this limit.
128
146
  - `urls` is an array of at most 20 strings.
129
147
  - Each URL must be HTTP/HTTPS, have a host, omit username/password, and be at
130
148
  most 8192 characters.
@@ -158,10 +176,11 @@ The result is a JSON wrapper:
158
176
  }
159
177
  ```
160
178
 
161
- Fields inside `search` and `fetched[].data` are provider data. The extension does
162
- not deduplicate, normalize, filter, re-rank, summarize, insert citation markers,
163
- or append source sections. The final guard keeps successful model-facing output
164
- within 96,000 Unicode code points by default (`PI_BETTER_WEB_SEARCH_MAX_CHARS`).
179
+ Fields inside `search` and `fetched[].data` are provider data. The extension
180
+ does not deduplicate,
181
+ normalize, filter, re-rank, summarize, insert citation markers, or append source
182
+ sections. The final guard keeps model-facing results and errors within 96,000
183
+ Unicode code points by default (`PI_BETTER_WEB_SEARCH_MAX_CHARS`).
165
184
  It preserves ordinary formatted JSON, or uses compact JSON if that alone fits.
166
185
  Otherwise it budgets sibling fields and array entries independently. Recognized
167
186
  link and identity fields stay whole; entries or branches that cannot fit them
@@ -171,8 +190,8 @@ rather than partially emitted. Unknown relative links or bare domains may not be
171
190
  identifiable. Other strings can be shortened, and fields or trailing array entries
172
191
  omitted. The JSON portion
173
192
  stays valid, followed by one `[truncated]` line; the complete text is therefore
174
- not valid JSON. No truncation metadata is injected into the model-facing JSON,
175
- while `details.truncated` marks actual data loss. When truncation is needed with a limit of 11–13 characters,
193
+ not valid JSON. No output-size truncation metadata is injected into the JSON;
194
+ `details.truncated` marks output-size data loss. When truncation is needed with a limit of 11–13 characters,
176
195
  only the marker is returned; below 11, a minimal JSON value is returned instead.
177
196
  This is a character guard, not a token or model-context limit; it does not
178
197
  provide pagination or retain the complete provider payload for later use.
@@ -214,6 +233,7 @@ the abort signal and resolve credentials through `lib/auth.ts`.
214
233
  | `extensions/index.ts` | Tool registration, exposure sync, lifecycle handlers |
215
234
  | `lib/candidates.ts` | Current/available candidates, ordering, cache resolution |
216
235
  | `lib/search.ts` | Input validation, search/fetch fallback, cache writes, output |
236
+ | `lib/health.ts` | Provider-wide failure cooldowns and candidate reordering |
217
237
  | `lib/auth.ts` | Credential resolution, header merging, env fallback |
218
238
  | `lib/cache.ts` | Preference cache and model-set fingerprint |
219
239
  | `lib/families.ts` | Provider family detection |
package/docs/providers.md CHANGED
@@ -20,8 +20,10 @@ stream parsing, and error behavior:
20
20
  | * | **Anthropic Messages** | api `anthropic-messages` | Yes | No | Messages API `web_search_20260209` tool & OAuth |
21
21
 
22
22
  A model whose API is `openai-completions` is not search-capable unless it is
23
- served by DeepSeek or Ollama Cloud. A local Ollama daemon is not supported;
24
- Ollama Cloud uses the hosted REST API.
23
+ served by the native DeepSeek provider or Ollama Cloud. In particular, the
24
+ built-in `opencode-go` DeepSeek models use `openai-completions`; brand ranking
25
+ does not make them Responses-compatible or expose them as search candidates.
26
+ A local Ollama daemon is not supported; Ollama Cloud uses the hosted REST API.
25
27
 
26
28
  ## DeepSeek
27
29
 
@@ -54,8 +56,11 @@ POST https://api.deepseek.com/v1/tools/search
54
56
  }
55
57
  ```
56
58
 
57
- - `query` is 1–128 Unicode characters, not all whitespace. Search operators are
58
- passed through unchanged.
59
+ - `query` is 1–128 Unicode characters, not all whitespace. Longer queries
60
+ return a model-facing error with the actual length and the 128-character
61
+ limit; the model should shorten the query and retry. No DeepSeek request is
62
+ sent, no automatic truncation or fallback occurs, and no failure cooldown is
63
+ recorded.
59
64
  - `count` is within the documented 1–50 range; this package uses 10.
60
65
  - `need_content` is `true`, so `content` can contain the page body. The output
61
66
  character guard protects the model context.
@@ -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.7.tgz`. The tarball is not
33
+ This produces `dist/pi-better-web-search-0.1.9.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.7.tgz --access public
45
+ npm publish dist/pi-better-web-search-0.1.9.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.7 -m "v0.1.7"
55
- git push origin v0.1.7
56
- gh release create v0.1.7 dist/pi-better-web-search-0.1.7.tgz \
57
- --title "v0.1.7" \
54
+ git tag -a v0.1.9 -m "v0.1.9"
55
+ git push origin v0.1.9
56
+ gh release create v0.1.9 dist/pi-better-web-search-0.1.9.tgz \
57
+ --title "v0.1.9" \
58
58
  --notes-file /path/to/release-notes.md
59
59
  ```
60
60
 
package/docs/testing.md CHANGED
@@ -17,7 +17,7 @@ npm run verify:package
17
17
  tarball contains runtime sources, docs, assets, and metadata, while excluding
18
18
  tests, scripts, CI files, the local reference checkout, and `DESIGN.md`.
19
19
  - `npm run build` runs the checks, tests, package verification, and packs
20
- `dist/pi-better-web-search-0.1.7.tgz`.
20
+ `dist/pi-better-web-search-0.1.9.tgz`.
21
21
 
22
22
  Tests import the TypeScript sources directly. The suite mocks `globalThis.fetch`
23
23
  and uses temporary cache directories. Coverage includes: