@viztor/dsh-tinyfish 0.3.0

package/lib/index.mjs

@@ -0,0 +1,825 @@
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
+import z from "@deepseek-ai/schemastery";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { WebError } from "@deepseek-ai/dsh-web";
+//#region src/client.ts
+/** Monid REST base. */
+const DEFAULT_MONID_BASE = "https://api.monid.ai";
+/** TinyFish's own search and fetch bases. */
+const DEFAULT_SEARCH_BASE = "https://api.search.tinyfish.ai";
+const DEFAULT_FETCH_BASE = "https://api.fetch.tinyfish.ai";
+/** Where the `monid` CLI keeps the platform key. */
+const DEFAULT_CREDENTIALS = "~/.config/monid/credentials.yaml";
+/** Where the official `tinyfish` CLI keeps its key (the same file it reads). */
+const DEFAULT_TINYFISH_CONFIG = "~/.tinyfish/config.json";
+/** Base backoff between attempts; doubles per attempt. */
+const DEFAULT_RETRY_DELAY_MS = 1200;
+/** Poll cadence and ceiling for an async Monid run. */
+const DEFAULT_POLL_MS = 1500;
+const DEFAULT_MAX_POLLS = 40;
+/**
+* Monid sits behind Cloudflare, which rejects the default fetch/undici
+* user-agent with a 403 `browser_signature_banned`. The direct API is fine
+* either way, so one browser UA is sent on every request.
+*/
+const USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
+const WEB_PROVIDER_ERROR = "WEB_PROVIDER_ERROR";
+const WEB_PROVIDER_CREDENTIAL_MISSING = "WEB_PROVIDER_CREDENTIAL_MISSING";
+const WEB_ABORTED = "WEB_ABORTED";
+/**
+* A `WebError` the retry loop may try again.
+*
+* A subclass rather than a flag on the error, because `WebError` is the
+* seam's own type and adding a field to it would put a property on something
+* the harness renders. `instanceof WebError` still holds, so cancellation and
+* error routing downstream are unaffected.
+*
+* Transient covers rate limits and upstream 5xx — the shapes that are worth
+* another attempt. It is deliberately not a code: the retry loop asks "would
+* this probably work next time", and one code cannot answer that for both a
+* 429 and a 503.
+*/
+var TransientWebError = class extends WebError {
+	constructor(message, code, options) {
+		super(message, code, options);
+		this.name = "TransientWebError";
+	}
+};
+/** True for an error the retry loop is allowed to try again. */
+const isTransient = (error) => error instanceof TransientWebError;
+/**
+* Build the provider's stable cancellation error.
+*
+* The caller's `reason` is kept as the `cause` when the signal has already
+* fired, so the harness's own abort reason survives instead of being replaced
+* by a generic string.
+*/
+const aborted = (signal, fallback) => new WebError("TinyFish request aborted", WEB_ABORTED, { cause: signal?.aborted ? signal.reason : fallback });
+/**
+* True for a fetch/`AbortSignal` abort.
+*
+* `signal.aborted` alone is not enough: a request can be cancelled by a
+* timeout racing an in-flight `fetch`, in which case the signal never fired
+* and the rejection arrives as a `DOMException` named `AbortError`. Treating
+* that as a transport failure would surface a user-initiated stop as an
+* upstream error.
+*/
+const isAbortError = (error) => error instanceof Error && error.name === "AbortError";
+/** Throw the stable cancellation error when the caller has already aborted. */
+const throwIfAborted = (signal) => {
+	if (signal?.aborted) throw aborted(signal);
+};
+/**
+* Race an operation against the caller's cancellation.
+*
+* The settlement handlers stay attached after an abort, so a late rejection
+* from the abandoned operation cannot become an unhandled rejection — the
+* usual failure mode of naively wrapping a promise in a race.
+*/
+async function abortable(operation, signal) {
+	if (!signal) return operation;
+	throwIfAborted(signal);
+	const cancelled = new Promise((_resolve, reject) => {
+		const onAbort = () => {
+			reject(aborted(signal));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+	return Promise.race([operation, cancelled]);
+}
+/** Sleep that rejects promptly when the caller's signal aborts. */
+async function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(aborted(signal));
+			return;
+		}
+		const timer = setTimeout(resolve, ms);
+		signal?.addEventListener("abort", () => {
+			clearTimeout(timer);
+			reject(aborted(signal));
+		}, { once: true });
+	});
+}
+/** Expand a leading `~`. */
+const home = (path) => path.startsWith("~/") ? join(homedir(), path.slice(2)) : path;
+/**
+* Read the active key out of the monid CLI's credentials file.
+*
+* The file is YAML, but its shape is fixed and tiny — `active_key:` plus one
+* indented `key:` per entry — so a targeted read beats pulling a YAML parser
+* into a plugin with no other use for one.
+*/
+function readMonidCredentials(path) {
+	let text;
+	try {
+		text = readFileSync(home(path), "utf8");
+	} catch {
+		return "";
+	}
+	const active = /^active_key:\s*(\S+)\s*$/m.exec(text)?.[1];
+	const parts = text.split(/^(\s{2,})(\S+):\s*$/m);
+	const entries = /* @__PURE__ */ new Map();
+	for (let i = 1; i + 2 < parts.length; i += 3) {
+		const name = parts[i + 1];
+		const body = parts[i + 2];
+		if (name !== void 0 && body !== void 0) entries.set(name, body);
+	}
+	const keyIn = (body) => /^\s+key:\s*(\S+)\s*$/m.exec(body ?? "")?.[1];
+	if (active) {
+		const chosen = keyIn(entries.get(active));
+		if (chosen) return chosen;
+	}
+	for (const body of entries.values()) {
+		const key = keyIn(body);
+		if (key) return key;
+	}
+	return keyIn(text) ?? "";
+}
+/**
+* Read the key the official `tinyfish` CLI already stored.
+*
+* Reusing that file is deliberate: the user has already authenticated the CLI
+* (`tinyfish auth login`), and reading the same store means the plugin has no
+* separate credential to provision, rotate, or leak.
+*/
+function readTinyfishConfig(path) {
+	try {
+		const config = JSON.parse(readFileSync(home(path), "utf8"));
+		if (config && typeof config === "object" && "api_key" in config) {
+			const value = config.api_key;
+			return typeof value === "string" ? value.trim() : "";
+		}
+		return "";
+	} catch {
+		return "";
+	}
+}
+/**
+* Resolve the credential for one channel.
+*
+* Explicit config wins, then the environment, then the channel's own
+* credential store. Stores are re-read per call rather than cached at module
+* load: they are a few hundred bytes, and caching would pin a rotated key
+* inside a long-lived host process.
+*/
+function resolveApiKey(channel, options = {}) {
+	const explicit = options.apiKey?.trim();
+	if (explicit) return explicit;
+	const env = options.env ?? process.env;
+	if (channel === "monid") {
+		const fromEnv = env.MONID_API_KEY ?? env.MONID_MCP_TOKEN;
+		if (fromEnv?.trim()) return fromEnv.trim();
+		return readMonidCredentials(options.credentialsPath ?? DEFAULT_CREDENTIALS);
+	}
+	const direct = env.TINYFISH_API_KEY;
+	if (direct?.trim()) return direct.trim();
+	return readTinyfishConfig(options.tinyfishConfigPath ?? DEFAULT_TINYFISH_CONFIG);
+}
+/**
+* The same resolution, with the harness credentials service consulted first.
+*
+* The split is deliberate rather than an oversight: `available()` must be a
+* cheap synchronous check that never awaits, and it uses the synchronous form.
+* Only the credential lookup is async, and only when a service is present.
+*/
+async function resolveApiKeyAsync(channel, options = {}) {
+	const explicit = options.apiKey?.trim();
+	if (explicit) return explicit;
+	const { apiKeyEnv, monidKeyEnv, resolveCredential } = options;
+	const ref = channel === "monid" ? monidKeyEnv : apiKeyEnv;
+	throwIfAborted(options.signal);
+	if (ref && resolveCredential) try {
+		const trimmed = (await abortable(Promise.resolve(resolveCredential(ref)), options.signal))?.trim();
+		if (trimmed) return trimmed;
+	} catch (error) {
+		if (options.signal?.aborted) throw aborted(options.signal, error);
+	}
+	return resolveApiKey(channel, options);
+}
+/**
+* Assert that a channel is configured, naming the fix in the message.
+*
+* Deliberately a statement rather than an accessor: the caller resolves the
+* key itself and must use that same value, so this only ever throws.
+*/
+function requireKey(channel, key) {
+	if (key) return;
+	if (channel === "monid") throw new WebError("The tinyfish provider has no Monid API key. Run `monid keys add` to store one in the local credential file, or export MONID_API_KEY, or set the web-tinyfish `apiKeyEnv` row in the profile's cordis.patch.yml.", WEB_PROVIDER_CREDENTIAL_MISSING);
+	throw new WebError("The tinyfish provider has no TinyFish API key. Run `tinyfish auth login` to save one, or export TINYFISH_API_KEY, or set the web-tinyfish `apiKeyEnv` row in the profile's cordis.patch.yml — or switch the provider's channel to 'monid' to use a Monid key instead.", WEB_PROVIDER_CREDENTIAL_MISSING);
+}
+/** `fetch` with auth applied and failures mapped to `WebError`. */
+async function call(url, options) {
+	const { channel, key, init, signal } = options;
+	const headers = {
+		"User-Agent": USER_AGENT,
+		...channel === "monid" ? {
+			Authorization: `Bearer ${key}`,
+			"Content-Type": "application/json"
+		} : { "X-API-Key": key },
+		...init.headers
+	};
+	let response;
+	try {
+		response = await fetch(url, {
+			...init,
+			headers,
+			redirect: "error",
+			...signal ? { signal } : {}
+		});
+	} catch (error) {
+		if (signal?.aborted) throw aborted(signal);
+		if (isAbortError(error)) throw aborted(signal, error);
+		throw new WebError(`TinyFish request to ${url} failed: ${String(error)}`, WEB_PROVIDER_ERROR, { cause: error });
+	}
+	if (response.status === 401 || response.status === 403) {
+		const fingerprint = createHash("sha256").update(key, "utf8").digest("hex").slice(0, 12);
+		throw new WebError(`TinyFish rejected the ${channel} API key (HTTP ${response.status}, key sha256:${fingerprint}). Refresh it, or switch the provider's channel.`, WEB_PROVIDER_ERROR);
+	}
+	if (response.status === 429) throw new TransientWebError("TinyFish rate limit reached (HTTP 429).", WEB_PROVIDER_ERROR);
+	if (!response.ok) throw new WebError(`TinyFish returned HTTP ${response.status} for ${url}`, WEB_PROVIDER_ERROR);
+	try {
+		return await response.json();
+	} catch (error) {
+		throw new WebError(`TinyFish returned a non-JSON body for ${url}`, WEB_PROVIDER_ERROR, { cause: error });
+	}
+}
+/** Query string for the direct channel, skipping empty filters. */
+function searchQueryString(params) {
+	const search = new URLSearchParams();
+	for (const [key, value] of Object.entries(params)) {
+		if (value === void 0 || value === null || value === "") continue;
+		search.set(key, String(value));
+	}
+	return search.toString();
+}
+/** One search through the monid channel, polling if the run is async. */
+async function searchMonid(options) {
+	const { key, base, params, signal, pollMs, maxPolls } = options;
+	let envelope = await call(`${base}/v1/run`, {
+		channel: "monid",
+		key,
+		signal,
+		init: {
+			method: "POST",
+			body: JSON.stringify({
+				provider: "tinyfish",
+				endpoint: "/search",
+				input: { queryParams: params }
+			})
+		}
+	});
+	let polls = 0;
+	while (envelope.status === "RUNNING" && polls < maxPolls) {
+		throwIfAborted(signal);
+		polls += 1;
+		await sleep(pollMs, signal);
+		envelope = await call(`${base}/v1/run`, {
+			channel: "monid",
+			key,
+			signal,
+			init: {
+				method: "POST",
+				body: JSON.stringify({ runId: envelope.runId })
+			}
+		});
+	}
+	if (envelope.status === "RUNNING") throw new WebError(`TinyFish run ${envelope.runId ?? "?"} did not settle within ${polls} polls`, WEB_PROVIDER_ERROR);
+	assertUsableRun(envelope);
+	return envelope.output ?? {};
+}
+/** Raise for a BLOCKED / FAILED run, which retrying will not fix. */
+function assertUsableRun(envelope) {
+	if (envelope.status === "BLOCKED") {
+		const { reason } = envelope;
+		const detail = reason && typeof reason === "object" ? [reason.reason, ...reason.hints ?? []].filter(Boolean).join(" ") : String(reason ?? "");
+		throw new WebError(`The Monid workspace blocked this run${detail ? `: ${detail}` : "."} Top up at https://app.monid.ai/wallet.`, WEB_PROVIDER_ERROR);
+	}
+	if (envelope.status === "FAILED" || envelope.status === "TIMED_OUT") throw new WebError(`TinyFish run ${envelope.runId ?? "?"} ended ${envelope.status}`, WEB_PROVIDER_ERROR);
+	const provider = envelope.providerResponse;
+	if (!envelope.output && (provider?.error || (provider?.httpStatus ?? 0) >= 500)) {
+		const message = extractProviderMessage(provider?.error);
+		throw new TransientWebError(`TinyFish is temporarily unavailable${message ? `: ${message}` : "."}`, WEB_PROVIDER_ERROR);
+	}
+}
+/** Dig a human message out of Monid's nested provider error, if there is one. */
+function extractProviderMessage(error) {
+	if (!error || typeof error !== "object") return "";
+	const message = error.error?.message;
+	return typeof message === "string" ? message : "";
+}
+/** One fetch through the monid channel. */
+async function fetchMonid(options) {
+	const { key, base, body, signal } = options;
+	const envelope = await call(`${base}/v1/run`, {
+		channel: "monid",
+		key,
+		signal,
+		init: {
+			method: "POST",
+			body: JSON.stringify({
+				provider: "tinyfish",
+				endpoint: "/fetch",
+				input: { body }
+			})
+		}
+	});
+	assertUsableRun(envelope);
+	return envelope.output ?? {};
+}
+/**
+* Run one operation with a bounded retry.
+*
+* Two transient shapes are worth retrying, and both are observed in practice:
+* a `SERVICE_BUSY`/5xx envelope from the monid channel, and a `/search` that
+* answers a perfectly valid query with zero results (roughly one run in three).
+* The endpoints are $0, so an empty result is worth a couple more attempts
+* before it is believed. A BLOCKED run never retries.
+*/
+async function withRetry(operation, policy) {
+	const { attempts, signal, delayMs = DEFAULT_RETRY_DELAY_MS, retryWhen, onRetry } = policy;
+	let lastError;
+	for (let attempt = 1; attempt <= attempts; attempt += 1) {
+		try {
+			const value = await operation();
+			if (attempt > 1) onRetry?.(attempt, attempts, lastError);
+			if (!retryWhen?.(value) || attempt === attempts) return value;
+			onRetry?.(attempt, attempts);
+		} catch (error) {
+			if (signal?.aborted) throw aborted(signal, error);
+			if (isAbortError(error)) throw aborted(signal, error);
+			if (!isTransient(error)) throw error;
+			if (attempt === attempts) throw error;
+			lastError = error;
+			onRetry?.(attempt, attempts, error);
+		}
+		await sleep(delayMs * attempt, signal);
+	}
+	throw lastError ?? new WebError("TinyFish gave up", "WEB_PROVIDER_ERROR");
+}
+/**
+* Search TinyFish. Returns the upstream payload for both channels:
+* `{ query, results[], total_results, page }`.
+*/
+async function tinyfishSearch(options) {
+	const { channel, query, apiKey, apiKeyEnv, monidKeyEnv, resolveCredential, credentialsPath, tinyfishConfigPath, filters = {}, monidBase = DEFAULT_MONID_BASE, searchBase = DEFAULT_SEARCH_BASE, signal, attempts = 3, delayMs, onRetry, pollMs = DEFAULT_POLL_MS, maxPolls = DEFAULT_MAX_POLLS } = options;
+	const key = await resolveApiKeyAsync(channel, {
+		apiKey,
+		apiKeyEnv,
+		monidKeyEnv,
+		resolveCredential,
+		credentialsPath,
+		env: options.env,
+		tinyfishConfigPath,
+		signal
+	});
+	requireKey(channel, key);
+	const params = {
+		query,
+		...filters
+	};
+	return withRetry(async () => channel === "monid" ? searchMonid({
+		key,
+		base: monidBase,
+		params,
+		signal,
+		pollMs,
+		maxPolls
+	}) : call(`${searchBase}?${searchQueryString(params)}`, {
+		channel: "direct",
+		key,
+		signal,
+		init: { method: "GET" }
+	}), {
+		attempts,
+		signal,
+		delayMs,
+		retryWhen: (payload) => {
+			const value = payload;
+			return !Array.isArray(value?.results) || value.results.length === 0;
+		},
+		onRetry: (attempt, total) => onRetry?.(attempt, total)
+	});
+}
+/**
+* Fetch up to 10 URLs as clean Markdown. Returns the upstream payload for both
+* channels: `{ results[], errors[] }`.
+*/
+async function tinyfishFetch(options) {
+	const { channel, urls, apiKey, apiKeyEnv, monidKeyEnv, resolveCredential, credentialsPath, tinyfishConfigPath, purpose, monidBase = DEFAULT_MONID_BASE, fetchBase = DEFAULT_FETCH_BASE, signal, attempts = 3, delayMs, onRetry } = options;
+	const key = await resolveApiKeyAsync(channel, {
+		apiKey,
+		apiKeyEnv,
+		monidKeyEnv,
+		resolveCredential,
+		credentialsPath,
+		env: options.env,
+		tinyfishConfigPath,
+		signal
+	});
+	requireKey(channel, key);
+	const body = {
+		urls,
+		format: "markdown"
+	};
+	if (purpose) body.purpose = purpose;
+	return withRetry(async () => channel === "monid" ? fetchMonid({
+		key,
+		base: monidBase,
+		body,
+		signal
+	}) : call(fetchBase, {
+		channel: "direct",
+		key,
+		signal,
+		init: {
+			method: "POST",
+			body: JSON.stringify(body)
+		}
+	}), {
+		attempts,
+		signal,
+		delayMs,
+		onRetry: (attempt, total) => onRetry?.(attempt, total)
+	});
+}
+//#endregion
+//#region src/provider.ts
+/**
+* The two `ctx.web` providers.
+*
+* Both are thin: dispatch through the transport, then normalise TinyFish's
+* payload into the seam's vocabulary. The seam owns `maxResults` truncation,
+* cancellation, error codes and the tool card, so nothing here re-implements
+* any of that.
+*
+* @module dsh-tinyfish/provider
+*/
+/** Stable id these providers register under. */
+const TINYFISH_PROVIDER_ID = "tinyfish";
+/**
+* TinyFish reports dates as human strings ("Apr 30, 2026", "1 year ago"), but
+* `WebSearchSource.publishedAt` is contractually an ISO-8601 string. Rather
+* than pass a value the type does not promise, coerce what parses and drop the
+* rest — a missing date is honest, a malformed one is not.
+*
+* A date carrying no timezone is read as UTC, not local. `Date.parse("Apr 30,
+* 2026")` means local midnight, so `.toISOString()` would shift the day for any
+* host east or west of Greenwich — the same page would report a different
+* `publishedAt` depending on where the Worker ran. These strings are date-only,
+* so UTC midnight is both the stable reading and the one that keeps the day the
+* publisher actually meant.
+*/
+function toIsoDate(value) {
+	if (typeof value !== "string" || !value.trim()) return void 0;
+	const text = value.trim();
+	const zoned = /(?:Z|[+-]\d{2}:?\d{2})$/i.test(text) || /\d{1,2}:\d{2}/.test(text);
+	let candidate = text;
+	if (!zoned) {
+		if (/^\d{4}-\d{2}-\d{2}$/.test(text)) candidate = `${text}T00:00:00Z`;
+		else if (/^[A-Za-z]{3,9}\s+\d{1,2},\s*\d{4}$/.test(text)) candidate = `${text} UTC`;
+	}
+	const parsed = Date.parse(candidate);
+	if (Number.isNaN(parsed)) return void 0;
+	return new Date(parsed).toISOString();
+}
+/**
+* TinyFish search through the `ctx.web` search seam.
+*
+* The seam's request is only `{query, maxResults}`; everything else
+* (`domainType`, `location`, `includeDomains`, …) comes from plugin config and
+* applies to every query, which is the shape these filters actually want.
+*/
+var TinyfishSearchProvider = class {
+	id = TINYFISH_PROVIDER_ID;
+	resolveOptions;
+	/**
+	* @param resolveOptions - a thunk, not a value: the plugin's settings section
+	*   can change between searches, and re-registering the provider to carry a
+	*   new config would make the seam's selection flicker for the user.
+	*/
+	constructor(resolveOptions) {
+		this.resolveOptions = resolveOptions;
+	}
+	/**
+	* Cheap local usability check. Must not make network calls — the seam calls
+	* this to decide between providers, and a network call here would turn
+	* selection into a latency spike on every search.
+	*
+	* Checks the same things the shipped providers do: a credential is
+	* resolvable *and* both endpoints parse as URLs. A misconfigured base is a
+	* setup mistake worth surfacing at selection time rather than as a 404 later.
+	*/
+	available() {
+		const options = this.resolveOptions();
+		return Boolean(options.search && hasCredential(options) && URL.canParse(options.searchBase) && (options.channel === "direct" || URL.canParse(options.monidBase)));
+	}
+	async search(request, signal) {
+		const options = this.resolveOptions();
+		const payload = await tinyfishSearch({
+			channel: options.channel,
+			apiKey: options.apiKey,
+			apiKeyEnv: options.apiKeyEnv,
+			monidKeyEnv: options.monidKeyEnv,
+			resolveCredential: options.resolveCredential,
+			query: request.query,
+			filters: { ...options.filters },
+			monidBase: options.monidBase,
+			searchBase: options.searchBase,
+			signal,
+			attempts: options.attempts
+		});
+		return {
+			sources: (Array.isArray(payload?.results) ? payload.results : []).filter((row) => typeof row?.url === "string" && row.url !== "").map((row) => {
+				const source = { url: row.url };
+				if (row.title) source.title = String(row.title);
+				const snippet = row.snippet ?? row.description;
+				if (snippet) source.snippet = String(snippet);
+				const publishedAt = toIsoDate(row.date);
+				if (publishedAt) source.publishedAt = publishedAt;
+				return source;
+			}),
+			truncated: false
+		};
+	}
+};
+/**
+* TinyFish fetch through the `ctx.web` fetch seam.
+*
+* Returns `kind: "text"` on purpose: TinyFish already extracts clean Markdown,
+* so `dsh-tool-web` passes it straight through. The `http` provider instead
+* returns `kind: "html"` and pays for a turndown conversion this path skips.
+*/
+var TinyfishFetchProvider = class {
+	id = TINYFISH_PROVIDER_ID;
+	/** A thunk, not a value; see {@link TinyfishSearchProvider} for why. */
+	resolveOptions;
+	constructor(resolveOptions) {
+		this.resolveOptions = resolveOptions;
+	}
+	/**
+	* Cheap local usability check. Must not make network calls — the seam calls
+	* this to decide between providers, and a network call here would turn
+	* selection into a latency spike on every search.
+	*
+	* Checks the same things the shipped providers do: a credential is
+	* resolvable *and* both endpoints parse as URLs. A misconfigured base is a
+	* setup mistake worth surfacing at selection time rather than as a 404 later.
+	*/
+	available() {
+		const options = this.resolveOptions();
+		return Boolean(options.fetch && hasCredential(options) && URL.canParse(options.fetchBase) && (options.channel === "direct" || URL.canParse(options.monidBase)));
+	}
+	async fetch(request, signal) {
+		const options = this.resolveOptions();
+		const payload = await tinyfishFetch({
+			channel: options.channel,
+			apiKey: options.apiKey,
+			apiKeyEnv: options.apiKeyEnv,
+			monidKeyEnv: options.monidKeyEnv,
+			resolveCredential: options.resolveCredential,
+			urls: [request.url],
+			purpose: options.purpose,
+			monidBase: options.monidBase,
+			fetchBase: options.fetchBase,
+			signal,
+			attempts: options.attempts
+		});
+		const results = Array.isArray(payload?.results) ? payload.results : [];
+		const failure = (Array.isArray(payload?.errors) ? payload.errors : []).find((row) => sameUrl(row?.url, request.url));
+		if (!results.length && failure) {
+			const status = Number(failure.status);
+			return {
+				url: request.url,
+				statusCode: Number.isFinite(status) && status > 0 ? status : 502,
+				body: {
+					kind: "text",
+					content: `Could not retrieve this page: ${failure.error ?? "fetch failed"} (HTTP ${failure.status ?? "?"}).`
+				},
+				truncated: false
+			};
+		}
+		const page = results[0];
+		if (!page) throw new WebError(`TinyFish returned no content for ${request.url}`, WEB_PROVIDER_ERROR);
+		return {
+			url: page.final_url ?? page.url ?? request.url,
+			statusCode: 200,
+			body: {
+				kind: "text",
+				content: String(page.text ?? "")
+			},
+			truncated: false
+		};
+	}
+};
+/**
+* True when this configuration can produce a credential without a network
+* call: a literal key, the environment, or a credential the CLIs already
+* stored. A `credential-ref` resolved by the harness service is not visible
+* from here, so a plugin that relies on one stays available through the
+* service-backed path in the client.
+*/
+function hasCredential(options) {
+	const ref = options.channel === "monid" ? options.monidKeyEnv : options.apiKeyEnv;
+	return Boolean(resolveApiKey(options.channel, {
+		apiKey: options.apiKey,
+		monidKeyEnv: options.monidKeyEnv,
+		env: {
+			TINYFISH_API_KEY: process.env[ref],
+			MONID_API_KEY: process.env[ref],
+			MONID_MCP_TOKEN: process.env[ref]
+		}
+	}));
+}
+/** Compare URLs ignoring a trailing slash, so `/a` and `/a/` match. */
+function sameUrl(a, b) {
+	if (typeof a !== "string") return false;
+	const strip = (value) => value.replace(/\/+$/, "");
+	return strip(a) === strip(b);
+}
+//#endregion
+//#region src/index.ts
+/**
+* `dsh-tinyfish` — TinyFish-backed search and fetch for the DSH web
+* capability seam.
+*
+* Registers two providers under one id, `tinyfish`, and lets the profile pick
+* the channel:
+*
+*   monid  — reach TinyFish through the Monid REST API. Costs nothing on the
+*            Monid wallet, and reuses the credential the MCP mount already
+*            holds, so it keeps working when no TinyFish account is configured.
+*   direct — call TinyFish's own API, using the key the `tinyfish` CLI already
+*            stored in ~/.tinyfish/config.json.
+*
+* Both channels return the same upstream payload, so nothing above this file
+* branches on which one is active.
+*
+* @module dsh-tinyfish
+*/
+/** Settings namespace, matching the `<kind>-<provider>` convention. */
+const WEB_TINYFISH_SETTINGS_NAMESPACE = "web-tinyfish";
+/**
+* The plugin's settings schema.
+*
+* This is the harness's own `@deepseek-ai/schemastery` fork rather than the
+* public package, because the fork is what implements the `.role()`,
+* `.volatile()` and `.get()` surface the loader and the settings UI both rely
+* on, and the public 3.18.x line does not have it. Cordis resolves a plugin's
+* `Config` through `resolveConfig` and falls back to the raw row when a plugin
+* exports none — so exporting this is what makes the row render as a real
+* settings section rather than free-form YAML.
+*
+* - `role("secret")` keeps a literal key out of any redacted dump.
+* - `role("credential-ref")` makes a field a *reference* to a stored
+*   credential, resolved through `ctx.get("credentials")` — the way the shipped
+*   search provider does it, so the value is manageable from Settings instead
+*   of only from a patch file.
+* - `volatile()` marks a field that must be re-read at the start of every
+*   operation. Everything here is: a key can be rotated while the harness is
+*   running, and a provider that captured one at load time would keep sending
+*   a dead credential.
+*/
+const Config = z.object({
+	channel: z.union([z.const("monid"), z.const("direct")]).default("direct").description("Which upstream route to use. `monid` reuses the MCP credential."),
+	apiKey: z.string().role("secret").volatile().description("Literal credential, overriding both refs. Prefer a credential ref or the environment."),
+	apiKeyEnv: z.string().role("credential-ref").default("TINYFISH_API_KEY").volatile().description("Stored credential or environment variable for the direct channel."),
+	monidKeyEnv: z.string().role("credential-ref").default("MONID_API_KEY").volatile().description("Stored credential or environment variable for the monid channel. Kept separate so both keys can be saved at once."),
+	purpose: z.string().volatile().description("Goal statement; TinyFish ranks on it."),
+	attempts: z.number().step(1).min(1).max(5).default(3).volatile().description("Attempts for a transient failure or an empty search."),
+	filters: z.object({
+		domainType: z.union([
+			z.const("web"),
+			z.const("news"),
+			z.const("research_paper")
+		]).description("Restrict the result corpus."),
+		language: z.string().description("Language code for geo-targeted results."),
+		location: z.string().description("Location code for geo-targeted results."),
+		includeDomains: z.string().description("Comma-separated domains to allow."),
+		excludeDomains: z.string().description("Comma-separated domains to drop.")
+	}).description("Search filters applied to every query.").volatile(),
+	monidBase: z.string().default(DEFAULT_MONID_BASE).description("Monid REST base."),
+	searchBase: z.string().default(DEFAULT_SEARCH_BASE).description("TinyFish search base."),
+	fetchBase: z.string().default(DEFAULT_FETCH_BASE).description("TinyFish fetch base."),
+	search: z.boolean().default(true).description("Offer TinyFish as the search provider."),
+	fetch: z.boolean().default(true).description("Offer TinyFish as the fetch provider.")
+});
+/** Cordis service dependencies. */
+const inject = ["web"];
+/** The bundle name. Must equal the manifest `name`: the loader matches on it. */
+const name = "dsh-tinyfish";
+/**
+* Clamp `attempts` to a range the retry loop can honour.
+*
+* Blank means unset, not zero. The value arrives via `readField`, which turns
+* an absent field into `""`, and `Number("")` is `0` — finite, and therefore
+* clamped up to the minimum of 1 rather than falling back to the default. A
+* field the user never set would have silently become "try once".
+*/
+function normalizeAttempts(value) {
+	if (value === "" || value === null || value === void 0) return 3;
+	const n = Number(value);
+	if (!Number.isFinite(n)) return 3;
+	return Math.min(5, Math.max(1, Math.floor(n)));
+}
+/**
+* Coerce one config value to a string, refusing anything that is not scalar.
+*
+* A validated section hands out boxed schema nodes; a raw patch row does not.
+* Both have to be readable, because a plugin can be called either way.
+*/
+function asScalar(value) {
+	if (value === null || value === void 0) return "";
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	return "";
+}
+/** Read one field from a section, whether it is boxed (`.get()`) or raw. */
+function readField(section, key) {
+	const value = section[key];
+	return asScalar(typeof value?.get === "function" ? value.get() : value);
+}
+/**
+* Build the credential lookup for one operation.
+*
+* Two sources, in the harness's own order of trust: the credentials service
+* first, then the launch environment — the snapshot the harness froze at
+* boot, which is what makes a value stable across a `chdir` or a workspace
+* switch mid-session.
+*
+* Both are optional at runtime. A host that has neither still works, because
+* the client falls through to the environment and then the CLI stores.
+*/
+function credentialLookup(ctx) {
+	let credentials;
+	try {
+		credentials = ctx.get("credentials");
+	} catch {
+		credentials = void 0;
+	}
+	let ambient;
+	try {
+		ambient = launchEnvironmentOf(ctx);
+	} catch {
+		ambient = void 0;
+	}
+	if (!credentials && !ambient) return void 0;
+	return async (ref) => {
+		if (credentials) {
+			const resolved = await credentials.resolve(credentialRef(ref));
+			if (resolved?.value) return resolved.value;
+		}
+		const value = ambient?.get(ref)?.value;
+		return value && value.length > 0 ? value : void 0;
+	};
+}
+/** Project one resolved section into the options the next operation serves. */
+function resolveOptions(config, ctx, env = process.env) {
+	const section = config ?? {};
+	const rawFilters = section.filters ?? {};
+	const filters = {};
+	const pick = (key, upstream) => {
+		const value = asScalar(rawFilters[key]);
+		if (value) filters[upstream] = value;
+	};
+	pick("domainType", "domain_type");
+	pick("language", "language");
+	pick("location", "location");
+	pick("includeDomains", "include_domains");
+	pick("excludeDomains", "exclude_domains");
+	const apiKey = readField(section, "apiKey").trim();
+	const purpose = readField(section, "purpose").trim();
+	return {
+		channel: readField(section, "channel") === "monid" ? "monid" : "direct",
+		apiKey: apiKey || void 0,
+		apiKeyEnv: readField(section, "apiKeyEnv") || "TINYFISH_API_KEY",
+		monidKeyEnv: readField(section, "monidKeyEnv") || "MONID_API_KEY",
+		resolveCredential: ctx ? credentialLookup(ctx) : void 0,
+		purpose: purpose || void 0,
+		filters,
+		attempts: normalizeAttempts(readField(section, "attempts")),
+		monidBase: readField(section, "monidBase") || env.TINYFISH_MONID_BASE_URL || "https://api.monid.ai",
+		searchBase: readField(section, "searchBase") || env.TINYFISH_SEARCH_BASE_URL || "https://api.search.tinyfish.ai",
+		fetchBase: readField(section, "fetchBase") || env.TINYFISH_FETCH_BASE_URL || "https://api.fetch.tinyfish.ai",
+		search: readField(section, "search") !== "false",
+		fetch: readField(section, "fetch") !== "false"
+	};
+}
+/**
+* Register both providers with `ctx.web`.
+*
+* Selection stays the profile's call: this plugin only offers `tinyfish`, and
+* `dsh-web`'s `searchProvider` / `fetchProvider` decide whether it is used.
+* Reverting is two words in the patch, with this plugin still mounted.
+*/
+function apply(ctx, config) {
+	const options = () => resolveOptions(config, ctx);
+	ctx.web.registerSearchProvider(new TinyfishSearchProvider(options));
+	ctx.web.registerFetchProvider(new TinyfishFetchProvider(options));
+}
+//#endregion
+export { Config, DEFAULT_FETCH_BASE, DEFAULT_MONID_BASE, DEFAULT_SEARCH_BASE, TINYFISH_PROVIDER_ID, TinyfishFetchProvider, TinyfishSearchProvider, WEB_ABORTED, WEB_PROVIDER_CREDENTIAL_MISSING, WEB_PROVIDER_ERROR, WEB_TINYFISH_SETTINGS_NAMESPACE, WebError, apply, inject, name, resolveApiKey, resolveOptions, tinyfishFetch, tinyfishSearch, toIsoDate };