dsh-exa-tools 0.1.1 → 0.2.0
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/README.en-US.md +8 -2
- package/README.md +8 -2
- package/client.js +21 -0
- package/docs/TECHNICAL.en-US.md +6 -1
- package/docs/TECHNICAL.md +6 -1
- package/index.js +49 -24
- package/lib/format.js +8 -4
- package/package.json +1 -1
- package/scripts/apply-test.mjs +17 -4
- package/scripts/client-test.mjs +2 -2
package/README.en-US.md
CHANGED
|
@@ -9,7 +9,12 @@ Exa web search and fetch tools for [DeepSeek Harness](https://github.com/deepsee
|
|
|
9
9
|
- **`exa_search`** — semantic web search: describe the ideal page in natural language, get back source URLs with titles and relevant excerpts.
|
|
10
10
|
- **`exa_fetch`** — read any webpage through Exa as clean text/markdown.
|
|
11
11
|
|
|
12
|
-
**No API key? It just works.**
|
|
12
|
+
**No API key? It just works.**
|
|
13
|
+
|
|
14
|
+
- Without a key, the tools use Exa's free hosted MCP endpoint (mcp.exa.ai, rate-limited);
|
|
15
|
+
- With a key, they call the official Exa REST API (api.exa.ai) under your account's limits;
|
|
16
|
+
- Enter the key under Settings → Exa tools — no config files, no restart, effective immediately;
|
|
17
|
+
- If the API fails (quota exhausted, rate limit, invalid key, network), calls automatically fall back to the free endpoint, the result notes the reason, and the fallback can be turned off on the settings page.
|
|
13
18
|
|
|
14
19
|
[中文文档](README.md) · [Technical documentation](docs/TECHNICAL.en-US.md) · [技术文档](docs/TECHNICAL.md)
|
|
15
20
|
|
|
@@ -77,7 +82,7 @@ Both tools coexist with DSH's built-in `web_search` / `web_fetch`; the system pr
|
|
|
77
82
|
|
|
78
83
|
## Configuration
|
|
79
84
|
|
|
80
|
-
The settings page (Settings → Exa tools) edits the live fields: API key, `searchMaxResults`, `fetchMaxCharacters`, `searchTimeoutMs`, `fetchTimeoutMs
|
|
85
|
+
The settings page (Settings → Exa tools) edits the live fields: API key, `searchMaxResults`, `fetchMaxCharacters`, `searchTimeoutMs`, `fetchTimeoutMs`, and the `fallbackToFree` switch. Deployment-level fields are edited in the profile's `cordis.patch.yml`:
|
|
81
86
|
|
|
82
87
|
```yaml
|
|
83
88
|
- id: exa-tools
|
|
@@ -96,6 +101,7 @@ The settings page (Settings → Exa tools) edits the live fields: API key, `sear
|
|
|
96
101
|
| `fetchMaxCharacters` | `50000` | yes | Cap on page characters per fetch (1 000–500 000) |
|
|
97
102
|
| `searchTimeoutMs` | `30000` | yes | Per-call search budget (ms) |
|
|
98
103
|
| `fetchTimeoutMs` | `60000` | yes | Per-call fetch budget (ms) |
|
|
104
|
+
| `fallbackToFree` | `true` | yes | Fall back to the free endpoint when the API fails |
|
|
99
105
|
| `search` / `fetch` | `true` | no (YAML) | Register each tool |
|
|
100
106
|
| `apiBaseUrl` / `mcpBaseUrl` | official endpoints | no (YAML) | Override for proxies or self-hosted MCP |
|
|
101
107
|
|
package/README.md
CHANGED
|
@@ -9,7 +9,12 @@
|
|
|
9
9
|
- **`exa_search`** —— 语义化网页搜索:用自然语言描述你想找的页面,返回来源 URL、标题和相关摘录。
|
|
10
10
|
- **`exa_fetch`** —— 通过 Exa 抓取任意网页,返回干净的正文(text/markdown)。
|
|
11
11
|
|
|
12
|
-
**没有 API Key 也能直接用。**
|
|
12
|
+
**没有 API Key 也能直接用。**
|
|
13
|
+
|
|
14
|
+
- 未填 Key 时走 Exa 免费托管 MCP 端点(mcp.exa.ai,有速率限制);
|
|
15
|
+
- 填了 Key 则走 Exa 官方 REST API(api.exa.ai),使用你账户的限额;
|
|
16
|
+
- Key 在「设置 → Exa 搜索」填写,不用改配置文件,不用重启立即生效;
|
|
17
|
+
- API 失败(额度耗尽、限流、密钥失效、网络错误)时自动回退到免费端点,结果中会注明回退原因,可在设置页关闭。
|
|
13
18
|
|
|
14
19
|
[English](README.en-US.md) · [技术文档](docs/TECHNICAL.md) · [Technical documentation](docs/TECHNICAL.en-US.md)
|
|
15
20
|
|
|
@@ -77,7 +82,7 @@ Key 保存在 profile 的 `cordis.patch.yml` 中(与其他插件设置同一
|
|
|
77
82
|
|
|
78
83
|
## 配置项
|
|
79
84
|
|
|
80
|
-
设置页(设置 → Exa 搜索)可实时修改:API Key、`searchMaxResults`、`fetchMaxCharacters`、`searchTimeoutMs`、`fetchTimeoutMs`。部署级字段在 profile 的 `cordis.patch.yml` 中编辑:
|
|
85
|
+
设置页(设置 → Exa 搜索)可实时修改:API Key、`searchMaxResults`、`fetchMaxCharacters`、`searchTimeoutMs`、`fetchTimeoutMs`、回退开关 `fallbackToFree`。部署级字段在 profile 的 `cordis.patch.yml` 中编辑:
|
|
81
86
|
|
|
82
87
|
```yaml
|
|
83
88
|
- id: exa-tools
|
|
@@ -96,6 +101,7 @@ Key 保存在 profile 的 `cordis.patch.yml` 中(与其他插件设置同一
|
|
|
96
101
|
| `fetchMaxCharacters` | `50000` | 是 | 单次抓取字符上限(1 000–500 000) |
|
|
97
102
|
| `searchTimeoutMs` | `30000` | 是 | 单次搜索超时(毫秒) |
|
|
98
103
|
| `fetchTimeoutMs` | `60000` | 是 | 单次抓取超时(毫秒) |
|
|
104
|
+
| `fallbackToFree` | `true` | 是 | API 失败时自动回退免费端点 |
|
|
99
105
|
| `search` / `fetch` | `true` | 否(YAML) | 是否注册对应工具 |
|
|
100
106
|
| `apiBaseUrl` / `mcpBaseUrl` | 官方端点 | 否(YAML) | 代理或自建 MCP 时覆盖 |
|
|
101
107
|
|
package/client.js
CHANGED
|
@@ -45,6 +45,8 @@ window.__ModuleLoader__.load({
|
|
|
45
45
|
fetchMaxCharacters: 'Max fetch characters',
|
|
46
46
|
searchTimeoutMs: 'Search timeout (ms)',
|
|
47
47
|
fetchTimeoutMs: 'Fetch timeout (ms)',
|
|
48
|
+
fallbackLabel: 'Fall back to the free endpoint on API failure',
|
|
49
|
+
fallbackHint: 'When the Exa API fails (quota exhausted, rate limit, invalid key, network), the call is retried on the free endpoint and the result notes the fallback.',
|
|
48
50
|
default: 'default',
|
|
49
51
|
save: 'Save',
|
|
50
52
|
saving: 'Saving…',
|
|
@@ -80,6 +82,8 @@ window.__ModuleLoader__.load({
|
|
|
80
82
|
fetchMaxCharacters: '抓取最大字符数',
|
|
81
83
|
searchTimeoutMs: '搜索超时(毫秒)',
|
|
82
84
|
fetchTimeoutMs: '抓取超时(毫秒)',
|
|
85
|
+
fallbackLabel: 'API 失败时回退到免费端点',
|
|
86
|
+
fallbackHint: 'Exa API 失败(额度耗尽、限流、密钥失效、网络错误)时自动改用免费端点重试,并在结果中注明回退原因。',
|
|
83
87
|
default: '默认',
|
|
84
88
|
save: '保存',
|
|
85
89
|
saving: '保存中…',
|
|
@@ -124,6 +128,8 @@ window.__ModuleLoader__.load({
|
|
|
124
128
|
.dsh-exa-dot-off { background: var(--dsw-alias-state-warn-primary, var(--dsw-alias-label-tertiary)); }
|
|
125
129
|
.dsh-exa-hint { margin: 0; font-size: 12px; line-height: 18px; color: var(--dsw-alias-label-tertiary); }
|
|
126
130
|
.dsh-exa-field { display: flex; flex-direction: column; gap: 6px; min-width: 0; }
|
|
131
|
+
.dsh-exa-check-row { display: flex; align-items: center; gap: 8px; font-size: 13px; line-height: 20px; color: var(--dsw-alias-label-primary); cursor: pointer; }
|
|
132
|
+
.dsh-exa-check-row input { width: 16px; height: 16px; margin: 0; accent-color: var(--dsw-alias-state-business-primary); }
|
|
127
133
|
.dsh-exa-label { font-size: 12px; line-height: 18px; font-weight: 500; color: var(--dsw-alias-label-secondary); }
|
|
128
134
|
.dsh-exa-input { box-sizing: border-box; width: 100%; height: 32px; padding: 0 10px; border: 0.5px solid var(--dsw-alias-border-l4); border-radius: var(--dsw-radius-md); font: inherit; font-size: 14px; line-height: 22px; background: var(--dsw-alias-bg-layer-1); color: var(--dsw-alias-label-primary); }
|
|
129
135
|
.dsh-exa-input:focus { outline: none; border-color: var(--dsw-alias-state-business-primary); }
|
|
@@ -206,6 +212,7 @@ window.__ModuleLoader__.load({
|
|
|
206
212
|
if (!/^\d+$/.test(text)) { dirty = true; continue }
|
|
207
213
|
if (Number(text) !== value[field.name]) dirty = true
|
|
208
214
|
}
|
|
215
|
+
if (drafts.fallbackToFree !== undefined && drafts.fallbackToFree !== (value.fallbackToFree ?? true)) dirty = true
|
|
209
216
|
|
|
210
217
|
const edit = (field, text) => {
|
|
211
218
|
if (baseRevision === undefined) setBaseRevision(snap.revision)
|
|
@@ -236,6 +243,9 @@ window.__ModuleLoader__.load({
|
|
|
236
243
|
}
|
|
237
244
|
if (number !== value[field.name]) ops.push({ op: 'set', path: [field.name], value: number })
|
|
238
245
|
}
|
|
246
|
+
if (drafts.fallbackToFree !== undefined && drafts.fallbackToFree !== (value.fallbackToFree ?? true)) {
|
|
247
|
+
ops.push({ op: 'set', path: ['fallbackToFree'], value: drafts.fallbackToFree })
|
|
248
|
+
}
|
|
239
249
|
if (firstInvalid) {
|
|
240
250
|
setInvalidField(firstInvalid.name)
|
|
241
251
|
setAdvancedOpen(true)
|
|
@@ -334,6 +344,17 @@ window.__ModuleLoader__.load({
|
|
|
334
344
|
target: '_blank',
|
|
335
345
|
rel: 'noreferrer',
|
|
336
346
|
}, t('keyLink')))),
|
|
347
|
+
h('div', { className: 'dsh-exa-field' },
|
|
348
|
+
h('label', { className: 'dsh-exa-check-row', htmlFor: `${idPrefix}-fallback` },
|
|
349
|
+
h('input', {
|
|
350
|
+
id: `${idPrefix}-fallback`,
|
|
351
|
+
type: 'checkbox',
|
|
352
|
+
checked: drafts.fallbackToFree ?? value.fallbackToFree ?? true,
|
|
353
|
+
disabled,
|
|
354
|
+
onChange: event => edit('fallbackToFree', event.target.checked),
|
|
355
|
+
}),
|
|
356
|
+
t('fallbackLabel')),
|
|
357
|
+
h('p', { className: 'dsh-exa-hint' }, t('fallbackHint'))),
|
|
337
358
|
h('details', {
|
|
338
359
|
className: 'dsh-exa-advanced',
|
|
339
360
|
open: advancedOpen,
|
package/docs/TECHNICAL.en-US.md
CHANGED
|
@@ -35,7 +35,7 @@ The inserted row's **id `exa-tools`** is also its settings namespace (the settin
|
|
|
35
35
|
|
|
36
36
|
`Config` is a schemastery object. Two field classes:
|
|
37
37
|
|
|
38
|
-
- **Volatile** (`.volatile()`): `apiKey`, `searchMaxResults`, `fetchMaxCharacters`, `searchTimeoutMs`, `fetchTimeoutMs`. The loader parses them into stable references; the plugin reads `config.field.get()` at call time, and a settings write commits new values **in place** — no remount, no stale closures.
|
|
38
|
+
- **Volatile** (`.volatile()`): `apiKey`, `searchMaxResults`, `fetchMaxCharacters`, `searchTimeoutMs`, `fetchTimeoutMs`, `fallbackToFree`. The loader parses them into stable references; the plugin reads `config.field.get()` at call time, and a settings write commits new values **in place** — no remount, no stale closures.
|
|
39
39
|
- **Ordinary**: `search`, `fetch`, `apiBaseUrl`, `mcpBaseUrl`. Edited in the profile patch; a change remounts the plugin.
|
|
40
40
|
|
|
41
41
|
`apiKey` additionally carries `.role('secret')`. The settings subsystem strips secret fields from every wire response and ships a sidecar instead: `secrets: [{ path: ['apiKey'], set: true|false }]`. The client learns *whether* a key exists, never its value.
|
|
@@ -132,6 +132,10 @@ Canonical outputs (identical for both backends):
|
|
|
132
132
|
|
|
133
133
|
Rendering follows `dsh-tool-web` conventions: the standing untrusted-content notice, `- [title](url) — excerpt (date)` source lines, a cite-your-sources instruction, and a truncation footer. Snippets are whitespace-collapsed and capped at 800 characters (surrogate-safe cut). Fetch truncation is `text.length >= maxCharacters` (heuristic; an exactly-sized page may be flagged).
|
|
134
134
|
|
|
135
|
+
### 4.4 Failure fallback
|
|
136
|
+
|
|
137
|
+
With a key, each call tries REST first; on any failure (402 quota, 429 rate limit, 401/403 invalid key, 5xx, network, timeout) with `fallbackToFree` on (the default), it retries on the free MCP endpoint and writes a short reason (≤160 chars) into the optional `fallback` field of the canonical output, rendered as the result's first line: `(Exa API unavailable: <reason> — this result comes from the free endpoint.)`. If both backends fail, a combined error is thrown. Caller cancellation (`exec.signal` aborted) never falls back and rethrows untouched. Each attempt gets its own full timeout budget (worst-case total ≈ twice the configured budget). Without a key the free endpoint is the primary path, so there is nothing to fall back from.
|
|
138
|
+
|
|
135
139
|
## 5. Settings UI
|
|
136
140
|
|
|
137
141
|
The page and card work identically in the Web client and the Desktop app: the client module runs in both renderers and uses the same registration and transport contracts.
|
|
@@ -163,6 +167,7 @@ ctx.configForms.whileServed(['exa-tools'], () =>
|
|
|
163
167
|
- Reads: `ctx.configForms.get('exa-tools')` (values + ordered writes) and `ctx.configForms.describe()` (the shared mirror, for the secret presence marker). Both are consumed with `useSyncExternalStore`; class methods are wrapped in `useCallback` to keep `this`.
|
|
164
168
|
- Writes: staged drafts, one **Save** submits `form.mutate(ops, revision)` — `set` for changed fields, `unset` for emptied numeric fields (restores the composed default; the form says so and shows each field's default). The revision fence is captured **when editing begins**, so a concurrent write elsewhere is refused instead of silently overwritten; a refusal auto-reloads the latest values, keeps the drafts, and resets the fence so an informed retry can proceed. Invalid numeric input names the field, marks it `aria-invalid`, expands the fold, and focuses it. Success messages announce via `role="status"`. **Clear API key** is `form.unset('apiKey')`.
|
|
165
169
|
- The key input is write-only (`type=password`, `autocomplete=new-password`, reveal toggle for the draft). Its placeholder reflects the presence marker: “Key configured — type to replace” vs “Paste your Exa API key”.
|
|
170
|
+
- Fallback switch: a `fallbackToFree` checkbox, staged and saved with the other fields.
|
|
166
171
|
- Styling: self-contained controls under a `dsh-exa-` prefix, colors exclusively through `--dsw-alias-*` theme tokens (patterns copied from the official Models settings page). No Harness Client package is imported as a module; React comes from the client module table (`require('react')`).
|
|
167
172
|
- Locale dictionaries (en/zh) register through `ctx.locale`; all visible text routes through `t`.
|
|
168
173
|
|
package/docs/TECHNICAL.md
CHANGED
|
@@ -35,7 +35,7 @@ icon.svg 原创 36×36 图标,导出为 ./icon
|
|
|
35
35
|
|
|
36
36
|
`Config` 是 schemastery object,字段分两类:
|
|
37
37
|
|
|
38
|
-
- **Volatile**(`.volatile()`):`apiKey`、`searchMaxResults`、`fetchMaxCharacters`、`searchTimeoutMs`、`fetchTimeoutMs`。loader 把它们解析为稳定引用;插件在调用时读 `config.field.get()`,settings 写入会**就地**提交新值——不重挂载、无过期闭包。
|
|
38
|
+
- **Volatile**(`.volatile()`):`apiKey`、`searchMaxResults`、`fetchMaxCharacters`、`searchTimeoutMs`、`fetchTimeoutMs`、`fallbackToFree`。loader 把它们解析为稳定引用;插件在调用时读 `config.field.get()`,settings 写入会**就地**提交新值——不重挂载、无过期闭包。
|
|
39
39
|
- **普通字段**:`search`、`fetch`、`apiBaseUrl`、`mcpBaseUrl`。在 profile patch 中编辑,修改会重挂载插件。
|
|
40
40
|
|
|
41
41
|
`apiKey` 额外带 `.role('secret')`。settings 子系统从所有跨线响应中剥离 secret 字段,改发一个旁路记录:`secrets: [{ path: ['apiKey'], set: true|false }]`。客户端只知道 Key **是否存在**,永远拿不到值。
|
|
@@ -132,6 +132,10 @@ POST tools/call → 200,SSE(或 JSON);按 JSON-RPC id 匹
|
|
|
132
132
|
|
|
133
133
|
渲染沿用 `dsh-tool-web` 约定:固定的不可信内容提示、`- [标题](url) — 摘录 (日期)` 来源行、引用提示、截断尾注。摘录折叠空白并截断到 800 字符(不切开代理对)。抓取截断判据为 `text.length >= maxCharacters`(启发式;恰好等长的页面可能被标记)。
|
|
134
134
|
|
|
135
|
+
### 4.4 失败回退
|
|
136
|
+
|
|
137
|
+
有 Key 时每次调用先走 REST;任何失败(402 额度耗尽、429 限流、401/403 密钥失效、5xx、网络错误、超时)且 `fallbackToFree` 开启(默认)时,自动改用免费 MCP 端点重试,并把简短原因(≤160 字符)写入规范输出的可选 `fallback` 字段,渲染为结果首行提示:`(Exa API unavailable: <原因> — this result comes from the free endpoint.)`。两端都失败时抛出合并错误。调用方取消(`exec.signal` aborted)不触发回退,原样重抛。每次尝试各自享有完整的超时预算(最坏总耗时约为配置的两倍)。无 Key 时本就直接走免费端点,无所谓回退。
|
|
138
|
+
|
|
135
139
|
## 5. 设置界面
|
|
136
140
|
|
|
137
141
|
设置页与卡片在 Web 端和桌面端同样可用:客户端模块运行于两者的渲染层,注册与传输契约一致。
|
|
@@ -162,6 +166,7 @@ ctx.configForms.whileServed(['exa-tools'], () =>
|
|
|
162
166
|
- 读:`ctx.configForms.get('exa-tools')`(值 + 有序写入)与 `ctx.configForms.describe()`(共享 mirror,取 secret 存在标记)。两者都用 `useSyncExternalStore` 消费;类方法用 `useCallback` 包一层以保住 `this`。
|
|
163
167
|
- 写:草稿暂存,一次「保存」提交 `form.mutate(ops, revision)`——变更字段 `set`,清空的数字字段 `unset`(恢复组合默认值;表单会说明这一语义并显示各字段默认值)。revision 围栏在**开始编辑时**取快照,因此别处的并发写入会被拒绝而非静默覆盖;被拒时自动重载最新值、保留草稿并重置围栏,用户核对后可重试。数字校验错误会指明字段、标 `aria-invalid`、展开折叠并聚焦该输入框。成功消息带 `role="status"` 播报。「清除 API Key」即 `form.unset('apiKey')`。
|
|
164
168
|
- Key 输入框只写(`type=password`、`autocomplete=new-password`、草稿可切换显示)。占位符反映存在标记:「已配置 —— 输入新值可替换」/「粘贴 Exa API Key」。
|
|
169
|
+
- 回退开关:`fallbackToFree` 复选框,与其他字段一同暂存、一次保存。
|
|
165
170
|
- 样式:`dsh-exa-` 前缀的自包含控件,颜色全部走 `--dsw-alias-*` 主题令牌(样式范式抄自官方 Models 设置页)。不把任何 Harness Client 包当模块 import;React 来自客户端模块表(`require('react')`)。
|
|
166
171
|
- 字典(en/zh)经 `ctx.locale` 注册;所有可见文本走 `t`。
|
|
167
172
|
|
package/index.js
CHANGED
|
@@ -51,6 +51,8 @@ export const Config = z.object({
|
|
|
51
51
|
.description('Cooperative timeout budget (ms) for one exa_search call.'),
|
|
52
52
|
fetchTimeoutMs: z.number().default(60_000).min(1_000).max(300_000).step(1_000).volatile()
|
|
53
53
|
.description('Cooperative timeout budget (ms) for one exa_fetch call.'),
|
|
54
|
+
fallbackToFree: z.boolean().default(true).volatile()
|
|
55
|
+
.description('When the Exa API fails (quota exhausted, rate limit, invalid key, network), retry the call on the free endpoint and note the fallback in the result.'),
|
|
54
56
|
search: z.boolean().default(true)
|
|
55
57
|
.description('Register the exa_search tool.'),
|
|
56
58
|
fetch: z.boolean().default(true)
|
|
@@ -108,6 +110,32 @@ export function apply(ctx, config) {
|
|
|
108
110
|
|
|
109
111
|
const keyOf = () => (config.apiKey.get() ?? '').trim()
|
|
110
112
|
|
|
113
|
+
/**
|
|
114
|
+
* Backend selection with automatic fallback. With a key, try REST first;
|
|
115
|
+
* on any failure (quota, rate limit, invalid key, network, timeout) retry
|
|
116
|
+
* on the free MCP endpoint when fallbackToFree is on, carrying a short
|
|
117
|
+
* reason into the result. Caller cancellation is never fallen back from.
|
|
118
|
+
* Each attempt gets the full timeout budget of its own.
|
|
119
|
+
*/
|
|
120
|
+
const runBackend = async (exec, restFn, mcpFn) => {
|
|
121
|
+
const apiKey = keyOf()
|
|
122
|
+
if (!apiKey) return { value: await mcpFn(), fallback: undefined }
|
|
123
|
+
try {
|
|
124
|
+
return { value: await restFn(apiKey), fallback: undefined }
|
|
125
|
+
} catch (error) {
|
|
126
|
+
if (exec.signal?.aborted) throw error
|
|
127
|
+
if (!(config.fallbackToFree.get() ?? true)) throw error
|
|
128
|
+
const reason = String(error instanceof Error ? error.message : error).replace(/\s+/gu, ' ').slice(0, 160)
|
|
129
|
+
try {
|
|
130
|
+
return { value: await mcpFn(), fallback: reason }
|
|
131
|
+
} catch (freeError) {
|
|
132
|
+
if (exec.signal?.aborted) throw freeError
|
|
133
|
+
const freeMessage = String(freeError instanceof Error ? freeError.message : freeError)
|
|
134
|
+
throw new Error(`Exa API failed (${reason}); free endpoint also failed: ${freeMessage}`)
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
|
|
111
139
|
// This plugin ships its own configuration page (the Plugins-page card), so
|
|
112
140
|
// tell the settings service not to auto-generate one for this instance.
|
|
113
141
|
// Optional: a composition without the settings service still gets the tools.
|
|
@@ -178,6 +206,7 @@ export function apply(ctx, config) {
|
|
|
178
206
|
},
|
|
179
207
|
},
|
|
180
208
|
text: { type: 'string' },
|
|
209
|
+
fallback: { type: 'string' },
|
|
181
210
|
},
|
|
182
211
|
required: ['sources'],
|
|
183
212
|
additionalProperties: false,
|
|
@@ -191,29 +220,27 @@ export function apply(ctx, config) {
|
|
|
191
220
|
const query = typeof args.query === 'string' ? args.query.trim() : ''
|
|
192
221
|
if (!query) throw new Error('query must be a non-empty string')
|
|
193
222
|
checkOptionalCount(args, 'num_results')
|
|
194
|
-
const apiKey = keyOf()
|
|
195
223
|
const numResults = clampInt(args.num_results, DEFAULT_NUM_RESULTS, 1, config.searchMaxResults.get() ?? 10)
|
|
196
224
|
const timeoutMs = config.searchTimeoutMs.get() ?? 30_000
|
|
197
225
|
try {
|
|
198
|
-
|
|
199
|
-
|
|
226
|
+
const { value, fallback } = await runBackend(exec,
|
|
227
|
+
apiKey => restSearch({
|
|
200
228
|
baseUrl: config.apiBaseUrl, apiKey, query, numResults, timeoutMs, signal: exec.signal,
|
|
201
|
-
})
|
|
202
|
-
return {
|
|
229
|
+
}).then(sources => ({
|
|
203
230
|
sources: sources.map(({ snippet, ...rest }) => {
|
|
204
231
|
const capped = collapseSnippet(snippet)
|
|
205
232
|
return capped ? { ...rest, snippet: capped } : rest
|
|
206
233
|
}),
|
|
207
|
-
}
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
234
|
+
})),
|
|
235
|
+
() => mcp.callTool(
|
|
236
|
+
'web_search_exa',
|
|
237
|
+
{ query, numResults, objective: query },
|
|
238
|
+
{ signal: exec.signal, timeoutMs },
|
|
239
|
+
).then(parseMcpSearch),
|
|
213
240
|
)
|
|
214
|
-
return
|
|
241
|
+
return { ...value, ...fallback ? { fallback } : {} }
|
|
215
242
|
} catch (error) {
|
|
216
|
-
throw toolError(error, exec, !
|
|
243
|
+
throw toolError(error, exec, !keyOf())
|
|
217
244
|
}
|
|
218
245
|
},
|
|
219
246
|
})
|
|
@@ -247,6 +274,7 @@ export function apply(ctx, config) {
|
|
|
247
274
|
title: { type: 'string' },
|
|
248
275
|
text: { type: 'string' },
|
|
249
276
|
truncated: { type: 'boolean' },
|
|
277
|
+
fallback: { type: 'string' },
|
|
250
278
|
},
|
|
251
279
|
required: ['url', 'text', 'truncated'],
|
|
252
280
|
additionalProperties: false,
|
|
@@ -264,31 +292,28 @@ export function apply(ctx, config) {
|
|
|
264
292
|
if (target.protocol !== 'http:' && target.protocol !== 'https:') {
|
|
265
293
|
throw new Error('url must use http or https')
|
|
266
294
|
}
|
|
267
|
-
const apiKey = keyOf()
|
|
268
295
|
const maxCharacters = clampInt(args.max_characters, DEFAULT_MAX_CHARACTERS, 1, config.fetchMaxCharacters.get() ?? 50_000)
|
|
269
296
|
const timeoutMs = config.fetchTimeoutMs.get() ?? 60_000
|
|
270
297
|
try {
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
result = await restFetch({
|
|
298
|
+
const { value: result, fallback } = await runBackend(exec,
|
|
299
|
+
apiKey => restFetch({
|
|
274
300
|
baseUrl: config.apiBaseUrl, apiKey, url: target.href, maxCharacters, timeoutMs, signal: exec.signal,
|
|
275
|
-
})
|
|
276
|
-
|
|
277
|
-
const content = await mcp.callTool(
|
|
301
|
+
}),
|
|
302
|
+
() => mcp.callTool(
|
|
278
303
|
'web_fetch_exa',
|
|
279
304
|
{ urls: [target.href], maxCharacters },
|
|
280
305
|
{ signal: exec.signal, timeoutMs },
|
|
281
|
-
)
|
|
282
|
-
|
|
283
|
-
}
|
|
306
|
+
).then(content => parseMcpFetch(content, target.href)),
|
|
307
|
+
)
|
|
284
308
|
return {
|
|
285
309
|
url: result.url,
|
|
286
310
|
...result.title ? { title: result.title } : {},
|
|
287
311
|
text: safeSlice(result.text, maxCharacters),
|
|
288
312
|
truncated: result.text.length >= maxCharacters,
|
|
313
|
+
...fallback ? { fallback } : {},
|
|
289
314
|
}
|
|
290
315
|
} catch (error) {
|
|
291
|
-
throw toolError(error, exec, !
|
|
316
|
+
throw toolError(error, exec, !keyOf())
|
|
292
317
|
}
|
|
293
318
|
},
|
|
294
319
|
})
|
package/lib/format.js
CHANGED
|
@@ -112,11 +112,13 @@ function sourceLabel(url, title) {
|
|
|
112
112
|
|
|
113
113
|
/**
|
|
114
114
|
* Render the canonical exa_search output as one model-facing text block.
|
|
115
|
-
* @param {{sources: Array<{url: string, title?: string, snippet?: string, publishedAt?: string}>, text?: string}} value
|
|
115
|
+
* @param {{sources: Array<{url: string, title?: string, snippet?: string, publishedAt?: string}>, text?: string, fallback?: string}} value
|
|
116
116
|
* @returns {string}
|
|
117
117
|
*/
|
|
118
118
|
export function renderSearch(value) {
|
|
119
|
-
const parts = [
|
|
119
|
+
const parts = []
|
|
120
|
+
if (value.fallback) parts.push(`(Exa API unavailable: ${value.fallback} — this result comes from the free endpoint.)`)
|
|
121
|
+
parts.push(EXTERNAL_NOTICE)
|
|
120
122
|
if (value.sources.length > 0) {
|
|
121
123
|
const lines = value.sources.map((source) => {
|
|
122
124
|
const meta = []
|
|
@@ -137,11 +139,13 @@ export function renderSearch(value) {
|
|
|
137
139
|
|
|
138
140
|
/**
|
|
139
141
|
* Render the canonical exa_fetch output as one model-facing text block.
|
|
140
|
-
* @param {{url: string, title?: string, text: string, truncated: boolean}} value
|
|
142
|
+
* @param {{url: string, title?: string, text: string, truncated: boolean, fallback?: string}} value
|
|
141
143
|
* @returns {string}
|
|
142
144
|
*/
|
|
143
145
|
export function renderFetch(value) {
|
|
144
|
-
const parts = [
|
|
146
|
+
const parts = []
|
|
147
|
+
if (value.fallback) parts.push(`(Exa API unavailable: ${value.fallback} — this result comes from the free endpoint.)`)
|
|
148
|
+
parts.push(`Fetched ${value.url}`, EXTERNAL_NOTICE, value.text)
|
|
145
149
|
if (value.truncated) {
|
|
146
150
|
parts.push('(Content truncated. Fetch a more specific URL or section for the full text.)')
|
|
147
151
|
}
|
package/package.json
CHANGED
package/scripts/apply-test.mjs
CHANGED
|
@@ -56,19 +56,32 @@ for (const [tool, args, expect] of [
|
|
|
56
56
|
}
|
|
57
57
|
}
|
|
58
58
|
|
|
59
|
-
// API-key mode
|
|
59
|
+
// API-key mode with fallback disabled: an invalid key must surface the mapped 401.
|
|
60
60
|
const keyed = []
|
|
61
61
|
const keyedCtx = makeCtx()
|
|
62
|
-
const origRegister = keyedCtx.tools.register
|
|
63
62
|
keyedCtx.tools.register = def => { keyed.push(def); return () => {} }
|
|
64
|
-
apply(keyedCtx, new Config({ apiKey: 'invalid-key-for-test' }))
|
|
63
|
+
apply(keyedCtx, new Config({ apiKey: 'invalid-key-for-test', fallbackToFree: false }))
|
|
65
64
|
try {
|
|
66
65
|
await keyed.find(d => d.name === 'exa_search').execute({ query: 'test' }, exec)
|
|
67
66
|
throw new Error('invalid key unexpectedly succeeded')
|
|
68
67
|
} catch (error) {
|
|
69
68
|
if (!/HTTP 401/.test(error.message)) throw error
|
|
70
|
-
console.log('\nAPI-mode
|
|
69
|
+
console.log('\nAPI-mode (no fallback) ok:', error.message.slice(0, 100))
|
|
71
70
|
}
|
|
72
71
|
|
|
72
|
+
// Fallback: invalid key + default fallbackToFree → the free endpoint answers
|
|
73
|
+
// and the result carries the fallback reason, in the value and the render.
|
|
74
|
+
const fb = []
|
|
75
|
+
const fbCtx = makeCtx()
|
|
76
|
+
fbCtx.tools.register = def => { fb.push(def); return () => {} }
|
|
77
|
+
apply(fbCtx, new Config({ apiKey: 'invalid-key-for-test' }))
|
|
78
|
+
const fbSearch = fb.find(d => d.name === 'exa_search')
|
|
79
|
+
const fbValue = await fbSearch.execute({ query: 'Exa AI search API documentation', num_results: 2 }, exec)
|
|
80
|
+
if (!fbValue.fallback || !/HTTP 401/.test(fbValue.fallback)) throw new Error('fallback reason missing')
|
|
81
|
+
if (!Array.isArray(fbValue.sources) || fbValue.sources.length === 0) throw new Error('fallback produced no sources')
|
|
82
|
+
const fbText = fbSearch.output.render({}, fbValue)[0].text
|
|
83
|
+
if (!fbText.includes('free endpoint')) throw new Error('render missing fallback notice')
|
|
84
|
+
console.log('fallback ok:', fbValue.fallback.slice(0, 80))
|
|
85
|
+
|
|
73
86
|
for (const cleanup of cleanups) await cleanup()
|
|
74
87
|
console.log('\nAPPLY TEST OK')
|
package/scripts/client-test.mjs
CHANGED
|
@@ -40,8 +40,8 @@ const form = {
|
|
|
40
40
|
subscribe: () => () => {},
|
|
41
41
|
getSnapshot: () => ({
|
|
42
42
|
status: 'ready',
|
|
43
|
-
value: { searchMaxResults: 10, fetchMaxCharacters: 50000, searchTimeoutMs: 30000, fetchTimeoutMs: 60000 },
|
|
44
|
-
base: { searchMaxResults: 10, fetchMaxCharacters: 50000, searchTimeoutMs: 30000, fetchTimeoutMs: 60000 },
|
|
43
|
+
value: { searchMaxResults: 10, fetchMaxCharacters: 50000, searchTimeoutMs: 30000, fetchTimeoutMs: 60000, fallbackToFree: true },
|
|
44
|
+
base: { searchMaxResults: 10, fetchMaxCharacters: 50000, searchTimeoutMs: 30000, fetchTimeoutMs: 60000, fallbackToFree: true },
|
|
45
45
|
revision: 3,
|
|
46
46
|
writable: true,
|
|
47
47
|
}),
|