@moguiyu/dsh-tavily 0.3.3 → 0.3.4

package/README.md

@@ -29,4 +29,5 @@ which is exactly how the old tool-level switch broke. Both old packages are depr
 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.
+See the [workspace README](https://github.com/moguiyu/dsh-tavily#readme) for install and
+configuration.

package/lib/client.js

@@ -6,11 +6,18 @@ window.__ModuleLoader__.load({
   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'],
@@ -280,6 +287,49 @@ window.__ModuleLoader__.load({
       }
     }
 
+    // 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-manager', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ add: [], remove: [], strategy, accounts: { [masked]: choice } })
+        })
+        const data = await response.json()
+        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) {
+        setNotice({ error: String(error && error.message ? error.message : error) })
+      } finally {
+        setBusy(false)
+      }
+    }
+
+    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, accountCap: Number(value) })
+        })
+        const data = await response.json()
+        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) })
+      } finally {
+        setBusy(false)
+      }
+    }
+
     const saveAdd = async (item) => {
       const value = item.value.trim()
       if (!value) return
@@ -404,6 +454,35 @@ window.__ModuleLoader__.load({
       : 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.
@@ -422,6 +501,7 @@ window.__ModuleLoader__.load({
                 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')
@@ -447,6 +527,13 @@ window.__ModuleLoader__.load({
                       ? 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
@@ -465,6 +552,26 @@ window.__ModuleLoader__.load({
                               })
                             )
                       ),
+                      react.createElement('td', { style: cellStyle },
+                        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,
@@ -514,6 +621,7 @@ window.__ModuleLoader__.load({
                     ),
                     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 }),
@@ -530,11 +638,21 @@ window.__ModuleLoader__.load({
                 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)' } },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@moguiyu/dsh-tavily",
-  "version": "0.3.3",
-  "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.",
+  "version": "0.3.4",
+  "description": "Advanced Tavily model tools for DeepSeek Harness (tavily_search, tavily_extract, tavily_map, tavily_crawl) with multi-key rotation, failover and a per-account in-flight cap, plus a key and usage management card on the Plugins page. The built-in web_search is never replaced. | DSH Tavily 可选高级搜索工具：多 Key 轮换、故障转移与按账号并发上限，插件配置页含密钥与用量管理卡片；内置 web_search 永不替换。",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
@@ -64,7 +64,8 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/moguiyu/dsh-tavily.git"
+    "url": "git+https://github.com/moguiyu/dsh-tavily.git",
+    "directory": "packages/dsh-tavily"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",

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'],
@@ -285,6 +292,49 @@ export function factory(require) {
       }
     }
 
+    // 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-manager', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ add: [], remove: [], strategy, accounts: { [masked]: choice } })
+        })
+        const data = await response.json()
+        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) {
+        setNotice({ error: String(error && error.message ? error.message : error) })
+      } finally {
+        setBusy(false)
+      }
+    }
+
+    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, accountCap: Number(value) })
+        })
+        const data = await response.json()
+        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) })
+      } finally {
+        setBusy(false)
+      }
+    }
+
     const saveAdd = async (item) => {
       const value = item.value.trim()
       if (!value) return
@@ -409,6 +459,35 @@ export function factory(require) {
       : 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.
@@ -427,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')
@@ -452,6 +532,13 @@ export function factory(require) {
                       ? 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
@@ -470,6 +557,26 @@ export function factory(require) {
                               })
                             )
                       ),
+                      react.createElement('td', { style: cellStyle },
+                        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,
@@ -519,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 }),
@@ -535,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)' } },

package/src/lib.js

@@ -3,12 +3,130 @@
  */
 import { readFileSync } from 'node:fs'
 
-export const STRATEGIES = ['rotate', 'low-usage-first', 'high-usage-first']
+export const STRATEGIES = ['rotate', 'low-usage-first', 'high-usage-first', 'load-balance']
 
 export function isValidStrategy(value) {
   return STRATEGIES.includes(value)
 }
 
+/**
+ * Concurrent requests allowed per Tavily account in `load-balance` mode. One is
+ * the safe default: Tavily's published limits are per environment/key
+ * (100 requests/minute on a free Development key) and every key of one account
+ * shares that budget and its credit pool.
+ */
+export const DEFAULT_ACCOUNT_CAP = 1
+export const MAX_ACCOUNT_CAP = 8
+
+export function clampAccountCap(value) {
+  const n = Number(value)
+  if (!Number.isFinite(n)) return DEFAULT_ACCOUNT_CAP
+  return Math.min(MAX_ACCOUNT_CAP, Math.max(DEFAULT_ACCOUNT_CAP, Math.round(n)))
+}
+
+/** The `/usage` `account` fields that identify an account; order is canonical. */
+const ACCOUNT_FIELDS = [
+  'current_plan', 'plan', 'plan_limit', 'plan_usage', 'paygo_limit', 'paygo_usage',
+  'search_usage', 'extract_usage', 'map_usage', 'crawl_usage', 'research_usage',
+]
+
+/**
+ * Fingerprint a Tavily `/usage` `account` block. Tavily publishes no account id,
+ * but every key of one account reports the identical account block at the same
+ * moment (observed live: two keys both at search_usage 846 / extract 129 / map
+ * 23), so an equal fingerprint is the only account-level signal available.
+ * Returns `null` when the block carries no recognizable field, which means
+ * "makes no claim about the account" rather than "its own account".
+ */
+export function accountFingerprint(account) {
+  if (account === null || account === undefined || typeof account !== 'object' || Array.isArray(account)) return null
+  const parts = []
+  for (const field of ACCOUNT_FIELDS) {
+    const value = account[field]
+    if (value === undefined || value === null) continue
+    parts.push(field + '=' + String(value))
+  }
+  return parts.length === 0 ? null : parts.join('|')
+}
+
+/**
+ * Assign stable account group ids to the stored keys.
+ *
+ * `entries` is `[{ masked, fingerprint }]` in credential-list order; `previous`
+ * is the persisted `accounts` map. A `manual: true` entry is kept verbatim —
+ * that is the user's override — and offers its group id to keys that turn out
+ * to share its account. Inferred ids survive a re-run: a cluster carries over
+ * the id its own members already had instead of being renumbered, so usage
+ * drifting between fetches cannot reshuffle the groups.
+ */
+export function groupAccounts(entries, previous) {
+  const prior = previous !== null && previous !== undefined && typeof previous === 'object' && !Array.isArray(previous)
+    ? previous
+    : {}
+  const assigned = {}
+  const used = new Set()
+  const manualGroupByFingerprint = new Map()
+
+  for (const entry of entries) {
+    const before = prior[entry.masked]
+    if (before === null || before === undefined || typeof before !== 'object') continue
+    if (before.manual !== true) continue
+    if (typeof before.group !== 'string' || before.group.length === 0) continue
+    assigned[entry.masked] = { group: before.group, manual: true }
+    used.add(before.group)
+    if (typeof entry.fingerprint === 'string' && entry.fingerprint.length > 0 && !manualGroupByFingerprint.has(entry.fingerprint)) {
+      manualGroupByFingerprint.set(entry.fingerprint, before.group)
+    }
+  }
+
+  const clusters = new Map()
+  for (const entry of entries) {
+    if (assigned[entry.masked] !== undefined) continue
+    const fingerprint = typeof entry.fingerprint === 'string' && entry.fingerprint.length > 0 ? entry.fingerprint : null
+    if (fingerprint === null) continue
+    const members = clusters.get(fingerprint)
+    if (members === undefined) clusters.set(fingerprint, [entry.masked])
+    else members.push(entry.masked)
+  }
+
+  let next = 1
+  for (const [fingerprint, members] of clusters) {
+    const carried = new Map()
+    for (const masked of members) {
+      const before = prior[masked]
+      if (before !== null && before !== undefined && typeof before === 'object' &&
+        typeof before.group === 'string' && before.group.length > 0) {
+        carried.set(before.group, (carried.get(before.group) ?? 0) + 1)
+      }
+    }
+    let group = manualGroupByFingerprint.get(fingerprint)
+    if (group === undefined) {
+      let best = null
+      let bestCount = 0
+      for (const [id, count] of carried) {
+        if (count > bestCount) {
+          best = id
+          bestCount = count
+        }
+      }
+      if (best !== null) group = best
+    }
+    if (group === undefined) {
+      while (used.has('acct-' + next)) next += 1
+      group = 'acct-' + next
+      next += 1
+    }
+    used.add(group)
+    for (const masked of members) assigned[masked] = { group, manual: false }
+  }
+
+  const out = {}
+  for (const entry of entries) {
+    if (assigned[entry.masked] !== undefined) out[entry.masked] = assigned[entry.masked]
+  }
+  return out
+}
+
 /**
  * Mask a key for display: `first12…last4`; comma-separated lists are masked
  * per part. Never reveals more than a fingerprint.
@@ -39,10 +157,12 @@ export function parseKeyList(value) {
 
 /**
  * Order keys according to a strategy. `usageOf(key)` returns a number or null
- * (unknown usage is treated as 0). `rotate` keeps the given order.
+ * (unknown usage is treated as 0). `rotate` keeps the given order, and so does
+ * `load-balance`: that mode is about how many requests may be in flight per
+ * account, not about which key comes first.
  */
 export function orderKeys(values, strategy, usageOf) {
-  if (strategy === 'rotate') return [...values]
+  if (strategy === 'rotate' || strategy === 'load-balance') return [...values]
   const usageOfKey = (value) => {
     const usage = usageOf(value)
     return usage !== null && typeof usage === 'number' ? usage : 0

package/src/tools.js

@@ -16,7 +16,10 @@
  * (0.1.6 row restart, then the 0.2.x dependency-range skew). Removing the
  * capability removes the failure mode; see `docs/agents/verification.md`.
  */
+import { join } from 'node:path'
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths'
 import { defineTool } from '@deepseek-ai/dsh-tools'
+import { clampAccountCap, maskValue, readJsonFile } from './lib.js'
 
 const TAVILY_BASE_URL = 'https://api.tavily.com'
 
@@ -37,6 +40,106 @@ const RETRYABLE_REASON = new Map([
   [433, 'Tavily pay-as-you-go limit exceeded'],
 ])
 
+const MANAGER_STATE = 'tavily-manager.json'
+
+/**
+ * The concurrency policy the card writes: the strategy, the per-account cap,
+ * and the account grouping the usage route inferred (or the user pinned). Read
+ * per call, so a card change takes effect on the next search, and tolerant of a
+ * missing or half-written file.
+ */
+function readConcurrencyPolicy() {
+  const state = readJsonFile(join(resolveDshHome(), MANAGER_STATE), {})
+  const accounts = state.accounts !== null && state.accounts !== undefined &&
+    typeof state.accounts === 'object' && !Array.isArray(state.accounts)
+    ? state.accounts
+    : {}
+  return {
+    balanced: state.strategy === 'load-balance',
+    cap: clampAccountCap(state.accountCap),
+    accounts,
+  }
+}
+
+/**
+ * The account one key belongs to. A key the usage route could not group is
+ * treated as its own account: the cap still applies to it, and it stays
+ * parallel-safe with keys of other accounts.
+ */
+function accountOfKey(key, accounts) {
+  const masked = maskValue(key)
+  const entry = accounts[masked]
+  if (entry !== null && entry !== undefined && typeof entry === 'object' &&
+    typeof entry.group === 'string' && entry.group.length > 0) {
+    return entry.group
+  }
+  return 'key:' + masked
+}
+
+/**
+ * Per-account in-flight limiter. One instance per installed tool half, so every
+ * tool call in the process shares it — which is the point: parallel calls queue
+ * behind one free account instead of hitting it at the same time.
+ */
+function createAccountScheduler() {
+  const active = new Map()
+  const waiters = []
+  const activeIn = (group) => active.get(group) ?? 0
+
+  const detach = (waiter) => {
+    if (waiter.signal !== null && waiter.signal !== undefined && waiter.onAbort !== undefined) {
+      waiter.signal.removeEventListener('abort', waiter.onAbort)
+    }
+  }
+
+  function wake() {
+    for (let index = 0; index < waiters.length; index += 1) {
+      const waiter = waiters[index]
+      if (activeIn(waiter.group) >= waiter.cap) continue
+      waiters.splice(index, 1)
+      index -= 1
+      detach(waiter)
+      // Reserve the slot here: waking two waiters must never hand out one slot.
+      active.set(waiter.group, activeIn(waiter.group) + 1)
+      waiter.resolve()
+    }
+  }
+
+  return {
+    activeIn,
+    /** Resolves `true` when the caller had to wait for capacity. */
+    async acquire(group, cap, signal) {
+      if (activeIn(group) < cap) {
+        active.set(group, activeIn(group) + 1)
+        return false
+      }
+      const aborted = () => new Error('tavily: request aborted while waiting for account capacity')
+      if (signal !== null && signal !== undefined && signal.aborted === true) throw aborted()
+      await new Promise((resolve, reject) => {
+        const waiter = { group, cap, resolve, signal }
+        if (signal !== null && signal !== undefined) {
+          waiter.onAbort = () => {
+            const index = waiters.indexOf(waiter)
+            if (index >= 0) waiters.splice(index, 1)
+            detach(waiter)
+            reject(aborted())
+          }
+          signal.addEventListener('abort', waiter.onAbort, { once: true })
+        }
+        waiters.push(waiter)
+      })
+      // The waker already reserved this slot.
+      return true
+    },
+    release(group) {
+      const next = activeIn(group) - 1
+      if (next <= 0) active.delete(group)
+      else active.set(group, next)
+      wake()
+    },
+  }
+}
+
 /** Clamp a number into [min, max]; `fallback` when not finite. */
 export function clampInt(value, min, max, fallback) {
   const n = Number(value)
@@ -450,6 +553,7 @@ const NAVIGATION_PARAMETERS = {
  */
 export function installTavilyTool(ctx) {
   let rotation = 0
+  const scheduler = createAccountScheduler()
 
   // Every registration is collected into one disposer so the fiber tears the
   // half down cleanly: on row unload, and on the Plugins page's runtime unload
@@ -483,6 +587,12 @@ export function installTavilyTool(ctx) {
    * key at most once. Folding the attempt offset into the cursor instead
    * (the earlier shape) skipped keys and repeated others whenever the pool
    * size was even.
+   *
+   * Under `load-balance` the slot is chosen by account capacity instead: the
+   * first key, from the cursor, whose account is below the cap — so parallel
+   * calls spread across accounts, and a call queues rather than opening a
+   * second connection to one free account. Every other strategy keeps the
+   * plain order above, untouched.
    */
   async function requestWithRotation(operation, body, timeoutMs, exec, detail) {
     const { keys, source } = await resolveKeys()
@@ -491,12 +601,44 @@ export function installTavilyTool(ctx) {
     }
     const attempts = keys.length
     const first = rotation
+    const policy = readConcurrencyPolicy()
+    const groups = policy.balanced ? keys.map((key) => accountOfKey(key, policy.accounts)) : null
+    const signal = exec !== null && exec !== undefined ? exec.signal : undefined
+    const tried = new Set()
+    const pickBalancedIndex = (fallbackAttempt) => {
+      let leastBusy = null
+      let leastLoad = Infinity
+      for (let step = 0; step < keys.length; step += 1) {
+        const candidate = (first + step) % keys.length
+        if (tried.has(candidate)) continue
+        const load = scheduler.activeIn(groups[candidate])
+        if (load < policy.cap) return candidate
+        if (load < leastLoad) {
+          leastBusy = candidate
+          leastLoad = load
+        }
+      }
+      return leastBusy === null ? (first + fallbackAttempt) % keys.length : leastBusy
+    }
     let lastRetryable = 0
     for (let attempt = 0; attempt < attempts; attempt++) {
-      const index = (first + attempt) % keys.length
+      const index = groups === null ? (first + attempt) % keys.length : pickBalancedIndex(attempt)
+      tried.add(index)
       const key = keys[index]
+      const group = groups === null ? null : groups[index]
+      if (group !== null) {
+        const waited = await scheduler.acquire(group, policy.cap, signal)
+        if (waited) {
+          ctx.logger.info(`tavily_${operation}: waited for account capacity %j`, { group, cap: policy.cap, keys: keys.length })
+        }
+      }
       const started = Date.now()
-      const outcome = await callOperation(operation, body, key, exec, timeoutMs)
+      let outcome
+      try {
+        outcome = await callOperation(operation, body, key, exec, timeoutMs)
+      } finally {
+        if (group !== null) scheduler.release(group)
+      }
       if (outcome.kind === 'ok') {
         rotation = (index + 1) % keys.length
         const extra = typeof detail === 'function' ? detail(outcome.json) : {}