pi-better-web-search 0.1.7 → 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 +30 -0
- package/README.md +37 -21
- package/docs/README.zh-CN.md +26 -16
- package/docs/architecture.md +28 -16
- package/docs/providers.md +3 -1
- package/lib/candidates.ts +95 -35
- package/lib/health.ts +147 -0
- package/lib/providers/deepseek.ts +23 -2
- package/lib/search.ts +46 -11
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,35 @@
|
|
|
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
|
+
|
|
3
33
|
## 0.1.7
|
|
4
34
|
|
|
5
35
|
- Keep recognized URL/URI/link and title/name/ID fields intact when truncating;
|
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,
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
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
|
|
161
|
-
|
|
162
|
-
model
|
|
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
|
|
168
|
-
|
|
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
|
|
|
@@ -316,8 +330,10 @@ Authorization: Bearer <DeepSeek API Key>
|
|
|
316
330
|
Content-Type: application/json
|
|
317
331
|
```
|
|
318
332
|
|
|
319
|
-
Search uses `query`, `count: 10`, and `need_content: true`.
|
|
320
|
-
|
|
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`,
|
|
321
337
|
`snippet`, `summary`, `content`, `site_name`, `site_icon`, `date`, `authority`,
|
|
322
338
|
and any unknown fields.
|
|
323
339
|
|
package/docs/README.zh-CN.md
CHANGED
|
@@ -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
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
provider
|
|
130
|
-
|
|
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
|
-
|
|
136
|
+
当前模型支持搜索时通常优先当前模型,除非该 provider 或该模型正处于失败冷却期。
|
|
137
|
+
缓存不会覆盖它。缓存主要用于当前模型不支持搜索时,让下一次调用直接使用之前成功
|
|
138
|
+
的兼容 provider。
|
|
136
139
|
|
|
137
140
|
Provider 报错时记录 attempt 并继续下一个接口。取消会立即停止。每次尝试有
|
|
138
141
|
超时(默认 60 秒,`PI_BETTER_WEB_SEARCH_TIMEOUT_MS` 可调)。所有尝试都失败时,
|
|
139
|
-
|
|
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
|
|
|
@@ -268,8 +277,9 @@ Authorization: Bearer <DeepSeek API Key>
|
|
|
268
277
|
Content-Type: application/json
|
|
269
278
|
```
|
|
270
279
|
|
|
271
|
-
搜索使用 `query`、`count: 10`、`need_content: true
|
|
272
|
-
|
|
280
|
+
搜索使用 `query`、`count: 10`、`need_content: true`。DeepSeek 的 `query` 上限为
|
|
281
|
+
128 个 Unicode 字符,因此超长 query 只在请求中按词边界缩短。原始 `results`
|
|
282
|
+
数组原样返回,包括 `rerank_score`、`title`、`url`、`snippet`、`summary`、`content`、
|
|
273
283
|
`site_name`、`site_icon`、`date`、`authority` 和未知字段。
|
|
274
284
|
|
|
275
285
|
Fetch 发送 `{ "url": "..." }`,原样保存 `{ title, content }`。URL 最长 8192
|
package/docs/architecture.md
CHANGED
|
@@ -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
|
|
18
|
-
provider
|
|
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
|
|
76
|
-
id, round-robin across families, up to 12 attempts. A
|
|
77
|
-
|
|
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
|
|
83
|
-
|
|
84
|
-
`
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
`
|
|
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
|
-
|
|
93
|
-
|
|
94
|
-
|
|
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.
|
|
@@ -214,6 +225,7 @@ the abort signal and resolve credentials through `lib/auth.ts`.
|
|
|
214
225
|
| `extensions/index.ts` | Tool registration, exposure sync, lifecycle handlers |
|
|
215
226
|
| `lib/candidates.ts` | Current/available candidates, ordering, cache resolution |
|
|
216
227
|
| `lib/search.ts` | Input validation, search/fetch fallback, cache writes, output |
|
|
228
|
+
| `lib/health.ts` | Provider-wide failure cooldowns and candidate reordering |
|
|
217
229
|
| `lib/auth.ts` | Credential resolution, header merging, env fallback |
|
|
218
230
|
| `lib/cache.ts` | Preference cache and model-set fingerprint |
|
|
219
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.
|
package/lib/candidates.ts
CHANGED
|
@@ -54,17 +54,17 @@ export const FETCH_CAP = FETCH_ATTEMPT_CAP;
|
|
|
54
54
|
|
|
55
55
|
/**
|
|
56
56
|
* Cheapest-first capability tiers per family, ordered small to large. The
|
|
57
|
-
* first matching tier wins and ids that match no tier rank last
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
* tier names need an entry; everywhere else every model shares tier 0.
|
|
57
|
+
* first matching tier wins and ids that match no tier rank last. Tiers are a
|
|
58
|
+
* tiebreaker only after version comparison, so a newer model is not skipped
|
|
59
|
+
* just because its tier name is new or unknown. Only families whose provider
|
|
60
|
+
* uses tier names need an entry; everywhere else every model shares tier 0.
|
|
61
61
|
*/
|
|
62
62
|
function tierMatcher(name: string): RegExp {
|
|
63
63
|
return new RegExp(`(?:^|[^a-z0-9])${name}(?:$|[^a-z0-9])`, "i");
|
|
64
64
|
}
|
|
65
65
|
|
|
66
66
|
const MODEL_TIERS: Partial<Record<ProviderFamily, readonly RegExp[]>> = {
|
|
67
|
-
openai: ["luna", "sol", "astra"].map(tierMatcher),
|
|
67
|
+
openai: ["luna", "terra", "sol", "astra"].map(tierMatcher),
|
|
68
68
|
anthropic: ["haiku", "sonnet", "opus", "fable"].map(tierMatcher),
|
|
69
69
|
};
|
|
70
70
|
|
|
@@ -78,14 +78,64 @@ function modelTier(candidate: Candidate): number {
|
|
|
78
78
|
}
|
|
79
79
|
|
|
80
80
|
/**
|
|
81
|
-
*
|
|
82
|
-
*
|
|
83
|
-
*
|
|
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.
|
|
84
85
|
*/
|
|
85
|
-
function
|
|
86
|
-
const
|
|
87
|
-
if (
|
|
88
|
-
|
|
86
|
+
function modelBrandRank(id: string): number {
|
|
87
|
+
const normalized = id.toLowerCase();
|
|
88
|
+
if (/^deepseek(?:[-_.:]|$)/.test(normalized)) return 0;
|
|
89
|
+
if (/^(?:gpt|chatgpt|codex)(?:[-_.:]|$)/.test(normalized) || /^o\d/.test(normalized)) return 1;
|
|
90
|
+
if (/^claude(?:[-_.:]|$)/.test(normalized)) return 2;
|
|
91
|
+
if (/^(?:gemini|gemma)(?:[-_.:]|$)/.test(normalized)) return 3;
|
|
92
|
+
return 4;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
function modelVariantRank(id: string): number {
|
|
96
|
+
const normalized = id.toLowerCase();
|
|
97
|
+
if (/(?:^|[-_.])flash(?:$|[-_.])/.test(normalized)) return 0;
|
|
98
|
+
if (/(?:^|[-_.])pro(?:$|[-_.])/.test(normalized)) return 2;
|
|
99
|
+
return 1;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
function usesVariantOrdering(brand: number): boolean {
|
|
103
|
+
return brand !== 1 && brand !== 2;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/**
|
|
107
|
+
* Parse the model version, not a date suffix or parameter count. The version
|
|
108
|
+
* prefix depends on the family: `gpt-6.1-terra` -> [6, 1], `o3-mini` -> [3],
|
|
109
|
+
* `claude-opus-4-5-20251101` -> [4, 5], `gemini-3.8-flash` -> [3, 8].
|
|
110
|
+
* Ids without a recognizable version return an empty tuple and rank below
|
|
111
|
+
* versioned models.
|
|
112
|
+
*/
|
|
113
|
+
function versionTuple(id: string, family: ProviderFamily): number[] {
|
|
114
|
+
const normalized = id.toLowerCase();
|
|
115
|
+
let match: RegExpMatchArray | null = null;
|
|
116
|
+
|
|
117
|
+
if (family === "openai") {
|
|
118
|
+
match = normalized.match(/^(?:gpt|o)[-_ ]?(\d+(?:\.\d+)*)/);
|
|
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)];
|
|
124
|
+
} else if (family === "google") {
|
|
125
|
+
match = normalized.match(/^(?:gemini|gemma)[-_]?(\d+(?:\.\d+)*)/);
|
|
126
|
+
if (!match) return [];
|
|
127
|
+
} else if (family === "xai") {
|
|
128
|
+
match = normalized.match(/^grok[-_]?(\d+(?:\.\d+)*)/);
|
|
129
|
+
} else if (family === "deepseek") {
|
|
130
|
+
match = normalized.match(/^deepseek[-_]?v?(\d+(?:\.\d+)*)/);
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
if (match) return match[1].split(".").map((part) => Number.parseInt(part, 10));
|
|
134
|
+
|
|
135
|
+
// Generic fallback for custom models. Only dot-separated numbers count so
|
|
136
|
+
// date suffixes such as `...-10-2025` do not look like a newer version.
|
|
137
|
+
const generic = normalized.match(/\d+(?:\.\d+)*/);
|
|
138
|
+
return generic ? generic[0].split(".").map((part) => Number.parseInt(part, 10)) : [];
|
|
89
139
|
}
|
|
90
140
|
|
|
91
141
|
/** Compare version tuples so that a larger, newer version sorts first. */
|
|
@@ -178,15 +228,32 @@ function compareText(left: string, right: string): number {
|
|
|
178
228
|
return left < right ? -1 : left > right ? 1 : 0;
|
|
179
229
|
}
|
|
180
230
|
|
|
181
|
-
/**
|
|
231
|
+
/**
|
|
232
|
+
* Rank candidates inside one family independently of registry order. Brand
|
|
233
|
+
* order comes first (DeepSeek before OpenAI inside a gateway), then the
|
|
234
|
+
* flash / base / pro variant order for non-tiered brands, then the version
|
|
235
|
+
* number. Capability tier is a final tiebreaker for GPT and Claude models.
|
|
236
|
+
*/
|
|
182
237
|
export function rankFamilyCandidates(candidates: Candidate[]): Candidate[] {
|
|
183
|
-
return [...candidates].sort(
|
|
184
|
-
(left
|
|
185
|
-
|
|
186
|
-
|
|
238
|
+
return [...candidates].sort((left, right) => {
|
|
239
|
+
const leftBrand = modelBrandRank(left.model.id);
|
|
240
|
+
const rightBrand = modelBrandRank(right.model.id);
|
|
241
|
+
const brandOrder = leftBrand - rightBrand;
|
|
242
|
+
if (brandOrder !== 0) return brandOrder;
|
|
243
|
+
|
|
244
|
+
if (usesVariantOrdering(leftBrand)) {
|
|
245
|
+
const variantOrder = modelVariantRank(left.model.id) - modelVariantRank(right.model.id);
|
|
246
|
+
if (variantOrder !== 0) return variantOrder;
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
return compareVersionsDesc(
|
|
250
|
+
versionTuple(left.model.id, left.family),
|
|
251
|
+
versionTuple(right.model.id, right.family),
|
|
252
|
+
)
|
|
253
|
+
|| modelTier(left) - modelTier(right)
|
|
187
254
|
|| compareText(candidateKey(left), candidateKey(right))
|
|
188
|
-
|| compareText(left.model.baseUrl ?? "", right.model.baseUrl ?? "")
|
|
189
|
-
);
|
|
255
|
+
|| compareText(left.model.baseUrl ?? "", right.model.baseUrl ?? "");
|
|
256
|
+
});
|
|
190
257
|
}
|
|
191
258
|
|
|
192
259
|
function supportsSearch(candidate: Candidate | undefined): candidate is Candidate {
|
|
@@ -274,25 +341,18 @@ function buildCandidates(
|
|
|
274
341
|
}
|
|
275
342
|
}
|
|
276
343
|
|
|
277
|
-
// Deeper fallback: alternate models from
|
|
278
|
-
// model's provider. Providers frequently reject one specific model
|
|
279
|
-
// IDs, account tiers, regional availability) while serving a sibling,
|
|
280
|
-
// single interface per family is too fragile. Round-robin across
|
|
281
|
-
// every family gets a second chance before any family gets a
|
|
282
|
-
// the broad cross-provider coverage that the one-per-family
|
|
283
|
-
//
|
|
284
|
-
//
|
|
285
|
-
// in the same family (for example `openai` vs `openai-codex`, or `anthropic`
|
|
286
|
-
// vs `opencode-go`) has its own credentials and endpoint and is still worth
|
|
287
|
-
// trying. This mirrors the original "never repeat a provider id" rule while
|
|
288
|
-
// still allowing sibling models of a fallback provider.
|
|
289
|
-
const currentProvider = resolution.current?.model.provider;
|
|
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.
|
|
290
352
|
const queues = new Map<ProviderFamily, Candidate[]>();
|
|
291
353
|
for (const family of PROVIDER_FAMILIES) {
|
|
292
354
|
const queue = usableFamilyCandidates(resolution, family, isUsable).filter(
|
|
293
|
-
(candidate) =>
|
|
294
|
-
candidate.model.provider !== currentProvider
|
|
295
|
-
&& !seen.has(candidateKey(candidate)),
|
|
355
|
+
(candidate) => !seen.has(candidateKey(candidate)),
|
|
296
356
|
);
|
|
297
357
|
if (queue.length > 0) queues.set(family, queue);
|
|
298
358
|
}
|
package/lib/health.ts
ADDED
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
import type { Candidate } from "./candidates.ts";
|
|
2
|
+
|
|
3
|
+
const DEFAULT_FAILURE_COOLDOWN_MS = 60_000;
|
|
4
|
+
const MAX_FAILURE_COOLDOWN_MS = 10 * 60_000;
|
|
5
|
+
|
|
6
|
+
export type ProviderPhase = "search" | "fetch";
|
|
7
|
+
|
|
8
|
+
interface ProviderFailure {
|
|
9
|
+
provider: string;
|
|
10
|
+
phase: ProviderPhase;
|
|
11
|
+
message: string;
|
|
12
|
+
consecutiveFailures: number;
|
|
13
|
+
retryAt: number;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
const failures = new Map<string, ProviderFailure>();
|
|
17
|
+
|
|
18
|
+
function providerFailureKey(phase: ProviderPhase, provider: string): string {
|
|
19
|
+
return `${phase}:provider:${provider}`;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
function modelFailureKey(phase: ProviderPhase, provider: string, model: string): string {
|
|
23
|
+
return `${phase}:model:${provider}/${model}`;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
function failureCooldownMs(): number {
|
|
27
|
+
const configured = Math.floor(Number(process.env.PI_BETTER_WEB_SEARCH_FAILURE_COOLDOWN_MS));
|
|
28
|
+
return Number.isFinite(configured) && configured >= 0
|
|
29
|
+
? configured
|
|
30
|
+
: DEFAULT_FAILURE_COOLDOWN_MS;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Remember a provider-wide or model-specific failure so later calls do not
|
|
35
|
+
* immediately repeat it. Search and fetch are tracked separately because their
|
|
36
|
+
* endpoints can fail independently. The cooldown grows on consecutive failures
|
|
37
|
+
* and only applies while another candidate is available; see
|
|
38
|
+
* prioritizeCandidates.
|
|
39
|
+
*/
|
|
40
|
+
function recordFailure(
|
|
41
|
+
key: string,
|
|
42
|
+
phase: ProviderPhase,
|
|
43
|
+
provider: string,
|
|
44
|
+
message: string,
|
|
45
|
+
now: number,
|
|
46
|
+
): void {
|
|
47
|
+
const previous = failures.get(key);
|
|
48
|
+
const consecutiveFailures = (previous?.consecutiveFailures ?? 0) + 1;
|
|
49
|
+
const base = failureCooldownMs();
|
|
50
|
+
const exponent = Math.min(consecutiveFailures - 1, 10);
|
|
51
|
+
const cooldown = Math.min(base * 2 ** exponent, MAX_FAILURE_COOLDOWN_MS);
|
|
52
|
+
failures.set(key, {
|
|
53
|
+
provider,
|
|
54
|
+
phase,
|
|
55
|
+
message,
|
|
56
|
+
consecutiveFailures,
|
|
57
|
+
retryAt: now + cooldown,
|
|
58
|
+
});
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
export function recordProviderFailure(
|
|
62
|
+
phase: ProviderPhase,
|
|
63
|
+
provider: string,
|
|
64
|
+
message: string,
|
|
65
|
+
now = Date.now(),
|
|
66
|
+
): void {
|
|
67
|
+
recordFailure(providerFailureKey(phase, provider), phase, provider, message, now);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** Remember a single model failure without cooling down its whole provider. */
|
|
71
|
+
export function recordModelFailure(
|
|
72
|
+
phase: ProviderPhase,
|
|
73
|
+
provider: string,
|
|
74
|
+
model: string,
|
|
75
|
+
message: string,
|
|
76
|
+
now = Date.now(),
|
|
77
|
+
): void {
|
|
78
|
+
recordFailure(modelFailureKey(phase, provider, model), phase, provider, message, now);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
export function clearProviderFailure(phase: ProviderPhase, provider: string): void {
|
|
82
|
+
failures.delete(providerFailureKey(phase, provider));
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
export function clearModelFailure(phase: ProviderPhase, provider: string, model: string): void {
|
|
86
|
+
failures.delete(modelFailureKey(phase, provider, model));
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
export function isProviderCoolingDown(
|
|
90
|
+
phase: ProviderPhase,
|
|
91
|
+
provider: string,
|
|
92
|
+
now = Date.now(),
|
|
93
|
+
): boolean {
|
|
94
|
+
const failure = failures.get(providerFailureKey(phase, provider));
|
|
95
|
+
return !!failure && failure.retryAt > now;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
export function isModelCoolingDown(
|
|
99
|
+
phase: ProviderPhase,
|
|
100
|
+
provider: string,
|
|
101
|
+
model: string,
|
|
102
|
+
now = Date.now(),
|
|
103
|
+
): boolean {
|
|
104
|
+
const failure = failures.get(modelFailureKey(phase, provider, model));
|
|
105
|
+
return !!failure && failure.retryAt > now;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
export function getProviderFailure(
|
|
109
|
+
phase: ProviderPhase,
|
|
110
|
+
provider: string,
|
|
111
|
+
): ProviderFailure | undefined {
|
|
112
|
+
const failure = failures.get(providerFailureKey(phase, provider));
|
|
113
|
+
return failure ? { ...failure } : undefined;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* Keep the configured candidate order except that providers with a recent
|
|
118
|
+
* provider-wide failure and individual models with a recent model-specific
|
|
119
|
+
* failure are moved behind healthy candidates. They remain as a last resort
|
|
120
|
+
* when every candidate is cooling down.
|
|
121
|
+
*/
|
|
122
|
+
export function prioritizeCandidates(
|
|
123
|
+
phase: ProviderPhase,
|
|
124
|
+
candidates: Candidate[],
|
|
125
|
+
now = Date.now(),
|
|
126
|
+
): Candidate[] {
|
|
127
|
+
const healthy: Candidate[] = [];
|
|
128
|
+
const cooling: Candidate[] = [];
|
|
129
|
+
for (const candidate of candidates) {
|
|
130
|
+
const provider = candidate.model.provider;
|
|
131
|
+
const model = candidate.model.id;
|
|
132
|
+
if (
|
|
133
|
+
isProviderCoolingDown(phase, provider, now)
|
|
134
|
+
|| isModelCoolingDown(phase, provider, model, now)
|
|
135
|
+
) {
|
|
136
|
+
cooling.push(candidate);
|
|
137
|
+
} else {
|
|
138
|
+
healthy.push(candidate);
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
return healthy.length > 0 ? [...healthy, ...cooling] : [...candidates];
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** Test helper: health state is process-local and must not leak across tests. */
|
|
145
|
+
export function resetProviderFailures(): void {
|
|
146
|
+
failures.clear();
|
|
147
|
+
}
|
|
@@ -69,6 +69,26 @@ function validateQuery(query: string): string | undefined {
|
|
|
69
69
|
return undefined;
|
|
70
70
|
}
|
|
71
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
|
+
}
|
|
91
|
+
|
|
72
92
|
function validateFetchUrl(url: string): string | undefined {
|
|
73
93
|
if (typeof url !== "string" || !url) return "Invalid URL: a non-empty string is required";
|
|
74
94
|
if (url.length > DEEPSEEK_MAX_URL_LENGTH) {
|
|
@@ -147,7 +167,8 @@ export const deepseekAdapter: ProviderAdapter = {
|
|
|
147
167
|
): Promise<ProviderSearchResult> {
|
|
148
168
|
checkAbort(signal);
|
|
149
169
|
|
|
150
|
-
const
|
|
170
|
+
const effectiveQuery = clampDeepSeekQuery(query);
|
|
171
|
+
const queryError = validateQuery(effectiveQuery);
|
|
151
172
|
if (queryError) throw new Error(queryError);
|
|
152
173
|
|
|
153
174
|
const target = await resolveDeepSeekTarget(ctx, model);
|
|
@@ -157,7 +178,7 @@ export const deepseekAdapter: ProviderAdapter = {
|
|
|
157
178
|
method: "POST",
|
|
158
179
|
headers: target.headers,
|
|
159
180
|
body: JSON.stringify({
|
|
160
|
-
query,
|
|
181
|
+
query: effectiveQuery,
|
|
161
182
|
count: DEEPSEEK_SEARCH_COUNT,
|
|
162
183
|
need_content: DEEPSEEK_NEED_CONTENT,
|
|
163
184
|
}),
|
package/lib/search.ts
CHANGED
|
@@ -18,6 +18,13 @@ import {
|
|
|
18
18
|
type WebSearchDetails,
|
|
19
19
|
type WebSearchOutput,
|
|
20
20
|
} from "./format.ts";
|
|
21
|
+
import {
|
|
22
|
+
clearModelFailure,
|
|
23
|
+
clearProviderFailure,
|
|
24
|
+
prioritizeCandidates,
|
|
25
|
+
recordModelFailure,
|
|
26
|
+
recordProviderFailure,
|
|
27
|
+
} from "./health.ts";
|
|
21
28
|
import { MAX_URLS } from "./schema.ts";
|
|
22
29
|
|
|
23
30
|
export const DEFAULT_ATTEMPT_TIMEOUT_MS = 60_000;
|
|
@@ -204,11 +211,14 @@ function resultCount(result: { results?: unknown }): number | undefined {
|
|
|
204
211
|
return Array.isArray(result.results) ? result.results.length : undefined;
|
|
205
212
|
}
|
|
206
213
|
|
|
207
|
-
function
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
.
|
|
214
|
+
function attemptMessages(attempts: WebSearchAttempt[], phase: "search" | "fetch"): string {
|
|
215
|
+
const messages = new Set<string>();
|
|
216
|
+
for (const attempt of attempts) {
|
|
217
|
+
if (attempt.phase !== phase) continue;
|
|
218
|
+
const message = attempt.message.trim();
|
|
219
|
+
if (message) messages.add(message);
|
|
220
|
+
}
|
|
221
|
+
return [...messages].join("; ");
|
|
212
222
|
}
|
|
213
223
|
|
|
214
224
|
function nextCache(
|
|
@@ -254,7 +264,7 @@ async function runSearch(
|
|
|
254
264
|
// whole attempt budget on one interface.
|
|
255
265
|
const failedProviders = new Set<string>();
|
|
256
266
|
|
|
257
|
-
for (const candidate of candidates) {
|
|
267
|
+
for (const candidate of prioritizeCandidates("search", candidates)) {
|
|
258
268
|
if (externalSignal?.aborted) throw abortReason(externalSignal);
|
|
259
269
|
if (failedProviders.has(candidate.model.provider)) continue;
|
|
260
270
|
|
|
@@ -268,6 +278,8 @@ async function runSearch(
|
|
|
268
278
|
signal,
|
|
269
279
|
);
|
|
270
280
|
if (externalSignal?.aborted) throw abortReason(externalSignal);
|
|
281
|
+
clearProviderFailure("search", candidate.model.provider);
|
|
282
|
+
clearModelFailure("search", candidate.model.provider, candidate.model.id);
|
|
271
283
|
return { candidate, result: result ?? {} };
|
|
272
284
|
} catch (error) {
|
|
273
285
|
if (externalSignal?.aborted) throw abortReason(externalSignal);
|
|
@@ -278,7 +290,17 @@ async function runSearch(
|
|
|
278
290
|
model: candidate.model.id,
|
|
279
291
|
message,
|
|
280
292
|
});
|
|
281
|
-
if (isProviderWideFailure(message))
|
|
293
|
+
if (isProviderWideFailure(message)) {
|
|
294
|
+
failedProviders.add(candidate.model.provider);
|
|
295
|
+
recordProviderFailure("search", candidate.model.provider, message);
|
|
296
|
+
} else {
|
|
297
|
+
recordModelFailure(
|
|
298
|
+
"search",
|
|
299
|
+
candidate.model.provider,
|
|
300
|
+
candidate.model.id,
|
|
301
|
+
message,
|
|
302
|
+
);
|
|
303
|
+
}
|
|
282
304
|
}
|
|
283
305
|
}
|
|
284
306
|
|
|
@@ -348,7 +370,7 @@ async function runFetch(
|
|
|
348
370
|
// from the same provider id.
|
|
349
371
|
const failedProviders = new Set<string>();
|
|
350
372
|
|
|
351
|
-
for (const candidate of candidates) {
|
|
373
|
+
for (const candidate of prioritizeCandidates("fetch", candidates)) {
|
|
352
374
|
if (remaining.length === 0) break;
|
|
353
375
|
if (externalSignal?.aborted) throw abortReason(externalSignal);
|
|
354
376
|
if (failedProviders.has(candidate.model.provider)) continue;
|
|
@@ -378,6 +400,8 @@ async function runFetch(
|
|
|
378
400
|
|
|
379
401
|
const assigned = assignFetchEntries(states, remaining, result?.entries ?? [], candidate);
|
|
380
402
|
remaining = assigned.remaining;
|
|
403
|
+
clearProviderFailure("fetch", candidate.model.provider);
|
|
404
|
+
clearModelFailure("fetch", candidate.model.provider, candidate.model.id);
|
|
381
405
|
|
|
382
406
|
if (assigned.successful > 0) {
|
|
383
407
|
// Replace only on a strictly larger success count, so the first
|
|
@@ -396,7 +420,17 @@ async function runFetch(
|
|
|
396
420
|
model: candidate.model.id,
|
|
397
421
|
message,
|
|
398
422
|
});
|
|
399
|
-
if (isProviderWideFailure(message))
|
|
423
|
+
if (isProviderWideFailure(message)) {
|
|
424
|
+
failedProviders.add(candidate.model.provider);
|
|
425
|
+
recordProviderFailure("fetch", candidate.model.provider, message);
|
|
426
|
+
} else {
|
|
427
|
+
recordModelFailure(
|
|
428
|
+
"fetch",
|
|
429
|
+
candidate.model.provider,
|
|
430
|
+
candidate.model.id,
|
|
431
|
+
message,
|
|
432
|
+
);
|
|
433
|
+
}
|
|
400
434
|
for (const index of remaining) {
|
|
401
435
|
states[index].error = message;
|
|
402
436
|
}
|
|
@@ -463,7 +497,8 @@ export async function runWebSearch(
|
|
|
463
497
|
|
|
464
498
|
searchSuccess = await runSearch(resolution, query, signal, onUpdate, attempts);
|
|
465
499
|
if (!searchSuccess) {
|
|
466
|
-
const
|
|
500
|
+
const providerErrors = attemptMessages(attempts, "search");
|
|
501
|
+
const message = providerErrors || "This tool is not available in this conversation.";
|
|
467
502
|
return formatError(message, { attempts, error: message });
|
|
468
503
|
}
|
|
469
504
|
}
|
|
@@ -494,7 +529,7 @@ export async function runWebSearch(
|
|
|
494
529
|
fetchSuccessful = fetched.successful;
|
|
495
530
|
|
|
496
531
|
if (!searchRequested && fetchSuccessful === 0) {
|
|
497
|
-
const failure =
|
|
532
|
+
const failure = attemptMessages(attempts, "fetch");
|
|
498
533
|
const urlFailure = [
|
|
499
534
|
...states.map((state) => `${state.url}: ${state.error || "fetch failed"}`),
|
|
500
535
|
...urlErrors.map((entry) => `${entry.url}: ${entry.error}`),
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-better-web-search",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.8",
|
|
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",
|