@moguiyu/dsh-tavily 0.1.10 → 0.1.12

package/README.md

@@ -1,18 +1,27 @@
-# @moguiyu/dsh-tool-tavily-search
+# @moguiyu/dsh-tavily
 
-Registers the `tavily_search` model tool and the **Tavily Search** settings card for the
-DeepSeek Harness web UI.
+Combined plugin: the opt-in advanced `tavily_search` model tool, the **Tavily Search**
+settings card, and the local HTTP backend for key/usage management.
 
 - **`tavily_search`** — full Tavily surface (`max_results`, `search_depth`, `topic`, `days`,
-  `include_answer`, `include_raw_content`, `include_domains`, `exclude_domains`). Keys are
-  resolved from the `TAVILY_API_KEYS` credential on every call; round-robin rotation with
-  failover on HTTP 401/429.
-- **Settings card** (`settings.plugin.item`, id `tavily-search`) — expandable card matching
-  the native plugin-config design: flat key list (masked values, saved dates, show/edit/delete
-  icons), key-usage strategy selector, usage gauge, and the on/off switch for the `web`
-  provider.
+  `include_answer`, `include_raw_content`, `include_domains`, `exclude_domains`). Opt-in and
+  off by default.
+- **Settings card** — key list, usage gauge, strategy selector, and the advanced-tool switch.
+- **Plugin-config settings card** — the Host registers the `tavily-search` settings namespace
+  and the card is keyed by it (keyed `settings.plugin.item`), so the Plugins configuration tab
+  serves the card exactly when this plugin is composed (needs DSH **0.1.0-rc.7 or newer**).
+  The switch writes the namespace and restarts the row; the choice is mirrored to
+  `~/.dsh/tavily-tool.json`.
+- **`web_search` is never replaced** — no `ctx.web` provider is registered and
+  `web.searchProvider` is never rewritten; the built-in DeepSeek `web_search` keeps its
+  native provider and schema. Tavily is an extra, opt-in search option.
 
 Host half: plain ESM (`src/index.js`). Client half: prebuilt `window.__ModuleLoader__` bundle
 at `lib/client.js`, generated from `src/client.js` via `pnpm build`.
 
+The host half composes the two standalone packages instead of carrying a second copy of the
+implementation: the tool comes from [`@moguiyu/dsh-tool-tavily-search`](../dsh-tool-tavily-search)
+and the routes/switch pipeline from [`@moguiyu/dsh-tavily-backend`](../dsh-tavily-backend).
+Both are regular dependencies, installed automatically with this package.
+
 See the [workspace README](../../README.md) for install and configuration.

package/lib/client.js

@@ -97,7 +97,7 @@ window.__ModuleLoader__.load({
 
     const refresh = react.useCallback(async () => {
       try {
-        const response = await fetch('/api/tavily-toggle', { cache: 'no-store' })
+        const response = await fetch('/api/tavily-tool', { cache: 'no-store' })
         const data = await response.json()
         if (data.ok) { setEnabled(data.enabled); setLoadError(null) } else { setLoadError(data.error || 'Failed to load settings') }
       } catch (error) {
@@ -127,7 +127,7 @@ window.__ModuleLoader__.load({
       setBusy(true)
       setNotice(null)
       try {
-        const response = await fetch('/api/tavily-toggle', {
+        const response = await fetch('/api/tavily-tool', {
           method: 'POST',
           headers: { 'content-type': 'application/json' },
           body: JSON.stringify({ enabled: next })
@@ -135,7 +135,7 @@ window.__ModuleLoader__.load({
         const data = await response.json()
         if (!data.ok) { setNotice({ error: data.error || 'Switch failed' }); return }
         setEnabled(data.enabled)
-        setNotice({ ok: data.enabled ? 'Tavily search enabled — web_search uses Tavily.' : 'Tavily search off — web_search uses the native provider (DeepSeek). No Tavily key is needed.' })
+        setNotice({ ok: data.enabled ? 'Advanced tavily_search tool enabled.' : 'Advanced tavily_search tool disabled — built-in web_search is unchanged.' })
       } catch (error) {
         setNotice({ error: String(error && error.message ? error.message : error) })
       } finally {
@@ -295,10 +295,10 @@ window.__ModuleLoader__.load({
           style: { flex: 1, minWidth: 0, textAlign: 'left', background: 'none', border: 'none', padding: 0, cursor: 'pointer', display: 'flex', flexDirection: 'column', gap: 2, font: 'inherit', color: 'inherit' }
         },
           react.createElement('strong', { style: { fontSize: 14, fontWeight: 600, lineHeight: '20px', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' } }, 'Tavily Search'),
-          react.createElement('span', { style: { fontSize: 12, lineHeight: '16px', color: 'var(--dsw-alias-label-tertiary)', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' } }, 'Tavily-backed web_search · key rotation · usage')
+          react.createElement('span', { style: { fontSize: 12, lineHeight: '16px', color: 'var(--dsw-alias-label-tertiary)', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' } }, 'Advanced tavily_search tool · key rotation · usage')
         ),
         react.createElement('span', { style: { display: 'inline-flex', alignItems: 'center', gap: 6, flex: 'none' } },
-          react.createElement(Switch, { checked: enabled, disabled: busy, label: 'Tavily search enabled', onChange: toggleEnabled }),
+          react.createElement(Switch, { checked: enabled, disabled: busy, label: 'Advanced tavily_search tool enabled', onChange: toggleEnabled }),
           react.createElement('button', {
             type: 'button',
             className: 'dts-icon-btn',
@@ -316,11 +316,11 @@ window.__ModuleLoader__.load({
       expanded && react.createElement('div', { style: { borderTop: '1px solid var(--dsw-alias-border-l2)', padding: '12px 14px', display: 'flex', flexDirection: 'column', gap: 16 } },
         isOff
           ? react.createElement('p', { style: { margin: 0, fontSize: 13, color: 'var(--dsw-alias-label-tertiary)' } },
-              'Tavily search is off — web_search uses the native provider (DeepSeek). No Tavily key is needed.'
+              'The advanced tavily_search tool is off. The built-in web_search keeps its native provider and is never replaced.'
             )
           : react.createElement(react.Fragment, null,
               react.createElement('p', { style: { margin: 0, fontSize: 13, color: 'var(--dsw-alias-label-tertiary)' } },
-                'All keys are listed below; the key marked with the green dot is the primary key used by web_search. The tavily_search tool uses all keys according to the strategy. Changes take effect on the next search.'
+                'All keys are listed below; the green dot marks the first (primary) key. The tavily_search tool uses all keys according to the strategy. Built-in web_search is unaffected.'
               ),
               loadError !== null && react.createElement('p', { style: { margin: 0, fontSize: 12, color: 'var(--dsw-alias-state-error-primary)' } }, String(loadError)),
               react.createElement('table', { style: { width: '100%', borderCollapse: 'collapse', fontSize: 13 } },
@@ -357,7 +357,7 @@ window.__ModuleLoader__.load({
                           : react.createElement('span', null,
                               isRevealed ? revealed[masked] : masked,
                               key.primary === true && !isRemoved && react.createElement('span', {
-                                title: 'Primary — used by web_search',
+                                title: 'Primary — the first key in the rotation',
                                 style: { display: 'inline-block', width: 8, height: 8, borderRadius: 4, background: 'var(--dsw-alias-state-success-primary)', marginLeft: 8, verticalAlign: 'middle', flex: 'none' }
                               })
                             )
@@ -437,6 +437,11 @@ window.__ModuleLoader__.load({
   function apply(ctx) {
     ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({
       name: 'settings.plugin.item',
+      // rc.7 plugin management: this card is keyed by the settings namespace
+      // the Host serves (`tavily-search`); the Plugins configuration tab
+      // dispatches it when the namespace is present. The id/order/label props
+      // keep rc.6 list-slot deployments rendering the card as well.
+      key: 'tavily-search',
       id: 'tavily-search',
       order: 30,
       label: 'Tavily Search'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@moguiyu/dsh-tavily",
-  "version": "0.1.10",
-  "description": "Tavily Search for DSH: multiple API keys, rotation/failover, usage gauge, settings card, and web_search toggle in one plugin.",
+  "version": "0.1.12",
+  "description": "Opt-in advanced tavily_search tool for DeepSeek Harness with the Tavily Search settings card (rc.8 plugin management). The built-in web_search is never replaced.",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
@@ -30,7 +30,8 @@
       "platform": "web",
       "inject": [
         "@deepseek-ai/dsh-client-runtime",
-        "@deepseek-ai/dsh-client-ui-settings"
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-settings-plugins"
       ]
     }
   },
@@ -52,7 +53,17 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.8"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@moguiyu/dsh-tavily-backend": "^0.1.12",
+    "@moguiyu/dsh-tool-tavily-search": "^0.1.12"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.8"
   }
 }

package/src/client.js

@@ -102,7 +102,7 @@ export function factory(require) {
 
     const refresh = react.useCallback(async () => {
       try {
-        const response = await fetch('/api/tavily-toggle', { cache: 'no-store' })
+        const response = await fetch('/api/tavily-tool', { cache: 'no-store' })
         const data = await response.json()
         if (data.ok) { setEnabled(data.enabled); setLoadError(null) } else { setLoadError(data.error || 'Failed to load settings') }
       } catch (error) {
@@ -132,7 +132,7 @@ export function factory(require) {
       setBusy(true)
       setNotice(null)
       try {
-        const response = await fetch('/api/tavily-toggle', {
+        const response = await fetch('/api/tavily-tool', {
           method: 'POST',
           headers: { 'content-type': 'application/json' },
           body: JSON.stringify({ enabled: next })
@@ -140,7 +140,7 @@ export function factory(require) {
         const data = await response.json()
         if (!data.ok) { setNotice({ error: data.error || 'Switch failed' }); return }
         setEnabled(data.enabled)
-        setNotice({ ok: data.enabled ? 'Tavily search enabled — web_search uses Tavily.' : 'Tavily search off — web_search uses the native provider (DeepSeek). No Tavily key is needed.' })
+        setNotice({ ok: data.enabled ? 'Advanced tavily_search tool enabled.' : 'Advanced tavily_search tool disabled — built-in web_search is unchanged.' })
       } catch (error) {
         setNotice({ error: String(error && error.message ? error.message : error) })
       } finally {
@@ -300,10 +300,10 @@ export function factory(require) {
           style: { flex: 1, minWidth: 0, textAlign: 'left', background: 'none', border: 'none', padding: 0, cursor: 'pointer', display: 'flex', flexDirection: 'column', gap: 2, font: 'inherit', color: 'inherit' }
         },
           react.createElement('strong', { style: { fontSize: 14, fontWeight: 600, lineHeight: '20px', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' } }, 'Tavily Search'),
-          react.createElement('span', { style: { fontSize: 12, lineHeight: '16px', color: 'var(--dsw-alias-label-tertiary)', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' } }, 'Tavily-backed web_search · key rotation · usage')
+          react.createElement('span', { style: { fontSize: 12, lineHeight: '16px', color: 'var(--dsw-alias-label-tertiary)', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' } }, 'Advanced tavily_search tool · key rotation · usage')
         ),
         react.createElement('span', { style: { display: 'inline-flex', alignItems: 'center', gap: 6, flex: 'none' } },
-          react.createElement(Switch, { checked: enabled, disabled: busy, label: 'Tavily search enabled', onChange: toggleEnabled }),
+          react.createElement(Switch, { checked: enabled, disabled: busy, label: 'Advanced tavily_search tool enabled', onChange: toggleEnabled }),
           react.createElement('button', {
             type: 'button',
             className: 'dts-icon-btn',
@@ -321,11 +321,11 @@ export function factory(require) {
       expanded && react.createElement('div', { style: { borderTop: '1px solid var(--dsw-alias-border-l2)', padding: '12px 14px', display: 'flex', flexDirection: 'column', gap: 16 } },
         isOff
           ? react.createElement('p', { style: { margin: 0, fontSize: 13, color: 'var(--dsw-alias-label-tertiary)' } },
-              'Tavily search is off — web_search uses the native provider (DeepSeek). No Tavily key is needed.'
+              'The advanced tavily_search tool is off. The built-in web_search keeps its native provider and is never replaced.'
             )
           : react.createElement(react.Fragment, null,
               react.createElement('p', { style: { margin: 0, fontSize: 13, color: 'var(--dsw-alias-label-tertiary)' } },
-                'All keys are listed below; the key marked with the green dot is the primary key used by web_search. The tavily_search tool uses all keys according to the strategy. Changes take effect on the next search.'
+                'All keys are listed below; the green dot marks the first (primary) key. The tavily_search tool uses all keys according to the strategy. Built-in web_search is unaffected.'
               ),
               loadError !== null && react.createElement('p', { style: { margin: 0, fontSize: 12, color: 'var(--dsw-alias-state-error-primary)' } }, String(loadError)),
               react.createElement('table', { style: { width: '100%', borderCollapse: 'collapse', fontSize: 13 } },
@@ -362,7 +362,7 @@ export function factory(require) {
                           : react.createElement('span', null,
                               isRevealed ? revealed[masked] : masked,
                               key.primary === true && !isRemoved && react.createElement('span', {
-                                title: 'Primary — used by web_search',
+                                title: 'Primary — the first key in the rotation',
                                 style: { display: 'inline-block', width: 8, height: 8, borderRadius: 4, background: 'var(--dsw-alias-state-success-primary)', marginLeft: 8, verticalAlign: 'middle', flex: 'none' }
                               })
                             )
@@ -442,6 +442,11 @@ export function factory(require) {
   function apply(ctx) {
     ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({
       name: 'settings.plugin.item',
+      // rc.7 plugin management: this card is keyed by the settings namespace
+      // the Host serves (`tavily-search`); the Plugins configuration tab
+      // dispatches it when the namespace is present. The id/order/label props
+      // keep rc.6 list-slot deployments rendering the card as well.
+      key: 'tavily-search',
       id: 'tavily-search',
       order: 30,
       label: 'Tavily Search'

package/src/index.js

@@ -1,592 +1,110 @@
 /**
- * `@moguiyu/dsh-tavily` combined host half: `tavily_search` model tool plus
- * the local HTTP backend for usage, key management, and the web provider toggle.
+ * `@moguiyu/dsh-tavily` combined package: the advanced `tavily_search` model
+ * tool plus the local HTTP backend for usage and key management. The
+ * implementations live in the two standalone packages and are composed here,
+ * so there is exactly one copy of each:
+ *
+ * - tool half — `@moguiyu/dsh-tool-tavily-search` {@link installTavilyTool};
+ * - backend half — `@moguiyu/dsh-tavily-backend` {@link installBackend}.
+ *
+ * This package adds the rc.7 plugin-management seam: the Host registers the
+ * `tavily-search` settings namespace (the key the Plugins configuration tab
+ * pairs the card against). The switch value lives both in that namespace and
+ * in `~/.dsh/tavily-tool.json`; every write path converges on
+ * `settings.update` (or the state file when no settings service exists),
+ * persisted first, then the row restarts itself so the tool registers or
+ * unregisters cleanly.
+ *
+ * The settings-card switch controls ONLY the opt-in `tavily_search` tool. The
+ * built-in `web_search` tool is never replaced: this package registers no web
+ * search provider and never rewrites `web.searchProvider` — `web_search`
+ * keeps its native provider.
  */
-import { readFileSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { resolveDshHome } from '@deepseek-ai/dsh-home-paths'
-import { defineTool } from '@deepseek-ai/dsh-tools'
-import { STRATEGIES, isValidStrategy, maskValue, parseKeyList, orderKeys, readJsonFile } from './lib.js'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import z from '@deepseek-ai/schemastery'
+import { isToolEnabled, installTavilyTool } from '@moguiyu/dsh-tool-tavily-search'
+import { installBackend, readToolState, restoreToolState, writeToolState } from '@moguiyu/dsh-tavily-backend'
 
 export const name = 'dsh-tavily'
 
-export const inject = ['tools', 'webServer', 'credentials']
+export const inject = ['tools', 'webServer', 'credentials', 'systemPrompt', 'loader']
 
-const USAGE_TTL_MS = 60000
-const usageCache = new Map()
+export const Config = z.object({
+  enabled: z.boolean().default(false),
+})
 
-/** Clamp a number into [min, max]; `fallback` when not finite. */
-export function clampInt(value, min, max, fallback) {
-  const n = Number(value)
-  if (!Number.isFinite(n)) return fallback
-  return Math.min(max, Math.max(min, Math.round(n)))
-}
-
-/** Normalize and validate model arguments (exported for tests). */
-export function normalizeArgs(args) {
-  const query = typeof args.query === 'string' ? args.query.trim() : ''
-  if (query.length === 0) throw new Error('tavily_search: query must be a non-empty string')
-  const maxResults = clampInt(args.max_results, 1, 20, 5)
-  const searchDepth = args.search_depth === 'advanced' ? 'advanced' : 'basic'
-  const topic = args.topic === 'news' ? 'news' : 'general'
-  const days = args.days === undefined ? undefined : clampInt(args.days, 1, 30, undefined)
-  const includeAnswer = args.include_answer === true
-  const includeRawContent = args.include_raw_content === true
-  const includeDomains = Array.isArray(args.include_domains)
-    ? args.include_domains.filter((d) => typeof d === 'string' && d.length > 0)
-    : []
-  const excludeDomains = Array.isArray(args.exclude_domains)
-    ? args.exclude_domains.filter((d) => typeof d === 'string' && d.length > 0)
-    : []
-  return { query, maxResults, searchDepth, topic, days, includeAnswer, includeRawContent, includeDomains, excludeDomains }
-}
-
-function hostnameOf(url) {
-  try {
-    return new URL(url).hostname
-  } catch {
-    return url
-  }
-}
-
-/** Combine a caller signal with a hard timeout; call dispose() after the request. */
-function combineSignals(signal, ms) {
-  const controller = new AbortController()
-  const timer = setTimeout(() => controller.abort(), ms)
-  const onAbort = () => controller.abort()
-  if (signal !== undefined && signal !== null) {
-    if (signal.aborted) controller.abort()
-    else signal.addEventListener('abort', onAbort, { once: true })
-  }
-  return {
-    signal: controller.signal,
-    dispose() {
-      clearTimeout(timer)
-      if (signal !== undefined && signal !== null) signal.removeEventListener('abort', onAbort)
-    },
-  }
-}
-
-function buildBody(input) {
-  const body = {
-    query: input.query,
-    max_results: input.maxResults,
-    search_depth: input.searchDepth,
-  }
-  if (input.topic === 'news') {
-    body.topic = 'news'
-    if (input.days !== undefined) body.days = input.days
-  }
-  if (input.includeAnswer) body.include_answer = true
-  if (input.includeRawContent) body.include_raw_content = true
-  if (input.includeDomains.length > 0) body.include_domains = input.includeDomains
-  if (input.excludeDomains.length > 0) body.exclude_domains = input.excludeDomains
-  return body
-}
-
-async function callTavily(input, key, exec) {
-  const combined = combineSignals(exec.signal, 30000)
-  try {
-    const response = await fetch('https://api.tavily.com/search', {
-      method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        accept: 'application/json',
-        authorization: 'Bearer ' + key,
-        'user-agent': 'dsh-tool-tavily-search/0.1.0',
-      },
-      body: JSON.stringify(buildBody(input)),
-      signal: combined.signal,
-    })
-    if (response.status === 401 || response.status === 429) {
-      return { kind: 'retryable', statusCode: response.status }
-    }
-    if (!response.ok) {
-      let message = 'HTTP ' + response.status
-      try {
-        const parsed = await response.json()
-        if (parsed !== null && typeof parsed === 'object') {
-          if (typeof parsed.error === 'string') message = parsed.error
-          else if (parsed.error !== null && typeof parsed.error === 'object' && typeof parsed.error.message === 'string') message = parsed.error.message
-        }
-      } catch {
-        /* keep the status message */
-      }
-      throw new Error('tavily_search: ' + message)
-    }
-    return { kind: 'ok', statusCode: response.status, json: await response.json() }
-  } catch (error) {
-    if (error instanceof Error && error.name === 'AbortError') {
-      throw new Error('tavily_search: request timed out or was aborted')
-    }
-    throw error
-  } finally {
-    combined.dispose()
-  }
-}
-
-function projectResults(json) {
-  const results = Array.isArray(json.results) ? json.results : []
-  const mapped = results.map((r) => {
-    const item = { url: String(r.url !== undefined && r.url !== null ? r.url : '') }
-    if (typeof r.title === 'string' && r.title.length > 0) item.title = r.title
-    if (typeof r.content === 'string' && r.content.length > 0) item.content = r.content
-    if (typeof r.score === 'number') item.score = r.score
-    if (typeof r.published_date === 'string' && r.published_date.length > 0) item.publishedAt = r.published_date
-    if (typeof r.raw_content === 'string' && r.raw_content.length > 0) {
-      item.rawContent = r.raw_content.length > 4000 ? r.raw_content.slice(0, 4000) + '…' : r.raw_content
-    }
-    return item
-  })
-  const value = { results: mapped }
-  if (typeof json.answer === 'string' && json.answer.length > 0) value.answer = json.answer
-  return value
-}
-
-function formatOutput(value) {
-  const parts = []
-  if (typeof value.answer === 'string' && value.answer.length > 0) parts.push(value.answer)
-  if (value.results.length > 0) {
-    const lines = value.results.map((r) => {
-      const label = typeof r.title === 'string' && r.title.length > 0 ? r.title : hostnameOf(r.url)
-      const meta = []
-      if (typeof r.content === 'string' && r.content.length > 0) meta.push(r.content)
-      if (typeof r.publishedAt === 'string' && r.publishedAt.length > 0) meta.push('(' + r.publishedAt + ')')
-      if (typeof r.score === 'number') meta.push('(relevance ' + r.score.toFixed(2) + ')')
-      const suffix = meta.length > 0 ? ' — ' + meta.join(' ') : ''
-      return '- [' + label + '](' + r.url + ')' + suffix
-    })
-    parts.push('Sources:\n' + lines.join('\n'))
-  } else {
-    parts.push('No results found.')
-  }
-  parts.push('Cite the relevant URLs above as markdown links in your answer.')
-  return parts.join('\n\n')
-}
-
-export function apply(ctx) {
-  applyBackend(ctx)
-
-  let rotation = 0
-
-  async function resolveKeys() {
-    const credentials = ctx.get('credentials')
-    if (credentials !== undefined) {
-      try {
-        const resolved = await credentials.resolve('TAVILY_API_KEYS')
-        if (resolved !== undefined && typeof resolved.value === 'string' && resolved.value.length > 0) {
-          const list = resolved.value.split(',').map((s) => s.trim()).filter((s) => s.length > 0)
-          if (list.length > 0) return { keys: list, source: resolved.source }
-        }
-      } catch (error) {
-        ctx.logger.warn('tavily_search: credential resolution failed: %s', error instanceof Error ? error.message : String(error))
-      }
-    }
-    return { keys: [], source: 'unconfigured' }
-  }
-
-  async function execute(args, exec) {
-    const input = normalizeArgs(args)
-    const { keys, source } = await resolveKeys()
-    if (keys.length === 0) {
-      throw new Error('tavily_search: TAVILY_API_KEYS is not configured — add it via the Tavily Search settings card or ~/.dsh/.credentials.yaml (comma-separated)')
-    }
-    const attempts = keys.length
-    let lastRetryable = 0
-    for (let attempt = 0; attempt < attempts; attempt++) {
-      const index = (rotation + attempt) % keys.length
-      const key = keys[index]
-      const started = Date.now()
-      const outcome = await callTavily(input, key, exec)
-      if (outcome.kind === 'ok') {
-        rotation = (index + 1) % keys.length
-        const count = Array.isArray(outcome.json.results) ? outcome.json.results.length : 0
-        ctx.logger.info('tavily_search: ok %j', { query: input.query, status: outcome.statusCode, results: count, ms: Date.now() - started, keys: keys.length, source })
-        return projectResults(outcome.json)
-      }
-      lastRetryable = outcome.statusCode
-      rotation = (index + 1) % keys.length
-      ctx.logger.info('tavily_search: key %d/%d returned HTTP %d, rotating', index + 1, keys.length, outcome.statusCode)
-    }
-    throw new Error('tavily_search: all ' + attempts + ' configured key(s) failed with HTTP ' + lastRetryable + ' (invalid key or rate limit)')
-  }
-
-  ctx.tools.register(defineTool({
-    name: 'tavily_search',
-    description: 'Search the web through the Tavily API. Returns ranked results with titles, URLs, snippets, relevance scores, and an optional generated answer. Supports basic/advanced depth, news topic with a freshness window, and domain allow/deny filters.',
-    parameters: {
-      query: { type: 'string', required: true, description: 'The search query.' },
-      max_results: { type: 'number', description: 'Number of results to return, 1-20 (default 5).' },
-      search_depth: { type: 'string', enum: ['basic', 'advanced'], description: 'basic is faster and cheaper; advanced returns deeper analysis (default basic).' },
-      topic: { type: 'string', enum: ['general', 'news'], description: 'Search scope: general web or news (default general).' },
-      days: { type: 'number', description: 'News freshness window in days, e.g. 7 for the last week; only applies when topic is news.' },
-      include_answer: { type: 'boolean', description: 'Ask Tavily to generate a concise answer to the query (default false).' },
-      include_raw_content: { type: 'boolean', description: 'Include raw page content for each result (default false; capped per result).' },
-      include_domains: { type: 'array', items: { type: 'string' }, description: 'Only search within these domains.' },
-      exclude_domains: { type: 'array', items: { type: 'string' }, description: 'Exclude these domains from results.' },
-    },
-    output: {
-      schema: {
-        type: 'object',
-        additionalProperties: false,
-        properties: {
-          answer: { type: 'string' },
-          results: {
-            type: 'array',
-            required: true,
-            items: {
-              type: 'object',
-              additionalProperties: false,
-              properties: {
-                url: { type: 'string', required: true },
-                title: { type: 'string' },
-                content: { type: 'string' },
-                score: { type: 'number' },
-                publishedAt: { type: 'string' },
-                rawContent: { type: 'string' },
-              },
-            },
-          },
-        },
-      },
-      render: (_args, value) => [{ type: 'text', text: formatOutput(value) }],
-    },
-    timeoutMs: 30000,
-    isConcurrencySafe: () => true,
-    execute,
-  }))
-
-  const systemPrompt = ctx.get('systemPrompt')
-  if (systemPrompt !== undefined) {
-    systemPrompt.section({
-      name: 'tool:tavily_search',
-      order: 111,
-      text: 'Use the tavily_search tool for web search powered by the Tavily API. It supports result count, search depth, news topic with a freshness window, domain allow/deny filters, and an optional generated answer (include_answer). Cite the returned URLs as markdown links in your answer.',
-    })
-  }
-
-  const credentials = ctx.get('credentials')
-  if (credentials !== undefined) {
-    credentials.describe('TAVILY_API_KEYS').then((info) => {
-      if (!info.configured) {
-        ctx.logger.warn('tavily_search: TAVILY_API_KEYS credential is not configured; add it via the Tavily Search settings card or ~/.dsh/.credentials.yaml')
-      }
-    }).catch((error) => {
-      ctx.logger.warn('tavily_search: credential describe failed: %s', error instanceof Error ? error.message : String(error))
-    })
-  }
-}
-const MANAGER_STATE = 'tavily-manager.json'
-const TOGGLE_STATE = 'tavily-toggle.json'
-const LEGACY_STATE = 'tavily-settings.json'
-const REFS = ['TAVILY_API_KEYS', 'TAVILY_API_KEY']
-
-function statePath(file) {
-  return join(resolveDshHome(), file)
-}
-
-function readState(file) {
-  return readJsonFile(statePath(file), {})
-}
-
-function writeState(file, state) {
-  writeFileSync(statePath(file), JSON.stringify(state, null, 2) + '\n', { mode: 0o600 })
-}
-
-function readBody(req) {
-  return new Promise((resolve, reject) => {
-    const chunks = []
-    req.on('data', (chunk) => chunks.push(chunk))
-    req.on('end', () => {
-      const text = Buffer.concat(chunks).toString('utf8')
-      try {
-        resolve(text.length > 0 ? JSON.parse(text) : {})
-      } catch {
-        reject(new Error('invalid JSON body'))
-      }
-    })
-    req.on('error', reject)
-  })
-}
-
-async function fetchUsageDetailsFor(key) {
-  const cached = usageCache.get(key)
-  if (cached !== undefined && Date.now() - cached.at < USAGE_TTL_MS) return cached.details
-  try {
-    const controller = new AbortController()
-    const timer = setTimeout(() => controller.abort(), 15000)
-    let response
-    try {
-      response = await fetch('https://api.tavily.com/usage', {
-        headers: { authorization: 'Bearer ' + key, accept: 'application/json' },
-        signal: controller.signal,
-      })
-    } finally {
-      clearTimeout(timer)
-    }
-    if (!response.ok) return null
-    const json = await response.json()
-    const account = json !== null && typeof json === 'object' ? json.account : undefined
-    const keyUsage = json !== null && typeof json === 'object' ? json.key : undefined
-    const usage = keyUsage !== undefined && typeof keyUsage.usage === 'number'
-      ? keyUsage.usage
-      : (account !== undefined && typeof account.plan_usage === 'number' ? account.plan_usage : null)
-    const planUsage = account !== undefined && typeof account.plan_usage === 'number'
-      ? account.plan_usage
-      : (keyUsage !== undefined && typeof keyUsage.usage === 'number' ? keyUsage.usage : null)
-    const planLimit = account !== undefined && typeof account.plan_limit === 'number'
-      ? account.plan_limit
-      : (keyUsage !== undefined && typeof keyUsage.limit === 'number' ? keyUsage.limit
-        : (keyUsage !== undefined && typeof keyUsage.plan_limit === 'number' ? keyUsage.plan_limit : null))
-    const currentPlan = account !== undefined && typeof account.plan === 'string'
-      ? account.plan
-      : (keyUsage !== undefined && typeof keyUsage.plan === 'string' ? keyUsage.plan : null)
-    if (usage === null && planUsage === null) return null
-    const details = { usage, planUsage, planLimit, currentPlan }
-    usageCache.set(key, { at: Date.now(), details })
-    return details
-  } catch {
-    return null
-  }
-}
-
-async function fetchUsageFor(key) {
-  const details = await fetchUsageDetailsFor(key)
-  if (details === null) return null
-  if (details.planLimit !== null && details.planLimit > 0 && details.planUsage !== null) {
-    return (details.planUsage / details.planLimit) * 100
-  }
-  return details.usage !== null ? details.usage : details.planUsage
-}
-
-async function collectStoredKeys(credentials) {
-  const out = []
-  const seen = new Set()
-  for (const ref of REFS) {
-    let hit
+/**
+ * Settings namespace owned by this package. It is the join key between the
+ * Host half and the browser card: the rc.7 Plugins configuration tab serves
+ * this namespace and dispatches the card registered under the same key.
+ */
+export const TAVILY_NS = settingsNamespace('tavily-search')
+
+export function apply(ctx, config) {
+  // The switch value the current fiber is acting on. Every write path updates
+  // this before the row restart so a watcher re-fired after a restart no-ops.
+  let lastApplied = isToolEnabled(config)
+  let settingsScope = null
+
+  /** Persist the switch first, then restart this row so the tool (un)registers. */
+  async function applySwitchLocal(enabled) {
+    if (enabled === lastApplied) return
+    lastApplied = enabled
+    const previous = readToolState()
+    writeToolState(enabled)
     try {
-      hit = await credentials.resolve(ref)
-    } catch {
-      continue
-    }
-    if (hit === undefined || typeof hit.value !== 'string') continue
-    for (const key of parseKeyList(hit.value)) {
-      if (!seen.has(key)) {
-        seen.add(key)
-        out.push(key)
-      }
-    }
-  }
-  return out
-}
-
-function applyBackend(ctx) {
-  const credentials = ctx.get('credentials')
-  const loader = ctx.get('loader')
-
-  const send = (res, status, payload) => {
-    res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' })
-    res.end(JSON.stringify(payload))
-  }
-
-  // ── key manager payload ────────────────────────────────────────────────────
-  async function buildManagerPayload(keys) {
-    const state = readState(MANAGER_STATE)
-    const keySavedAt = state.keySavedAt !== undefined && typeof state.keySavedAt === 'object' ? state.keySavedAt : {}
-    if (Object.keys(keySavedAt).length === 0 && credentials !== undefined) {
-      // Migrate dates recorded by the pre-0.2 layout (ref-keyed legacy file).
-      const legacy = readJsonFile(statePath(LEGACY_STATE), null)
-      if (legacy !== null && typeof legacy === 'object') {
-        for (const ref of REFS) {
-          const entry = legacy[ref]
-          if (entry !== null && typeof entry === 'object' && typeof entry.savedAt === 'string') {
-            try {
-              const hit = await credentials.resolve(ref)
-              if (hit !== undefined) keySavedAt[maskValue(hit.value)] = entry.savedAt
-            } catch {
-              /* keep going */
-            }
-          }
-        }
+      const loader = ctx.get('loader')
+      const self = loader !== undefined && loader !== null ? loader.resolve('include:dsh-tavily') : undefined
+      if (self === undefined || self === null || self.fiber === undefined) {
+        throw new Error('dsh-tavily: row include:dsh-tavily is not loaded')
       }
-    }
-    const primaryMasked = keys.length > 0 ? maskValue(keys[0]) : null
-    const display = keys.map((value) => {
-      const masked = maskValue(value)
-      return {
-        masked,
-        savedAt: keySavedAt[masked] !== undefined ? keySavedAt[masked] : null,
-      }
-    }).sort((a, b) => {
-      if (a.savedAt === b.savedAt) return 0
-      if (a.savedAt === null) return 1
-      if (b.savedAt === null) return -1
-      return a.savedAt < b.savedAt ? -1 : 1
-    })
-    return {
-      keys: display.map((entry) => ({
-        masked: entry.masked,
-        savedAt: entry.savedAt,
-        primary: entry.masked === primaryMasked,
-      })),
-      strategy: isValidStrategy(state.strategy) ? state.strategy : 'rotate',
+      await self.fiber.update({ enabled }, true)
+    } catch (error) {
+      lastApplied = previous !== null ? previous.enabled : (config.enabled !== false)
+      restoreToolState(previous)
+      throw error
     }
   }
 
-  // ── persisted on/off + live provider flip ───────────────────────────────────
-  async function applyProvider(enabled) {
-    if (loader === undefined) return
+  // First-class settings integration (rc.7 plugin management): register the
+  // `tavily-search` namespace so the Plugins configuration surface serves it
+  // and pairs this package's card. The row config is the composition base
+  // layer; the user document overlays it. Runs whether or not the tool is on.
+  const settings = ctx.get('settings')
+  if (settings !== undefined && settings !== null && typeof settings.register === 'function') {
     try {
-      const entry = loader.resolve('include:web')
-      if (entry !== undefined && entry !== null && entry.fiber !== undefined) {
-        await entry.fiber.update({ searchProvider: enabled ? 'tavily' : 'deepseek-official' }, true)
-      }
+      settingsScope = settings.register(TAVILY_NS, Config, {
+        base: { enabled: config.enabled },
+        applies: 'restart',
+      })
+      settingsScope.watch((next) => {
+        const nextEnabled = next !== null && typeof next === 'object' && typeof next.enabled === 'boolean'
+          ? next.enabled
+          : false
+        applySwitchLocal(nextEnabled).catch((error) => {
+          ctx.logger.warn('tavily-search: applying settings switch failed: %s', error instanceof Error ? error.message : String(error))
+        })
+      })
     } catch (error) {
-      ctx.logger.warn('tavily-backend: web provider flip failed: %s', error instanceof Error ? error.message : String(error))
+      ctx.logger.warn('tavily-search: settings namespace registration failed: %s', error instanceof Error ? error.message : String(error))
+      settingsScope = null
     }
   }
 
-  // Re-apply the persisted choice at activation (default: enabled).
-  const toggleState = readState(TOGGLE_STATE)
-  if (toggleState.enabled === false) {
-    void applyProvider(false)
-  }
-
-  ctx.webServer.register({
-    kind: 'exact',
-    path: '/api/tavily-usage',
-    handler: async (_req, res) => {
-      if (credentials === undefined) return send(res, 500, { ok: false, error: 'credentials service unavailable' })
-      try {
-        const keys = await collectStoredKeys(credentials)
-        if (keys.length === 0) return send(res, 200, { ok: false, error: 'no Tavily API key configured' })
-        const state = readState(MANAGER_STATE)
-        const keySavedAt = state.keySavedAt !== undefined && typeof state.keySavedAt === 'object' ? state.keySavedAt : {}
-        const orderedKeys = keys.slice().sort((a, b) => {
-          const am = keySavedAt[maskValue(a)] !== undefined ? keySavedAt[maskValue(a)] : null
-          const bm = keySavedAt[maskValue(b)] !== undefined ? keySavedAt[maskValue(b)] : null
-          if (am === bm) return 0
-          if (am === null) return 1
-          if (bm === null) return -1
-          return am < bm ? -1 : 1
-        })
-        const perKey = []
-        for (const key of orderedKeys) {
-          try {
-            const usage = await fetchUsageDetailsFor(key)
-            perKey.push(usage !== null
-              ? { ok: true, masked: maskValue(key), ...usage }
-              : { ok: false, masked: maskValue(key), error: 'usage unavailable' })
-          } catch (error) {
-            perKey.push({ ok: false, masked: maskValue(key), error: String(error && error.message ? error.message : error) })
-          }
-        }
-        const okRows = perKey.filter((row) => row.ok)
-        return send(res, 200, {
-          ok: true,
-          perKey,
-          totals: {
-            keys: keys.length,
-            okKeys: okRows.length,
-            usage: okRows.reduce((sum, row) => sum + (row.usage || 0), 0),
-            planUsage: okRows.reduce((sum, row) => sum + (row.planUsage || 0), 0),
-            planLimit: okRows.every((row) => row.planLimit !== null) ? okRows.reduce((sum, row) => sum + row.planLimit, 0) : null,
-          },
-        })
-      } catch (error) {
-        send(res, 500, { ok: false, error: String(error && error.message ? error.message : error) })
-      }
-    },
-  })
-
-  ctx.webServer.register({
-    kind: 'exact',
-    path: '/api/tavily-manager',
-    handler: async (req, res) => {
-      if (credentials === undefined) return send(res, 500, { ok: false, error: 'credentials service unavailable' })
-      try {
-        const url = new URL(req.url || '/', 'http://x')
-        if (req.method === 'GET') {
-          const reveal = url.searchParams.get('reveal')
-          const keys = await collectStoredKeys(credentials)
-          if (reveal !== null) {
-            const match = keys.find((key) => maskValue(key) === reveal)
-            if (match === undefined) return send(res, 404, { ok: false, error: 'key not found' })
-            return send(res, 200, { ok: true, value: match })
-          }
-          return send(res, 200, { ok: true, ...(await buildManagerPayload(keys)) })
-        }
-        if (req.method === 'POST') {
-          const body = await readBody(req)
-          const strategy = isValidStrategy(body.strategy) ? body.strategy : 'rotate'
-          const addValues = Array.isArray(body.add)
-            ? body.add.map((item) => typeof item === 'string' ? item.trim() : '').filter((value) => value.length > 0)
-            : []
-          const removeMasked = Array.isArray(body.remove)
-            ? body.remove.filter((item) => typeof item === 'string' && item.length > 0)
-            : []
-
-          let stored = await collectStoredKeys(credentials)
-          if (removeMasked.length > 0) {
-            stored = stored.filter((key) => !removeMasked.includes(maskValue(key)))
-          }
-          let values = [...stored]
-          for (const value of addValues) {
-            if (!values.includes(value)) values.push(value)
-          }
-          if (values.length === 0) {
-            await credentials.unset('TAVILY_API_KEYS')
-            await credentials.unset('TAVILY_API_KEY')
-          } else {
-            if (strategy !== 'rotate') {
-              const usageRows = await Promise.all(values.map(async (value) => ({ value, usage: await fetchUsageFor(value) })))
-              const usageOf = (value) => {
-                const row = usageRows.find((r) => r.value === value)
-                return row !== undefined && row.usage !== null ? row.usage : null
-              }
-              values = orderKeys(values, strategy, usageOf)
-            }
-            await credentials.set('TAVILY_API_KEYS', values.join(','))
-            await credentials.set('TAVILY_API_KEY', values[0])
-          }
-
-          const state = readState(MANAGER_STATE)
-          const keySavedAt = state.keySavedAt !== undefined && typeof state.keySavedAt === 'object' ? state.keySavedAt : {}
-          const now = new Date().toISOString()
-          for (const value of values) {
-            const masked = maskValue(value)
-            if (keySavedAt[masked] === undefined) keySavedAt[masked] = now
-          }
-          writeState(MANAGER_STATE, { keySavedAt, strategy })
-
-          return send(res, 200, { ok: true, ...(await buildManagerPayload(values)) })
-        }
-        return send(res, 405, { ok: false, error: 'method not allowed' })
-      } catch (error) {
-        send(res, 500, { ok: false, error: String(error && error.message ? error.message : error) })
+  installBackend(ctx, {
+    enabled: () => isToolEnabled(config),
+    async applySwitch(enabled) {
+      // Every write converges on one pipeline: the settings namespace when a
+      // settings service is served (its watcher persists and restarts this
+      // row), or the plain state-file path otherwise.
+      if (settings !== undefined && settingsScope !== null) {
+        await settings.update(TAVILY_NS, { enabled })
+      } else {
+        await applySwitchLocal(enabled)
       }
     },
   })
 
-  ctx.webServer.register({
-    kind: 'exact',
-    path: '/api/tavily-toggle',
-    handler: async (req, res) => {
-      try {
-        if (req.method === 'GET') {
-          return send(res, 200, { ok: true, enabled: readState(TOGGLE_STATE).enabled === true })
-        }
-        if (req.method === 'POST') {
-          const body = await readBody(req)
-          const enabled = body !== null && typeof body === 'object' && body.enabled === true
-          writeState(TOGGLE_STATE, { enabled })
-          await applyProvider(enabled)
-          return send(res, 200, { ok: true, enabled })
-        }
-        return send(res, 405, { ok: false, error: 'method not allowed' })
-      } catch (error) {
-        send(res, 500, { ok: false, error: String(error && error.message ? error.message : error) })
-      }
-    },
-  })
+  if (!isToolEnabled(config)) return
+  installTavilyTool(ctx)
 }

package/src/lib.js

@@ -1,65 +0,0 @@
-/**
- * Pure helpers for the Tavily backend (exported for tests).
- */
-import { readFileSync } from 'node:fs'
-
-export const STRATEGIES = ['rotate', 'low-usage-first', 'high-usage-first']
-
-export function isValidStrategy(value) {
-  return STRATEGIES.includes(value)
-}
-
-/**
- * Mask a key for display: `first12…last4`; comma-separated lists are masked
- * per part. Never reveals more than a fingerprint.
- */
-export function maskValue(value) {
-  if (typeof value !== 'string' || value.length === 0) return ''
-  return value.split(',').map((part) => {
-    const p = part.trim()
-    if (p.length <= 12) return '••••'
-    return p.slice(0, 12) + '…' + p.slice(-4)
-  }).join(', ')
-}
-
-/** Split a comma-separated credential value into trimmed, deduped keys. */
-export function parseKeyList(value) {
-  if (typeof value !== 'string') return []
-  const seen = new Set()
-  const out = []
-  for (const part of value.split(',')) {
-    const key = part.trim()
-    if (key.length > 0 && !seen.has(key)) {
-      seen.add(key)
-      out.push(key)
-    }
-  }
-  return out
-}
-
-/**
- * Order keys according to a strategy. `usageOf(key)` returns a number or null
- * (unknown usage is treated as 0). `rotate` keeps the given order.
- */
-export function orderKeys(values, strategy, usageOf) {
-  if (strategy === 'rotate') return [...values]
-  const usageOfKey = (value) => {
-    const usage = usageOf(value)
-    return usage !== null && typeof usage === 'number' ? usage : 0
-  }
-  const sorted = [...values]
-  sorted.sort((a, b) => strategy === 'low-usage-first'
-    ? usageOfKey(a) - usageOfKey(b)
-    : usageOfKey(b) - usageOfKey(a))
-  return sorted
-}
-
-/** Read a JSON object file; `fallback` on missing or unparsable content. */
-export function readJsonFile(path, fallback) {
-  try {
-    const parsed = JSON.parse(readFileSync(path, 'utf8'))
-    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : fallback
-  } catch {
-    return fallback
-  }
-}