dsh-web-search-firecrawl 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aa2246740
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# dsh-web-search-firecrawl
+
+```sh
+dsh plugin --profile web add github:aa2246740/dsh-firecrawl
+```
+
+PATH 上要有官方 `dsh`（没有就用 `npx @deepseek-ai/dsh`）和 **pnpm**。`dsh plugin add` 会在 `$DSH_HOME/profiles/web` 里跑 pnpm。仓库已提交编译好的 `lib/`，git 安装不用 `prepare`，也不用改 profile 的 `allowBuilds`。
+
+然后重启这个 Host，再刷新页面。`dsh plugin add` 只写 profile，不会热挂正在跑的进程。
+
+给 DeepSeek Harness 的 `web_search` 换 Firecrawl，并带多账号池。包名仍是 `dsh-web-search-firecrawl`。仓库是 `dsh-firecrawl`。
+
+在 `ctx.web` 上注册 `id: firecrawl` 的 `WebSearchProvider`，走 Firecrawl `/v1/search`。调度默认 `round-robin`，也可 `least-loaded`。`429` 或 `5xx` 切到下一个健康账号，默认冷却 60 秒。不可重试的 `4xx` 立刻失败并点名那个账号。
+
+这个 bundle 会把官方 `web.searchProvider` 设成 `firecrawl`，并保留 `fetchProvider: http`。设置在 Settings → Plugins → Plugin configuration → **Firecrawl search**。
+
+面向官方 DeepSeek Harness **0.1.5-rc.3**。
+
+## 其它装法
+
+本地目录或 tarball：
+
+```sh
+dsh plugin --profile web add ./dsh-firecrawl
+dsh plugin --profile web add ./dsh-web-search-firecrawl-0.1.1.tgz
+```
+
+`dsh.bundle` 是开机捕获的。不要再往 profile 的 `cordis.patch.yml` 手写同一条 insert，会重复挂载。
+
+```sh
+dsh plugin --profile web remove dsh-web-search-firecrawl
+```
+
+## 使用
+
+1. 打开 WebUI：Settings → Plugins → Plugin configuration → **Firecrawl search**。
+2. 加至少一个 Firecrawl API key（[firecrawl.dev](https://firecrawl.dev) 的 `fc-...`），点 **保存**。密钥不会回显。改名时 key 留空表示保留原 key。
+3. 用会暴露 `web_search` 的新会话。
+
+激活时会把旧的按账号密钥迁进按账号 ID 索引的 secret dictionary。
+
+## 许可
+
+MIT。Firecrawl 服务用你自己的账号，遵守它的条款。不要把 API key 或 DSH home/profile 提交进这个仓库。

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# Official bundle layer. `dsh plugin add` applies this into the profile.
+# Rows resolve by package name so the installed copy is what boots.
+# Official `id: web` already pins searchProvider + fetchProvider; a patch
+# replaces that whole config, so both keys are restated.
+- id: web
+  config:
+    searchProvider: firecrawl
+    fetchProvider: http
+- insert:
+    - id: dsh-web-search-firecrawl
+      name: dsh-web-search-firecrawl

package/lib/client.js

@@ -0,0 +1,346 @@
+window.__ModuleLoader__.load({
+	id: "dsh-web-search-firecrawl",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let react = require("react");
+		let react_jsx_runtime = require("react/jsx-runtime");
+		//#region src/accounts.ts
+		/** Wire-safe metadata projection; never repeat any credential in an array write. */
+		function metadataOnly(accounts) {
+			return accounts.map(({ id, label }) => ({
+				id,
+				label
+			}));
+		}
+		//#endregion
+		//#region src/client/accounts-controller.ts
+		/** All edits use the namespace's revision fence and never read credential values. */
+		var AccountsController = class {
+			scope;
+			constructor(scope) {
+				this.scope = scope;
+			}
+			snapshot() {
+				const snapshot = this.scope.getSnapshot();
+				if (snapshot.status !== "ready" || !snapshot.writable) throw new Error("Settings are not writable");
+				return {
+					accounts: metadataOnly(snapshot.value?.accounts ?? []),
+					revision: snapshot.revision
+				};
+			}
+			add(id) {
+				const { accounts, revision } = this.snapshot();
+				return this.scope.mutate([{
+					op: "set",
+					path: ["accounts"],
+					value: [...accounts, {
+						id,
+						label: ""
+					}]
+				}], revision);
+			}
+			save(id, label, key) {
+				const { accounts, revision } = this.snapshot();
+				if (!accounts.some((account) => account.id === id)) throw new Error("Account was removed");
+				const ops = [{
+					op: "set",
+					path: ["accounts"],
+					value: accounts.map((account) => account.id === id ? {
+						id,
+						label
+					} : account)
+				}];
+				if (key.trim()) ops.push({
+					op: "set",
+					path: ["apiKeys", id],
+					value: key.trim()
+				});
+				return this.scope.mutate(ops, revision);
+			}
+			remove(id) {
+				const { accounts, revision } = this.snapshot();
+				return this.scope.mutate([{
+					op: "set",
+					path: ["accounts"],
+					value: accounts.filter((account) => account.id !== id)
+				}, {
+					op: "unset",
+					path: ["apiKeys", id]
+				}], revision);
+			}
+		};
+		//#endregion
+		//#region src/client/index.tsx
+		const NAMESPACE = "dsh-web-search-firecrawl";
+		const name = "dsh-web-search-firecrawl-client";
+		const inject = [
+			"slots",
+			"settingsScope",
+			"remote",
+			"remote.settings"
+		];
+		function apply(ctx) {
+			const scope = ctx.settingsScope.bind({ namespace: NAMESPACE });
+			const accounts = new AccountsController(scope);
+			ctx.slots.inject("settings.plugin.item", () => ctx.slots.register({
+				name: "settings.plugin.item",
+				key: NAMESPACE
+			}, () => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(FirecrawlCard, {
+				scope,
+				accounts,
+				ctx
+			})));
+		}
+		const inputStyle = {
+			padding: "6px 8px",
+			border: "1px solid #8886",
+			borderRadius: 6,
+			background: "transparent",
+			color: "inherit"
+		};
+		const buttonStyle = {
+			...inputStyle,
+			cursor: "pointer"
+		};
+		function AccountRow({ account, configured, busy, save, remove }) {
+			const [label, setLabel] = (0, react.useState)(account.label);
+			const [key, setKey] = (0, react.useState)("");
+			(0, react.useEffect)(() => {
+				setLabel(account.label);
+			}, [account.label]);
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("fieldset", {
+				style: {
+					border: "1px solid #8884",
+					borderRadius: 6,
+					padding: 10,
+					marginTop: 10
+				},
+				disabled: busy,
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("legend", { children: account.label || "新账号" }), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					style: {
+						display: "flex",
+						gap: 8,
+						flexWrap: "wrap",
+						alignItems: "end"
+					},
+					children: [
+						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
+							style: {
+								display: "grid",
+								gap: 4
+							},
+							children: ["名称", /* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+								"aria-label": "账号名称",
+								style: inputStyle,
+								value: label,
+								onChange: (event) => setLabel(event.target.value)
+							})]
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
+							style: {
+								display: "grid",
+								gap: 4
+							},
+							children: [
+								"API key · ",
+								configured === void 0 ? "状态待确认" : configured ? "已配置" : "未配置",
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+									"aria-label": "Firecrawl API key",
+									style: inputStyle,
+									type: "password",
+									autoComplete: "off",
+									value: key,
+									placeholder: configured ? "留空保留已有 key" : "fc-...",
+									onChange: (event) => setKey(event.target.value)
+								})
+							]
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							style: buttonStyle,
+							onClick: () => {
+								save(label, key).then(() => setKey("")).catch(() => {});
+							},
+							children: "保存"
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							style: buttonStyle,
+							onClick: remove,
+							children: "移除账号"
+						})
+					]
+				})]
+			});
+		}
+		function FirecrawlCard({ scope, accounts: controller, ctx }) {
+			const snapshot = (0, react.useSyncExternalStore)(scope.subscribe.bind(scope), scope.getSnapshot.bind(scope));
+			const [open, setOpen] = (0, react.useState)(false);
+			const [busy, setBusy] = (0, react.useState)(false);
+			const [error, setError] = (0, react.useState)("");
+			const [configured, setConfigured] = (0, react.useState)();
+			(0, react.useEffect)(() => {
+				let current = true;
+				setConfigured(void 0);
+				ctx.remote.settings.describe().then((result) => {
+					if (!current || !result.ok) return;
+					const ns = result.value.namespaces.find((item) => item.ns === NAMESPACE);
+					if (ns) setConfigured(Object.fromEntries(ns.secrets.filter((secret) => secret.path[0] === "apiKeys").map((secret) => [secret.path[1], secret.set])));
+				}).catch(() => {});
+				return () => {
+					current = false;
+				};
+			}, [snapshot.revision, ctx]);
+			if (snapshot.status !== "ready") return null;
+			const section = snapshot.value ?? {};
+			async function run(action) {
+				setBusy(true);
+				setError("");
+				try {
+					await action();
+				} catch (error) {
+					setError("保存失败，未确认写入。请重新打开设置后重试。");
+					throw error;
+				} finally {
+					setBusy(false);
+				}
+			}
+			function act(action) {
+				run(action).catch(() => {});
+			}
+			const disabled = busy || !snapshot.writable;
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("li", {
+				style: {
+					listStyle: "none",
+					border: "1px solid #8884",
+					borderRadius: 8,
+					margin: "8px 0"
+				},
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("button", {
+					style: {
+						...buttonStyle,
+						border: 0,
+						width: "100%",
+						textAlign: "left",
+						padding: 14
+					},
+					"aria-expanded": open,
+					onClick: () => setOpen(!open),
+					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("strong", { children: "Firecrawl search" }), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						style: {
+							opacity: .7,
+							fontSize: 12
+						},
+						children: ["搜索账号与负载均衡 · ", open ? "收起" : "展开"]
+					})]
+				}), open && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					style: { padding: "0 14px 14px" },
+					children: [
+						(section.accounts ?? []).map((account) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AccountRow, {
+							account,
+							configured: configured === void 0 ? void 0 : configured[account.id] === true,
+							busy: disabled,
+							save: (label, key) => run(() => controller.save(account.id, label, key)),
+							remove: () => act(() => controller.remove(account.id))
+						}, account.id)),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+							style: {
+								...buttonStyle,
+								marginTop: 10
+							},
+							disabled,
+							onClick: () => act(() => controller.add(crypto.randomUUID())),
+							children: "添加账号"
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+							style: {
+								fontSize: 12,
+								opacity: .75
+							},
+							children: "Key 只写入、不回显。填写后点“保存”；只改名称不会清除已有 key。"
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("fieldset", {
+							disabled,
+							style: {
+								border: 0,
+								padding: 0,
+								display: "flex",
+								gap: 12,
+								flexWrap: "wrap"
+							},
+							children: [
+								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", { children: ["策略 ", /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("select", {
+									"aria-label": "账号策略",
+									style: inputStyle,
+									value: section.strategy ?? "round-robin",
+									onChange: (event) => act(() => scope.set("strategy", event.target.value)),
+									children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("option", {
+										value: "round-robin",
+										children: "轮询"
+									}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("option", {
+										value: "least-loaded",
+										children: "最少使用"
+									})]
+								})] }),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", { children: ["结果数 ", /* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+									"aria-label": "搜索结果数",
+									style: {
+										...inputStyle,
+										width: 65
+									},
+									type: "number",
+									min: 1,
+									defaultValue: section.limit ?? 5,
+									onBlur: (event) => {
+										const value = Number(event.target.value);
+										if (Number.isInteger(value) && value > 0) act(() => scope.set("limit", value));
+									}
+								})] }),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", { children: ["冷却毫秒 ", /* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+									"aria-label": "冷却毫秒",
+									style: {
+										...inputStyle,
+										width: 90
+									},
+									type: "number",
+									min: 0,
+									defaultValue: section.cooldownMs ?? 6e4,
+									onBlur: (event) => {
+										const value = Number(event.target.value);
+										if (Number.isInteger(value) && value >= 0) act(() => scope.set("cooldownMs", value));
+									}
+								})] })
+							]
+						}),
+						error && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+							role: "alert",
+							children: error
+						}),
+						/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("p", {
+							style: {
+								fontSize: 12,
+								opacity: .75
+							},
+							children: [
+								"这个 bundle 会把 ",
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", { children: "web.searchProvider" }),
+								" 设为 ",
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", { children: "firecrawl" }),
+								"。加好账号后，用会暴露 ",
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", { children: "web_search" }),
+								" 的新会话。"
+							]
+						})
+					]
+				})]
+			});
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		exports.name = name;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":["useState","useSyncExternalStore"],"sources":["../src/accounts.ts","../src/client/accounts-controller.ts","../src/client/index.tsx"],"sourcesContent":["import type { FirecrawlAccount } from './provider.js'\n\n/** Legacy secrets are accepted only for migration; new writes keep them separate. */\nexport interface AccountMetadata {\n  id: string\n  label: string\n  apiKey?: string\n}\n\nexport interface AccountSettings {\n  accounts?: AccountMetadata[]\n  apiKeys?: Record<string, string>\n}\n\n/** Storage boundary: an unfinished account is not a usable credential. */\nexport function resolvedAccounts(config: AccountSettings): FirecrawlAccount[] {\n  return (config.accounts ?? []).flatMap(account => {\n    const apiKey = config.apiKeys?.[account.id] ?? account.apiKey\n    return typeof apiKey === 'string' && apiKey.trim().length > 0\n      ? [{ id: account.id, label: account.label, apiKey }]\n      : []\n  })\n}\n\n/** One atomic owner-side migration, never reconstructed from a redacted view. */\nexport function legacyAccountMigration(config: AccountSettings): AccountSettings | undefined {\n  if (!(config.accounts ?? []).some(account => account.apiKey !== undefined)) return undefined\n  const apiKeys = { ...config.apiKeys }\n  const accounts = (config.accounts ?? []).map(({ id, label, apiKey }) => {\n    if (!Object.hasOwn(apiKeys, id) && typeof apiKey === 'string' && apiKey.trim()) apiKeys[id] = apiKey\n    return { id, label }\n  })\n  return { accounts, apiKeys }\n}\n\n/** Wire-safe metadata projection; never repeat any credential in an array write. */\nexport function metadataOnly(accounts: AccountMetadata[]): { id: string; label: string }[] {\n  return accounts.map(({ id, label }) => ({ id, label }))\n}\n","import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client'\nimport type { SettingsPathOpView } from '@deepseek-ai/dsh-settings/types'\nimport { metadataOnly, type AccountSettings } from '../accounts.js'\n\n/** All edits use the namespace's revision fence and never read credential values. */\nexport class AccountsController {\n  constructor(private readonly scope: SettingsScope<AccountSettings>) {}\n\n  private snapshot() {\n    const snapshot = this.scope.getSnapshot()\n    if (snapshot.status !== 'ready' || !snapshot.writable) throw new Error('Settings are not writable')\n    return { accounts: metadataOnly(snapshot.value?.accounts ?? []), revision: snapshot.revision }\n  }\n\n  add(id: string): Promise<void> {\n    const { accounts, revision } = this.snapshot()\n    return this.scope.mutate([{ op: 'set', path: ['accounts'], value: [...accounts, { id, label: '' }] }], revision)\n  }\n\n  save(id: string, label: string, key: string): Promise<void> {\n    const { accounts, revision } = this.snapshot()\n    if (!accounts.some(account => account.id === id)) throw new Error('Account was removed')\n    const ops: SettingsPathOpView[] = [{ op: 'set', path: ['accounts'], value: accounts.map(account => account.id === id ? { id, label } : account) }]\n    if (key.trim()) ops.push({ op: 'set', path: ['apiKeys', id], value: key.trim() })\n    return this.scope.mutate(ops, revision)\n  }\n\n  remove(id: string): Promise<void> {\n    const { accounts, revision } = this.snapshot()\n    return this.scope.mutate([\n      { op: 'set', path: ['accounts'], value: accounts.filter(account => account.id !== id) },\n      { op: 'unset', path: ['apiKeys', id] },\n    ], revision)\n  }\n}\n","import { useEffect, useState, useSyncExternalStore, type ReactNode } from 'react'\nimport type { Context } from '@deepseek-ai/cordis'\nimport type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client'\nimport type {} from '@deepseek-ai/dsh-client-ui-settings-plugins/client'\nimport type {} from '@deepseek-ai/dsh-client-ui-slots'\nimport type {} from '@deepseek-ai/dsh-client-ui-renderer/client'\nimport type { SettingsDescribeValue } from '@deepseek-ai/dsh-settings/types'\nimport type {} from '@deepseek-ai/dsh-api-remotes/client'\nimport type { AccountSettings, AccountMetadata } from '../accounts.js'\nimport { AccountsController } from './accounts-controller.js'\n\nconst NAMESPACE = 'dsh-web-search-firecrawl'\ninterface Section extends AccountSettings {\n  limit?: number\n  strategy?: 'round-robin' | 'least-loaded'\n  cooldownMs?: number\n}\nexport const name = 'dsh-web-search-firecrawl-client'\nexport const inject = ['slots', 'settingsScope', 'remote', 'remote.settings']\n\nexport function apply(ctx: Context): void {\n  const scope = ctx.settingsScope.bind<Section>({ namespace: NAMESPACE })\n  const accounts = new AccountsController(scope)\n  ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({ name: 'settings.plugin.item', key: NAMESPACE },\n    () => <FirecrawlCard scope={scope} accounts={accounts} ctx={ctx} />))\n}\n\nconst inputStyle = { padding: '6px 8px', border: '1px solid #8886', borderRadius: 6, background: 'transparent', color: 'inherit' }\nconst buttonStyle = { ...inputStyle, cursor: 'pointer' }\n\nfunction AccountRow({ account, configured, busy, save, remove }: {\n  account: AccountMetadata; configured: boolean | undefined; busy: boolean\n  save: (label: string, key: string) => Promise<void>; remove: () => void\n}): ReactNode {\n  const [label, setLabel] = useState(account.label)\n  const [key, setKey] = useState('')\n  useEffect(() => { setLabel(account.label) }, [account.label])\n  return <fieldset style={{ border: '1px solid #8884', borderRadius: 6, padding: 10, marginTop: 10 }} disabled={busy}>\n    <legend>{account.label || '新账号'}</legend>\n    <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap', alignItems: 'end' }}>\n      <label style={{ display: 'grid', gap: 4 }}>名称\n        <input aria-label=\"账号名称\" style={inputStyle} value={label} onChange={event => setLabel(event.target.value)} />\n      </label>\n      <label style={{ display: 'grid', gap: 4 }}>API key · {configured === undefined ? '状态待确认' : configured ? '已配置' : '未配置'}\n        <input aria-label=\"Firecrawl API key\" style={inputStyle} type=\"password\" autoComplete=\"off\" value={key}\n          placeholder={configured ? '留空保留已有 key' : 'fc-...'} onChange={event => setKey(event.target.value)} />\n      </label>\n      <button style={buttonStyle} onClick={() => { void save(label, key).then(() => setKey('')).catch(() => {}) }}>保存</button>\n      <button style={buttonStyle} onClick={remove}>移除账号</button>\n    </div>\n  </fieldset>\n}\n\nfunction FirecrawlCard({ scope, accounts: controller, ctx }: { scope: SettingsScope<Section>; accounts: AccountsController; ctx: Context }): ReactNode {\n  const snapshot = useSyncExternalStore(scope.subscribe.bind(scope), scope.getSnapshot.bind(scope))\n  const [open, setOpen] = useState(false)\n  const [busy, setBusy] = useState(false)\n  const [error, setError] = useState('')\n  const [configured, setConfigured] = useState<Record<string, boolean> | undefined>()\n  // The API reports configured-state metadata, never credential values.\n  useEffect(() => {\n    let current = true\n    setConfigured(undefined)\n    void ctx.remote.settings.describe().then((result: { ok: true; value: SettingsDescribeValue } | { ok: false }) => {\n      if (!current || !result.ok) return\n      const ns = result.value.namespaces.find(item => item.ns === NAMESPACE)\n      if (ns) setConfigured(Object.fromEntries(ns.secrets.filter(secret => secret.path[0] === 'apiKeys').map(secret => [secret.path[1], secret.set])))\n    }).catch(() => {})\n    return () => { current = false }\n  }, [snapshot.revision, ctx])\n\n  if (snapshot.status !== 'ready') return null\n  const section = snapshot.value ?? {}\n  async function run(action: () => Promise<void>): Promise<void> {\n    setBusy(true)\n    setError('')\n    try { await action() }\n    catch (error) { setError('保存失败，未确认写入。请重新打开设置后重试。'); throw error }\n    finally { setBusy(false) }\n  }\n  function act(action: () => Promise<void>): void { void run(action).catch(() => {}) }\n  const disabled = busy || !snapshot.writable\n  return <li style={{ listStyle: 'none', border: '1px solid #8884', borderRadius: 8, margin: '8px 0' }}>\n    <button style={{ ...buttonStyle, border: 0, width: '100%', textAlign: 'left', padding: 14 }} aria-expanded={open} onClick={() => setOpen(!open)}>\n      <strong>Firecrawl search</strong><div style={{ opacity: 0.7, fontSize: 12 }}>搜索账号与负载均衡 · {open ? '收起' : '展开'}</div>\n    </button>\n    {open && <div style={{ padding: '0 14px 14px' }}>\n      {(section.accounts ?? []).map(account => <AccountRow key={account.id} account={account}\n        configured={configured === undefined ? undefined : configured[account.id] === true} busy={disabled}\n        save={(label, key) => run(() => controller.save(account.id, label, key))}\n        remove={() => act(() => controller.remove(account.id))} />)}\n      <button style={{ ...buttonStyle, marginTop: 10 }} disabled={disabled} onClick={() => act(() => controller.add(crypto.randomUUID()))}>添加账号</button>\n      <p style={{ fontSize: 12, opacity: 0.75 }}>Key 只写入、不回显。填写后点“保存”；只改名称不会清除已有 key。</p>\n      <fieldset disabled={disabled} style={{ border: 0, padding: 0, display: 'flex', gap: 12, flexWrap: 'wrap' }}>\n        <label>策略 <select aria-label=\"账号策略\" style={inputStyle} value={section.strategy ?? 'round-robin'} onChange={event => act(() => scope.set('strategy', event.target.value))}>\n          <option value=\"round-robin\">轮询</option><option value=\"least-loaded\">最少使用</option>\n        </select></label>\n        <label>结果数 <input aria-label=\"搜索结果数\" style={{ ...inputStyle, width: 65 }} type=\"number\" min={1} defaultValue={section.limit ?? 5}\n          onBlur={event => { const value = Number(event.target.value); if (Number.isInteger(value) && value > 0) act(() => scope.set('limit', value)) }} /></label>\n        <label>冷却毫秒 <input aria-label=\"冷却毫秒\" style={{ ...inputStyle, width: 90 }} type=\"number\" min={0} defaultValue={section.cooldownMs ?? 60000}\n          onBlur={event => { const value = Number(event.target.value); if (Number.isInteger(value) && value >= 0) act(() => scope.set('cooldownMs', value)) }} /></label>\n      </fieldset>\n      {error && <p role=\"alert\">{error}</p>}\n      <p style={{ fontSize: 12, opacity: 0.75 }}>这个 bundle 会把 <code>web.searchProvider</code> 设为 <code>firecrawl</code>。加好账号后，用会暴露 <code>web_search</code> 的新会话。</p>\n    </div>}\n  </li>\n}\n"],"mappings":"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"}

package/lib/dsh-web-search-firecrawl.js

@@ -0,0 +1,333 @@
+import z from "@deepseek-ai/schemastery";
+import { WebError } from "@deepseek-ai/dsh-web";
+//#region lib/types/accounts.js
+/** Storage boundary: an unfinished account is not a usable credential. */
+function resolvedAccounts(config) {
+	return (config.accounts ?? []).flatMap((account) => {
+		const apiKey = config.apiKeys?.[account.id] ?? account.apiKey;
+		return typeof apiKey === "string" && apiKey.trim().length > 0 ? [{
+			id: account.id,
+			label: account.label,
+			apiKey
+		}] : [];
+	});
+}
+/** One atomic owner-side migration, never reconstructed from a redacted view. */
+function legacyAccountMigration(config) {
+	if (!(config.accounts ?? []).some((account) => account.apiKey !== void 0)) return void 0;
+	const apiKeys = { ...config.apiKeys };
+	return {
+		accounts: (config.accounts ?? []).map(({ id, label, apiKey }) => {
+			if (!Object.hasOwn(apiKeys, id) && typeof apiKey === "string" && apiKey.trim()) apiKeys[id] = apiKey;
+			return {
+				id,
+				label
+			};
+		}),
+		apiKeys
+	};
+}
+//#endregion
+//#region lib/types/provider.js
+/**
+* Firecrawl-backed `WebSearchProvider` with a multi-account load-balanced pool.
+*
+* Firecrawl (`https://firecrawl.dev`) exposes a simple REST `/v1/search`
+* endpoint: POST `{ query, limit, ... }` with `Authorization: Bearer <key>`.
+* Each API key is rate-limited independently, so a user with several keys can
+* pool them. This provider spreads searches across the pool, fails a request
+* over to another healthy account on a rate-limit (`429`) or transient server
+* error (`5xx`), and cools an exhausted account down for a short window before
+* it is eligible again. `available()` is cheap and makes no network calls.
+*
+* The wire format and native `fetch` client are provider-private and do not use
+* `ctx.llm`.
+*
+* @module dsh-web-search-firecrawl/provider
+*/
+/** Stable id this provider registers under (`ctx.web.registerSearchProvider`). */
+const FIRECRAWL_PROVIDER_ID = "firecrawl";
+/** Default Firecrawl API base; `/v1/search` is the operation. */
+const FIRECRAWL_DEFAULT_BASE_URL = "https://api.firecrawl.dev";
+/** Default maximum search results per request. */
+const FIRECRAWL_DEFAULT_LIMIT = 5;
+/** Attribution header sent on every request. Bump with the package version. */
+const USER_AGENT = "deepseek-harness/0.0.1";
+/**
+* Map one structured Firecrawl search item to a normalized source. Blank
+* fields are omitted rather than set empty; a URL is required.
+*/
+function mapFirecrawlItem(item) {
+	if (item.url == null || item.url.length === 0) return void 0;
+	return {
+		url: item.url,
+		...item.title != null && item.title.length > 0 ? { title: item.title } : {},
+		...item.description != null && item.description.length > 0 ? { snippet: item.description } : {},
+		...item.publishedAt != null && item.publishedAt.length > 0 ? { publishedAt: item.publishedAt } : {}
+	};
+}
+/**
+* Map a Firecrawl `/v1/search` response to a normalized search result. `data[]`
+* is deduped by URL (Firecrawl may surface the same page more than once across
+* engines). The web service owns the final `maxResults` truncation, so
+* `truncated` is always `false` here.
+*
+* @param response - the parsed Firecrawl response body.
+* @returns the normalized result with deduped sources.
+*/
+function mapFirecrawlResponse(response) {
+	const seen = /* @__PURE__ */ new Set();
+	const sources = [];
+	for (const item of response.data ?? []) {
+		const source = mapFirecrawlItem(item);
+		if (source === void 0 || seen.has(source.url)) continue;
+		seen.add(source.url);
+		sources.push(source);
+	}
+	return {
+		sources,
+		truncated: false
+	};
+}
+/** True for a fetch/`AbortSignal` abort, surfaced as `WEB_ABORTED`. */
+function isAbortError(error) {
+	return error instanceof DOMException && error.name === "AbortError";
+}
+/** True for a request limit that can be sent to Firecrawl (a positive whole number). */
+function isPositiveInteger(value) {
+	return Number.isInteger(value) && value > 0;
+}
+/** Build the provider's stable cancellation error while retaining the caller's reason. */
+function searchAborted(signal, fallback) {
+	return new WebError("Firecrawl search aborted", "WEB_ABORTED", { cause: signal?.aborted === true ? signal.reason : fallback });
+}
+/** Throw the provider's stable cancellation error when the caller already aborted. */
+function throwIfSearchAborted(signal) {
+	if (signal?.aborted === true) throw searchAborted(signal);
+}
+/** Race a same-process asynchronous preflight against caller cancellation. */
+function abortable(operation, signal) {
+	if (signal === void 0) return operation;
+	if (signal.aborted) return Promise.reject(searchAborted(signal));
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			reject(searchAborted(signal));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		operation.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(new Error(String(error).replace(/^Error: /u, ""), { cause: error }));
+		});
+	});
+}
+/** Add endpoint/account recovery instructions to a provider failure. */
+function searchEndpointError(message, cause) {
+	return new WebError(`${message}\n\nThis came from the Firecrawl search provider. Check the accounts in Settings > Plugins > Plugin configuration > Firecrawl search: each saved account needs a valid Firecrawl API key, and rate-limited accounts are cooled down automatically before they are reused. Only the user should change or choose which account serves a search.`, "WEB_PROVIDER_ERROR", cause === void 0 ? void 0 : { cause });
+}
+/**
+* The Firecrawl-backed search provider. Spreads work across a pool of accounts,
+* failing a rate-limited or server-erroring account over to the next healthy
+* one and cooling the exhausted account down for {@link FirecrawlSearchProviderOptions.cooldownMs}.
+*/
+var FirecrawlSearchProvider = class {
+	resolveOptions;
+	id = FIRECRAWL_PROVIDER_ID;
+	slots = [];
+	next = 0;
+	/**
+	* @param resolveOptions - the options for the NEXT operation, snapshotted
+	* once at each operation's entry so one search never mixes two settings
+	* sections. A thunk rather than a value because the settings section can
+	* change between searches, and re-registering the provider to carry a new
+	* account pool would make the seam's selection observable as a flicker.
+	*/
+	constructor(resolveOptions) {
+		this.resolveOptions = resolveOptions;
+	}
+	/** Cheap local usability check; makes no network calls. */
+	available() {
+		const options = this.resolveOptions();
+		return options.accounts.some((account) => account.apiKey.length > 0) && URL.canParse(options.baseURL) && isPositiveInteger(options.limit) && Number.isInteger(options.cooldownMs) && options.cooldownMs >= 0;
+	}
+	async search(request, signal) {
+		const options = this.resolveOptions();
+		throwIfSearchAborted(signal);
+		const slots = this.syncSlots(options);
+		if (slots.length === 0) throw new WebError("Firecrawl search has no accounts configured; add at least one Firecrawl API key through Settings > Plugins > Plugin configuration > Firecrawl search, or set the dsh-web-search-firecrawl config", "WEB_PROVIDER_CREDENTIAL_MISSING");
+		const endpoint = `${options.baseURL}/v1/search`;
+		const body = {
+			query: request.query,
+			...request.maxResults !== void 0 ? { limit: Math.min(request.maxResults, options.limit) } : { limit: options.limit }
+		};
+		const ordered = this.orderCandidates(slots, options.strategy);
+		const attempts = [];
+		let lastError;
+		for (const account of ordered) {
+			throwIfSearchAborted(signal);
+			let response;
+			try {
+				response = await abortable(fetch(endpoint, {
+					method: "POST",
+					redirect: "error",
+					headers: {
+						"authorization": `Bearer ${account.account.apiKey}`,
+						"content-type": "application/json",
+						"accept": "application/json",
+						"user-agent": USER_AGENT
+					},
+					body: JSON.stringify(body),
+					...signal !== void 0 ? { signal } : {}
+				}), signal);
+			} catch (error) {
+				if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+				lastError = error;
+				account.lastStatus = 0;
+				account.uses += 1;
+				this.startCooldown(account, options.cooldownMs);
+				continue;
+			}
+			account.lastStatus = response.status;
+			account.uses += 1;
+			if (response.ok) try {
+				return mapFirecrawlResponse(await response.json());
+			} catch (error) {
+				if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+				throw searchEndpointError(error instanceof WebError ? error.message : `Firecrawl returned an unprocessable response body: ${String(error)}`, error);
+			}
+			attempts.push({
+				response,
+				account,
+				endpoint
+			});
+			if (response.status === 429 || response.status >= 500) {
+				this.startCooldown(account, options.cooldownMs);
+				continue;
+			}
+			const message = await this.errorMessage(response, signal);
+			throw searchEndpointError(`Firecrawl API error (HTTP ${response.status}) for account "${this.label(account.account)}"${message.length > 0 ? `: ${message}` : ""}`);
+		}
+		if (attempts.length === 0) throw searchEndpointError(`Firecrawl search request failed: ${String(lastError ?? "no accounts could be reached")}`, lastError);
+		const last = attempts[attempts.length - 1];
+		const message = await this.errorMessage(last.response, signal);
+		throw searchEndpointError(`Firecrawl search failed after trying ${attempts.length} account(s); last attempt was HTTP ${last.response.status}${message.length > 0 ? `: ${message}` : ""}`);
+	}
+	/** Reconcile the persistent slot table with the latest snapshot's accounts. */
+	syncSlots(options) {
+		const byId = new Map(this.slots.map((slot) => [slot.account.id, slot]));
+		this.slots = options.accounts.map((account) => {
+			const existing = byId.get(account.id);
+			if (existing !== void 0) {
+				existing.account = account;
+				return existing;
+			}
+			return {
+				account,
+				uses: 0,
+				cooledUntil: 0,
+				lastStatus: 0
+			};
+		});
+		return this.slots;
+	}
+	/**
+	* Order candidate accounts for this operation: healthy ones first (in
+	* strategy order), then cooling-down ones, so a small exhausted pool still
+	* degrades gracefully.
+	*/
+	orderCandidates(slots, strategy) {
+		const now = Date.now();
+		const healthy = slots.filter((slot) => slot.cooledUntil <= now);
+		const cooling = slots.filter((slot) => slot.cooledUntil > now);
+		if (strategy === "least-loaded") {
+			healthy.sort((a, b) => a.uses - b.uses);
+			cooling.sort((a, b) => a.uses - b.uses);
+		} else if (healthy.length > 0) {
+			this.next = this.next % healthy.length;
+			const rotated = healthy.slice(this.next).concat(healthy.slice(0, this.next));
+			this.next = (this.next + 1) % healthy.length;
+			return rotated.concat(cooling);
+		}
+		return healthy.concat(cooling);
+	}
+	/** Put one account in cooldown (or extend an existing cooldown) for `cooldownMs`. */
+	startCooldown(slot, cooldownMs) {
+		const until = Date.now() + cooldownMs;
+		slot.cooledUntil = Math.max(slot.cooledUntil, until);
+	}
+	label(account) {
+		return account.label !== void 0 && account.label.length > 0 ? account.label : account.id;
+	}
+	/** Extract a human-readable message from a non-ok error body, honoring abort. */
+	async errorMessage(response, signal) {
+		try {
+			const parsed = await response.json();
+			return parsed.error ?? parsed.message ?? "";
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+			return "";
+		}
+	}
+};
+//#endregion
+//#region lib/types/dsh-web-search-firecrawl.js
+/**
+* Firecrawl-backed search provider for the DeepSeek Harness web capability
+* seam (`ctx.web`). Unlike the bundled DeepSeek search, which only accepts the
+* DeepSeek API key, this plugin lets the user bring their own Firecrawl
+* account(s) and load-balances across a pool of Firecrawl API keys.
+*
+* Two halves, one package:
+* - Host half (this file): registers the {@link FirecrawlSearchProvider} on
+*   `ctx.web` and a `settings` section so accounts are manageable.
+* - Browser half (`src/client/`): a `settings.plugin.item` card that adds,
+*   edits, and removes accounts and tunes pool behavior.
+*
+* @module dsh-web-search-firecrawl
+*/
+/** Cordis plugin name used by loader diagnostics. */
+const name = "dsh-web-search-firecrawl";
+/** The web seam this provider registers into. */
+const inject = ["web"];
+/** Default cooldown for a rate-limited account (one minute). */
+const DEFAULT_COOLDOWN_MS = 6e4;
+/** Settings namespace carrying this provider's accounts and pool options. */
+const FIRECRAWL_SETTINGS_NAMESPACE = "dsh-web-search-firecrawl";
+const Config = z.object({
+	accounts: z.array(z.object({
+		id: z.string(),
+		label: z.string(),
+		apiKey: z.string().role("secret")
+	})),
+	apiKeys: z.dict(z.string().role("secret")),
+	baseURL: z.string(),
+	limit: z.number().step(1).min(1),
+	strategy: z.union(["round-robin", "least-loaded"]),
+	cooldownMs: z.number().step(1).min(0)
+});
+/** Project one resolved section into the options the provider serves next. */
+function resolveOptions(config) {
+	return {
+		accounts: resolvedAccounts(config),
+		baseURL: config.baseURL ?? "https://api.firecrawl.dev",
+		limit: config.limit ?? 5,
+		strategy: config.strategy ?? "round-robin",
+		cooldownMs: config.cooldownMs ?? DEFAULT_COOLDOWN_MS
+	};
+}
+/** Register the Firecrawl search provider with `ctx.web` and its settings section. */
+function apply(ctx, config) {
+	console.log("[my-plugins/dsh-web-search-firecrawl] loaded");
+	let current = () => config;
+	ctx.inject(["settings"], async (settingsCtx) => {
+		const scope = settingsCtx.settings.register(FIRECRAWL_SETTINGS_NAMESPACE, Config, { base: config });
+		const migration = legacyAccountMigration(scope.get());
+		if (migration !== void 0) await scope.update(migration);
+		current = () => scope.get();
+	});
+	ctx.web.registerSearchProvider(new FirecrawlSearchProvider(() => resolveOptions(current())));
+}
+//#endregion
+export { Config, FIRECRAWL_DEFAULT_BASE_URL, FIRECRAWL_DEFAULT_LIMIT, FIRECRAWL_PROVIDER_ID, FIRECRAWL_SETTINGS_NAMESPACE, FirecrawlSearchProvider, apply, inject, name };

package/lib/types/accounts.d.ts

@@ -0,0 +1,21 @@
+import type { FirecrawlAccount } from './provider.js';
+/** Legacy secrets are accepted only for migration; new writes keep them separate. */
+export interface AccountMetadata {
+    id: string;
+    label: string;
+    apiKey?: string;
+}
+export interface AccountSettings {
+    accounts?: AccountMetadata[];
+    apiKeys?: Record<string, string>;
+}
+/** Storage boundary: an unfinished account is not a usable credential. */
+export declare function resolvedAccounts(config: AccountSettings): FirecrawlAccount[];
+/** One atomic owner-side migration, never reconstructed from a redacted view. */
+export declare function legacyAccountMigration(config: AccountSettings): AccountSettings | undefined;
+/** Wire-safe metadata projection; never repeat any credential in an array write. */
+export declare function metadataOnly(accounts: AccountMetadata[]): {
+    id: string;
+    label: string;
+}[];
+//# sourceMappingURL=accounts.d.ts.map

package/lib/types/client/accounts-controller.d.ts

@@ -0,0 +1,12 @@
+import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+import { type AccountSettings } from '../accounts.js';
+/** All edits use the namespace's revision fence and never read credential values. */
+export declare class AccountsController {
+    private readonly scope;
+    constructor(scope: SettingsScope<AccountSettings>);
+    private snapshot;
+    add(id: string): Promise<void>;
+    save(id: string, label: string, key: string): Promise<void>;
+    remove(id: string): Promise<void>;
+}
+//# sourceMappingURL=accounts-controller.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "dsh-web-search-firecrawl-client";
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/dsh-web-search-firecrawl.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Firecrawl-backed search provider for the DeepSeek Harness web capability
+ * seam (`ctx.web`). Unlike the bundled DeepSeek search, which only accepts the
+ * DeepSeek API key, this plugin lets the user bring their own Firecrawl
+ * account(s) and load-balances across a pool of Firecrawl API keys.
+ *
+ * Two halves, one package:
+ * - Host half (this file): registers the {@link FirecrawlSearchProvider} on
+ *   `ctx.web` and a `settings` section so accounts are manageable.
+ * - Browser half (`src/client/`): a `settings.plugin.item` card that adds,
+ *   edits, and removes accounts and tunes pool behavior.
+ *
+ * @module dsh-web-search-firecrawl
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { type AccountSettings } from './accounts.js';
+import { type FirecrawlPoolStrategy } from './provider.js';
+export { FIRECRAWL_DEFAULT_BASE_URL, FIRECRAWL_DEFAULT_LIMIT, FIRECRAWL_PROVIDER_ID, FirecrawlSearchProvider, } from './provider.js';
+export type { FirecrawlAccount, FirecrawlPoolStrategy, FirecrawlSearchProviderOptions, } from './provider.ts';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "dsh-web-search-firecrawl";
+/** The web seam this provider registers into. */
+export declare const inject: string[];
+/** Settings namespace carrying this provider's accounts and pool options. */
+export declare const FIRECRAWL_SETTINGS_NAMESPACE = "dsh-web-search-firecrawl";
+/** Plugin config (all optional — `apply` fills defaults). */
+export interface Config extends AccountSettings {
+    /** Load-balanced pool of Firecrawl accounts (each is one API key). */
+    /** Endpoint base; `/v1/search` is appended. Defaults to the public API. */
+    baseURL?: string;
+    /** Maximum search results requested per search. Defaults to 5. */
+    limit?: number;
+    /** Pool scheduling: round-robin (default) or least-loaded. */
+    strategy?: FirecrawlPoolStrategy;
+    /** How long a rate-limited account stays cooled down, in ms. */
+    cooldownMs?: number;
+}
+export declare const Config: z<Config>;
+/** Register the Firecrawl search provider with `ctx.web` and its settings section. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=dsh-web-search-firecrawl.d.ts.map

package/lib/types/provider.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Firecrawl-backed `WebSearchProvider` with a multi-account load-balanced pool.
+ *
+ * Firecrawl (`https://firecrawl.dev`) exposes a simple REST `/v1/search`
+ * endpoint: POST `{ query, limit, ... }` with `Authorization: Bearer <key>`.
+ * Each API key is rate-limited independently, so a user with several keys can
+ * pool them. This provider spreads searches across the pool, fails a request
+ * over to another healthy account on a rate-limit (`429`) or transient server
+ * error (`5xx`), and cools an exhausted account down for a short window before
+ * it is eligible again. `available()` is cheap and makes no network calls.
+ *
+ * The wire format and native `fetch` client are provider-private and do not use
+ * `ctx.llm`.
+ *
+ * @module dsh-web-search-firecrawl/provider
+ */
+import type { WebSearchProvider, WebSearchRequest, WebSearchResult, WebSearchSource } from '@deepseek-ai/dsh-web';
+/** Stable id this provider registers under (`ctx.web.registerSearchProvider`). */
+export declare const FIRECRAWL_PROVIDER_ID = "firecrawl";
+/** Default Firecrawl API base; `/v1/search` is the operation. */
+export declare const FIRECRAWL_DEFAULT_BASE_URL = "https://api.firecrawl.dev";
+/** Default maximum search results per request. */
+export declare const FIRECRAWL_DEFAULT_LIMIT = 5;
+/** Default pool scheduling strategy: strict round-robin across healthy accounts. */
+export type FirecrawlPoolStrategy = 'round-robin' | 'least-loaded';
+/**
+ * One Firecrawl account. A pool needs at least one account to serve a search;
+ * each account is an independent API key with its own rate limit.
+ */
+export interface FirecrawlAccount {
+    /** Stable, user-assigned id (used as the credential's display label fallback). */
+    id: string;
+    /** Optional human-readable label shown in the settings card. */
+    label?: string;
+    /** The Firecrawl API key (kept secret; never logged or echoed). */
+    apiKey: string;
+}
+/** Resolved provider options (the plugin's `apply` supplies defaults). */
+export interface FirecrawlSearchProviderOptions {
+    /** The load-balanced pool of accounts. */
+    accounts: readonly FirecrawlAccount[];
+    /** Endpoint base; `/v1/search` is appended. */
+    baseURL: string;
+    /** Maximum results requested per search; defaulted before this point. */
+    limit: number;
+    /** How the next account is chosen: round-robin or least-recently-used. */
+    strategy: FirecrawlPoolStrategy;
+    /** How long an exhausted (rate-limited) account stays cooled down, in ms. */
+    cooldownMs: number;
+}
+/** A Firecrawl `/v1/search` result item (`data[]`). */
+interface FirecrawlSearchItem {
+    url?: string;
+    title?: string | null;
+    description?: string | null;
+    /** Search engines may surface a recency/publish string; mapped to `publishedAt`. */
+    publishedAt?: string | null;
+}
+/** A Firecrawl `/v1/search` response envelope (best-effort; fields vary by API version). */
+interface FirecrawlSearchResponse {
+    success?: boolean;
+    data?: FirecrawlSearchItem[];
+    error?: string;
+}
+/**
+ * Map one structured Firecrawl search item to a normalized source. Blank
+ * fields are omitted rather than set empty; a URL is required.
+ */
+export declare function mapFirecrawlItem(item: FirecrawlSearchItem): WebSearchSource | undefined;
+/**
+ * Map a Firecrawl `/v1/search` response to a normalized search result. `data[]`
+ * is deduped by URL (Firecrawl may surface the same page more than once across
+ * engines). The web service owns the final `maxResults` truncation, so
+ * `truncated` is always `false` here.
+ *
+ * @param response - the parsed Firecrawl response body.
+ * @returns the normalized result with deduped sources.
+ */
+export declare function mapFirecrawlResponse(response: FirecrawlSearchResponse): WebSearchResult;
+/**
+ * The Firecrawl-backed search provider. Spreads work across a pool of accounts,
+ * failing a rate-limited or server-erroring account over to the next healthy
+ * one and cooling the exhausted account down for {@link FirecrawlSearchProviderOptions.cooldownMs}.
+ */
+export declare class FirecrawlSearchProvider implements WebSearchProvider {
+    private readonly resolveOptions;
+    readonly id = "firecrawl";
+    private slots;
+    private next;
+    /**
+     * @param resolveOptions - the options for the NEXT operation, snapshotted
+     * once at each operation's entry so one search never mixes two settings
+     * sections. A thunk rather than a value because the settings section can
+     * change between searches, and re-registering the provider to carry a new
+     * account pool would make the seam's selection observable as a flicker.
+     */
+    constructor(resolveOptions: () => FirecrawlSearchProviderOptions);
+    /** Cheap local usability check; makes no network calls. */
+    available(): boolean;
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+    /** Reconcile the persistent slot table with the latest snapshot's accounts. */
+    private syncSlots;
+    /**
+     * Order candidate accounts for this operation: healthy ones first (in
+     * strategy order), then cooling-down ones, so a small exhausted pool still
+     * degrades gracefully.
+     */
+    private orderCandidates;
+    /** Put one account in cooldown (or extend an existing cooldown) for `cooldownMs`. */
+    private startCooldown;
+    private label;
+    /** Extract a human-readable message from a non-ok error body, honoring abort. */
+    private errorMessage;
+}
+export {};
+//# sourceMappingURL=provider.d.ts.map

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "dsh-web-search-firecrawl",
+  "version": "0.1.1",
+  "description": "Firecrawl search provider and multi-account settings for DeepSeek Harness",
+  "repository": { "type": "git", "url": "https://github.com/aa2246740/dsh-firecrawl.git" },
+  "homepage": "https://github.com/aa2246740/dsh-firecrawl#readme",
+  "bugs": { "url": "https://github.com/aa2246740/dsh-firecrawl/issues" },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "firecrawl",
+    "web-search"
+  ],
+  "type": "module",
+  "main": "lib/dsh-web-search-firecrawl.js",
+  "types": "lib/types/dsh-web-search-firecrawl.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm build && node --test tests/*.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/types/dsh-web-search-firecrawl.d.ts",
+      "default": "./lib/dsh-web-search-firecrawl.js"
+    },
+    "./client": "./lib/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings-plugins"
+      ],
+      "platform": "web"
+    }
+  },
+  "files": [
+    "lib/*.js",
+    "lib/*.js.map",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.5-rc.3",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.5-rc.3",
+    "@deepseek-ai/dsh-settings": "^0.1.5-rc.3",
+    "@deepseek-ai/dsh-web": "^0.1.5-rc.3",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.5-rc.3",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.3",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.5-rc.3",
+    "@deepseek-ai/dsh-scope": "^0.1.5-rc.3",
+    "@deepseek-ai/dsh-invariants": "^0.1.5-rc.3",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.5-rc.3",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.5-rc.3",
+    "@deepseek-ai/dsh-settings": "^0.1.5-rc.3",
+    "@deepseek-ai/dsh-web": "^0.1.5-rc.3",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3"
+  }
+}