@rm-vstar/dsh-web-search-tinyfish

English | 中文

A TinyFish-backed WebSearchProvider for the harness web capability seam (ctx.web). It calls TinyFish's dedicated search REST endpoint (GET {baseURL}?query=...), authenticates with the X-API-Key header — not a Bearer token — and maps the structured results[] TinyFish returns into the seam's normalized WebSearchResult.

This is an implementation package: it registers a provider into ctx.web, resolves its credential for each search through the optional ctx.credentials seam (defaulting to the TINYFISH_API_KEY reference), and does not register a model-facing tool. Like the other web-search-* packages it is a function/namespace plugin (inject: ['web']). Each search costs one cheap retrieval call, not a model turn.

Auth: X-API-Key, not Bearer

TinyFish's REST API expects the key in the X-API-Key request header. The provider sends exactly that header and never Authorization: Bearer (unlike the Exa provider, which sends the latter).

Config

Key	Default	Meaning
apiKey	omitted	Literal TinyFish API key. Prefer apiKeyEnv so no secret enters configuration; a non-empty literal wins.
apiKeyEnv	TINYFISH_API_KEY	Credential reference resolved for each search through ctx.credentials, or from the launching environment when that seam is absent. A missing value fails the call as WEB_PROVIDER_CREDENTIAL_MISSING.
baseURL	https://api.search.tinyfish.ai	TinyFish search endpoint; ?query=, &location= and &domain_type= are appended. An unparseable value makes the provider unavailable.
location	US	location query parameter (region bias).
domainType	web	domain_type query parameter (search scope).
maxResults	omitted	Default result count when a request carries no maxResults; the provider truncates locally.

- id: web-search-tinyfish
  name: '@rm-vstar/dsh-web-search-tinyfish'
  config:
    apiKeyEnv: TINYFISH_API_KEY
    baseURL: https://gateway.internal/search

The entry above is the base layer of the web-search-tinyfish Settings section: a user layer over it reaches the NEXT search, because the provider projects the section per call rather than capturing it at registration. The seam's provider selection therefore never flickers when an endpoint changes. apiKey carries role('secret'), so it never rides a describe() response in any layer.

Mapping

TinyFish returns no generated answer, so content is omitted. sources[] comes from results[]: url ← url, title ← title, and snippet ← snippet; when TinyFish supplies a blank excerpt, the hosting site_name is used as the fallback snippet — the provider never invents prose. maxResults is enforced locally exactly as the seam enforces it on the way back: over-returned sources are cut and truncated is set.

Provider failures become WEB_PROVIDER_ERROR; caller cancellation becomes WEB_ABORTED. HTTP redirects are rejected before the Location target is contacted and surface as WEB_PROVIDER_ERROR.