@moguiyu/dsh-tavily 0.2.8 → 0.3.1

package/src/backend.js

@@ -0,0 +1,376 @@
+/**
+ * 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
+}
+
+/** Resolve one credential ref to its string value, or `null` when absent. */
+async function resolveRef(credentials, ref) {
+  try {
+    const hit = await credentials.resolve(ref)
+    return hit !== undefined && hit !== null && typeof hit.value === 'string' ? hit.value : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Whether a ref can be written here. The launching environment's variables are
+ * inherited READ-ONLY: `set`/`unset` throw for them (`describe().writable === false`).
+ * Assume writable when the service cannot say.
+ */
+async function refWritable(credentials, ref) {
+  try {
+    const info = await credentials.describe(ref)
+    return info === undefined || info === null || info.writable !== false
+  } catch {
+    return true
+  }
+}
+
+/**
+ * The managed key list, and where it came from.
+ *
+ * `TAVILY_API_KEYS` is AUTHORITATIVE. `TAVILY_API_KEY` — the derived primary — is
+ * read only as a fallback, for a deployment that sets nothing else. The two used to
+ * be unioned, and that was a bug with two faces: an environment-supplied
+ * `TAVILY_API_KEY` re-added its key on every read, so that key could never be deleted
+ * from the card; and every write then tried to re-sync the primary, which the
+ * launching environment owns, so the write threw AFTER the list had already changed.
+ */
+async function collectStoredKeys(credentials) {
+  const fromList = parseKeyList(await resolveRef(credentials, 'TAVILY_API_KEYS') ?? '')
+  if (fromList.length > 0) return { values: dedupe([...fromList]), source: 'list' }
+  const fromPrimary = parseKeyList(await resolveRef(credentials, 'TAVILY_API_KEY') ?? '')
+  return { values: dedupe([...fromPrimary]), source: fromPrimary.length > 0 ? 'primary' : 'list' }
+}
+
+function dedupe(values) {
+  const out = []
+  const seen = new Set()
+  for (const key of values) {
+    if (!seen.has(key)) {
+      seen.add(key)
+      out.push(key)
+    }
+  }
+  return out
+}
+
+/**
+ * Keep the derived primary in step with the list, best effort. The tools read
+ * `TAVILY_API_KEYS`, so a primary the environment owns must never fail the request.
+ */
+async function syncPrimary(credentials, value) {
+  if (!(await refWritable(credentials, 'TAVILY_API_KEY'))) return false
+  try {
+    if (value === null) await credentials.unset('TAVILY_API_KEY')
+    else await credentials.set('TAVILY_API_KEY', value)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 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, source = 'list') {
+    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
+    })
+    // The card needs to know what it may change. A ref inherited from the
+    // launching environment is read-only, and saying so beats a raw 500 from
+    // `set` after the list has already been written.
+    const keysWritable = credentials === undefined ? true : await refWritable(credentials, 'TAVILY_API_KEYS')
+    const primaryWritable = credentials === undefined ? true : await refWritable(credentials, 'TAVILY_API_KEY')
+    const removable = source === 'list' ? keysWritable : primaryWritable
+    return {
+      keys: display.map((entry) => ({
+        masked: entry.masked,
+        savedAt: entry.savedAt,
+        primary: entry.masked === primaryMasked,
+        removable,
+      })),
+      strategy: isValidStrategy(state.strategy) ? state.strategy : 'rotate',
+      source,
+      writable: { keys: keysWritable, primary: primaryWritable },
+    }
+  }
+
+  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 { values: 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 { values: keys, source } = 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, source)) })
+        }
+        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 { values: stored, source } = 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)
+          }
+
+          // A ref the launching environment supplies is inherited READ-ONLY: set and
+          // unset throw for it. Decide that BEFORE writing anything. The old order
+          // wrote `TAVILY_API_KEYS` first and then threw on the derived-primary sync,
+          // so the card reported a failure for a write that had half happened — and
+          // the unioned read then put the deleted key straight back.
+          const canWriteList = await refWritable(credentials, 'TAVILY_API_KEYS')
+          const canWritePrimary = await refWritable(credentials, 'TAVILY_API_KEY')
+          const READONLY_LIST = 'TAVILY_API_KEYS is supplied read-only by the launching environment, so the key list cannot be changed here. Unset it in the shell you start dsh from, or manage keys in ~/.dsh/.credentials.yaml.'
+          const READONLY_PRIMARY = 'That key comes from TAVILY_API_KEY, which the launching environment supplies read-only. Unset it in the shell you start dsh from.'
+          if (!canWriteList && (addValues.length > 0 || removeMasked.length > 0)) {
+            return send(res, 409, { ok: false, error: READONLY_LIST })
+          }
+          if (!canWritePrimary && source === 'primary' && removeMasked.length > 0) {
+            return send(res, 409, { ok: false, error: READONLY_PRIMARY })
+          }
+          // Emptying the list while an inherited primary still carries a key would
+          // read straight back as that key, so refuse rather than appear to undo itself.
+          if (values.length === 0 && !canWritePrimary) {
+            const inherited = parseKeyList(await resolveRef(credentials, 'TAVILY_API_KEY') ?? '')
+            if (inherited.length > 0) return send(res, 409, { ok: false, error: READONLY_PRIMARY })
+          }
+
+          if (values.length === 0) {
+            await credentials.unset('TAVILY_API_KEYS')
+            await syncPrimary(credentials, null)
+          } 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 syncPrimary(credentials, 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, source)) })
+        }
+        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')
+
+}

package/src/client.js

@@ -7,7 +7,6 @@ export const id = '@moguiyu/dsh-tavily'
 
 export function factory(require) {
   const react = require('react')
-  const _primitives = require('@deepseek-ai/dsh-client-ui-primitives')
 
   const inject = ['slots']
 
@@ -57,18 +56,6 @@ export function factory(require) {
     }, 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
@@ -84,8 +71,6 @@ export function factory(require) {
   }
 
   function TavilySettingsCard() {
-    const [enabled, setEnabled] = react.useState(null)
-    const [expanded, setExpanded] = react.useState(false)
     const [server, setServer] = react.useState(null)
     const [loadError, setLoadError] = react.useState(null)
     const [strategy, setStrategy] = react.useState('rotate')
@@ -101,13 +86,6 @@ export function factory(require) {
     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()
@@ -127,27 +105,6 @@ export function factory(require) {
 
     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)
@@ -288,49 +245,19 @@ export function factory(require) {
     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.'
               ),
+              server !== null && server.writable !== undefined && server.writable.keys === false &&
+                react.createElement('p', { style: { margin: 0, fontSize: 12, color: 'var(--dsw-alias-label-tertiary)' } },
+                  'Read-only: these keys come from the environment that launched dsh, so this card cannot change them. Unset TAVILY_API_KEYS / TAVILY_API_KEY in that shell and restart dsh to manage keys here.'
+                ),
               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 } },
                 react.createElement('thead', null,
@@ -386,11 +313,15 @@ export function factory(require) {
                               !isRemoved && react.createElement(IconButton, { icon: 'pencil', title: 'Edit', onClick: () => startReplace(masked), disabled: busy }),
                               react.createElement(IconButton, {
                                 icon: isRemoved ? 'restore' : (confirm[masked] === true ? 'check' : 'trash'),
-                                title: isRemoved ? 'Restore' : (confirm[masked] === true ? 'Click again to confirm' : 'Delete'),
+                                // A key the launching environment supplies is read-only, so the
+                                // server would refuse. Say so on the control instead.
+                                title: key.removable === false
+                                  ? 'Read-only: this key comes from the environment that launched dsh. Unset it there and restart dsh to change it here.'
+                                  : (isRemoved ? 'Restore' : (confirm[masked] === true ? 'Click again to confirm' : 'Delete')),
                                 danger: !isRemoved,
                                 className: isRemoved ? 'dts-icon-btn' : 'dts-icon-btn dts-icon-btn-danger',
                                 onClick: () => isRemoved ? restore(masked) : markRemoved(masked),
-                                disabled: busy
+                                disabled: busy || (key.removable === false && !isRemoved)
                               })
                             )
                       )
@@ -439,35 +370,27 @@ export function factory(require) {
               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 card the host renders. 0.1.6-alpha.2 asks a bundle-config entry for
-  // `view: 'page'` only; the legacy keyed settings slot passes no view at all.
+  // 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 react.createElement(TavilySummary, null)
+    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)
   }
 
-  // One-liner for the summary view. Deliberately static and cheap: the page
-  // draws the title, the icon, and the crumb itself, and never asks this entry
-  // for anything but `page`.
-  function TavilySummary() {
-    return react.createElement('p', { style: { margin: 0, fontSize: 12, color: 'var(--dsw-alias-label-tertiary)' } },
-      'Rotating Tavily API keys for the advanced search tools. The built-in web_search keeps its native provider and is never replaced.'
-    )
-  }
-
   function apply(ctx) {
-    // 0.1.6-alpha.2 moved plugin configuration off the Settings page and
-    // replaced the keyed `settings.plugin.item` slot with the Plugins page's
-    // `plugins.*` family (`dsh-client-ui-plugin-manager` declares it).
-    // `slots.inject` fires only for a slot the host actually declares, so
-    // injecting both IS the feature detection: exactly one mounts per harness
-    // line, and neither throws on the other. Keep both -- dropping the retired
-    // name silently removes the card from rc.7 through 0.1.6-alpha.1, and
-    // dropping the new one silently removes it from 0.1.6-alpha.2 onward.
+    // 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
@@ -475,18 +398,6 @@ export function factory(require) {
       key: '@moguiyu/dsh-tavily',
       id: '@moguiyu/dsh-tavily'
     }, TavilyCard))
-
-    ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({
-      name: 'settings.plugin.item',
-      // rc.7 through 0.1.6-alpha.1: 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'
-    }, TavilyCard))
   }
 
   return { apply, inject }