stormbuf/dsh-tavily-pool

English | 简体中文

Tavily-backed web search and page fetching for DeepSeek Harness: multi-key pool with balance-aware rotation, automatic failover, cooldown, official /usage balance reporting, and independent toggles for search and fetch — configurable from the DSH settings panel.

Not to be confused with SZMY-haruhi/dsh-tavily (single key / keyless, no scheduling) or @yuuz12/dsh-tavily (multi-key, but no fetch takeover and it rewrites internal fields at runtime). This plugin manages a pool of keys, schedules by remaining balance, and takes over both web_search and web_fetch.

Features

• Multi-key pool — add one key or paste a whole batch (one per line), label, enable/disable, reorder, remove one or several at once; the UI only ever shows masked keys
• Scheduling policy — switch between balance-first ordering and plain manual order, where the list order becomes the scheduling order
• Balance-aware rotation — highest remaining balance first; three-state balance (the limit comes from key.limit, falling back to the account's account.plan_limit — only when both are explicitly null is a key unlimited and ranked first; unknown goes last)
• Automatic failover — a failing key hands the request to the next one
• Cooldown — honors upstream Retry-After; cooled keys are hard-excluded until it expires, and when every key is cooling the request waits for the earliest one within a bounded budget
• Status-aware errors — separates temporary failures, permanent key death (body-inspected, never status-code-only), and quota exhaustion (432 / 433 treated alike: the key stays out of rotation until /usage confirms a positive balance)
• Official balance, refreshed on use — the card's credit figure is the official /usage reading (limit − used). A reading is pulled again when the key being used has one over an hour old, when a key is added, and for any key still missing a reading the next time the plugin is used at all. The plugin keeps no credit accounting of its own: Tavily's billing rules can change at any time, so a locally computed figure could silently become wrong. Between readings the ordering is nudged forward by a deliberately rough per-call estimate that is never shown as a number of its own; it does move the displayed used figure, so the card also says how old the last official reading is. Nothing runs in the background: no search or fetch means no /usage traffic at all
• Balance refresh — pulls official /usage with per-key sliding-window quota reservation, so it never trips the 10-per-10-minutes limit
• Configurable search parameters — search depth, result cap, topic, and generated-answer toggle, all taking effect immediately
• Fetch takeover (off by default) — maps web_fetch to Tavily /extract, returning plain text (never HTML, which DSH would convert a second time); extraction depth and output format are configurable. Turn it on in settings when you want Tavily to handle fetching too
• Call history and chart — every call is recorded (key, endpoint, outcome, duration, request_id) and drawn as a 14-day call-count chart; the file is bounded by both an entry cap and a 30-day window
• Independent toggles — search and fetch can be switched back to the official providers separately
• Zero runtime dependencies — plain ESM, no build step

Shipped: the whole spec — search takeover and its toggle, the key pool (single key, pasted batch, bulk removal), failover with cooldown, search parameters, the scheduling policy, balance refresh, fetch takeover with its own toggle (off by default), call history with its chart, the per-key call stats and balance bar, the connectivity test, and the settings card with its HTTP API.

Install

From the npm registry:

dsh plugin add dsh-tavily-pool

Or straight from GitHub, which needs no registry account. Pin a released tag when you want a reproducible version — see the tags for the ones that exist:

dsh plugin add github:stormbuf/dsh-tavily-pool
dsh plugin add github:stormbuf/dsh-tavily-pool#vX.Y.Z

Both routes install the same files: the files whitelist in package.json applies to git installs too, so no test/ or scripts/ directory comes along.

Then restart DSH, open Settings → Plugins → dsh-tavily-pool and paste your Tavily API key(s). Keys are entered through the panel only — the plugin does not read environment variables or the DSH credentials service.

See docs/usage.md for configuration, scheduling behaviour, billing, and manual rollback steps.

Compatibility

DeepSeek Harness is in preview, so its architecture and plugin interfaces may change between releases. This plugin isolates nearly all host-specific knowledge in one thin adapter layer (lib/dsh/), plus the zero-build client half (lib/client.js) and the provider pin in cordis.patch.yml, and probes host capabilities at load time, so that adapting to a breaking change stays cheap.

Tested against DSH 0.1.7-rc.2. A newer release may still need re-adaptation; the plugin probes host capabilities at load time and reports a clear error naming the missing one rather than failing silently. Its host peer ranges carry only a lower bound, so an untested DSH release never refuses to load the plugin — DSH 0.1.7 added a hard gate that skips a whole bundle whose peer range excludes the running version, which turns a stale upper bound into a silently missing plugin. The step-by-step checklist lives in docs/dsh-upgrade.md.

Installing through dsh plugin add makes this package a bundle layer of the target profile (it lands in that profile's dsh.profile.bundles, after the DSH bundles), which is what lets its cordis.patch.yml pin the providers. Your own profile patch is applied after every bundle layer, so it can always override or disable what this plugin does — see Manual rollback.

License

MIT