@viztor/dsh-tinyfish 0.3.0 → 0.4.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.md +104 -120
- package/lib/client.js +27 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,36 +1,52 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
|
+
<img src="assets/tinyfish.svg" alt="TinyFish logo" width="120" />
|
|
3
|
+
<h1>dsh-tinyfish</h1>
|
|
4
|
+
<p><strong>Free web search and fetch for the DeepSeek Harness.</strong><br />Give your agent the live web — at $0 per call.</p>
|
|
2
5
|
|
|
3
|
-
|
|
6
|
+
[](https://www.npmjs.com/package/dsh-tinyfish) [](https://www.npmjs.com/package/dsh-tinyfish) [](https://github.com/viztor/dsh-tinyfish/actions/workflows/ci.yml) [](https://github.com/viztor/dsh-tinyfish/blob/main/LICENSE)
|
|
4
7
|
|
|
5
|
-
|
|
8
|
+
</div>
|
|
6
9
|
|
|
7
|
-
|
|
10
|
+
---
|
|
8
11
|
|
|
9
|
-
|
|
12
|
+
Your agent can already reason. This gives it something to reason _about_: live search results and clean page content, wired straight into the harness's own `web_search` and `web_fetch` tools. Powered by [TinyFish](https://tinyfish.ai) — both endpoints are free, so the web path on your host stops costing money per call.
|
|
10
13
|
|
|
11
|
-
|
|
|
12
|
-
| --- | --- |
|
|
13
|
-
|
|
|
14
|
-
|
|
|
15
|
-
|
|
|
16
|
-
|
|
14
|
+
| Before | After |
|
|
15
|
+
| --- | --- |
|
|
16
|
+
| Search bills per call | **$0**, forever |
|
|
17
|
+
| Fetched pages arrive as HTML, converted clumsily | **Clean Markdown**, straight from a browser-grade extractor |
|
|
18
|
+
| Switching providers means reinstalling | **Two words** in a config file, no reinstall |
|
|
19
|
+
|
|
20
|
+
## 🚀 Quick start
|
|
17
21
|
|
|
18
|
-
|
|
22
|
+
**1. Install** — in your web profile:
|
|
19
23
|
|
|
20
24
|
```sh
|
|
21
25
|
cd ~/.dsh/profiles/web
|
|
22
|
-
npm install dsh-tinyfish
|
|
23
|
-
|
|
24
|
-
|
|
26
|
+
npm install dsh-tinyfish # or: npm install @viztor/dsh-tinyfish — same thing
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
<details>
|
|
30
|
+
<summary><strong>📦 Installing from GitHub Packages instead</strong></summary>
|
|
31
|
+
|
|
32
|
+
<br />
|
|
33
|
+
|
|
34
|
+
Every release mirrors both names to GitHub Packages — a second source if npmjs.org is unreachable, and what populates the repository sidebar. Unlike npmjs, GitHub Packages requires authentication even for public packages: an unauthenticated request 404s without saying whether the package exists. With a token carrying `read:packages`:
|
|
35
|
+
|
|
36
|
+
```ini
|
|
37
|
+
# project-local .npmrc is better than global for a token
|
|
38
|
+
@viztor:registry=https://npm.pkg.github.com
|
|
39
|
+
//npm.pkg.github.com/:_authToken=ghp_xxx
|
|
25
40
|
```
|
|
26
41
|
|
|
27
|
-
|
|
42
|
+
then `npm install @viztor/dsh-tinyfish` resolves from the mirror. Unless npmjs is down, prefer it: no token, no extra configuration.
|
|
43
|
+
</details>
|
|
28
44
|
|
|
29
|
-
|
|
45
|
+
**2. Mount it** — add to that profile's `package.json`, then restart DSH:
|
|
30
46
|
|
|
31
47
|
```jsonc
|
|
32
48
|
{
|
|
33
|
-
"dependencies": { "dsh-tinyfish": "^0.
|
|
49
|
+
"dependencies": { "dsh-tinyfish": "^0.3.0" },
|
|
34
50
|
"dsh": {
|
|
35
51
|
"profile": {
|
|
36
52
|
"bundles": [
|
|
@@ -43,52 +59,20 @@ Add the bundle to that profile's `package.json`, then restart DSH:
|
|
|
43
59
|
}
|
|
44
60
|
```
|
|
45
61
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
```yaml
|
|
49
|
-
- id: web
|
|
50
|
-
name: "@deepseek-ai/dsh-web"
|
|
51
|
-
config:
|
|
52
|
-
searchProvider: tinyfish
|
|
53
|
-
fetchProvider: tinyfish
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
Restarting matters: bundles are resolved when the harness boots, so `patchReload` will not pick up a newly mounted one.
|
|
57
|
-
|
|
58
|
-
**To go back**, set those two back to `deepseek-official` and `http`. The bundle stays mounted and idle — registration and selection are separate, and only your profile decides which provider wins.
|
|
62
|
+
> Bundles resolve at boot, so a restart picks it up — reloading the patch alone won't.
|
|
59
63
|
|
|
60
|
-
**
|
|
64
|
+
**3. Add a key** — pick a channel below, save the key, and ask your agent to search for something. That's the whole install.
|
|
61
65
|
|
|
62
|
-
##
|
|
66
|
+
## 🔑 Two channels, one plugin
|
|
63
67
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
```sh
|
|
67
|
-
cd ~/.dsh/profiles/web
|
|
68
|
-
node -e '
|
|
69
|
-
const m = require("dsh-tinyfish");
|
|
70
|
-
const ctx = { web: { registerSearchProvider(){}, registerFetchProvider(){} }, get: () => undefined };
|
|
71
|
-
m.apply(ctx, m.Config({}));
|
|
72
|
-
console.log("registered:", m.name, "| no throw above = wired");
|
|
73
|
-
'
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
If search reports `WEB_PROVIDER_CREDENTIAL_MISSING` or `WEB_PROVIDER_UNAVAILABLE`, that is the next section.
|
|
77
|
-
|
|
78
|
-
## Credentials
|
|
79
|
-
|
|
80
|
-
A fresh install has none, and never will — a key inside an npm tarball would be published forever. Both endpoints are free, but both need an account.
|
|
81
|
-
|
|
82
|
-
**In the profile patch (no restart needed).** The `web-tinyfish` row in your profile's `cordis.patch.yml` sets `apiKeyEnv`, which the harness resolves through its credentials service and the launch environment, and re-reads on every call — so a change takes effect on the next search.
|
|
83
|
-
|
|
84
|
-
**By hand:**
|
|
85
|
-
|
|
86
|
-
| channel | get a key | then |
|
|
68
|
+
| | Direct _(default)_ | Via Monid |
|
|
87
69
|
| --- | --- | --- |
|
|
88
|
-
|
|
|
89
|
-
|
|
|
70
|
+
| What's behind it | TinyFish's own API | The same TinyFish endpoints, through your Monid wallet |
|
|
71
|
+
| You need | A free key from [tinyfish.ai](https://tinyfish.ai) | A platform key from [app.monid.ai](https://app.monid.ai) |
|
|
72
|
+
| Fastest setup | `tinyfish auth login` | `monid keys add` |
|
|
73
|
+
| Costs | $0 | $0 |
|
|
90
74
|
|
|
91
|
-
The default is `direct
|
|
75
|
+
The default is `direct`, because the package is named for TinyFish — a fresh install asks for the credential its own name implies. Prefer Monid (it reuses a platform key your Monid MCP mount may already hold)? Pin it in your profile patch:
|
|
92
76
|
|
|
93
77
|
```yaml
|
|
94
78
|
- id: web-tinyfish
|
|
@@ -96,31 +80,38 @@ The default is `direct` because the package is named for TinyFish: a fresh insta
|
|
|
96
80
|
channel: monid
|
|
97
81
|
```
|
|
98
82
|
|
|
99
|
-
|
|
83
|
+
Both keys can live side by side — saving one never overwrites the other, and switching channels loses nothing.
|
|
84
|
+
|
|
85
|
+
## ⚙️ Settings page
|
|
86
|
+
|
|
87
|
+
**Settings → Plugins → TinyFish.** Everything editable lives here: the channel picker, your keys, what the search ranks on, retries, and the search/fetch toggles. Changes stage and save together; a key you type is stored by the harness, never in your profile.
|
|
100
88
|
|
|
101
|
-
|
|
89
|
+
The page shows the key for the **selected** channel, plus the saved-or-not status of both — so you always know where you stand without switching back and forth.
|
|
102
90
|
|
|
103
|
-
|
|
91
|
+
> Going back is two words: set `searchProvider`/`fetchProvider` to `deepseek-official` and `http`. The bundle stays mounted and idle.
|
|
104
92
|
|
|
105
|
-
|
|
93
|
+
<details>
|
|
94
|
+
<summary><strong>📖 Full configuration reference</strong></summary>
|
|
106
95
|
|
|
107
|
-
|
|
96
|
+
<br />
|
|
97
|
+
|
|
98
|
+
Everything lives in one row, `web-tinyfish`. The row is validated, so an out-of-range value is rejected with a message rather than silently clamped.
|
|
108
99
|
|
|
109
100
|
| key | default | meaning |
|
|
110
101
|
| --- | --- | --- |
|
|
111
|
-
| `channel` | `direct` | `monid` or `direct
|
|
102
|
+
| `channel` | `direct` | `monid` or `direct` |
|
|
112
103
|
| `apiKey` | _(unset)_ | literal credential for either channel; prefer a ref |
|
|
113
104
|
| `apiKeyEnv` | `TINYFISH_API_KEY` | credential reference, or env var, for `direct` |
|
|
114
105
|
| `monidKeyEnv` | `MONID_API_KEY` | credential reference, or env var, for `monid` |
|
|
115
106
|
| `purpose` | _(unset)_ | goal statement; TinyFish ranks on it |
|
|
116
107
|
| `attempts` | `3` | retries for a transient failure or an empty search (1–5) |
|
|
117
|
-
| `filters.domainType` | _(unset)_ | `web` \| `news` \| `research_paper` |
|
|
118
|
-
| `filters.language` / `.location` | _(unset)_ | geo targeting |
|
|
119
|
-
| `filters.includeDomains` / `.excludeDomains` | _(unset)_ | comma-separated |
|
|
108
|
+
| `filters.domainType` | _(unset)_ | `web` \| `news` \| `research_paper` — patch file only |
|
|
109
|
+
| `filters.language` / `.location` | _(unset)_ | geo targeting — patch file only |
|
|
110
|
+
| `filters.includeDomains` / `.excludeDomains` | _(unset)_ | comma-separated — patch file only |
|
|
120
111
|
| `monidBase` / `searchBase` / `fetchBase` | upstream | endpoint override, for staging |
|
|
121
112
|
| `search` / `fetch` | `true` | offer this kind at all; `false` declines without unregistering |
|
|
122
113
|
|
|
123
|
-
|
|
114
|
+
Turning one off reports _unavailable_ rather than _missing_ — the harness tells those apart, and only the second means "the install is broken".
|
|
124
115
|
|
|
125
116
|
```yaml
|
|
126
117
|
- id: web-tinyfish
|
|
@@ -129,83 +120,76 @@ Search and fetch are switched independently. Both always register, so turning on
|
|
|
129
120
|
fetch: false # keep TinyFish for search, let dsh-web use another fetch
|
|
130
121
|
```
|
|
131
122
|
|
|
132
|
-
###
|
|
133
|
-
|
|
134
|
-
Every setting resolves in the same three rungs — **row, then environment, then built-in default** — so a deployment can be retargeted without writing a patch file. This is the shape the shipped providers use for `$DEEPSEEK_SEARCH_BASE_URL`.
|
|
135
|
-
|
|
136
|
-
| setting | environment variable |
|
|
137
|
-
| ------------ | -------------------------- |
|
|
138
|
-
| `monidBase` | `TINYFISH_MONID_BASE_URL` |
|
|
139
|
-
| `searchBase` | `TINYFISH_SEARCH_BASE_URL` |
|
|
140
|
-
| `fetchBase` | `TINYFISH_FETCH_BASE_URL` |
|
|
141
|
-
|
|
142
|
-
An endpoint that does not parse makes the provider report itself unavailable rather than being trusted.
|
|
123
|
+
### Filters live in the patch file
|
|
143
124
|
|
|
144
|
-
|
|
125
|
+
`filters` is a nested object, and the settings form addresses one flat key per field — so search tuning stays operator-level:
|
|
145
126
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
127
|
+
```yaml
|
|
128
|
+
- id: web-tinyfish
|
|
129
|
+
config:
|
|
130
|
+
channel: monid
|
|
131
|
+
filters:
|
|
132
|
+
domainType: research_paper
|
|
133
|
+
language: zh
|
|
134
|
+
includeDomains: arxiv.org,openreview.net
|
|
135
|
+
```
|
|
155
136
|
|
|
156
|
-
|
|
137
|
+
### Where a credential comes from
|
|
157
138
|
|
|
158
|
-
|
|
139
|
+
Resolved **per call** — a rotated key takes effect on the next search, no restart. First match wins:
|
|
159
140
|
|
|
160
|
-
|
|
141
|
+
1. the `apiKey` literal in the row (a secret in config; prefer 2–3)
|
|
142
|
+
2. the credentials service — `apiKeyEnv` (direct) or `monidKeyEnv` (monid), saved from the settings UI
|
|
143
|
+
3. the launch environment (exported before DSH started)
|
|
144
|
+
4. the live environment (`MONID_API_KEY` / `TINYFISH_API_KEY`)
|
|
145
|
+
5. the channel's CLI store (`monid keys add` / `tinyfish auth login`)
|
|
161
146
|
|
|
162
|
-
|
|
147
|
+
A failing service falls through to the next source rather than failing the search.
|
|
163
148
|
|
|
164
|
-
|
|
149
|
+
### Where an endpoint comes from
|
|
165
150
|
|
|
166
|
-
|
|
151
|
+
Row, then environment, then built-in default — so staging can retarget without a patch:
|
|
167
152
|
|
|
168
|
-
|
|
153
|
+
| setting | environment variable |
|
|
154
|
+
| ------------ | -------------------------- |
|
|
155
|
+
| `monidBase` | `TINYFISH_MONID_BASE_URL` |
|
|
156
|
+
| `searchBase` | `TINYFISH_SEARCH_BASE_URL` |
|
|
157
|
+
| `fetchBase` | `TINYFISH_FETCH_BASE_URL` |
|
|
169
158
|
|
|
170
|
-
|
|
159
|
+
</details>
|
|
171
160
|
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
| search | `GET api.search.tinyfish.ai` | `POST api.monid.ai/v1/run` |
|
|
175
|
-
| fetch | `POST api.fetch.tinyfish.ai` | `POST api.monid.ai/v1/run` |
|
|
176
|
-
| auth | `X-API-Key` | `Authorization: Bearer` |
|
|
177
|
-
| cost | $0, direct | $0, on the Monid wallet |
|
|
161
|
+
<details>
|
|
162
|
+
<summary><strong>🔍 Behaviour worth knowing</strong></summary>
|
|
178
163
|
|
|
179
|
-
|
|
164
|
+
<br />
|
|
180
165
|
|
|
181
166
|
- **A 404 is a result, not an error.** A per-URL fetch failure comes back carrying its status, because that is resource state the model needs.
|
|
182
|
-
- **`publishedAt` is honest.** TinyFish reports
|
|
183
|
-
- **
|
|
184
|
-
- **A blocked run is terminal.** If a Monid workspace control stops a run, the error says why and links to top up.
|
|
167
|
+
- **`publishedAt` is honest.** TinyFish reports human dates (`"Apr 30, 2026"`, `"1 year ago"`). What parses becomes ISO-8601; what doesn't is dropped, never invented. Unzoned dates read as UTC, so the same page reports the same day everywhere.
|
|
168
|
+
- **Empty searches retry.** The upstream answers a valid query with nothing about one run in three — a blank result is retried up to `attempts` before it is believed.
|
|
169
|
+
- **A blocked run is terminal.** If a Monid workspace control stops a run, the error says why and links to top up. Never retried.
|
|
185
170
|
|
|
186
|
-
|
|
171
|
+
TinyFish's `agent` and `browser` surfaces are **not** exposed: metered, wallet-billed, and not a search or a fetch. Use the `tinyfish` CLI directly when a page genuinely needs a real browser.
|
|
187
172
|
|
|
188
|
-
|
|
173
|
+
</details>
|
|
189
174
|
|
|
190
|
-
|
|
175
|
+
<details>
|
|
176
|
+
<summary><strong>🛠 Development</strong></summary>
|
|
191
177
|
|
|
192
|
-
|
|
178
|
+
<br />
|
|
179
|
+
|
|
180
|
+
The toolchain is [Vite+](https://viteplus.dev): `vp pack` builds with tsdown, `vp test` runs Vitest, `vp lint` / `vp fmt` are Oxlint and Oxfmt, type-aware. Lint and format live in `vite.config.ts` — Vite+ ignores standalone configs.
|
|
193
181
|
|
|
194
182
|
```sh
|
|
195
183
|
pnpm install
|
|
196
|
-
pnpm test #
|
|
184
|
+
pnpm test # 143 hermetic tests — no network, no credential
|
|
197
185
|
pnpm run check # format + lint + types
|
|
198
|
-
pnpm run release:gate # build, then the full gate
|
|
186
|
+
pnpm run release:gate # build, then the full gate incl. 11 package checks
|
|
199
187
|
pnpm run test:live # the real APIs, still $0, needs credentials
|
|
200
188
|
```
|
|
201
189
|
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
Full process and invariants: [`AGENTS.md`](./AGENTS.md).
|
|
205
|
-
|
|
206
|
-
## Compatibility
|
|
190
|
+
Requires **DSH 0.2.0+** and **Node 22.14+**. Full process and invariants: [`AGENTS.md`](./AGENTS.md). Contributing: [`CONTRIBUTING.md`](./CONTRIBUTING.md).
|
|
207
191
|
|
|
208
|
-
|
|
192
|
+
</details>
|
|
209
193
|
|
|
210
194
|
## License
|
|
211
195
|
|
package/lib/client.js
CHANGED
|
@@ -233,7 +233,11 @@ function TinyfishCard(props) {
|
|
|
233
233
|
}
|
|
234
234
|
});
|
|
235
235
|
const channel = (state.fields[FIELD.channel]?.text ?? "") === "monid" ? "monid" : "direct";
|
|
236
|
-
const key = state.keys[channel]
|
|
236
|
+
const key = state.keys[channel] ?? {
|
|
237
|
+
text: "",
|
|
238
|
+
named: false,
|
|
239
|
+
ref: channel === "monid" ? DEFAULT_MONID_KEY_REF : DEFAULT_API_KEY_REF
|
|
240
|
+
};
|
|
237
241
|
const keyChannel = channel === "monid" ? FIELD.monidApiKey : FIELD.apiKey;
|
|
238
242
|
const searchOn = switchValue(state.fields[FIELD.search]?.text ?? "");
|
|
239
243
|
const fetchOn = switchValue(state.fields[FIELD.fetch]?.text ?? "");
|
|
@@ -270,6 +274,24 @@ function TinyfishCard(props) {
|
|
|
270
274
|
/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", { children: t("channelHint") }),
|
|
271
275
|
resetButton(FIELD.channel, state.fields[FIELD.channel]?.overridden ?? false)
|
|
272
276
|
] }),
|
|
277
|
+
/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("p", { children: [
|
|
278
|
+
t("apiKey"),
|
|
279
|
+
":",
|
|
280
|
+
" ",
|
|
281
|
+
state.keys.direct?.named ?? false ? t("apiKeySet") : t("apiKeyUnset"),
|
|
282
|
+
" ",
|
|
283
|
+
"(",
|
|
284
|
+
state.keys.direct?.ref ?? DEFAULT_API_KEY_REF,
|
|
285
|
+
") · ",
|
|
286
|
+
t("monidApiKey"),
|
|
287
|
+
":",
|
|
288
|
+
" ",
|
|
289
|
+
state.keys.monid?.named ?? false ? t("apiKeySet") : t("apiKeyUnset"),
|
|
290
|
+
" ",
|
|
291
|
+
"(",
|
|
292
|
+
state.keys.monid?.ref ?? DEFAULT_MONID_KEY_REF,
|
|
293
|
+
")"
|
|
294
|
+
] }),
|
|
273
295
|
/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.SettingsSecretField, {
|
|
274
296
|
id: `plugin-config-tinyfish-${keyChannel}`,
|
|
275
297
|
label: channel === "monid" ? t("monidApiKey") : t("apiKey"),
|
|
@@ -363,11 +385,13 @@ function apply(ctx) {
|
|
|
363
385
|
keys: {
|
|
364
386
|
direct: {
|
|
365
387
|
text: model.field(FIELD.apiKey).text,
|
|
366
|
-
named: refOf(scope.getSnapshot(), "direct") !== DEFAULT_API_KEY_REF
|
|
388
|
+
named: refOf(scope.getSnapshot(), "direct") !== DEFAULT_API_KEY_REF,
|
|
389
|
+
ref: refOf(scope.getSnapshot(), "direct")
|
|
367
390
|
},
|
|
368
391
|
monid: {
|
|
369
392
|
text: model.field(FIELD.monidApiKey).text,
|
|
370
|
-
named: refOf(scope.getSnapshot(), "monid") !== DEFAULT_MONID_KEY_REF
|
|
393
|
+
named: refOf(scope.getSnapshot(), "monid") !== DEFAULT_MONID_KEY_REF,
|
|
394
|
+
ref: refOf(scope.getSnapshot(), "monid")
|
|
371
395
|
}
|
|
372
396
|
}
|
|
373
397
|
}));
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@viztor/dsh-tinyfish",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "TinyFish-backed search and fetch providers for the DeepSeek Harness web capability seam (ctx.web) — $0 SERP and page extraction, direct or via Monid.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"cordis",
|