@moguiyu/dsh-tavily 0.3.3 → 0.3.5

package/README.md

@@ -1,13 +1,19 @@
 # @moguiyu/dsh-tavily
 
 Everything in one package: the advanced Tavily model tools (`tavily_search`, `tavily_extract`,
-`tavily_map`, `tavily_crawl`), the key/usage HTTP routes, and the browser card on the **Plugins**
-page.
+`tavily_map`, `tavily_crawl`, `tavily_research`, `tavily_get_research`), the key/usage HTTP
+routes, and the browser card on the **Plugins** page.
 
 - **`tavily_search`** — full Tavily surface (`max_results`, `search_depth`, `topic`, `days`,
   `include_answer`, `include_raw_content`, `include_domains`, `exclude_domains`).
 - **`tavily_extract` / `tavily_map` / `tavily_crawl`** — read a known URL's content, map a
   site's links, or crawl a site and return its pages. Same key-rotation/failover as search.
+- **`tavily_research` / `tavily_get_research`** — Tavily's Research endpoint: queue a task
+  (`model`: `mini` / `pro` / `auto`, plus `citation_format`, `output_length`, domain filters and an
+  optional `output_schema`), wait for it, and get a synthesized, cited report; the second tool
+  collects a task that outlived the first call. Research is billed per request and far above
+  search — **mini 4-110 credits, pro 15-250**, against 1-2 for a search — so it is a per-call
+  choice, never a default. `timeout_seconds: 0` queues the task and returns its id immediately.
 - **Card** — key list, usage gauge, and the strategy selector. It registers into the Plugins
   page's `plugins.bundle.config` slot, keyed `@moguiyu/dsh-tavily`, and needs DSH
   **0.1.6-alpha.2 or newer** — the release that retired `settings.plugin.item` and moved plugin
@@ -29,4 +35,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,19 +1,21 @@
 {
   "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.5",
+  "description": "Advanced Tavily model tools for DeepSeek Harness (tavily_search, tavily_extract, tavily_map, tavily_crawl, tavily_research, tavily_get_research) 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 轮换、故障转移与按账号并发上限，另有 research 综合调研报告，插件配置页含密钥与用量管理卡片；内置 web_search 永不替换。",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
     ".": "./src/index.js",
-    "./invariant": "./src/invariant.js",
     "./client": "./lib/client.js",
-    "./src/*": "./src/*",
     "./package.json": "./package.json"
   },
   "files": [
-    "src",
-    "lib",
+    "src/index.js",
+    "src/tools.js",
+    "src/backend.js",
+    "src/lib.js",
+    "src/client.js",
+    "lib/client.js",
     "cordis.patch.yml",
     "README.md",
     "LICENSE"
@@ -40,7 +42,9 @@
         "0.1.6-alpha.2": "compatible",
         "0.1.7-rc.2": "compatible",
         "0.2.0-rc.1": "compatible",
-        "0.2.0-rc.2": "compatible"
+        "0.2.0-rc.2": "compatible",
+        "0.2.1-alpha.1": "compatible",
+        "0.2.1-alpha.2": "compatible"
       }
     },
     "client": {
@@ -64,12 +68,13 @@
   ],
   "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",
-    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.7 || ^0.1.1-rc.1 || ^0.1.2-alpha.2 || ^0.1.3-alpha.1 || ^0.1.5-0 || ^0.1.6-0 || ^0.1.7-0 || ^0.2.0-0",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7 || ^0.1.1-rc.1 || ^0.1.2-alpha.2 || ^0.1.3-alpha.1 || ^0.1.5-0 || ^0.1.6-0 || ^0.1.7-0 || ^0.2.0-0"
+    "@deepseek-ai/cordis": "^4.0.1 || ^4.0.5-0",
+    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.7 || ^0.1.1-rc.1 || ^0.1.2-alpha.2 || ^0.1.3-alpha.1 || ^0.1.5-0 || ^0.1.6-0 || ^0.1.7-0 || ^0.2.0-0 || ^0.2.1-0",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.7 || ^0.1.1-rc.1 || ^0.1.2-alpha.2 || ^0.1.3-alpha.1 || ^0.1.5-0 || ^0.1.6-0 || ^0.1.7-0 || ^0.2.0-0 || ^0.2.1-0"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.2"

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)' } },