@moguiyu/dsh-tavily 0.2.7 → 0.3.0

package/README.md

@@ -1,32 +1,32 @@
 # @moguiyu/dsh-tavily
 
-Combined plugin: the opt-in advanced Tavily model tools (`tavily_search`, `tavily_extract`,
-`tavily_map`, `tavily_crawl`), the **Tavily Search** settings card, and the local HTTP backend
-for key/usage management.
+Everything in one package: the advanced Tavily model tools (`tavily_search`, `tavily_extract`,
+`tavily_map`, `tavily_crawl`), the key/usage HTTP routes, and the browser card on the **Plugins**
+page.
 
 - **`tavily_search`** — full Tavily surface (`max_results`, `search_depth`, `topic`, `days`,
-  `include_answer`, `include_raw_content`, `include_domains`, `exclude_domains`). Opt-in and
-  off by default.
+  `include_answer`, `include_raw_content`, `include_domains`, `exclude_domains`).
 - **`tavily_extract` / `tavily_map` / `tavily_crawl`** — read a known URL's content, map a
   site's links, or crawl a site and return its pages. Same key-rotation/failover as search.
-- **Settings card** — key list, usage gauge, strategy selector, and the advanced-tool switch.
-- **Plugin-config settings card** — the Host installs the `tavily-search` settings section
-  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**,
-  including `0.1.2-alpha.x`, the `0.1.3` line, and the `0.1.5`/current `0.1.6` lines — both seam
-  generations are detected at runtime).
-  The switch writes the namespace and restarts the row; the choice is mirrored to
-  `~/.dsh/tavily-tool.json`.
+- **Card** — key list, usage gauge, and the strategy selector. It registers into the Plugins
+  page's `plugins.bundle.config` slot, keyed `@moguiyu/dsh-tavily`, and needs DSH
+  **0.1.6-alpha.2 or newer** — the release that retired `settings.plugin.item` and moved plugin
+  configuration off the Settings page. On older lines the tools and routes work; there is simply
+  no card.
 - **`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.
+  `web.searchProvider` is never rewritten; the built-in `web_search` keeps its native provider
+  and schema.
 
-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`.
+Host half: plain ESM (`src/index.js`, `src/tools.js`, `src/backend.js`, `src/lib.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.
+Earlier releases split this across `@moguiyu/dsh-tool-tavily-search` and
+`@moguiyu/dsh-tavily-backend`, which this package imported as regular dependencies. From 0.3.0
+both are folded in here: one package means no dependency range can drift behind the contract,
+which is exactly how the old tool-level switch broke. Both old packages are deprecated.
+
+There is no tool-level on/off switch. Composing the plugin registers the tools, and the Plugins
+page's own bundle toggle is the only on/off.
 
 See the [workspace README](../../README.md) for install and configuration.

package/lib/client.js

@@ -2,7 +2,6 @@ window.__ModuleLoader__.load({
   id: "@moguiyu/dsh-tavily",
   factory: function factory(require) {
   const react = require('react')
-  const _primitives = require('@deepseek-ai/dsh-client-ui-primitives')
 
   const inject = ['slots']
 
@@ -52,18 +51,6 @@ window.__ModuleLoader__.load({
     }, react.createElement(SvgIcon, { name: icon, size: 13 }))
   }
 
-  function Switch({ checked, disabled, label, onChange }) {
-    return react.createElement('button', {
-      type: 'button',
-      role: 'switch',
-      'aria-checked': checked === true,
-      'aria-label': label,
-      disabled: disabled || checked === null,
-      onClick: onChange,
-      style: { width: 36, height: 20, borderRadius: 10, border: '1px solid var(--dsw-alias-border-l2)', background: checked === true ? 'var(--dsw-alias-state-success-primary)' : 'var(--dsw-alias-bg-layer-1)', cursor: 'pointer', padding: 0, position: 'relative', flex: 'none', opacity: disabled ? 0.5 : 1 }
-    }, react.createElement('span', { style: { position: 'absolute', top: 2, left: checked === true ? 18 : 2, width: 14, height: 14, borderRadius: 7, background: '#fff', transition: 'left .12s ease' } }))
-  }
-
   function UsageCircle({ percent, size, label, onClick }) {
     const radius = 15
     const circumference = 2 * Math.PI * radius
@@ -78,9 +65,7 @@ window.__ModuleLoader__.load({
     )
   }
 
-  function TavilyCard() {
-    const [enabled, setEnabled] = react.useState(null)
-    const [expanded, setExpanded] = react.useState(false)
+  function TavilySettingsCard() {
     const [server, setServer] = react.useState(null)
     const [loadError, setLoadError] = react.useState(null)
     const [strategy, setStrategy] = react.useState('rotate')
@@ -96,13 +81,6 @@ window.__ModuleLoader__.load({
     const [usageError, setUsageError] = react.useState(null)
 
     const refresh = react.useCallback(async () => {
-      try {
-        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) {
-        setLoadError(String(error && error.message ? error.message : error))
-      }
       try {
         const response = await fetch('/api/tavily-manager', { cache: 'no-store' })
         const data = await response.json()
@@ -122,27 +100,6 @@ window.__ModuleLoader__.load({
 
     react.useEffect(() => { refresh() }, [refresh])
 
-    const toggleEnabled = async () => {
-      const next = enabled !== true
-      setBusy(true)
-      setNotice(null)
-      try {
-        const response = await fetch('/api/tavily-tool', {
-          method: 'POST',
-          headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({ enabled: next })
-        })
-        const data = await response.json()
-        if (!data.ok) { setNotice({ error: data.error || 'Switch failed' }); return }
-        setEnabled(data.enabled)
-        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 {
-        setBusy(false)
-      }
-    }
-
     const saveStrategy = async (next) => {
       setBusy(true)
       setNotice(null)
@@ -283,46 +240,12 @@ window.__ModuleLoader__.load({
     const headStyle = { textAlign: 'left', padding: '6px 8px', borderBottom: '1px solid var(--dsw-alias-border-l2)', fontSize: 12, color: 'var(--dsw-alias-label-tertiary)' }
     const cellStyle = { padding: '8px', verticalAlign: 'top' }
 
-    const isOff = enabled === false
-
-    // Card box mirrors the native plugin-config card (PluginCard.module.css,
-    // ui-settings-plugins): bg-layer-3 fill, .5px border-l4, 16px radius,
-    // hover/open border lift, and the open state's bg-layer-2 upgrade — so
-    // the card sits at the same elevation as native cards in dark mode too.
-    return react.createElement('div', { className: expanded ? 'dts-card dts-card-open' : 'dts-card', style: { minWidth: 0 } },
-      react.createElement('style', null, '.dts-card{border:.5px solid var(--dsw-alias-border-l4);border-radius:16px;background:var(--dsw-alias-bg-layer-3);transition:border-color .16s,background .16s}.dts-card:hover{border-color:var(--dsw-alias-label-dimmed)}.dts-card-open{background:var(--dsw-alias-bg-layer-2);border-color:var(--dsw-alias-label-dimmed)}.dts-icon-btn:hover{background:var(--dsw-alias-interactive-bg-hover)}.dts-icon-btn:disabled{opacity:.4;cursor:default}.dts-icon-btn-danger:hover{background:var(--dsw-alias-interactive-bg-hover-danger)}'),
-      react.createElement('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', gap: 12, padding: '12px 14px', minHeight: 52, boxSizing: 'border-box' } },
-        react.createElement('button', {
-          type: 'button',
-          'aria-expanded': expanded,
-          onClick: () => setExpanded((current) => !current),
-          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' } }, '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: 'Advanced tavily_search tool enabled', onChange: toggleEnabled }),
-          react.createElement('button', {
-            type: 'button',
-            className: 'dts-icon-btn',
-            title: expanded ? 'Collapse' : 'Expand',
-            'aria-label': expanded ? 'Collapse' : 'Expand',
-            onClick: () => setExpanded((current) => !current),
-            style: { width: 26, height: 26, borderRadius: 6, border: 'none', background: 'transparent', color: 'var(--dsw-alias-label-tertiary)', cursor: 'pointer', display: 'inline-flex', alignItems: 'center', justifyContent: 'center', padding: 0 }
-          },
-            react.createElement('span', { style: { display: 'inline-flex', transform: expanded ? 'rotate(180deg)' : undefined, transition: 'transform .14s var(--ds-ease-in-out)' } },
-              react.createElement(_primitives.IconChevronDownOutline14, { size: 12, 'aria-hidden': 'true' })
-            )
-          )
-        )
-      ),
-      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)' } },
-              '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,
+    // The Plugins page draws the title, the icon, and the crumb — the
+    // `plugins.bundle.config` contract puts the form alone in the entry — so
+    // this renders no card chrome, no second heading, and no collapse.
+    return react.createElement('div', { style: { display: 'flex', flexDirection: 'column', gap: 16, minWidth: 0 } },
+      react.createElement('style', null, '.dts-icon-btn:hover{background:var(--dsw-alias-interactive-bg-hover)}.dts-icon-btn:disabled{opacity:.4;cursor:default}.dts-icon-btn-danger:hover{background:var(--dsw-alias-interactive-bg-hover-danger)}'),
+      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 green dot marks the first (primary) key. The tavily_search tool uses all keys according to the strategy. Built-in web_search is unaffected.'
               ),
@@ -434,21 +357,33 @@ window.__ModuleLoader__.load({
               usageError !== null && react.createElement('p', { style: { margin: 0, fontSize: 12, color: 'var(--dsw-alias-state-error-primary)' } }, String(usageError)),
               usage !== null && usage.ok === false && react.createElement('p', { style: { margin: 0, fontSize: 12, color: 'var(--dsw-alias-state-error-primary)' } }, String(usage.error))
             )
-      )
     )
   }
 
+  // The entry the Plugins page renders. The contract asks for two views:
+  // `summary` for the one-liner under the title, and `page` for the form with
+  // its own save control. The page supplies the title, icon, and crumb, so the
+  // summary is a plain string and the page view is the form alone — matching
+  // how the shipped cards (WebSearchCard and friends) are written.
+  function TavilyCard(props) {
+    if (props && props.view === 'summary') {
+      return 'Manage Tavily API keys and the key-usage strategy. The built-in web_search is never replaced.'
+    }
+    return react.createElement(TavilySettingsCard, null)
+  }
+
   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'
+    // ONE slot. 0.1.6-alpha.2 moved plugin configuration to the sidebar
+    // Plugins page and retired `settings.plugin.item`. This package no longer
+    // registers a settings namespace, so the retired keyed slot has no key it
+    // could claim. On rc.7 through 0.1.6-alpha.1 the tools and routes work but
+    // this card has no host — see `docs/agents/plugin-design.md`.
+    ctx.slots.inject('plugins.bundle.config', () => ctx.slots.register({
+      name: 'plugins.bundle.config',
+      // Keyed by the bundle's package name. The Plugins page renders this on
+      // the @moguiyu/dsh-tavily bundle page, between its description and rows.
+      key: '@moguiyu/dsh-tavily',
+      id: '@moguiyu/dsh-tavily'
     }, TavilyCard))
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@moguiyu/dsh-tavily",
-  "version": "0.2.7",
-  "description": "Opt-in advanced Tavily model tools for DeepSeek Harness with the Tavily Search settings card (rc.7/rc.8 and the 0.1.2-0.1.6 plugin management lines). The built-in web_search is never replaced.",
+  "version": "0.3.0",
+  "description": "Advanced Tavily model tools for DeepSeek Harness (tavily_search, tavily_extract, tavily_map, tavily_crawl) with a key and usage management card on the Plugins page. The built-in web_search is never replaced.",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
@@ -36,14 +36,14 @@
         "0.1.5-alpha.2": "compatible",
         "0.1.5-rc.1": "compatible",
         "0.1.5-rc.2": "compatible",
-        "0.1.6-alpha.1": "compatible"
+        "0.1.6-alpha.1": "compatible",
+        "0.1.6-alpha.2": "compatible"
       }
     },
     "client": {
       "platform": "web",
       "inject": [
-        "@deepseek-ai/dsh-client-ui-settings",
-        "@deepseek-ai/dsh-client-ui-settings-plugins"
+        "@deepseek-ai/dsh-client-ui-plugin-manager"
       ]
     }
   },
@@ -66,16 +66,9 @@
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.7 || ^0.1.1-rc.1 || ^0.1.2-alpha.2 || ^0.1.3-alpha.1 || ^0.1.5-0 || ^0.1.6-0",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7 || ^0.1.1-rc.1 || ^0.1.2-alpha.2 || ^0.1.3-alpha.1 || ^0.1.5-0 || ^0.1.6-0",
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.7 || ^0.1.1-rc.1 || ^0.1.2-alpha.2 || ^0.1.3-alpha.1 || ^0.1.5-0 || ^0.1.6-0"
-  },
-  "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.2",
-    "@moguiyu/dsh-tavily-backend": "^0.2.1",
-    "@moguiyu/dsh-tool-tavily-search": "^0.2.1"
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7 || ^0.1.1-rc.1 || ^0.1.2-alpha.2 || ^0.1.3-alpha.1 || ^0.1.5-0 || ^0.1.6-0"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.2",
     "@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.2"
   }
 }

package/src/backend.js

@@ -0,0 +1,297 @@
+/**
+ * Routes half of `@moguiyu/dsh-tavily`: key and usage management on the
+ * harness webServer (`/api/tavily-usage`, `/api/tavily-manager`). The
+ * built-in `web_search` tool is never replaced — no web search provider is
+ * registered and `web.searchProvider` is never touched.
+ *
+ * There is no `/api/tavily-tool` switch route: the tool-level on/off is gone
+ * (see `tools.js`). Key management is not a capability gate — it only edits
+ * the credentials the tools read.
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths'
+import { STRATEGIES, isValidStrategy, maskValue, parseKeyList, orderKeys, readJsonFile } from './lib.js'
+
+const USAGE_TTL_MS = 60000
+const usageCache = new Map()
+
+const MANAGER_STATE = 'tavily-manager.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
+    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
+}
+
+/**
+ * Register the Tavily key/usage routes on `ctx.webServer`:
+ * `/api/tavily-usage` and `/api/tavily-manager`.
+ *
+ * Every route is registered through `ctx.effect`, so the calling fiber owns
+ * it and unloading the row leaves nothing registered.
+ */
+export function installBackend(ctx) {
+  const credentials = ctx.get('credentials')
+
+  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 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',
+    }
+  }
+
+  ctx.effect(() => 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) })
+      }
+    },
+  }), 'tavily-backend: route /api/tavily-usage')
+
+  ctx.effect(() => 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) })
+      }
+    },
+  }), 'tavily-backend: route /api/tavily-manager')
+
+}