pi-better-web-search 0.1.6 → 0.1.8

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,46 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.8
4
+
5
+ - Shorten overlong DeepSeek search queries at a word boundary before sending
6
+ them to the provider. DeepSeek rejects queries above 128 Unicode characters,
7
+ so concurrent agent search batches with long queries previously failed with
8
+ the generic unavailable error while shorter sibling calls succeeded. The
9
+ original query remains in the model-facing output.
10
+ - Return the provider errors when every search attempt fails, instead of
11
+ replacing them with the generic unavailable message. For example, an OpenAI
12
+ timeout and a DeepSeek validation error are now both visible to the model.
13
+ - Remember provider-wide and model-specific failures per search/fetch phase and
14
+ move the failed provider or model behind healthy candidates on later calls.
15
+ The cooldown is exponential (60s to 10 minutes) and is cleared by a
16
+ successful call. Configure with `PI_BETTER_WEB_SEARCH_FAILURE_COOLDOWN_MS`;
17
+ set it to `0` to disable.
18
+ - Surface provider error text without prepending provider/model labels to the
19
+ model-facing message.
20
+ - Rank GPT and Claude models by version number first, newest first; capability
21
+ tier is now only a tiebreaker for the same version. Add the
22
+ OpenAI `terra` tier between `luna` and `sol`. This prevents an older
23
+ `gpt-5.6-luna` from outranking newer `gpt-6.1-sol`/`gpt-6.1-terra` models.
24
+ `gpt-6-luna` now outranks `gpt-5.6-luna`.
25
+ - Order model brands inside a provider family as DeepSeek, OpenAI, Claude,
26
+ Gemini/Gemma, then other gateway brands. For non-tiered brands, order model
27
+ variants as `flash → base → pro` before comparing versions.
28
+ - Alternate fallback now includes sibling models from the current model's
29
+ provider id. A provider-wide failure still skips that provider, while a
30
+ model-specific failure can use a newer sibling instead of jumping to another
31
+ provider.
32
+
33
+ ## 0.1.7
34
+
35
+ - Keep recognized URL/URI/link and title/name/ID fields intact when truncating;
36
+ omit entries that cannot fit rather than returning partial links. Preserve
37
+ provider order and drop incomplete URL tokens at text boundaries.
38
+ - Raise the default model-facing output limit from 64,000 to 96,000 Unicode
39
+ code points; the environment override remains available.
40
+ - Replace model-facing truncation metadata and per-string markers with a single
41
+ `[truncated]` line at the end of oversized results. Keep the existing fair
42
+ allocation across search results and fetched pages.
43
+
3
44
  ## 0.1.6
4
45
 
5
46
  - Keep oversized results as valid JSON, sharing the character budget across
package/README.md CHANGED
@@ -81,7 +81,9 @@ The runtime schema is logically:
81
81
 
82
82
  - `query` searches the web. Search operators such as `site:`, quotes, `AND`,
83
83
  `OR`, and `-term` are passed through unchanged (only outer whitespace is
84
- trimmed).
84
+ trimmed). If a provider enforces a shorter query limit, its adapter shortens
85
+ only the provider-bound copy at a word boundary; the original query stays in
86
+ the output.
85
87
  - `urls` analyzes the listed pages. URLs can be used **alone** or together with
86
88
  `query`. A query plus URLs performs a search and then analyzes the URLs.
87
89
  - At most **20** URLs may be supplied.
@@ -137,36 +139,48 @@ support per family.
137
139
  For a search:
138
140
 
139
141
  1. The current conversation model is tried first when its provider family
140
- supports web search.
142
+ supports web search and neither the provider nor that model is cooling down
143
+ after a recent failure.
141
144
  2. A remembered successful provider from the preference cache is tried next
142
145
  when the cache fingerprint is current.
143
146
  3. The remaining provider families are tried in this fixed order:
144
147
  **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.
148
+ 4. Within a family, brand order comes first: DeepSeek models, then OpenAI,
149
+ then Claude, then Gemini/Gemma, then other gateway brands. For brands
150
+ without named tiers, variants order `flash → base → pro`; within a variant,
151
+ newer versions come first. GPT and Claude keep version-first ordering, with
152
+ their capability tier as a tiebreaker: OpenAI tiers are
153
+ `luna → terra → sol → astra` and Claude tiers are
154
+ `haiku → sonnet → opus → fable`. Ties are deterministic.
155
+ 5. Alternate models from every provider are tried round-robin, so a provider
156
+ that rejects one specific model can still serve a sibling, including a
157
+ newer sibling from the same provider id. A provider-wide failure (auth,
158
+ balance, network, timeout, malformed request) skips the rest of that
159
+ provider; a model-specific failure keeps trying sibling models.
156
160
 
157
161
  URL fetching uses the same idea, but considers only providers that implement
158
162
  URL fetching.
159
163
 
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.
164
+ The current model is normally tried first when it supports search, unless its
165
+ provider or model is in a failure cooldown. The cache does not replace a
166
+ supported current model; it mainly lets an unsupported current model use a
167
+ remembered compatible provider immediately on later calls.
163
168
 
164
169
  If a provider errors, the extension records the attempt and moves to the next
165
170
  interface. Aborts stop immediately. Each attempt has a timeout (60 seconds by
166
171
  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.
172
+ fails, the tool returns an error whose message contains the provider errors.
173
+ Provider/model routing remains in `details.attempts`. For a URL-only call, the
174
+ error also reports the per-URL failures.
175
+
176
+ Provider-wide failures (auth, balance, network, timeout, malformed request) and
177
+ model-specific failures are remembered for the life of the extension process.
178
+ On later calls the failed provider or model is moved behind healthy candidates
179
+ for search and fetch independently. The cooldown starts at 60 seconds, doubles
180
+ on consecutive failures, and is capped at 10 minutes; a successful call clears
181
+ it. Set `PI_BETTER_WEB_SEARCH_FAILURE_COOLDOWN_MS=0` to disable this behavior.
182
+ This does not prevent several calls already in flight from trying the same
183
+ candidate at the same time.
170
184
 
171
185
  ### Cache fingerprint invalidation
172
186
 
@@ -252,20 +266,24 @@ this:
252
266
  - Redirects are not resolved and sources are not derived.
253
267
  - Unknown provider fields are preserved when the result fits the size guard.
254
268
 
255
- A final output-size guard limits successful model-facing results to **64,000
269
+ A final output-size guard limits successful model-facing results to **96,000
256
270
  Unicode code points** by default. Normal-sized results retain their original
257
271
  fields and formatting. If indentation alone exceeds the limit, compact JSON is
258
272
  returned without dropping data or setting the truncation flag.
259
273
 
260
274
  When even compact JSON is too large, the guard allocates space across sibling
261
- fields and array entries, redistributing unused space. It tries to preserve
262
- identifying fields such as URLs, titles and errors, while shortening long
263
- strings or omitting fields and trailing array entries when needed. The result
264
- remains valid JSON. Shortened strings end in `…[truncated]` when space permits,
265
- and the model-facing `_truncation` object reports `truncated`, `originalChars`
266
- (the original indented JSON size), and `affectedPaths`. `moreAffectedPaths`
267
- indicates that the path list is incomplete. Array paths can indicate omitted
268
- entries; with very small budgets, not every URL or field can be preserved.
275
+ fields and array entries, redistributing unused space. Recognized link and
276
+ identity fields (`url`, `uri`, `href`, `link`, `title`, `name`, `id`, and common
277
+ aliases) stay complete; if they cannot fit, the associated entry or branch is
278
+ omitted instead. Standalone URLs and entries in link/citation arrays also stay
279
+ whole. When a text cut would split a recognizable embedded URL token (such as
280
+ `https://`, `mailto:`, or `www.`), the incomplete token is omitted. Relative
281
+ links or bare domains in unrecognized fields cannot always be identified. Other long strings may be shortened, and fields or trailing array
282
+ entries omitted; results are not re-ranked or summarized.
283
+
284
+ The JSON portion remains valid, followed by a single `[truncated]` line. No
285
+ truncation metadata or per-string markers are added to the model-facing JSON.
286
+ Because of the trailing line, the complete text is not itself valid JSON.
269
287
  `details.truncated` is also set to `true` when data is actually removed.
270
288
 
271
289
  Change the limit **before starting pi**:
@@ -276,10 +294,12 @@ export PI_BETTER_WEB_SEARCH_MAX_CHARS=100000
276
294
 
277
295
  In PowerShell, use `$env:PI_BETTER_WEB_SEARCH_MAX_CHARS = "100000"`. The limit
278
296
  is in code points, **not tokens**, and does not adapt to the current model's
279
- context window. Extremely small limits below 19 characters cannot fit a
280
- model-visible truncation flag; the result is still valid JSON and
281
- `details.truncated` remains true. There is no continuation/pagination cache:
282
- retry individual URLs or raise the limit if more content is needed.
297
+ context window. The marker counts toward the limit. If truncation is needed and
298
+ the limit is 11–13 characters, only `[truncated]` is returned; below 11
299
+ characters the marker does not fit and only a minimal JSON value is returned.
300
+ `details.truncated` remains true in both cases. There is no continuation or
301
+ pagination cache: retry individual URLs or raise the limit if more content is
302
+ needed.
283
303
 
284
304
  ## Exposure rules
285
305
 
@@ -310,8 +330,10 @@ Authorization: Bearer <DeepSeek API Key>
310
330
  Content-Type: application/json
311
331
  ```
312
332
 
313
- Search uses `query`, `count: 10`, and `need_content: true`. The raw `results`
314
- array is returned unchanged, including `rerank_score`, `title`, `url`,
333
+ Search uses `query`, `count: 10`, and `need_content: true`. DeepSeek limits
334
+ `query` to 128 Unicode characters, so longer queries are shortened at a word
335
+ boundary for the request only. The raw `results` array is returned unchanged,
336
+ including `rerank_score`, `title`, `url`,
315
337
  `snippet`, `summary`, `content`, `site_name`, `site_icon`, `date`, `authority`,
316
338
  and any unknown fields.
317
339
 
@@ -384,7 +406,7 @@ npm run build
384
406
  ```
385
407
 
386
408
  `npm run build` runs the checks and tests, verifies the npm file list, and packs
387
- `dist/pi-better-web-search-0.1.0.tgz`. Nothing is published automatically.
409
+ `dist/pi-better-web-search-0.1.7.tgz`. Nothing is published automatically.
388
410
 
389
411
  The test suite uses plain `.mjs` files that import the `.ts` sources directly.
390
412
  It mocks `globalThis.fetch`, uses a temporary cache file, and exercises
@@ -66,7 +66,8 @@ pi install ./path/to/pi-better-web-search
66
66
  ```
67
67
 
68
68
  - `query` 搜索网页。`site:`、引号、`AND`、`OR`、`-term` 等搜索语法原样传给
69
- provider,只去掉首尾空白。
69
+ provider,只去掉首尾空白。如果 provider 有更短的 query 上限,adapter 只会在
70
+ 发给该 provider 的副本上按词边界缩短;输出中仍保留原始 query。
70
71
  - `urls` 分析指定页面。可以**单独使用**,也可以和 `query` 一起使用。两者同时
71
72
  提供时,先搜索,再分析 URL。
72
73
  - 最多 **20** 个 URL。
@@ -116,28 +117,36 @@ Provider 识别顺序:
116
117
 
117
118
  搜索顺序:
118
119
 
119
- 1. 当前模型支持搜索时,优先当前模型。
120
+ 1. 当前模型支持搜索,且对应 provider 和该模型都不在失败冷却期时,优先当前模型。
120
121
  2. 缓存指纹有效时,使用记住的搜索 provider。
121
122
  3. 其余 provider family 按固定顺序尝试:
122
123
  **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 的其他模型。
124
+ 4. 同一 family 内先按品牌排序:DeepSeek 模型、OpenAI、Claude、Gemini/Gemma,
125
+ 然后其他网关品牌。没有命名等级的品牌按变体 `flash → base → pro` 排序,同一变体
126
+ 内版本号从新到旧;GPT 和 Claude 仍按版本优先,版本相同时才按能力等级排序
127
+ (便宜的等级优先,未知等级排最后):OpenAI 为 `luna → terra → sol → astra`,
128
+ Claude 为 `haiku → sonnet → opus → fable`。
129
+ 5. 所有 provider 的备用模型都会按 round-robin 继续尝试,包括当前模型同一
130
+ provider id 下的其他模型,这样即使某个账号拒绝某个具体模型,也能换用同
131
+ provider 的更新模型。provider 级失败(鉴权、余额、网络、超时、请求头异常)
132
+ 会跳过该 provider 的其余模型;模型级失败则继续尝试同 provider 的其他模型。
131
133
 
132
134
  URL 抓取使用同样的思路,但只考虑实现了 URL 抓取的 provider。
133
135
 
134
- 当前模型支持搜索时始终优先当前模型;缓存不会覆盖它。缓存主要用于当前模型
135
- 不支持搜索时,让下一次调用直接使用之前成功的兼容 provider。
136
+ 当前模型支持搜索时通常优先当前模型,除非该 provider 或该模型正处于失败冷却期。
137
+ 缓存不会覆盖它。缓存主要用于当前模型不支持搜索时,让下一次调用直接使用之前成功
138
+ 的兼容 provider。
136
139
 
137
140
  Provider 报错时记录 attempt 并继续下一个接口。取消会立即停止。每次尝试有
138
141
  超时(默认 60 秒,`PI_BETTER_WEB_SEARCH_TIMEOUT_MS` 可调)。所有尝试都失败时,
139
- 工具返回错误,列出尝试过的 provider/model 和错误。URL-only 调用还会报告每个
140
- URL 的失败原因。
142
+ 工具返回错误,消息中包含 provider 返回的错误;provider/model 路由信息保留在
143
+ `details.attempts` 中。URL-only 调用还会报告每个 URL 的失败原因。
144
+
145
+ Provider 级失败(鉴权、余额、网络、超时、请求头异常)和单个模型失败都会在扩展进程内
146
+ 记住。后续调用会把失败的 provider 或模型排到健康候选之后,搜索和 URL 抓取分别记录。
147
+ 冷却时间从 60 秒开始,连续失败时翻倍,最多 10 分钟;成功一次后清除。设置
148
+ `PI_BETTER_WEB_SEARCH_FAILURE_COOLDOWN_MS=0` 可禁用。已经在途的并发调用仍可能同时
149
+ 尝试同一个候选。
141
150
 
142
151
  ### 缓存指纹失效
143
152
 
@@ -217,18 +226,23 @@ Provider 数据放在 JSON 外层中返回,不做清理。示例:
217
226
  - 不解析 redirect,不派生 sources。
218
227
  - 未超出大小限制时,provider 的未知字段也会保留。
219
228
 
220
- 最终大小保护默认限制成功结果不超过 **64,000 个 Unicode code point**。
229
+ 最终大小保护默认限制成功结果不超过 **96,000 个 Unicode code point**。
221
230
  未超限时保留原始字段及格式;如果只是缩进导致超限,会先压缩 JSON,
222
231
  不丢失数据,也不标记为截断。
223
232
 
224
- 压缩后仍超限时,按字段和数组条目分配预算,未用完的额度会重新分配;
225
- 尽量保留 URL、标题和错误等标识信息。必要时会缩短字符串或省略字段、
226
- 数组末尾的条目,但返回值始终是合法 JSON。空间允许时,缩短的字符串以
227
- `…[truncated]` 结尾;模型可见的 `_truncation` 对象包含 `truncated`、
228
- `originalChars`(原始缩进 JSON 的字符数)和 `affectedPaths`。
229
- `moreAffectedPaths` 表示路径列表不完整,数组路径也可能表示部分条目被省略。
230
- 预算极小时无法保证保留所有 URL 或字段。确实丢失数据时,
231
- `details.truncated` 也会设为 `true`。
233
+ 压缩后仍超限时,按字段和数组条目分配预算,未用完的额度会重新分配。
234
+ 已识别的链接及标识字段(包括 `url`、`uri`、`href`、`link`、`title`、
235
+ `name`、`id` 和常见别名)保持完整;放不下时省略对应条目或分支,而不是
236
+ 返回半截值。独立 URL 和链接、引用数组中的条目也保持完整;正文截断点
237
+ 若落在可识别的 URL(如 `https://`、`mailto:` 或 `www.`)中间,会省略该
238
+ 未完整显示的 URL。未知字段中的相对链接或裸域名无法保证都能识别。
239
+ 其他长字符串可能被缩短,字段或数组末尾的条目可能被省略;
240
+ 不对结果重排或总结。
241
+
242
+ JSON 部分仍然合法,末尾仅追加一行 `[truncated]`。不会向模型可见的 JSON
243
+ 中添加截断元数据,也不会逐个标记缩短的字符串。由于末尾追加了这一行,
244
+ 整个文本不再是合法 JSON。确实丢失数据时,`details.truncated` 也会设为
245
+ `true`。
232
246
 
233
247
  可在**启动 pi 之前**通过环境变量调整:
234
248
 
@@ -238,9 +252,10 @@ export PI_BETTER_WEB_SEARCH_MAX_CHARS=100000
238
252
 
239
253
  PowerShell 使用 `$env:PI_BETTER_WEB_SEARCH_MAX_CHARS = "100000"`。
240
254
  上限是 code point,**不是 token**,不会根据当前模型的上下文窗口自动调整。
241
- 极小上限(少于 19 字符)无法在模型可见内容中容纳截断标记,此时仍返回
242
- 合法 JSON,并在 `details.truncated` 中报告。当前没有续读或分页缓存;
243
- 需要更多内容时可单独重新抓取 URL 或提高上限。
255
+ 标记也计入上限。需要截断且上限为 11–13 字符时,只返回 `[truncated]`;
256
+ 少于 11 字符时放不下标记,只返回一个最小 JSON 值。这两种情况仍会通过
257
+ `details.truncated` 报告截断。当前没有续读或分页缓存;需要更多内容时可
258
+ 单独重新抓取 URL 或提高上限。
244
259
 
245
260
  ## 暴露规则
246
261
 
@@ -262,8 +277,9 @@ Authorization: Bearer <DeepSeek API Key>
262
277
  Content-Type: application/json
263
278
  ```
264
279
 
265
- 搜索使用 `query`、`count: 10`、`need_content: true`。原始 `results` 数组原样
266
- 返回,包括 `rerank_score`、`title`、`url`、`snippet`、`summary`、`content`、
280
+ 搜索使用 `query`、`count: 10`、`need_content: true`。DeepSeek 的 `query` 上限为
281
+ 128 个 Unicode 字符,因此超长 query 只在请求中按词边界缩短。原始 `results`
282
+ 数组原样返回,包括 `rerank_score`、`title`、`url`、`snippet`、`summary`、`content`、
267
283
  `site_name`、`site_icon`、`date`、`authority` 和未知字段。
268
284
 
269
285
  Fetch 发送 `{ "url": "..." }`,原样保存 `{ title, content }`。URL 最长 8192
@@ -323,7 +339,7 @@ npm run build
323
339
  ```
324
340
 
325
341
  `npm run build` 会运行检查、测试、包内容验证,并生成
326
- `dist/pi-better-web-search-0.1.0.tgz`。不会自动发布。
342
+ `dist/pi-better-web-search-0.1.7.tgz`。不会自动发布。
327
343
 
328
344
  测试是 `.mjs` 文件,直接导入 `.ts` 源码,mock `globalThis.fetch`,使用临时缓存
329
345
  目录。详见 [测试](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,34 @@ 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. Alternate models from every provider, including the current model's
77
+ provider id, round-robin across families, up to 12 attempts. A provider-wide
78
+ failure still skips that provider id; a model-specific failure can use a
79
+ sibling model from the same provider.
78
80
 
79
81
  Fetch candidates use the same shape but include only adapters with
80
82
  `supportsUrls` and a `fetch` implementation. The fetch cap is 6 attempts.
81
83
 
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.
84
+ Within a family, models are ordered by brand first: DeepSeek, OpenAI, Claude,
85
+ Gemini/Gemma, then other gateway brands. Brands without named tiers use variant
86
+ order `flash → base → pro`, then version number, newest first. GPT and Claude
87
+ use version number first, newest first, with capability tier as a tiebreaker:
88
+ OpenAI uses `luna → terra → sol → astra` and Claude uses
89
+ `haiku → sonnet → opus → fable`. Ties fall back to the deterministic
90
+ `provider/id@baseUrl` order.
88
91
  A provider id is only retried with another model when the first failure was
89
92
  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.
93
+ malformed request) skip the rest of that provider. Provider failures and
94
+ model-specific failures are remembered per phase (search/fetch) for the life of
95
+ the process. On later calls the failed provider or model is moved behind healthy
96
+ candidates for a 60-second to 10-minute exponential cooldown; a success clears
97
+ it. Calls already in flight are not cancelled or reordered.
98
+
99
+ The current model is preferred when it supports search and neither its provider
100
+ nor that model is cooling down. The cache is a fallback, not an override. When
101
+ the current model
102
+ is unsupported, the cached provider is tried first, which avoids repeating
103
+ discovery on every call.
95
104
 
96
105
  ## Cache and fingerprint
97
106
 
@@ -125,6 +134,8 @@ be used. A cached provider that is no longer available is ignored.
125
134
  ## Input validation
126
135
 
127
136
  - `query` is trimmed; search operators are otherwise passed through unchanged.
137
+ Provider adapters may shorten the provider-bound copy when that provider has
138
+ a lower query-length limit; the model-facing output keeps the original query.
128
139
  - `urls` is an array of at most 20 strings.
129
140
  - Each URL must be HTTP/HTTPS, have a host, omit username/password, and be at
130
141
  most 8192 characters.
@@ -161,15 +172,21 @@ The result is a JSON wrapper:
161
172
  Fields inside `search` and `fetched[].data` are provider data. The extension does
162
173
  not deduplicate, normalize, filter, re-rank, summarize, insert citation markers,
163
174
  or append source sections. The final guard keeps successful model-facing output
164
- within 64,000 Unicode code points by default (`PI_BETTER_WEB_SEARCH_MAX_CHARS`).
175
+ within 96,000 Unicode code points by default (`PI_BETTER_WEB_SEARCH_MAX_CHARS`).
165
176
  It preserves ordinary formatted JSON, or uses compact JSON if that alone fits.
166
- Otherwise it budgets sibling fields and array entries independently, preferring
167
- identifiers when space is tight. Strings can be shortened, and fields or trailing
168
- array entries omitted; the output remains valid JSON. `_truncation` records the
169
- original indented JSON length and affected paths, while `details.truncated` marks
170
- actual data loss. For very small limits below 19 characters, only the details
171
- flag fits. This is a character guard, not a token or model-context limit; it does
172
- not provide pagination or retain the complete provider payload for later use.
177
+ Otherwise it budgets sibling fields and array entries independently. Recognized
178
+ link and identity fields stay whole; entries or branches that cannot fit them
179
+ are omitted instead, without re-ranking. Standalone URLs and link/citation array
180
+ entries remain intact, and a recognizable URL crossing a text cut is omitted
181
+ rather than partially emitted. Unknown relative links or bare domains may not be
182
+ identifiable. Other strings can be shortened, and fields or trailing array entries
183
+ omitted. The JSON portion
184
+ stays valid, followed by one `[truncated]` line; the complete text is therefore
185
+ not valid JSON. No truncation metadata is injected into the model-facing JSON,
186
+ while `details.truncated` marks actual data loss. When truncation is needed with a limit of 11–13 characters,
187
+ only the marker is returned; below 11, a minimal JSON value is returned instead.
188
+ This is a character guard, not a token or model-context limit; it does not
189
+ provide pagination or retain the complete provider payload for later use.
173
190
 
174
191
  ## Provider adapter contract
175
192
 
@@ -208,6 +225,7 @@ the abort signal and resolve credentials through `lib/auth.ts`.
208
225
  | `extensions/index.ts` | Tool registration, exposure sync, lifecycle handlers |
209
226
  | `lib/candidates.ts` | Current/available candidates, ordering, cache resolution |
210
227
  | `lib/search.ts` | Input validation, search/fetch fallback, cache writes, output |
228
+ | `lib/health.ts` | Provider-wide failure cooldowns and candidate reordering |
211
229
  | `lib/auth.ts` | Credential resolution, header merging, env fallback |
212
230
  | `lib/cache.ts` | Preference cache and model-set fingerprint |
213
231
  | `lib/families.ts` | Provider family detection |
package/docs/providers.md CHANGED
@@ -55,7 +55,9 @@ POST https://api.deepseek.com/v1/tools/search
55
55
  ```
56
56
 
57
57
  - `query` is 1–128 Unicode characters, not all whitespace. Search operators are
58
- passed through unchanged.
58
+ passed through unchanged. Longer agent-generated queries are shortened at a
59
+ word boundary for the DeepSeek request only; the original query is retained
60
+ in the model-facing output.
59
61
  - `count` is within the documented 1–50 range; this package uses 10.
60
62
  - `need_content` is `true`, so `content` can contain the page body. The output
61
63
  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.6.tgz`. The tarball is not
33
+ This produces `dist/pi-better-web-search-0.1.7.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.6.tgz --access public
45
+ npm publish dist/pi-better-web-search-0.1.7.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.6 -m "v0.1.6"
55
- git push origin v0.1.6
56
- gh release create v0.1.6 dist/pi-better-web-search-0.1.6.tgz \
57
- --title "v0.1.6" \
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" \
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.6.tgz`.
20
+ `dist/pi-better-web-search-0.1.7.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:
@@ -30,8 +30,9 @@ and uses temporary cache directories. Coverage includes:
30
30
  - search and fetch fallback, including per-URL fallback;
31
31
  - provider request shapes and SSE parsing;
32
32
  - HTTP/stream errors and abort propagation;
33
- - structured character-guard truncation, valid JSON, Unicode and escaping,
34
- boundary lengths, and fair allocation across search results and URLs;
33
+ - structured character-guard truncation, a single trailing marker, valid JSON
34
+ before the marker, Unicode and escaping, boundary lengths, fair allocation,
35
+ and intact links and identifiers across search results and fetched pages;
35
36
  - one-tool registration and no system-prompt hooks.
36
37
 
37
38
  ## Live DeepSeek test