pi-better-web-search 0.1.8 → 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,21 @@
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
+
3
19
  ## 0.1.8
4
20
 
5
21
  - Shorten overlong DeepSeek search queries at a word boundary before sending
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,11 +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). 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
+ - `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.
87
90
  - `urls` analyzes the listed pages. URLs can be used **alone** or together with
88
91
  `query`. A query plus URLs performs a search and then analyzes the URLs.
89
92
  - At most **20** URLs may be supplied.
@@ -152,14 +155,16 @@ For a search:
152
155
  their capability tier as a tiebreaker: OpenAI tiers are
153
156
  `luna → terra → sol → astra` and Claude tiers are
154
157
  `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.
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.
160
162
 
161
- URL fetching uses the same idea, but considers only providers that implement
162
- URL fetching.
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.
163
168
 
164
169
  The current model is normally tried first when it supports search, unless its
165
170
  provider or model is in a failure cooldown. The cache does not replace a
@@ -167,20 +172,24 @@ supported current model; it mainly lets an unsupported current model use a
167
172
  remembered compatible provider immediately on later calls.
168
173
 
169
174
  If a provider errors, the extension records the attempt and moves to the next
170
- 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
171
177
  default, configurable with `PI_BETTER_WEB_SEARCH_TIMEOUT_MS`). If every attempt
172
178
  fails, the tool returns an error whose message contains the provider errors.
173
179
  Provider/model routing remains in `details.attempts`. For a URL-only call, the
174
- error also reports the per-URL failures.
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.
175
182
 
176
183
  Provider-wide failures (auth, balance, network, timeout, malformed request) and
177
184
  model-specific failures are remembered for the life of the extension process.
178
185
  On later calls the failed provider or model is moved behind healthy candidates
179
186
  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.
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.
184
193
 
185
194
  ### Cache fingerprint invalidation
186
195
 
@@ -266,7 +275,7 @@ this:
266
275
  - Redirects are not resolved and sources are not derived.
267
276
  - Unknown provider fields are preserved when the result fits the size guard.
268
277
 
269
- 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
270
279
  Unicode code points** by default. Normal-sized results retain their original
271
280
  fields and formatting. If indentation alone exceeds the limit, compact JSON is
272
281
  returned without dropping data or setting the truncation flag.
@@ -282,7 +291,7 @@ links or bare domains in unrecognized fields cannot always be identified. Other
282
291
  entries omitted; results are not re-ranked or summarized.
283
292
 
284
293
  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.
294
+ output-size truncation metadata or per-string markers are added to the JSON.
286
295
  Because of the trailing line, the complete text is not itself valid JSON.
287
296
  `details.truncated` is also set to `true` when data is actually removed.
288
297
 
@@ -331,8 +340,11 @@ Content-Type: application/json
331
340
  ```
332
341
 
333
342
  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,
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,
336
348
  including `rerank_score`, `title`, `url`,
337
349
  `snippet`, `summary`, `content`, `site_name`, `site_icon`, `date`, `authority`,
338
350
  and any unknown fields.
@@ -364,7 +376,7 @@ See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
364
376
 
365
377
  ## Verified
366
378
 
367
- - **116 unit and integration tests** covering exposure, schema variants,
379
+ - **Unit and integration tests** covering exposure, schema variants,
368
380
  provider request shapes, SSE parsing, raw-result preservation, fallback,
369
381
  cache invalidation, URL handling, truncation, and abort behavior.
370
382
  - **Real DeepSeek Search/Fetch run** with a real API key: 10 raw search results,
@@ -406,7 +418,7 @@ npm run build
406
418
  ```
407
419
 
408
420
  `npm run build` runs the checks and tests, verifies the npm file list, and packs
409
- `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.
410
422
 
411
423
  The test suite uses plain `.mjs` files that import the `.ts` sources directly.
412
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,9 +68,9 @@ pi install ./path/to/pi-better-web-search
65
68
  }
66
69
  ```
67
70
 
68
- - `query` 搜索网页。`site:`、引号、`AND`、`OR`、`-term` 等搜索语法原样传给
69
- provider,只去掉首尾空白。如果 provider 有更短的 query 上限,adapter 只会在
70
- 发给该 provider 的副本上按词边界缩短;输出中仍保留原始 query。
71
+ - `query` 搜索网页,只去掉首尾空白,搜索语法其余部分原样保留。如果选中
72
+ DeepSeek 且 query 超过 128 个 Unicode 字符,工具会直接返回实际长度和上限,
73
+ 提示模型缩短后重试;不会发送请求或静默截断。其他 provider 可以接受更长的查询。
71
74
  - `urls` 分析指定页面。可以**单独使用**,也可以和 `query` 一起使用。两者同时
72
75
  提供时,先搜索,再分析 URL。
73
76
  - 最多 **20** 个 URL。
@@ -126,25 +129,30 @@ Provider 识别顺序:
126
129
  内版本号从新到旧;GPT 和 Claude 仍按版本优先,版本相同时才按能力等级排序
127
130
  (便宜的等级优先,未知等级排最后):OpenAI 为 `luna → terra → sol → astra`,
128
131
  Claude 为 `haiku → sonnet → opus → fable`。
129
- 5. 所有 provider 的备用模型都会按 round-robin 继续尝试,包括当前模型同一
130
- provider id 下的其他模型,这样即使某个账号拒绝某个具体模型,也能换用同
131
- provider 的更新模型。provider 级失败(鉴权、余额、网络、超时、请求头异常)
132
- 会跳过该 provider 的其余模型;模型级失败则继续尝试同 provider 的其他模型。
132
+ 5. 优先尝试尚未覆盖的 provider,再按 family 的 round-robin 尝试各 provider
133
+ 的备用模型。provider 级失败会跳过该 provider;模型级失败(包括模型权限 403)
134
+ 则可继续尝试同 provider 的其他模型。
133
135
 
134
- URL 抓取使用同样的思路,但只考虑实现了 URL 抓取的 provider。
136
+ 搜索最多发起 12 次实际尝试;URL 抓取采用同样的思路,最多发起 6 次。跳过的候选
137
+ 不占用次数。排序只适用于支持的 API:例如内置的 `opencode-go` DeepSeek 模型
138
+ 使用 `openai-completions`,本扩展不会将它们当作 Responses 搜索接口。
135
139
 
136
140
  当前模型支持搜索时通常优先当前模型,除非该 provider 或该模型正处于失败冷却期。
137
141
  缓存不会覆盖它。缓存主要用于当前模型不支持搜索时,让下一次调用直接使用之前成功
138
142
  的兼容 provider。
139
143
 
140
- Provider 报错时记录 attempt 并继续下一个接口。取消会立即停止。每次尝试有
144
+ Provider 报错时记录 attempt 并继续下一个接口。DeepSeek 查询超长则直接返回错误,
145
+ 不继续尝试其他 provider,也不记录为 provider 健康故障。取消会立即停止。每次尝试有
141
146
  超时(默认 60 秒,`PI_BETTER_WEB_SEARCH_TIMEOUT_MS` 可调)。所有尝试都失败时,
142
147
  工具返回错误,消息中包含 provider 返回的错误;provider/model 路由信息保留在
143
- `details.attempts` 中。URL-only 调用还会报告每个 URL 的失败原因。
148
+ `details.attempts` 中。URL-only 调用还会报告每个 URL 的失败原因。provider 错误
149
+ 响应体与发给模型的错误文本都有大小限制,避免错误内容占满上下文。
144
150
 
145
151
  Provider 级失败(鉴权、余额、网络、超时、请求头异常)和单个模型失败都会在扩展进程内
146
152
  记住。后续调用会把失败的 provider 或模型排到健康候选之后,搜索和 URL 抓取分别记录。
147
- 冷却时间从 60 秒开始,连续失败时翻倍,最多 10 分钟;成功一次后清除。设置
153
+ 冷却时间从 60 秒开始,冷却结束后的再次尝试失败时翻倍,最多 10 分钟;同一冷却期内
154
+ 的并发失败不会延长时间。搜索成功,或至少一个 URL 抓取成功且没有 provider
155
+ 网络错误时,清除对应冷却。设置
148
156
  `PI_BETTER_WEB_SEARCH_FAILURE_COOLDOWN_MS=0` 可禁用。已经在途的并发调用仍可能同时
149
157
  尝试同一个候选。
150
158
 
@@ -226,7 +234,7 @@ Provider 数据放在 JSON 外层中返回,不做清理。示例:
226
234
  - 不解析 redirect,不派生 sources。
227
235
  - 未超出大小限制时,provider 的未知字段也会保留。
228
236
 
229
- 最终大小保护默认限制成功结果不超过 **96,000 个 Unicode code point**。
237
+ 最终大小保护默认限制结果及错误文本不超过 **96,000 个 Unicode code point**。
230
238
  未超限时保留原始字段及格式;如果只是缩进导致超限,会先压缩 JSON,
231
239
  不丢失数据,也不标记为截断。
232
240
 
@@ -239,8 +247,8 @@ Provider 数据放在 JSON 外层中返回,不做清理。示例:
239
247
  其他长字符串可能被缩短,字段或数组末尾的条目可能被省略;
240
248
  不对结果重排或总结。
241
249
 
242
- JSON 部分仍然合法,末尾仅追加一行 `[truncated]`。不会向模型可见的 JSON
243
- 中添加截断元数据,也不会逐个标记缩短的字符串。由于末尾追加了这一行,
250
+ 成功结果的 JSON 部分仍然合法,末尾仅追加一行 `[truncated]`。输出大小截断不会在
251
+ JSON 中添加元数据,也不会逐个标记字符串。由于末尾追加了这一行,
244
252
  整个文本不再是合法 JSON。确实丢失数据时,`details.truncated` 也会设为
245
253
  `true`。
246
254
 
@@ -278,8 +286,8 @@ Content-Type: application/json
278
286
  ```
279
287
 
280
288
  搜索使用 `query`、`count: 10`、`need_content: true`。DeepSeek 的 `query` 上限为
281
- 128 个 Unicode 字符,因此超长 query 只在请求中按词边界缩短。原始 `results`
282
- 数组原样返回,包括 `rerank_score`、`title`、`url`、`snippet`、`summary`、`content`、
289
+ 128 个 Unicode 字符,超长时会在发送请求前直接返回错误,提示缩短后重试。
290
+ 原始 `results` 数组原样返回,包括 `rerank_score`、`title`、`url`、`snippet`、`summary`、`content`、
283
291
  `site_name`、`site_icon`、`date`、`authority` 和未知字段。
284
292
 
285
293
  Fetch 发送 `{ "url": "..." }`,原样保存 `{ title, content }`。URL 最长 8192
@@ -304,7 +312,7 @@ provider;`403`/`404` 作为单个 URL 的错误上报,orchestrator 只重试
304
312
 
305
313
  ## 已验证
306
314
 
307
- - **116 个单元/集成测试**:暴露规则、schema 变体、provider 请求形状、SSE 解析、
315
+ - **单元/集成测试**:暴露规则、schema 变体、provider 请求形状、SSE 解析、
308
316
  原始结果保留、fallback、缓存失效、URL 处理、截断和取消。
309
317
  - **真实 DeepSeek Search/Fetch**:使用真实 API key,返回 10 条原始搜索结果、
310
318
  summary/content、合法 fetch 页面,以及文档中的 404/非法 URL 错误。
@@ -339,7 +347,7 @@ npm run build
339
347
  ```
340
348
 
341
349
  `npm run build` 会运行检查、测试、包内容验证,并生成
342
- `dist/pi-better-web-search-0.1.7.tgz`。不会自动发布。
350
+ `dist/pi-better-web-search-0.1.9.tgz`。不会自动发布。
343
351
 
344
352
  测试是 `.mjs` 文件,直接导入 `.ts` 源码,mock `globalThis.fetch`,使用临时缓存
345
353
  目录。详见 [测试](testing.md) 和 [发布](publishing.md)。
@@ -73,13 +73,14 @@ Search candidates:
73
73
  2. The remembered search provider when the cache fingerprint is current.
74
74
  3. One candidate per remaining family in this order:
75
75
  **DeepSeek → Ollama → Google → OpenAI → xAI → Anthropic**.
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.
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.
80
80
 
81
81
  Fetch candidates use the same shape but include only adapters with
82
- `supportsUrls` and a `fetch` implementation. The fetch cap is 6 attempts.
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.
83
84
 
84
85
  Within a family, models are ordered by brand first: DeepSeek, OpenAI, Claude,
85
86
  Gemini/Gemma, then other gateway brands. Brands without named tiers use variant
@@ -87,14 +88,19 @@ order `flash → base → pro`, then version number, newest first. GPT and Claud
87
88
  use version number first, newest first, with capability tier as a tiebreaker:
88
89
  OpenAI uses `luna → terra → sol → astra` and Claude uses
89
90
  `haiku → sonnet → opus → fable`. Ties fall back to the deterministic
90
- `provider/id@baseUrl` order.
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.
91
94
  A provider id is only retried with another model when the first failure was
92
95
  model-specific; provider-wide failures (auth, balance, network, timeout,
93
96
  malformed request) skip the rest of that provider. Provider failures and
94
97
  model-specific failures are remembered per phase (search/fetch) for the life of
95
98
  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.
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.
98
104
 
99
105
  The current model is preferred when it supports search and neither its provider
100
106
  nor that model is cooling down. The cache is a fallback, not an override. When
@@ -133,9 +139,10 @@ be used. A cached provider that is no longer available is ignored.
133
139
 
134
140
  ## Input validation
135
141
 
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.
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.
139
146
  - `urls` is an array of at most 20 strings.
140
147
  - Each URL must be HTTP/HTTPS, have a host, omit username/password, and be at
141
148
  most 8192 characters.
@@ -169,10 +176,11 @@ The result is a JSON wrapper:
169
176
  }
170
177
  ```
171
178
 
172
- Fields inside `search` and `fetched[].data` are provider data. The extension does
173
- not deduplicate, normalize, filter, re-rank, summarize, insert citation markers,
174
- or append source sections. The final guard keeps successful model-facing output
175
- 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`).
176
184
  It preserves ordinary formatted JSON, or uses compact JSON if that alone fits.
177
185
  Otherwise it budgets sibling fields and array entries independently. Recognized
178
186
  link and identity fields stay whole; entries or branches that cannot fit them
@@ -182,8 +190,8 @@ rather than partially emitted. Unknown relative links or bare domains may not be
182
190
  identifiable. Other strings can be shortened, and fields or trailing array entries
183
191
  omitted. The JSON portion
184
192
  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,
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,
187
195
  only the marker is returned; below 11, a minimal JSON value is returned instead.
188
196
  This is a character guard, not a token or model-context limit; it does not
189
197
  provide pagination or retain the complete provider payload for later use.
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,10 +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. 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
+ - `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.
61
64
  - `count` is within the documented 1–50 range; this package uses 10.
62
65
  - `need_content` is `true`, so `content` can contain the page body. The output
63
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:
package/lib/candidates.ts CHANGED
@@ -78,10 +78,10 @@ function modelTier(candidate: Candidate): number {
78
78
  }
79
79
 
80
80
  /**
81
- * Brand order inside one provider family. A gateway such as opencode-go can
82
- * expose DeepSeek and OpenAI models in the same family, and the user wants the
83
- * DeepSeek models attempted first. OpenAI and Claude keep their named-tier
84
- * ordering; other brands use the flash / base / pro variant order.
81
+ * Brand order among models that already support an adapter in the same family.
82
+ * A custom Responses gateway may expose several brands; OpenAI and Claude keep
83
+ * their named-tier ordering while other brands use flash / base / pro ordering.
84
+ * This ranking does not make an unsupported model API search-capable.
85
85
  */
86
86
  function modelBrandRank(id: string): number {
87
87
  const normalized = id.toLowerCase();
@@ -117,10 +117,14 @@ function versionTuple(id: string, family: ProviderFamily): number[] {
117
117
  if (family === "openai") {
118
118
  match = normalized.match(/^(?:gpt|o)[-_ ]?(\d+(?:\.\d+)*)/);
119
119
  } else if (family === "anthropic") {
120
- match = normalized.match(/^claude-(?:haiku|sonnet|opus|fable)-(\d+)(?:-(\d+))?/);
121
- if (match) return [Number(match[1]), Number(match[2] ?? 0)];
122
- match = normalized.match(/^claude-(\d+)(?:-(\d+))?/);
123
- if (match) return [Number(match[1]), Number(match[2] ?? 0)];
120
+ // A date can immediately follow a major version, e.g.
121
+ // claude-sonnet-4-20250514. Do not interpret it as a minor version.
122
+ match = normalized.match(/^claude-(?:haiku|sonnet|opus|fable)-(\d+)(?:-(\d+))?/)
123
+ ?? normalized.match(/^claude-(\d+)(?:-(\d+))?/);
124
+ if (match) {
125
+ const minor = match[2];
126
+ return [Number(match[1]), minor && minor.length < 8 ? Number(minor) : 0];
127
+ }
124
128
  } else if (family === "google") {
125
129
  match = normalized.match(/^(?:gemini|gemma)[-_]?(\d+(?:\.\d+)*)/);
126
130
  if (!match) return [];
@@ -319,8 +323,8 @@ function buildCandidates(
319
323
  }
320
324
 
321
325
  if (!resolution.fresh && cached && isUsable(cached)) {
322
- // Never repeat the same provider id after the current model failed. A
323
- // cached hint is only useful when it points at a different interface.
326
+ // Do not promote a cached sibling ahead of other providers. Siblings from
327
+ // the same provider remain eligible in the later fallback pass.
324
328
  const sameProviderSelected = selected.some(
325
329
  (candidate) => candidate.model.provider === cached.model.provider,
326
330
  );
@@ -341,14 +345,10 @@ function buildCandidates(
341
345
  }
342
346
  }
343
347
 
344
- // Deeper fallback: alternate models from every provider, including the
345
- // current model's provider. Providers frequently reject one specific model
346
- // (legacy IDs, account tiers, regional availability) while serving a sibling,
347
- // so a single interface per family is too fragile. Round-robin across
348
- // families so every family gets a second chance before any family gets a
349
- // third, keeping the broad cross-provider coverage that the one-per-family
350
- // pass provides. A provider-wide runtime failure still skips the rest of that
351
- // provider id; only model-specific failures reach these siblings.
348
+ // Prefer an interface from each provider before trying sibling models. A
349
+ // single provider may expose many highly ranked models in one family, but a
350
+ // provider-wide failure would make all of them unusable at once. Keep the
351
+ // family round-robin within each pass, then include every remaining sibling.
352
352
  const queues = new Map<ProviderFamily, Candidate[]>();
353
353
  for (const family of PROVIDER_FAMILIES) {
354
354
  const queue = usableFamilyCandidates(resolution, family, isUsable).filter(
@@ -356,33 +356,50 @@ function buildCandidates(
356
356
  );
357
357
  if (queue.length > 0) queues.set(family, queue);
358
358
  }
359
-
360
- let progressed = true;
361
- while (selected.length < cap && progressed) {
362
- progressed = false;
363
- for (const family of PROVIDER_FAMILIES) {
364
- if (selected.length >= cap) break;
365
- const queue = queues.get(family);
366
- const next = queue?.shift();
367
- if (next && addUnique(selected, next, seen, cap)) progressed = true;
359
+ const representedProviders = new Set(selected.map((candidate) => candidate.model.provider));
360
+ for (const distinctProvidersOnly of [true, false]) {
361
+ let progressed = true;
362
+ while (selected.length < cap && progressed) {
363
+ progressed = false;
364
+ for (const family of PROVIDER_FAMILIES) {
365
+ if (selected.length >= cap) break;
366
+ const queue = queues.get(family);
367
+ if (!queue) continue;
368
+ const index = distinctProvidersOnly
369
+ ? queue.findIndex((candidate) => !representedProviders.has(candidate.model.provider))
370
+ : 0;
371
+ if (index < 0 || index >= queue.length) continue;
372
+ const [next] = queue.splice(index, 1);
373
+ if (addUnique(selected, next, seen, cap)) {
374
+ representedProviders.add(next.model.provider);
375
+ progressed = true;
376
+ }
377
+ }
368
378
  }
369
379
  }
370
380
 
371
381
  return selected;
372
382
  }
373
383
 
374
- export function getSearchCandidates(resolution: ResolutionContext): Candidate[] {
384
+ /** The orchestrator can request all candidates and cap actual attempts instead. */
385
+ export function getSearchCandidates(
386
+ resolution: ResolutionContext,
387
+ cap = SEARCH_ATTEMPT_CAP,
388
+ ): Candidate[] {
375
389
  const cached = resolution.fresh
376
390
  ? undefined
377
391
  : resolveRef(resolution, resolution.cache.search, supportsSearch);
378
- return buildCandidates(resolution, supportsSearch, cached, SEARCH_ATTEMPT_CAP);
392
+ return buildCandidates(resolution, supportsSearch, cached, cap);
379
393
  }
380
394
 
381
- export function getFetchCandidates(resolution: ResolutionContext): Candidate[] {
395
+ export function getFetchCandidates(
396
+ resolution: ResolutionContext,
397
+ cap = FETCH_ATTEMPT_CAP,
398
+ ): Candidate[] {
382
399
  const cached = resolution.fresh
383
400
  ? undefined
384
401
  : resolveRef(resolution, resolution.cache.fetch, supportsUrls);
385
- return buildCandidates(resolution, supportsUrls, cached, FETCH_ATTEMPT_CAP);
402
+ return buildCandidates(resolution, supportsUrls, cached, cap);
386
403
  }
387
404
 
388
405
  export function hasExposedCandidate(resolution: ResolutionContext): boolean {
package/lib/format.ts CHANGED
@@ -70,10 +70,17 @@ export function formatSuccess(
70
70
  export function formatError(
71
71
  message: string,
72
72
  details: WebSearchDetails,
73
+ prefix = "Failed: ",
73
74
  ): AgentToolResult<WebSearchDetails> {
75
+ const full = `${prefix}${message}`;
76
+ const limited = truncateText(full, MAX_OUTPUT_CHARS);
77
+ const marker = "[truncated]";
78
+ const text = limited.truncated && MAX_OUTPUT_CHARS >= marker.length
79
+ ? `${truncateText(full, MAX_OUTPUT_CHARS - marker.length).text}${marker}`
80
+ : limited.text;
74
81
  return {
75
- content: [{ type: "text", text: `Failed: ${message}` }],
76
- details,
82
+ content: [{ type: "text", text }],
83
+ details: limited.truncated ? { ...details, truncated: true } : details,
77
84
  isError: true,
78
85
  };
79
86
  }
package/lib/health.ts CHANGED
@@ -43,10 +43,18 @@ function recordFailure(
43
43
  provider: string,
44
44
  message: string,
45
45
  now: number,
46
+ attemptStartedAt: number,
46
47
  ): void {
47
48
  const previous = failures.get(key);
48
- const consecutiveFailures = (previous?.consecutiveFailures ?? 0) + 1;
49
49
  const base = failureCooldownMs();
50
+ if (base === 0) {
51
+ failures.delete(key);
52
+ return;
53
+ }
54
+ // In-flight calls, or last-resort attempts started before expiry, are not a
55
+ // new probe even when they finish after the previous cooldown has expired.
56
+ if (previous && (previous.retryAt > now || attemptStartedAt < previous.retryAt)) return;
57
+ const consecutiveFailures = (previous?.consecutiveFailures ?? 0) + 1;
50
58
  const exponent = Math.min(consecutiveFailures - 1, 10);
51
59
  const cooldown = Math.min(base * 2 ** exponent, MAX_FAILURE_COOLDOWN_MS);
52
60
  failures.set(key, {
@@ -63,8 +71,9 @@ export function recordProviderFailure(
63
71
  provider: string,
64
72
  message: string,
65
73
  now = Date.now(),
74
+ attemptStartedAt = now,
66
75
  ): void {
67
- recordFailure(providerFailureKey(phase, provider), phase, provider, message, now);
76
+ recordFailure(providerFailureKey(phase, provider), phase, provider, message, now, attemptStartedAt);
68
77
  }
69
78
 
70
79
  /** Remember a single model failure without cooling down its whole provider. */
@@ -74,8 +83,9 @@ export function recordModelFailure(
74
83
  model: string,
75
84
  message: string,
76
85
  now = Date.now(),
86
+ attemptStartedAt = now,
77
87
  ): void {
78
- recordFailure(modelFailureKey(phase, provider, model), phase, provider, message, now);
88
+ recordFailure(modelFailureKey(phase, provider, model), phase, provider, message, now, attemptStartedAt);
79
89
  }
80
90
 
81
91
  export function clearProviderFailure(phase: ProviderPhase, provider: string): void {
@@ -91,6 +101,7 @@ export function isProviderCoolingDown(
91
101
  provider: string,
92
102
  now = Date.now(),
93
103
  ): boolean {
104
+ if (failureCooldownMs() === 0) return false;
94
105
  const failure = failures.get(providerFailureKey(phase, provider));
95
106
  return !!failure && failure.retryAt > now;
96
107
  }
@@ -101,6 +112,7 @@ export function isModelCoolingDown(
101
112
  model: string,
102
113
  now = Date.now(),
103
114
  ): boolean {
115
+ if (failureCooldownMs() === 0) return false;
104
116
  const failure = failures.get(modelFailureKey(phase, provider, model));
105
117
  return !!failure && failure.retryAt > now;
106
118
  }
@@ -12,6 +12,7 @@ import {
12
12
  readJson,
13
13
  responseError,
14
14
  } from "./http.ts";
15
+ import { QueryLengthError } from "./types.ts";
15
16
  import type {
16
17
  ProviderAdapter,
17
18
  ProviderFetchEntry,
@@ -58,35 +59,14 @@ function rethrowAbort(error: unknown, signal: AbortSignal | undefined): void {
58
59
  throw error;
59
60
  }
60
61
 
61
- function validateQuery(query: string): string | undefined {
62
- const length = typeof query === "string" ? Array.from(query).length : 0;
62
+ function validateQuery(query: string): void {
63
63
  if (typeof query !== "string" || query.trim().length === 0) {
64
- return `Invalid query: a non-whitespace query of 1-${DEEPSEEK_MAX_QUERY_LENGTH} Unicode characters is required`;
64
+ throw new Error(`Invalid query: a non-whitespace query of 1-${DEEPSEEK_MAX_QUERY_LENGTH} Unicode characters is required`);
65
65
  }
66
- if (length < 1 || length > DEEPSEEK_MAX_QUERY_LENGTH) {
67
- return `Invalid query: length must be 1-${DEEPSEEK_MAX_QUERY_LENGTH} Unicode characters`;
66
+ const length = Array.from(query).length;
67
+ if (length > DEEPSEEK_MAX_QUERY_LENGTH) {
68
+ throw new QueryLengthError("DeepSeek", length, DEEPSEEK_MAX_QUERY_LENGTH);
68
69
  }
69
- return undefined;
70
- }
71
-
72
- /**
73
- * DeepSeek rejects queries longer than 128 Unicode characters. Agent-generated
74
- * search queries routinely exceed that limit, especially when several parallel
75
- * calls are issued. Shorten only the provider-bound copy, preferring a word
76
- * boundary so the tail is not cut in the middle of a term. The original query
77
- * remains in the model-facing output.
78
- */
79
- export function clampDeepSeekQuery(query: string): string {
80
- const characters = Array.from(query);
81
- if (characters.length <= DEEPSEEK_MAX_QUERY_LENGTH) return query;
82
-
83
- const head = characters.slice(0, DEEPSEEK_MAX_QUERY_LENGTH).join("");
84
- const boundary = head.search(/\s+\S*$/u);
85
- // Keep the hard cut when word-trimming would discard too much of the query.
86
- if (boundary >= Math.floor(DEEPSEEK_MAX_QUERY_LENGTH / 2)) {
87
- return head.slice(0, boundary).trimEnd();
88
- }
89
- return head.trimEnd();
90
70
  }
91
71
 
92
72
  function validateFetchUrl(url: string): string | undefined {
@@ -167,9 +147,7 @@ export const deepseekAdapter: ProviderAdapter = {
167
147
  ): Promise<ProviderSearchResult> {
168
148
  checkAbort(signal);
169
149
 
170
- const effectiveQuery = clampDeepSeekQuery(query);
171
- const queryError = validateQuery(effectiveQuery);
172
- if (queryError) throw new Error(queryError);
150
+ validateQuery(query);
173
151
 
174
152
  const target = await resolveDeepSeekTarget(ctx, model);
175
153
  checkAbort(signal);
@@ -178,7 +156,7 @@ export const deepseekAdapter: ProviderAdapter = {
178
156
  method: "POST",
179
157
  headers: target.headers,
180
158
  body: JSON.stringify({
181
- query: effectiveQuery,
159
+ query,
182
160
  count: DEEPSEEK_SEARCH_COUNT,
183
161
  need_content: DEEPSEEK_NEED_CONTENT,
184
162
  }),
@@ -227,8 +205,11 @@ export const deepseekAdapter: ProviderAdapter = {
227
205
  });
228
206
  } catch (error) {
229
207
  rethrowAbort(error, signal);
230
- entries.push({ url, error: errorMessage(error) });
231
- continue;
208
+ const providerError = errorMessage(error);
209
+ entries.push({ url, error: providerError });
210
+ // This request reaches the provider endpoint, so a transport failure is
211
+ // not specific to the target URL. Preserve earlier successes and stop.
212
+ return { entries, providerError };
232
213
  }
233
214
  checkAbort(signal);
234
215
 
@@ -1,12 +1,57 @@
1
1
  export class HttpError extends Error {
2
2
  readonly status: number;
3
3
  readonly body?: string;
4
+ readonly code?: string;
4
5
 
5
- constructor(status: number, message: string, body?: string) {
6
+ constructor(status: number, message: string, body?: string, code?: string) {
6
7
  super(message);
7
8
  this.name = "HttpError";
8
9
  this.status = status;
9
10
  this.body = body;
11
+ this.code = code;
12
+ }
13
+ }
14
+
15
+ /** Bound untrusted HTTP error bodies before storing or forwarding them. */
16
+ export const MAX_ERROR_BODY_BYTES = 64 * 1024;
17
+
18
+ async function readErrorBody(response: Response): Promise<string> {
19
+ if (!response.body) return "";
20
+ const reader = response.body.getReader();
21
+ const decoder = new TextDecoder();
22
+ let text = "";
23
+ let bytes = 0;
24
+ let done = false;
25
+ let truncated = false;
26
+ try {
27
+ while (true) {
28
+ const chunk = await reader.read();
29
+ if (chunk.done) {
30
+ done = true;
31
+ break;
32
+ }
33
+ const remaining = MAX_ERROR_BODY_BYTES - bytes;
34
+ const part = chunk.value.subarray(0, remaining);
35
+ bytes += part.byteLength;
36
+ text += decoder.decode(part, { stream: true });
37
+ // Stop reading even if this chunk exactly fills the budget; the stream
38
+ // might be unbounded and waiting for another chunk could hang the call.
39
+ if (bytes >= MAX_ERROR_BODY_BYTES) {
40
+ truncated = true;
41
+ break;
42
+ }
43
+ }
44
+ text += decoder.decode();
45
+ return truncated ? `${text}\n[truncated]` : text;
46
+ } finally {
47
+ if (!done) {
48
+ try {
49
+ await reader.cancel();
50
+ } catch {
51
+ // An interrupted response may already be closed.
52
+ }
53
+ }
54
+ reader.releaseLock();
10
55
  }
11
56
  }
12
57
 
@@ -24,22 +69,26 @@ export async function readJson<T = unknown>(response: Response): Promise<T> {
24
69
  }
25
70
 
26
71
  export async function responseError(response: Response, label: string): Promise<HttpError> {
27
- const body = await response.text().catch(() => "");
72
+ const body = await readErrorBody(response).catch(() => "");
28
73
  let detail = body.trim();
74
+ let code: string | undefined;
29
75
 
30
76
  if (detail) {
31
77
  try {
32
78
  const parsed = JSON.parse(body) as {
33
- error?: { message?: unknown } | string;
79
+ error?: { message?: unknown; code?: unknown } | string;
34
80
  message?: unknown;
81
+ code?: unknown;
35
82
  };
36
- const nested = typeof parsed.error === "object" && parsed.error !== null ? parsed.error.message : undefined;
37
- const message = nested ?? (typeof parsed.error === "string" ? parsed.error : parsed.message);
83
+ const nestedError = typeof parsed.error === "object" && parsed.error !== null ? parsed.error : undefined;
84
+ const message = nestedError?.message ?? (typeof parsed.error === "string" ? parsed.error : parsed.message);
85
+ const errorCode = nestedError?.code ?? parsed.code;
86
+ if (typeof errorCode === "string") code = errorCode;
38
87
  if (typeof message === "string" && message.trim()) {
39
88
  detail = message.trim();
40
89
  }
41
90
  } catch {
42
- // Keep the raw response body when it is not JSON.
91
+ // Keep the bounded raw response body when it is not complete JSON.
43
92
  }
44
93
  }
45
94
 
@@ -48,6 +97,7 @@ export async function responseError(response: Response, label: string): Promise<
48
97
  response.status,
49
98
  `${label} API error (${response.status}${statusText}): ${detail || "no response body"}`,
50
99
  body || undefined,
100
+ code,
51
101
  );
52
102
  }
53
103
 
@@ -163,8 +163,11 @@ export const ollamaAdapter: ProviderAdapter = {
163
163
  });
164
164
  } catch (error) {
165
165
  rethrowAbort(error, signal);
166
- entries.push({ url, error: errorMessage(error) });
167
- continue;
166
+ const providerError = errorMessage(error);
167
+ entries.push({ url, error: providerError });
168
+ // Transport failures reach the provider endpoint, not the target URL.
169
+ // Preserve earlier successes but do not repeat a broken connection.
170
+ return { entries, providerError };
168
171
  }
169
172
  checkAbort(signal);
170
173
 
@@ -4,6 +4,24 @@ import type { Api, Model } from "@earendil-works/pi-ai";
4
4
  export const PROVIDER_FAMILIES = ["deepseek", "ollama", "google", "openai", "xai", "anthropic"] as const;
5
5
  export type ProviderFamily = (typeof PROVIDER_FAMILIES)[number];
6
6
 
7
+ /** A request validation error that the model can fix and retry. */
8
+ export class QueryLengthError extends Error {
9
+ readonly provider: string;
10
+ readonly actualLength: number;
11
+ readonly maxLength: number;
12
+
13
+ constructor(provider: string, actualLength: number, maxLength: number) {
14
+ super(
15
+ `Search query is too long (${actualLength} Unicode characters). `
16
+ + `The maximum is ${maxLength} Unicode characters. Shorten the query and retry.`,
17
+ );
18
+ this.name = "QueryLengthError";
19
+ this.provider = provider;
20
+ this.actualLength = actualLength;
21
+ this.maxLength = maxLength;
22
+ }
23
+ }
24
+
7
25
  export interface ProviderSearchResult {
8
26
  answer?: string;
9
27
  results?: unknown;
@@ -21,6 +39,8 @@ export interface ProviderFetchEntry {
21
39
 
22
40
  export interface ProviderFetchResult {
23
41
  entries: ProviderFetchEntry[];
42
+ /** A transport failure reaching the provider, not a failure of a target URL. */
43
+ providerError?: string;
24
44
  }
25
45
 
26
46
  export interface ProviderAdapter {
package/lib/search.ts CHANGED
@@ -4,6 +4,8 @@ import type {
4
4
  ExtensionContext,
5
5
  } from "@earendil-works/pi-coding-agent";
6
6
  import {
7
+ FETCH_ATTEMPT_CAP,
8
+ SEARCH_ATTEMPT_CAP,
7
9
  getFetchCandidates,
8
10
  getSearchCandidates,
9
11
  resolveResolutionContext,
@@ -14,6 +16,7 @@ import { writeCache, type PreferenceCache, type ProviderRef } from "./cache.ts";
14
16
  import {
15
17
  formatError,
16
18
  formatSuccess,
19
+ truncateText,
17
20
  type WebSearchAttempt,
18
21
  type WebSearchDetails,
19
22
  type WebSearchOutput,
@@ -25,6 +28,7 @@ import {
25
28
  recordModelFailure,
26
29
  recordProviderFailure,
27
30
  } from "./health.ts";
31
+ import { QueryLengthError } from "./providers/types.ts";
28
32
  import { MAX_URLS } from "./schema.ts";
29
33
 
30
34
  export const DEFAULT_ATTEMPT_TIMEOUT_MS = 60_000;
@@ -50,12 +54,22 @@ interface FetchState {
50
54
  error?: string;
51
55
  }
52
56
 
57
+ const MAX_ERROR_DETAIL_CHARS = 8_192;
58
+
53
59
  function errorMessage(error: unknown): string {
54
60
  if (error instanceof Error) return error.message;
55
61
  if (typeof error === "string") return error;
56
62
  return String(error);
57
63
  }
58
64
 
65
+ function limitErrorMessage(message: string): string {
66
+ const marker = "[truncated]";
67
+ const limited = truncateText(message, MAX_ERROR_DETAIL_CHARS);
68
+ return limited.truncated
69
+ ? `${truncateText(message, MAX_ERROR_DETAIL_CHARS - marker.length).text}${marker}`
70
+ : message;
71
+ }
72
+
59
73
  function summarizeUrlErrors(errors: UrlValidationError[]): string {
60
74
  return errors.map((entry) => `${entry.url}: ${entry.error}`).join("; ");
61
75
  }
@@ -203,7 +217,28 @@ const PROVIDER_WIDE_FAILURE_PATTERNS: readonly RegExp[] = [
203
217
  /\bbytestring\b/i,
204
218
  ];
205
219
 
206
- export function isProviderWideFailure(message: string): boolean {
220
+ const MODEL_PERMISSION_PATTERNS: readonly RegExp[] = [
221
+ /\bmodel[_ -](?:not[_ -](?:found|allowed|available|supported)|access[_ -]denied)\b/i,
222
+ /\bmodels?\b[^\n]{0,200}\b(?:not (?:found|allowed|available|accessible|enabled|supported)|does not exist|access denied|permission denied)\b/i,
223
+ /\b(?:do(?:es)? not have|don't have|no|lack(?:s)?|denied|not (?:allowed|authorized|permitted))\b[^\n]{0,160}\b(?:access|permission|use)\b[^\n]{0,160}\bmodels?\b/i,
224
+ /\b(?:access|permission)\b[^\n]{0,160}\b(?:denied|not (?:granted|allowed|permitted))\b[^\n]{0,160}\bmodels?\b/i,
225
+ /\b(?:access|permission)\b[^\n]{0,160}\bmodels?\b[^\n]{0,160}\b(?:denied|not (?:granted|allowed|permitted))\b/i,
226
+ ];
227
+
228
+ export function isProviderWideFailure(message: string, error?: unknown): boolean {
229
+ const details = typeof error === "object" && error !== null
230
+ ? error as { status?: unknown; code?: unknown }
231
+ : undefined;
232
+ const isForbidden = details?.status === 403 || details?.status === "403"
233
+ || /(?:\(|HTTP\s+|status(?:\s+code)?\s*)403\b|\bforbidden\b/i.test(message);
234
+ const code = typeof details?.code === "string" ? details.code : "";
235
+ if (isForbidden && MODEL_PERMISSION_PATTERNS.some((pattern) => pattern.test(`${code} ${message}`))) {
236
+ return false;
237
+ }
238
+ const status = typeof details?.status === "number" || typeof details?.status === "string"
239
+ ? Number(details.status)
240
+ : NaN;
241
+ if (status === 401 || status === 403 || status === 429 || (status >= 500 && status < 600)) return true;
207
242
  return PROVIDER_WIDE_FAILURE_PATTERNS.some((pattern) => pattern.test(message));
208
243
  }
209
244
 
@@ -256,17 +291,20 @@ async function runSearch(
256
291
  onUpdate: AgentToolUpdateCallback | undefined,
257
292
  attempts: WebSearchAttempt[],
258
293
  ): Promise<SearchSuccess | undefined> {
259
- const candidates = getSearchCandidates(resolution);
294
+ const candidates = getSearchCandidates(resolution, Infinity);
260
295
  if (candidates.length === 0) return undefined;
261
296
 
262
- // Providers whose failure was not model-specific are not retried with a
263
- // different model, so a dead credential or network path does not burn the
264
- // whole attempt budget on one interface.
297
+ // Skipped candidates do not consume the budget. Consider the full discovery
298
+ // set when applying cooldowns so a healthy provider beyond the cap is usable.
265
299
  const failedProviders = new Set<string>();
300
+ let attemptCount = 0;
266
301
 
267
302
  for (const candidate of prioritizeCandidates("search", candidates)) {
268
303
  if (externalSignal?.aborted) throw abortReason(externalSignal);
269
304
  if (failedProviders.has(candidate.model.provider)) continue;
305
+ if (attemptCount >= SEARCH_ATTEMPT_CAP) break;
306
+ attemptCount += 1;
307
+ const attemptStartedAt = Date.now();
270
308
 
271
309
  const timeout = timeoutMs();
272
310
  const signal = attemptSignal(externalSignal, timeout);
@@ -283,22 +321,29 @@ async function runSearch(
283
321
  return { candidate, result: result ?? {} };
284
322
  } catch (error) {
285
323
  if (externalSignal?.aborted) throw abortReason(externalSignal);
286
- const message = errorMessage(error);
324
+ // Input validation is actionable by the model and must not poison health
325
+ // or silently fall through to another provider.
326
+ if (error instanceof QueryLengthError) throw error;
327
+ const rawMessage = errorMessage(error);
328
+ const providerWide = isProviderWideFailure(rawMessage, error);
329
+ const message = limitErrorMessage(rawMessage);
287
330
  attempts.push({
288
331
  phase: "search",
289
332
  provider: candidate.model.provider,
290
333
  model: candidate.model.id,
291
334
  message,
292
335
  });
293
- if (isProviderWideFailure(message)) {
336
+ if (providerWide) {
294
337
  failedProviders.add(candidate.model.provider);
295
- recordProviderFailure("search", candidate.model.provider, message);
338
+ recordProviderFailure("search", candidate.model.provider, message, Date.now(), attemptStartedAt);
296
339
  } else {
297
340
  recordModelFailure(
298
341
  "search",
299
342
  candidate.model.provider,
300
343
  candidate.model.id,
301
344
  message,
345
+ Date.now(),
346
+ attemptStartedAt,
302
347
  );
303
348
  }
304
349
  }
@@ -331,7 +376,7 @@ function assignFetchEntries(
331
376
  if (index === undefined) continue;
332
377
 
333
378
  if (entry.error || entry.data === undefined) {
334
- states[index].error = entry.error || "Provider did not return data for this URL";
379
+ states[index].error = limitErrorMessage(entry.error || "Provider did not return data for this URL");
335
380
  continue;
336
381
  }
337
382
 
@@ -369,11 +414,15 @@ async function runFetch(
369
414
  // As with search, a provider-wide failure is not retried with another model
370
415
  // from the same provider id.
371
416
  const failedProviders = new Set<string>();
417
+ let attemptCount = 0;
372
418
 
373
419
  for (const candidate of prioritizeCandidates("fetch", candidates)) {
374
420
  if (remaining.length === 0) break;
375
421
  if (externalSignal?.aborted) throw abortReason(externalSignal);
376
422
  if (failedProviders.has(candidate.model.provider)) continue;
423
+ if (attemptCount >= FETCH_ATTEMPT_CAP) break;
424
+ attemptCount += 1;
425
+ const attemptStartedAt = Date.now();
377
426
 
378
427
  const timeout = timeoutMs();
379
428
  const signal = attemptSignal(externalSignal, timeout);
@@ -400,8 +449,21 @@ async function runFetch(
400
449
 
401
450
  const assigned = assignFetchEntries(states, remaining, result?.entries ?? [], candidate);
402
451
  remaining = assigned.remaining;
403
- clearProviderFailure("fetch", candidate.model.provider);
404
- clearModelFailure("fetch", candidate.model.provider, candidate.model.id);
452
+ if (result?.providerError) {
453
+ const message = limitErrorMessage(result.providerError);
454
+ attempts.push({
455
+ phase: "fetch",
456
+ provider: candidate.model.provider,
457
+ model: candidate.model.id,
458
+ message,
459
+ });
460
+ failedProviders.add(candidate.model.provider);
461
+ recordProviderFailure("fetch", candidate.model.provider, message, Date.now(), attemptStartedAt);
462
+ for (const index of remaining) states[index].error ||= message;
463
+ } else if (assigned.successful > 0) {
464
+ clearProviderFailure("fetch", candidate.model.provider);
465
+ clearModelFailure("fetch", candidate.model.provider, candidate.model.id);
466
+ }
405
467
 
406
468
  if (assigned.successful > 0) {
407
469
  // Replace only on a strictly larger success count, so the first
@@ -413,22 +475,26 @@ async function runFetch(
413
475
  }
414
476
  } catch (error) {
415
477
  if (externalSignal?.aborted) throw abortReason(externalSignal);
416
- const message = errorMessage(error);
478
+ const rawMessage = errorMessage(error);
479
+ const providerWide = isProviderWideFailure(rawMessage, error);
480
+ const message = limitErrorMessage(rawMessage);
417
481
  attempts.push({
418
482
  phase: "fetch",
419
483
  provider: candidate.model.provider,
420
484
  model: candidate.model.id,
421
485
  message,
422
486
  });
423
- if (isProviderWideFailure(message)) {
487
+ if (providerWide) {
424
488
  failedProviders.add(candidate.model.provider);
425
- recordProviderFailure("fetch", candidate.model.provider, message);
489
+ recordProviderFailure("fetch", candidate.model.provider, message, Date.now(), attemptStartedAt);
426
490
  } else {
427
491
  recordModelFailure(
428
492
  "fetch",
429
493
  candidate.model.provider,
430
494
  candidate.model.id,
431
495
  message,
496
+ Date.now(),
497
+ attemptStartedAt,
432
498
  );
433
499
  }
434
500
  for (const index of remaining) {
@@ -495,7 +561,12 @@ export async function runWebSearch(
495
561
  return formatError(message, { attempts, error: message });
496
562
  }
497
563
 
498
- searchSuccess = await runSearch(resolution, query, signal, onUpdate, attempts);
564
+ try {
565
+ searchSuccess = await runSearch(resolution, query, signal, onUpdate, attempts);
566
+ } catch (error) {
567
+ if (!(error instanceof QueryLengthError)) throw error;
568
+ return formatError(error.message, { attempts, error: error.message }, "");
569
+ }
499
570
  if (!searchSuccess) {
500
571
  const providerErrors = attemptMessages(attempts, "search");
501
572
  const message = providerErrors || "This tool is not available in this conversation.";
@@ -503,7 +574,7 @@ export async function runWebSearch(
503
574
  }
504
575
  }
505
576
 
506
- const fetchCandidates = validFetchRequested ? getFetchCandidates(resolution) : [];
577
+ const fetchCandidates = validFetchRequested ? getFetchCandidates(resolution, Infinity) : [];
507
578
  if (validFetchRequested && fetchCandidates.length === 0) {
508
579
  const message = "URL fetch is not available in this conversation.";
509
580
  // The search half succeeded; remember it even though the URL half did not.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-better-web-search",
3
- "version": "0.1.8",
3
+ "version": "0.1.9",
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",