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 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, models are ordered by capability tier first (cheapest
146
- available tier wins) and then by version number, newest first. OpenAI tiers
147
- are `luna → sol → astra` and Claude tiers are
148
- `haiku → sonnet → opus → fable`; other families have no named tiers and are
149
- ordered purely by version. Ties are deterministic.
150
- 5. Alternate models from other providers are tried round-robin, so a provider
151
- that rejects one specific model can still serve a sibling. Only the current
152
- model's provider id is excluded; a different provider id in the same family
153
- is still tried. A provider-wide failure (auth, balance, network, timeout,
154
- malformed request) skips the rest of that provider; a model-specific
155
- failure keeps trying sibling models.
148
+ 4. Within a family, brand order comes first: DeepSeek models, then OpenAI,
149
+ then Claude, then Gemini/Gemma, then other gateway brands. For brands
150
+ without named tiers, variants order `flash → base → pro`; within a variant,
151
+ newer versions come first. GPT and Claude keep version-first ordering, with
152
+ their capability tier as a tiebreaker: OpenAI tiers are
153
+ `luna → terra → sol → astra` and Claude tiers are
154
+ `haiku → sonnet → opus → fable`. Ties are deterministic.
155
+ 5. Alternate models from every provider are tried round-robin, so a provider
156
+ that rejects one specific model can still serve a sibling, including a
157
+ newer sibling from the same provider id. A provider-wide failure (auth,
158
+ balance, network, timeout, malformed request) skips the rest of that
159
+ provider; a model-specific failure keeps trying sibling models.
156
160
 
157
161
  URL fetching uses the same idea, but considers only providers that implement
158
162
  URL fetching.
159
163
 
160
- The current model is always tried first when it supports search. The cache does
161
- not replace a supported current model; it mainly lets an unsupported current
162
- model use a remembered compatible provider immediately on later calls.
164
+ The current model is normally tried first when it supports search, unless its
165
+ provider or model is in a failure cooldown. The cache does not replace a
166
+ supported current model; it mainly lets an unsupported current model use a
167
+ remembered compatible provider immediately on later calls.
163
168
 
164
169
  If a provider errors, the extension records the attempt and moves to the next
165
170
  interface. Aborts stop immediately. Each attempt has a timeout (60 seconds by
166
171
  default, configurable with `PI_BETTER_WEB_SEARCH_TIMEOUT_MS`). If every attempt
167
- fails, the tool returns an error whose message lists the attempted
168
- provider/model pairs and their errors. For a URL-only call, the error also
169
- reports the per-URL failures.
172
+ fails, the tool returns an error whose message contains the provider errors.
173
+ Provider/model routing remains in `details.attempts`. For a URL-only call, the
174
+ error also reports the per-URL failures.
175
+
176
+ Provider-wide failures (auth, balance, network, timeout, malformed request) and
177
+ model-specific failures are remembered for the life of the extension process.
178
+ On later calls the failed provider or model is moved behind healthy candidates
179
+ for search and fetch independently. The cooldown starts at 60 seconds, doubles
180
+ on consecutive failures, and is capped at 10 minutes; a successful call clears
181
+ it. Set `PI_BETTER_WEB_SEARCH_FAILURE_COOLDOWN_MS=0` to disable this behavior.
182
+ This does not prevent several calls already in flight from trying the same
183
+ candidate at the same time.
170
184
 
171
185
  ### Cache fingerprint invalidation
172
186
 
@@ -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`. The raw `results`
320
- array is returned unchanged, including `rerank_score`, `title`, `url`,
333
+ Search uses `query`, `count: 10`, and `need_content: true`. DeepSeek limits
334
+ `query` to 128 Unicode characters, so longer queries are shortened at a word
335
+ boundary for the request only. The raw `results` array is returned unchanged,
336
+ including `rerank_score`, `title`, `url`,
321
337
  `snippet`, `summary`, `content`, `site_name`, `site_icon`, `date`, `authority`,
322
338
  and any unknown fields.
323
339
 
@@ -66,7 +66,8 @@ pi install ./path/to/pi-better-web-search
66
66
  ```
67
67
 
68
68
  - `query` 搜索网页。`site:`、引号、`AND`、`OR`、`-term` 等搜索语法原样传给
69
- provider,只去掉首尾空白。
69
+ provider,只去掉首尾空白。如果 provider 有更短的 query 上限,adapter 只会在
70
+ 发给该 provider 的副本上按词边界缩短;输出中仍保留原始 query。
70
71
  - `urls` 分析指定页面。可以**单独使用**,也可以和 `query` 一起使用。两者同时
71
72
  提供时,先搜索,再分析 URL。
72
73
  - 最多 **20** 个 URL。
@@ -116,28 +117,36 @@ Provider 识别顺序:
116
117
 
117
118
  搜索顺序:
118
119
 
119
- 1. 当前模型支持搜索时,优先当前模型。
120
+ 1. 当前模型支持搜索,且对应 provider 和该模型都不在失败冷却期时,优先当前模型。
120
121
  2. 缓存指纹有效时,使用记住的搜索 provider。
121
122
  3. 其余 provider family 按固定顺序尝试:
122
123
  **DeepSeek → Ollama → Google → OpenAI → xAI → Anthropic**。
123
- 4. 同一 family 内先按能力等级排序(便宜的等级优先,未知等级排最后):
124
- OpenAI 为 `luna → sol → astra`,Claude 为 `haiku → sonnet → opus → fable`;
125
- 其他 family 没有命名等级,直接按版本号从新到旧排序。同级内版本号大的优先。
126
- 5. 除当前模型的 provider id 外,其他 provider 的备用模型会按 round-robin 继续尝试,
127
- 这样即使某个账号拒绝某个具体模型,也能换用同 provider 的其他模型。
128
- 同一 family 下不同 provider id(如 `openai` 与 `openai-codex`)仍会尝试。
129
- provider 级失败(鉴权、余额、网络、超时、请求头异常)会跳过该 provider 的
130
- 其余模型;模型级失败则继续尝试同 provider 的其他模型。
124
+ 4. 同一 family 内先按品牌排序:DeepSeek 模型、OpenAI、Claude、Gemini/Gemma,
125
+ 然后其他网关品牌。没有命名等级的品牌按变体 `flash → base → pro` 排序,同一变体
126
+ 内版本号从新到旧;GPT 和 Claude 仍按版本优先,版本相同时才按能力等级排序
127
+ (便宜的等级优先,未知等级排最后):OpenAI 为 `luna → terra → sol → astra`,
128
+ Claude 为 `haiku → sonnet → opus → fable`。
129
+ 5. 所有 provider 的备用模型都会按 round-robin 继续尝试,包括当前模型同一
130
+ provider id 下的其他模型,这样即使某个账号拒绝某个具体模型,也能换用同
131
+ provider 的更新模型。provider 级失败(鉴权、余额、网络、超时、请求头异常)
132
+ 会跳过该 provider 的其余模型;模型级失败则继续尝试同 provider 的其他模型。
131
133
 
132
134
  URL 抓取使用同样的思路,但只考虑实现了 URL 抓取的 provider。
133
135
 
134
- 当前模型支持搜索时始终优先当前模型;缓存不会覆盖它。缓存主要用于当前模型
135
- 不支持搜索时,让下一次调用直接使用之前成功的兼容 provider。
136
+ 当前模型支持搜索时通常优先当前模型,除非该 provider 或该模型正处于失败冷却期。
137
+ 缓存不会覆盖它。缓存主要用于当前模型不支持搜索时,让下一次调用直接使用之前成功
138
+ 的兼容 provider。
136
139
 
137
140
  Provider 报错时记录 attempt 并继续下一个接口。取消会立即停止。每次尝试有
138
141
  超时(默认 60 秒,`PI_BETTER_WEB_SEARCH_TIMEOUT_MS` 可调)。所有尝试都失败时,
139
- 工具返回错误,列出尝试过的 provider/model 和错误。URL-only 调用还会报告每个
140
- URL 的失败原因。
142
+ 工具返回错误,消息中包含 provider 返回的错误;provider/model 路由信息保留在
143
+ `details.attempts` 中。URL-only 调用还会报告每个 URL 的失败原因。
144
+
145
+ Provider 级失败(鉴权、余额、网络、超时、请求头异常)和单个模型失败都会在扩展进程内
146
+ 记住。后续调用会把失败的 provider 或模型排到健康候选之后,搜索和 URL 抓取分别记录。
147
+ 冷却时间从 60 秒开始,连续失败时翻倍,最多 10 分钟;成功一次后清除。设置
148
+ `PI_BETTER_WEB_SEARCH_FAILURE_COOLDOWN_MS=0` 可禁用。已经在途的并发调用仍可能同时
149
+ 尝试同一个候选。
141
150
 
142
151
  ### 缓存指纹失效
143
152
 
@@ -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`。原始 `results` 数组原样
272
- 返回,包括 `rerank_score`、`title`、`url`、`snippet`、`summary`、`content`、
280
+ 搜索使用 `query`、`count: 10`、`need_content: true`。DeepSeek 的 `query` 上限为
281
+ 128 个 Unicode 字符,因此超长 query 只在请求中按词边界缩短。原始 `results`
282
+ 数组原样返回,包括 `rerank_score`、`title`、`url`、`snippet`、`summary`、`content`、
273
283
  `site_name`、`site_icon`、`date`、`authority` 和未知字段。
274
284
 
275
285
  Fetch 发送 `{ "url": "..." }`,原样保存 `{ title, content }`。URL 最长 8192
@@ -14,8 +14,9 @@ output guard. It does not own provider result cleanup.
14
14
  4. **Use provider-native interfaces.** Each family keeps its request shape,
15
15
  authentication quirks, and stream format.
16
16
  5. **Prefer the current model, remember fallbacks.** A supported current model
17
- is tried first. An unsupported current model uses the remembered compatible
18
- provider first.
17
+ is tried first unless its provider is cooling down after a recent
18
+ provider-wide failure. An unsupported current model uses the remembered
19
+ compatible provider first.
19
20
  6. **Do not touch pi's system prompt.** No prompt snippets, guidelines, loadout
20
21
  hooks, commands, or extra tools.
21
22
 
@@ -72,26 +73,34 @@ Search candidates:
72
73
  2. The remembered search provider when the cache fingerprint is current.
73
74
  3. One candidate per remaining family in this order:
74
75
  **DeepSeek → Ollama → Google → OpenAI → xAI → Anthropic**.
75
- 4. Alternate models from every provider except the current model's provider
76
- id, round-robin across families, up to 12 attempts. A different provider id
77
- in the same family (for example `openai` vs `openai-codex`) is still tried.
76
+ 4. Alternate models from every provider, including the current model's
77
+ provider id, round-robin across families, up to 12 attempts. A provider-wide
78
+ failure still skips that provider id; a model-specific failure can use a
79
+ sibling model from the same provider.
78
80
 
79
81
  Fetch candidates use the same shape but include only adapters with
80
82
  `supportsUrls` and a `fetch` implementation. The fetch cap is 6 attempts.
81
83
 
82
- Within a family, models are ordered by capability tier first and version
83
- second. Named tiers rank cheapest first and unknown ids rank last: OpenAI uses
84
- `luna → sol → astra` and Claude uses `haiku → sonnet → opus → fable`. Other
85
- families have no named tiers. Version numbers are compared as tuples with the
86
- newest first (`gpt-7.0` before `gpt-6.1` before `gpt-4.1`, `gemini-3.8` before
87
- `gemini-2.5`). Ties fall back to the deterministic `provider/id@baseUrl` order.
84
+ Within a family, models are ordered by brand first: DeepSeek, OpenAI, Claude,
85
+ Gemini/Gemma, then other gateway brands. Brands without named tiers use variant
86
+ order `flash → base → pro`, then version number, newest first. GPT and Claude
87
+ use version number first, newest first, with capability tier as a tiebreaker:
88
+ OpenAI uses `luna → terra → sol → astra` and Claude uses
89
+ `haiku → sonnet → opus → fable`. Ties fall back to the deterministic
90
+ `provider/id@baseUrl` order.
88
91
  A provider id is only retried with another model when the first failure was
89
92
  model-specific; provider-wide failures (auth, balance, network, timeout,
90
- malformed request) skip the rest of that provider.
91
-
92
- The current model is preferred when it supports search. The cache is a fallback,
93
- not an override. When the current model is unsupported, the cached provider is
94
- tried first, which avoids repeating discovery on every call.
93
+ malformed request) skip the rest of that provider. Provider failures and
94
+ model-specific failures are remembered per phase (search/fetch) for the life of
95
+ the process. On later calls the failed provider or model is moved behind healthy
96
+ candidates for a 60-second to 10-minute exponential cooldown; a success clears
97
+ it. Calls already in flight are not cancelled or reordered.
98
+
99
+ The current model is preferred when it supports search and neither its provider
100
+ nor that model is cooling down. The cache is a fallback, not an override. When
101
+ the current model
102
+ is unsupported, the cached provider is tried first, which avoids repeating
103
+ discovery on every call.
95
104
 
96
105
  ## Cache and fingerprint
97
106
 
@@ -125,6 +134,8 @@ be used. A cached provider that is no longer available is ignored.
125
134
  ## Input validation
126
135
 
127
136
  - `query` is trimmed; search operators are otherwise passed through unchanged.
137
+ Provider adapters may shorten the provider-bound copy when that provider has
138
+ a lower query-length limit; the model-facing output keeps the original query.
128
139
  - `urls` is an array of at most 20 strings.
129
140
  - Each URL must be HTTP/HTTPS, have a host, omit username/password, and be at
130
141
  most 8192 characters.
@@ -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, so fallback
58
- * does not burn a large model when a small one is available. Version numbers
59
- * are compared separately, newest first. Only families whose provider uses
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
- * Parse the first version-like run in a model id into a numeric tuple.
82
- * `gpt-6.1` -> [6, 1], `claude-opus-4-5` -> [4, 5], `gpt-oss:120b` -> [120].
83
- * Ids without a number return an empty tuple and rank below versioned ones.
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 versionTuple(id: string): number[] {
86
- const match = id.match(/\d+(?:[.-]\d+)*/);
87
- if (!match) return [];
88
- return match[0].split(/[.-]/).map((part) => Number.parseInt(part, 10));
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
- /** Rank candidates inside one family independently of registry order. */
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, right) =>
185
- modelTier(left) - modelTier(right)
186
- || compareVersionsDesc(versionTuple(left.model.id), versionTuple(right.model.id))
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 providers other than the current
278
- // model's provider. Providers frequently reject one specific model (legacy
279
- // IDs, account tiers, regional availability) while serving a sibling, so a
280
- // single interface per family is too fragile. Round-robin across families so
281
- // every family gets a second chance before any family gets a third, keeping
282
- // the broad cross-provider coverage that the one-per-family pass provides.
283
- //
284
- // Only the current model's provider id is excluded: a different provider id
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 queryError = validateQuery(query);
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 attemptSummary(attempts: WebSearchAttempt[], phase: "search" | "fetch"): string {
208
- return attempts
209
- .filter((attempt) => attempt.phase === phase)
210
- .map((attempt) => `${attempt.provider}/${attempt.model}: ${attempt.message}`)
211
- .join("; ");
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)) failedProviders.add(candidate.model.provider);
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)) failedProviders.add(candidate.model.provider);
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 message = "This tool is not available in this conversation.";
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 = attemptSummary(attempts, "fetch");
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.7",
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",