@moguiyu/dsh-tavily 0.3.2 → 0.3.4

package/src/backend.js

@@ -11,11 +11,26 @@
 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'
+import { STRATEGIES, accountFingerprint, clampAccountCap, groupAccounts, isValidStrategy, maskValue, parseKeyList, orderKeys, readJsonFile } from './lib.js'
 
-const USAGE_TTL_MS = 60000
+/**
+ * Tavily allows only **10 `/usage` requests per 10 minutes** per key, so the
+ * card's refreshes must not each become an upstream call: entries are served
+ * for two minutes, and a 429 stops asking for as long as `Retry-After` says
+ * (ten minutes by default) while the numbers already loaded keep being served.
+ */
+const USAGE_TTL_MS = 120000
+const USAGE_BACKOFF_MS = 600000
 const usageCache = new Map()
 
+/**
+ * Test seam: age every cache entry so the next read is a real upstream call.
+ * The cache is module-scoped and time-based, which no test can otherwise reach.
+ */
+export function ageUsageCache(ms) {
+  for (const [key, entry] of usageCache) usageCache.set(key, { ...entry, at: entry.at - ms })
+}
+
 const MANAGER_STATE = 'tavily-manager.json'
 const LEGACY_STATE = 'tavily-settings.json'
 const REFS = ['TAVILY_API_KEYS', 'TAVILY_API_KEY']
@@ -50,7 +65,11 @@ function readBody(req) {
 
 async function fetchUsageDetailsFor(key) {
   const cached = usageCache.get(key)
-  if (cached !== undefined && Date.now() - cached.at < USAGE_TTL_MS) return cached.details
+  const now = Date.now()
+  if (cached !== undefined) {
+    if (cached.until !== undefined && now < cached.until) return cached.details
+    if (now - cached.at < USAGE_TTL_MS) return cached.details
+  }
   try {
     const controller = new AbortController()
     const timer = setTimeout(() => controller.abort(), 15000)
@@ -63,7 +82,18 @@ async function fetchUsageDetailsFor(key) {
     } finally {
       clearTimeout(timer)
     }
-    if (!response.ok) return null
+    if (!response.ok) {
+      if (response.status === 429) {
+        const header = response.headers !== undefined && typeof response.headers.get === 'function'
+          ? Number(response.headers.get('retry-after'))
+          : NaN
+        const waitMs = Number.isFinite(header) && header > 0 ? header * 1000 : USAGE_BACKOFF_MS
+        const details = cached !== undefined ? cached.details : null
+        usageCache.set(key, { at: cached !== undefined ? cached.at : now, details, until: now + waitMs })
+        return details
+      }
+      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
@@ -81,7 +111,7 @@ async function fetchUsageDetailsFor(key) {
       ? account.plan
       : (keyUsage !== undefined && typeof keyUsage.plan === 'string' ? keyUsage.plan : null)
     if (usage === null && planUsage === null) return null
-    const details = { usage, planUsage, planLimit, currentPlan }
+    const details = { usage, planUsage, planLimit, currentPlan, accountId: accountFingerprint(account) }
     usageCache.set(key, { at: Date.now(), details })
     return details
   } catch {
@@ -166,6 +196,35 @@ async function syncPrimary(credentials, value) {
   }
 }
 
+/**
+ * Apply the card's per-key account choices to the stored grouping.
+ *
+ * `auto` drops the entry so the next usage scan infers it again, `own` pins the
+ * key as its own account (the escape hatch when the inference wrongly merges two
+ * accounts), and any other string joins that group. Unknown keys are ignored.
+ */
+function applyAccountOverrides(previous, patch, keys) {
+  const next = previous !== null && previous !== undefined && typeof previous === 'object' && !Array.isArray(previous)
+    ? { ...previous }
+    : {}
+  const known = new Set(keys.map((key) => maskValue(key)))
+  for (const [masked, choice] of Object.entries(patch)) {
+    if (!known.has(masked)) continue
+    if (choice === null || choice === undefined || choice === 'auto') {
+      delete next[masked]
+      continue
+    }
+    if (choice === 'own') {
+      next[masked] = { group: 'own:' + masked, manual: true }
+      continue
+    }
+    if (typeof choice === 'string' && choice.length > 0) {
+      next[masked] = { group: choice, manual: true }
+    }
+  }
+  return next
+}
+
 /**
  * Register the Tavily key/usage routes on `ctx.webServer`:
  * `/api/tavily-usage` and `/api/tavily-manager`.
@@ -229,6 +288,12 @@ export function installBackend(ctx) {
         removable,
       })),
       strategy: isValidStrategy(state.strategy) ? state.strategy : 'rotate',
+      // The tools half reads these from the state file; the card needs them to
+      // show which keys share an account and to offer the per-key override.
+      accounts: state.accounts !== null && state.accounts !== undefined && typeof state.accounts === 'object' && !Array.isArray(state.accounts)
+        ? state.accounts
+        : {},
+      accountCap: clampAccountCap(state.accountCap),
       source,
       writable: { keys: keysWritable, primary: primaryWritable },
     }
@@ -253,20 +318,44 @@ export function installBackend(ctx) {
           return am < bm ? -1 : 1
         })
         const perKey = []
+        const entries = []
         for (const key of orderedKeys) {
+          const masked = maskValue(key)
           try {
             const usage = await fetchUsageDetailsFor(key)
-            perKey.push(usage !== null
-              ? { ok: true, masked: maskValue(key), ...usage }
-              : { ok: false, masked: maskValue(key), error: 'usage unavailable' })
+            if (usage !== null) {
+              perKey.push({
+                ok: true,
+                masked,
+                usage: usage.usage,
+                planUsage: usage.planUsage,
+                planLimit: usage.planLimit,
+                currentPlan: usage.currentPlan,
+              })
+              entries.push({ masked, fingerprint: typeof usage.accountId === 'string' ? usage.accountId : null })
+            } else {
+              perKey.push({ ok: false, masked, error: 'usage unavailable' })
+              entries.push({ masked, fingerprint: null })
+            }
           } catch (error) {
-            perKey.push({ ok: false, masked: maskValue(key), error: String(error && error.message ? error.message : error) })
+            perKey.push({ ok: false, masked, error: String(error && error.message ? error.message : error) })
+            entries.push({ masked, fingerprint: null })
           }
         }
+        // Tavily has no account id, so the account block each key reports is the
+        // only grouping signal there is. Recompute it here (the one place that
+        // already pays for `/usage`), persist it, and hand it to the card.
+        const accounts = groupAccounts(entries, state.accounts)
+        const accountCap = clampAccountCap(state.accountCap)
+        if (JSON.stringify(state.accounts ?? null) !== JSON.stringify(accounts)) {
+          writeState(MANAGER_STATE, { ...state, accounts, accountCap })
+        }
         const okRows = perKey.filter((row) => row.ok)
         return send(res, 200, {
           ok: true,
           perKey,
+          accounts,
+          accountCap,
           totals: {
             keys: keys.length,
             okKeys: okRows.length,
@@ -343,7 +432,10 @@ export function installBackend(ctx) {
             await credentials.unset('TAVILY_API_KEYS')
             await syncPrimary(credentials, null)
           } else {
-            if (strategy !== 'rotate') {
+            // Only the usage-ordered strategies need Tavily's counters, and
+            // `/usage` allows just 10 requests per 10 minutes: never spend one
+            // on a strategy that keeps the list order anyway.
+            if (strategy === 'low-usage-first' || strategy === 'high-usage-first') {
               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)
@@ -362,7 +454,14 @@ export function installBackend(ctx) {
             const masked = maskValue(value)
             if (keySavedAt[masked] === undefined) keySavedAt[masked] = now
           }
-          writeState(MANAGER_STATE, { keySavedAt, strategy })
+          // Spread the previous state: writing only these two keys used to drop
+          // every other one — including the account grouping and the cap.
+          const nextState = { ...state, keySavedAt, strategy }
+          if (body.accountCap !== undefined) nextState.accountCap = clampAccountCap(body.accountCap)
+          if (body.accounts !== null && body.accounts !== undefined && typeof body.accounts === 'object' && !Array.isArray(body.accounts)) {
+            nextState.accounts = applyAccountOverrides(state.accounts, body.accounts, values)
+          }
+          writeState(MANAGER_STATE, nextState)
 
           return send(res, 200, { ok: true, ...(await buildManagerPayload(values, source)) })
         }

package/src/client.js

@@ -11,11 +11,18 @@ export function factory(require) {
   const inject = ['slots']
 
   const STRATEGIES = [
-    { id: 'rotate', label: 'Round-robin', hint: 'Use keys in turn; on HTTP 401/429 the next key is tried automatically.' },
+    { id: 'rotate', label: 'Round-robin', hint: 'Use keys in turn; on HTTP 401/429/432/433 the next key is tried automatically.' },
     { id: 'low-usage-first', label: 'Lowest usage first', hint: 'Re-orders keys by current Tavily usage, least-used first. The first key becomes primary.' },
-    { id: 'high-usage-first', label: 'Highest usage first', hint: 'Re-orders keys by current Tavily usage, most-used first. The first key becomes primary.' }
+    { id: 'high-usage-first', label: 'Highest usage first', hint: 'Re-orders keys by current Tavily usage, most-used first. The first key becomes primary.' },
+    {
+      id: 'load-balance',
+      label: 'Load balance',
+      hint: 'Keeps at most the set number of requests in flight per Tavily account and spreads concurrent calls across accounts, so one free account is never hit in parallel. Accounts are inferred from live Tavily usage data — pin a key below if that is wrong. Keys on one account share its 100 requests/minute.'
+    }
   ]
 
+  const ACCOUNT_CAPS = [1, 2, 3, 4, 5, 6, 7, 8]
+
   const ICONS = {
     eye: ['M1.5 8C1.5 8 4 3.5 8 3.5S14.5 8 14.5 8 12 12.5 8 12.5 1.5 8 1.5 8Z', 'M8 5.8a2.2 2.2 0 1 0 0 4.4 2.2 2.2 0 0 0 0-4.4Z'],
     eyeOff: ['M1.5 8C1.5 8 4 3.5 8 3.5c1.6 0 3 .5 4.1 1.2', 'M14.5 8C14.5 8 12 12.5 8 12.5c-1.6 0-3-.5-4.1-1.2', 'M2 2l12 12', 'M8 5.8a2.2 2.2 0 0 1 2.2 2.2'],
@@ -37,6 +44,113 @@ export function factory(require) {
     return d.getFullYear() + '-' + pad(d.getMonth() + 1) + '-' + pad(d.getDate())
   }
 
+  function formatClock(iso) {
+    if (!iso) return null
+    const d = new Date(iso)
+    if (isNaN(d.getTime())) return null
+    const pad = (n) => String(n).padStart(2, '0')
+    return pad(d.getHours()) + ':' + pad(d.getMinutes())
+  }
+
+  // `/api/tavily-usage` asks Tavily for every key's counters, so it can take a
+  // while. Two rules follow: the cell must never look *empty* while that is in
+  // flight, and the last values already shown must survive a page reload. Only
+  // masked names and counters are stored — never key material.
+  const USAGE_SNAPSHOT_KEY = 'dsh-tavily:usage-snapshot:v1'
+  const RING_GROWTH_MS = 650
+
+  function usageStorage() {
+    try {
+      if (typeof window === 'undefined' || window === null || !window.localStorage) return null
+      return window.localStorage
+    } catch (error) {
+      return null
+    }
+  }
+
+  function readUsageSnapshot() {
+    const storage = usageStorage()
+    if (storage === null) return null
+    try {
+      const parsed = JSON.parse(storage.getItem(USAGE_SNAPSHOT_KEY))
+      if (parsed === null || typeof parsed !== 'object') return null
+      if (parsed.version !== 1) return null
+      if (parsed.rows === null || typeof parsed.rows !== 'object') return null
+      return parsed
+    } catch (error) {
+      return null
+    }
+  }
+
+  function writeUsageSnapshot(data) {
+    const storage = usageStorage()
+    if (storage === null) return
+    try {
+      const perKey = data !== null && data !== undefined && Array.isArray(data.perKey) ? data.perKey : []
+      const rows = {}
+      for (const row of perKey) {
+        if (row === null || typeof row !== 'object' || typeof row.masked !== 'string') continue
+        rows[row.masked] = {
+          ok: row.ok === true,
+          usage: typeof row.usage === 'number' ? row.usage : null,
+          planUsage: typeof row.planUsage === 'number' ? row.planUsage : null,
+          planLimit: typeof row.planLimit === 'number' ? row.planLimit : null
+        }
+      }
+      if (Object.keys(rows).length === 0) return
+      storage.setItem(USAGE_SNAPSHOT_KEY, JSON.stringify({ version: 1, at: new Date().toISOString(), rows: rows }))
+    } catch (error) {
+      /* storage is best-effort; the card still works without it */
+    }
+  }
+
+  function usagePercent(row) {
+    if (row === null || row === undefined || row.ok !== true) return null
+    if (row.planLimit === null || row.planLimit === undefined || row.planLimit <= 0) return null
+    if (row.planUsage === null || row.planUsage === undefined) return null
+    return Math.min(100, Math.round((row.planUsage / row.planLimit) * 100))
+  }
+
+  /**
+   * Count a number up to `target` instead of swapping it. Returns the value to
+   * paint now. A first-ever value (or a non-number) is set instantly: there is
+   * nothing to grow from.
+   */
+  function useAnimatedNumber(target, durationMs) {
+    const [display, setDisplay] = react.useState(target)
+    const displayRef = react.useRef(target)
+    const frameRef = react.useRef(0)
+    react.useEffect(() => {
+      const from = typeof displayRef.current === 'number' ? displayRef.current : null
+      const settle = (value) => { displayRef.current = value; setDisplay(value) }
+      if (typeof target !== 'number' || from === null || from === target) {
+        settle(typeof target === 'number' ? target : null)
+        return undefined
+      }
+      if (typeof requestAnimationFrame !== 'function') {
+        settle(target)
+        return undefined
+      }
+      let started = null
+      const tick = (now) => {
+        const stamp = typeof now === 'number' ? now : Date.now()
+        if (started === null) started = stamp
+        const elapsed = durationMs > 0 ? (stamp - started) / durationMs : 1
+        const t = Math.min(1, Math.max(0, elapsed))
+        const eased = 1 - Math.pow(1 - t, 3)
+        const next = t >= 1 ? target : Math.round(from + (target - from) * eased)
+        displayRef.current = next
+        setDisplay(next)
+        if (t < 1) frameRef.current = requestAnimationFrame(tick)
+      }
+      frameRef.current = requestAnimationFrame(tick)
+      return () => {
+        if (typeof cancelAnimationFrame === 'function' && frameRef.current) cancelAnimationFrame(frameRef.current)
+      }
+    }, [target, durationMs])
+    return display
+  }
+
   function SvgIcon({ name, size, style }) {
     const paths = ICONS[name] || []
     return react.createElement('svg', { width: size || 14, height: size || 14, viewBox: '0 0 16 16', fill: 'none', stroke: 'currentColor', strokeWidth: 1.4, strokeLinecap: 'round', strokeLinejoin: 'round', 'aria-hidden': 'true', style: style },
@@ -56,17 +170,54 @@ export function factory(require) {
     }, react.createElement(SvgIcon, { name: icon, size: 13 }))
   }
 
-  function UsageCircle({ percent, size, label, onClick }) {
+  function UsageCircle({ percent, number, loading, stale, staleAt, onClick }) {
     const radius = 15
     const circumference = 2 * Math.PI * radius
     const pct = percent != null ? Math.min(100, Math.max(0, percent)) : 0
-    const dim = size || 44
-    return react.createElement('button', { type: 'button', title: 'Reload usage', 'aria-label': 'Reload usage', onClick: onClick, style: { position: 'relative', width: dim, height: dim, border: 'none', background: 'transparent', padding: 0, cursor: 'pointer', display: 'inline-flex', alignItems: 'center', justifyContent: 'center' } },
-      react.createElement('svg', { width: dim, height: dim, viewBox: '0 0 40 40' },
+    const dim = 44
+    const animated = useAnimatedNumber(percent != null ? percent : (number != null ? number : null), RING_GROWTH_MS)
+    const shown = animated != null ? animated : (number != null ? number : null)
+    const offset = circumference - (pct / 100) * circumference
+    const label = percent != null
+      ? (shown != null ? shown + '%' : '—')
+      : (shown != null ? String(shown) : '—')
+    const clock = formatClock(staleAt)
+    const title = loading
+      ? (stale && clock !== null ? 'Updating usage… showing the values loaded at ' + clock : 'Updating usage…')
+      : (stale && clock !== null ? 'Showing the values loaded at ' + clock + ' — click to refresh' : 'Reload usage')
+    return react.createElement('button', {
+      type: 'button',
+      title: title,
+      'aria-label': 'Reload usage',
+      'aria-busy': loading ? 'true' : 'false',
+      'data-loading': loading ? 'true' : 'false',
+      'data-stale': stale ? 'true' : 'false',
+      onClick: onClick,
+      style: { position: 'relative', width: dim, height: dim, border: 'none', background: 'transparent', padding: 0, cursor: 'pointer', display: 'inline-flex', alignItems: 'center', justifyContent: 'center' }
+    },
+      react.createElement('svg', { width: dim, height: dim, viewBox: '0 0 40 40', className: loading ? 'dts-ring dts-ring-loading' : 'dts-ring' },
         react.createElement('circle', { cx: 20, cy: 20, r: radius, fill: 'none', stroke: 'var(--dsw-alias-border-l2)', strokeWidth: 4 }),
-        react.createElement('circle', { cx: 20, cy: 20, r: radius, fill: 'none', stroke: 'var(--dsw-alias-state-success-primary)', strokeWidth: 4, strokeLinecap: 'round', strokeDasharray: circumference, strokeDashoffset: circumference - (pct / 100) * circumference, transform: 'rotate(-90 20 20)' })
+        react.createElement('circle', {
+          className: 'dts-ring-progress',
+          cx: 20, cy: 20, r: radius, fill: 'none',
+          stroke: 'var(--dsw-alias-state-success-primary)', strokeWidth: 4, strokeLinecap: 'round',
+          strokeDasharray: circumference,
+          strokeDashoffset: offset,
+          transform: 'rotate(-90 20 20)',
+          // The offset is carried as a style value as well as an attribute:
+          // presentation attributes alone do not reliably transition.
+          style: { strokeDashoffset: offset, transition: 'stroke-dashoffset ' + RING_GROWTH_MS + 'ms cubic-bezier(.22,.61,.36,1)' }
+        }),
+        loading && react.createElement('g', { className: 'dts-ring-sweep', style: { transformOrigin: '20px 20px' } },
+          react.createElement('circle', {
+            cx: 20, cy: 20, r: radius, fill: 'none',
+            stroke: 'var(--dsw-alias-state-success-primary)', strokeWidth: 4, strokeLinecap: 'round',
+            strokeDasharray: (circumference * 0.22) + ' ' + (circumference * 0.78),
+            opacity: 0.45
+          })
+        )
       ),
-      react.createElement('span', { style: { position: 'absolute', fontSize: 11, fontWeight: 600, color: 'var(--dsw-alias-label-primary)' } }, label != null ? label : (percent != null ? percent + '%' : '—'))
+      react.createElement('span', { className: 'dts-ring-label', style: { position: 'absolute', fontSize: 11, fontWeight: 600, color: 'var(--dsw-alias-label-primary)' } }, label)
     )
   }
 
@@ -84,39 +235,98 @@ export function factory(require) {
     const [notice, setNotice] = react.useState(null)
     const [usage, setUsage] = react.useState(null)
     const [usageError, setUsageError] = react.useState(null)
+    const [usageLoading, setUsageLoading] = react.useState(true)
+    const [snapshot, setSnapshot] = react.useState(() => readUsageSnapshot())
 
     const refresh = react.useCallback(async () => {
+      setUsageLoading(true)
+      // The two endpoints are independent and the usage one is the slow half,
+      // so they run together: the keys must not wait for Tavily's counters.
+      const keys = (async () => {
+        try {
+          const response = await fetch('/api/tavily-manager', { cache: 'no-store' })
+          const data = await response.json()
+          if (data.ok) { setServer(data); setStrategy(data.strategy) } else { setLoadError(data.error || 'Failed to load keys') }
+        } catch (error) {
+          setLoadError(String(error && error.message ? error.message : error))
+        }
+      })()
+      const counters = (async () => {
+        try {
+          const response = await fetch('/api/tavily-usage', { cache: 'no-store' })
+          const data = await response.json()
+          setUsage(data)
+          setUsageError(null)
+          if (data.ok) {
+            writeUsageSnapshot(data)
+            setSnapshot(readUsageSnapshot())
+          }
+        } catch (error) {
+          setUsageError(String(error && error.message ? error.message : error))
+        } finally {
+          setUsageLoading(false)
+        }
+      })()
+      await Promise.all([keys, counters])
+    }, [])
+
+    react.useEffect(() => { refresh() }, [refresh])
+
+    const saveStrategy = async (next) => {
+      setBusy(true)
+      setNotice(null)
       try {
-        const response = await fetch('/api/tavily-manager', { cache: 'no-store' })
+        const response = await fetch('/api/tavily-manager', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ add: [], remove: [], strategy: next })
+        })
         const data = await response.json()
-        if (data.ok) { setServer(data); setStrategy(data.strategy) } else { setLoadError(data.error || 'Failed to load keys') }
+        if (!data.ok) { setNotice({ error: data.error || 'Strategy save failed' }); return }
+        setNotice({ ok: 'Strategy saved — effective on the next search.' })
+        await refresh()
       } catch (error) {
-        setLoadError(String(error && error.message ? error.message : error))
+        setNotice({ error: String(error && error.message ? error.message : error) })
+      } finally {
+        setBusy(false)
       }
+    }
+
+    // The account grouping is inferred from Tavily's usage counters, which is
+    // the only account-level signal the API offers; these two handlers are the
+    // human override for when the inference is wrong or the cap needs raising.
+    const saveAccount = async (masked, choice) => {
+      setBusy(true)
+      setNotice(null)
       try {
-        const response = await fetch('/api/tavily-usage', { cache: 'no-store' })
+        const response = await fetch('/api/tavily-manager', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ add: [], remove: [], strategy, accounts: { [masked]: choice } })
+        })
         const data = await response.json()
-        setUsage(data)
-        setUsageError(null)
+        if (!data.ok) { setNotice({ error: data.error || 'Account change failed' }); return }
+        setNotice({ ok: choice === 'auto' ? 'Account detected automatically again.' : 'Account pinned for this key.' })
+        await refresh()
       } catch (error) {
-        setUsageError(String(error && error.message ? error.message : error))
+        setNotice({ error: String(error && error.message ? error.message : error) })
+      } finally {
+        setBusy(false)
       }
-    }, [])
-
-    react.useEffect(() => { refresh() }, [refresh])
+    }
 
-    const saveStrategy = async (next) => {
+    const saveCap = async (value) => {
       setBusy(true)
       setNotice(null)
       try {
         const response = await fetch('/api/tavily-manager', {
           method: 'POST',
           headers: { 'content-type': 'application/json' },
-          body: JSON.stringify({ add: [], remove: [], strategy: next })
+          body: JSON.stringify({ add: [], remove: [], strategy, accountCap: Number(value) })
         })
         const data = await response.json()
-        if (!data.ok) { setNotice({ error: data.error || 'Strategy save failed' }); return }
-        setNotice({ ok: 'Strategy saved — effective on the next search.' })
+        if (!data.ok) { setNotice({ error: data.error || 'Cap save failed' }); return }
+        setNotice({ ok: 'Concurrency cap saved — effective on the next search.' })
         await refresh()
       } catch (error) {
         setNotice({ error: String(error && error.message ? error.message : error) })
@@ -244,12 +454,45 @@ 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 snapshotRows = snapshot !== null && typeof snapshot === 'object' && snapshot.rows !== null && typeof snapshot.rows === 'object'
+      ? snapshot.rows
+      : null
+    const snapshotAt = snapshot !== null && typeof snapshot === 'object' ? snapshot.at : null
+
+    // The usage response carries the freshest inference (it is the route that
+    // runs it); the manager payload is the fallback, and the only source of the
+    // policy before the first usage answer arrives.
+    const accountsMap = usage !== null && usage.ok === true && usage.accounts !== null && typeof usage.accounts === 'object'
+      ? usage.accounts
+      : (server !== null && server.accounts !== null && server.accounts !== undefined && typeof server.accounts === 'object' ? server.accounts : {})
+    const accountCap = usage !== null && usage.ok === true && typeof usage.accountCap === 'number'
+      ? usage.accountCap
+      : (server !== null && typeof server.accountCap === 'number' ? server.accountCap : 1)
+    const accountOf = (masked) => {
+      const entry = accountsMap[masked]
+      const group = entry !== null && entry !== undefined && typeof entry === 'object' && typeof entry.group === 'string' ? entry.group : null
+      return {
+        group,
+        own: group !== null && group.indexOf('own:') === 0,
+        manual: entry !== null && entry !== undefined && entry.manual === true,
+      }
+    }
+    const accountLabel = (group) => {
+      const name = /^acct-(\d+)$/.exec(group)
+      return name === null ? group : 'Account ' + name[1]
+    }
+    const groupChoices = []
+    for (const key of (server !== null ? server.keys : [])) {
+      const { group, own } = accountOf(key.masked)
+      if (group === null || own) continue
+      if (!groupChoices.includes(group)) groupChoices.push(group)
+    }
 
     // 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('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)}@keyframes dts-ring-spin{to{transform:rotate(360deg)}}@keyframes dts-ring-pulse{0%,100%{opacity:1}50%{opacity:.45}}.dts-ring-loading{animation:dts-ring-pulse 1.6s ease-in-out infinite}.dts-ring-sweep{animation:dts-ring-spin 1.1s linear infinite}@media (prefers-reduced-motion: reduce){.dts-ring-loading,.dts-ring-sweep{animation:none}.dts-ring-progress{transition:none!important}}'),
       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.'
@@ -263,6 +506,7 @@ export function factory(require) {
                 react.createElement('thead', null,
                   react.createElement('tr', null,
                     react.createElement('th', { style: headStyle }, 'Key'),
+                    react.createElement('th', { style: headStyle }, 'Account'),
                     react.createElement('th', { style: headStyle }, 'Usage'),
                     react.createElement('th', { style: headStyle }, 'Saved'),
                     react.createElement('th', { style: headStyle }, 'Actions')
@@ -274,12 +518,27 @@ export function factory(require) {
                     const isRemoved = removing[masked] === true
                     const isReplacing = replacing[masked] === true
                     const isRevealed = typeof revealed[masked] === 'string'
-                    const usageRow = usage !== null && usage.ok === true
+                    // Fresh counters win; until they arrive the last stored row is
+                    // shown so the cell reads as "updating", never as "empty".
+                    const freshRow = usage !== null && usage.ok === true
                       ? (usage.perKey.find((row) => row.masked === masked) || usage.perKey[index])
                       : null
-                    const pct = usageRow && usageRow.ok && usageRow.planLimit != null && usageRow.planLimit > 0 && usageRow.planUsage != null
-                      ? Math.min(100, Math.round((usageRow.planUsage / usageRow.planLimit) * 100))
+                    const storedRow = snapshotRows !== null && Object.prototype.hasOwnProperty.call(snapshotRows, masked)
+                      ? snapshotRows[masked]
+                      : null
+                    const usageRow = freshRow !== null && freshRow !== undefined ? freshRow : storedRow
+                    const pct = usagePercent(usageRow)
+                    const rawNumber = pct === null && usageRow !== null && usageRow !== undefined && usageRow.ok === true && usageRow.planUsage != null
+                      ? usageRow.planUsage
                       : null
+                    const isStale = (freshRow === null || freshRow === undefined) && storedRow !== null
+                    // Which Tavily account this key belongs to, and the override.
+                    const account = accountOf(masked)
+                    const currentChoice = account.manual ? (account.own ? 'own' : account.group) : 'auto'
+                    const accountChoices = ['auto'].concat(groupChoices).concat(['own'])
+                    if (currentChoice !== 'auto' && !accountChoices.includes(currentChoice)) {
+                      accountChoices.splice(1, 0, currentChoice)
+                    }
                     return react.createElement('tr', { key: masked, style: { borderBottom: '1px solid var(--dsw-alias-border-l2)', opacity: isRemoved ? 0.45 : 1 } },
                       react.createElement('td', { style: Object.assign({}, cellStyle, { fontFamily: 'var(--ds-font-family-code, monospace)', fontSize: 12, wordBreak: 'break-all' }) },
                         isReplacing
@@ -299,7 +558,34 @@ export function factory(require) {
                             )
                       ),
                       react.createElement('td', { style: cellStyle },
-                        react.createElement(UsageCircle, { percent: pct, label: pct != null ? pct + '%' : (usageRow && usageRow.ok && usageRow.planUsage != null ? String(usageRow.planUsage) : '—'), onClick: refresh })
+                        react.createElement('div', { style: { display: 'flex', flexDirection: 'column', gap: 4 } },
+                          react.createElement('span', {
+                            className: 'dts-account-chip',
+                            style: { fontSize: 11, color: account.group === null ? 'var(--dsw-alias-label-tertiary)' : 'var(--dsw-alias-label-secondary)' }
+                          }, account.group === null ? 'Ungrouped' : (account.own ? 'Separate' : accountLabel(account.group))),
+                          react.createElement('select', {
+                            className: 'dts-account',
+                            'data-masked': masked,
+                            title: 'Which Tavily account this key counts against. Auto follows the grouping inferred from usage; Separate gives the key its own account, so it is never held back by another key.',
+                            value: currentChoice,
+                            disabled: busy,
+                            onChange: (event) => saveAccount(masked, event.target.value),
+                            style: { height: 26, borderRadius: 6, border: '1px solid var(--dsw-alias-border-l2)', background: 'var(--dsw-alias-bg-layer-1)', color: 'var(--dsw-alias-label-primary)', fontSize: 11, maxWidth: 130 }
+                          },
+                            accountChoices.map((choice) => react.createElement('option', { key: choice, value: choice },
+                              choice === 'auto' ? 'Auto' : (choice === 'own' ? 'Separate' : accountLabel(choice))))
+                          )
+                        )
+                      ),
+                      react.createElement('td', { style: cellStyle },
+                        react.createElement(UsageCircle, {
+                          percent: pct,
+                          number: rawNumber,
+                          loading: usageLoading,
+                          stale: isStale,
+                          staleAt: snapshotAt,
+                          onClick: refresh
+                        })
                       ),
                       react.createElement('td', { style: Object.assign({}, cellStyle, { color: 'var(--dsw-alias-label-tertiary)', whiteSpace: 'nowrap' }) }, formatDate(key.savedAt)),
                       react.createElement('td', { style: cellStyle },
@@ -340,6 +626,7 @@ export function factory(require) {
                     ),
                     react.createElement('td', { style: cellStyle }, '—'),
                     react.createElement('td', { style: cellStyle }, '—'),
+                    react.createElement('td', { style: cellStyle }, '—'),
                     react.createElement('td', { style: cellStyle },
                       react.createElement('span', { style: { display: 'inline-flex', gap: 2 } },
                         react.createElement(IconButton, { icon: 'check', title: 'Save key', onClick: () => saveAdd(item), disabled: busy || item.value.trim().length === 0 }),
@@ -356,11 +643,21 @@ export function factory(require) {
                 react.createElement('div', { style: { display: 'flex', alignItems: 'center', gap: 8, flexWrap: 'wrap' } },
                   react.createElement('label', { style: { fontWeight: 500, fontSize: 13 } }, 'Key usage strategy'),
                   react.createElement('select', {
+                    className: 'dts-strategy',
                     style: { maxWidth: 280, height: 32, border: '1px solid var(--dsw-alias-border-l2)', borderRadius: 8, background: 'var(--dsw-alias-bg-layer-1)', color: 'var(--dsw-alias-label-primary)', padding: '0 10px', fontSize: 13 },
                     value: strategy,
                     onChange: (event) => saveStrategy(event.target.value),
                     disabled: busy
                   }, STRATEGIES.map((option) => react.createElement('option', { key: option.id, value: option.id }, option.label))),
+                  strategy === 'load-balance' && react.createElement('label', { style: { fontWeight: 500, fontSize: 13, marginLeft: 8 } }, 'Per account'),
+                  strategy === 'load-balance' && react.createElement('select', {
+                    className: 'dts-account-cap',
+                    title: 'How many requests may be in flight for one Tavily account at a time. One suits a free key.',
+                    style: { height: 32, border: '1px solid var(--dsw-alias-border-l2)', borderRadius: 8, background: 'var(--dsw-alias-bg-layer-1)', color: 'var(--dsw-alias-label-primary)', padding: '0 10px', fontSize: 13 },
+                    value: String(accountCap),
+                    onChange: (event) => saveCap(event.target.value),
+                    disabled: busy
+                  }, ACCOUNT_CAPS.map((n) => react.createElement('option', { key: n, value: String(n) }, String(n) + (n === 1 ? ' request' : ' requests')))),
                   notice !== null && react.createElement('span', { style: { fontSize: 13, color: notice.ok ? 'var(--dsw-alias-state-success-primary)' : 'var(--dsw-alias-state-error-primary)' } }, notice.ok ? notice.ok : String(notice.error))
                 ),
                 react.createElement('p', { style: { margin: 0, fontSize: 12, color: 'var(--dsw-alias-label-tertiary)' } },