@moguiyu/dsh-tavily 0.3.4 → 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

package/package.json

@@ -1,19 +1,21 @@
 {
   "name": "@moguiyu/dsh-tavily",
-  "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 永不替换。",
+  "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": {
@@ -68,9 +72,9 @@
     "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/tools.js

@@ -1,8 +1,9 @@
 /**
- * Tool half of `@moguiyu/dsh-tavily`: the advanced `tavily_search` model tool
- * plus the extra Tavily direct tools (`tavily_extract`, `tavily_map`,
- * `tavily_crawl`). Keys resolve from the `TAVILY_API_KEYS` credential per
- * call; rotation is round-robin with failover on every per-key refusal
+ * Tool half of `@moguiyu/dsh-tavily`: the advanced `tavily_search` model tool,
+ * the extra Tavily direct tools (`tavily_extract`, `tavily_map`,
+ * `tavily_crawl`), and the asynchronous Research pair (`tavily_research`,
+ * `tavily_get_research`). Keys resolve from the `TAVILY_API_KEYS` credential
+ * per call; rotation is round-robin with failover on every per-key refusal
  * (401/429, plus Tavily's 432 plan-limit and 433 pay-as-you-go-limit codes).
  *
  * The tools are an OPTION for search, never a replacement: they are
@@ -40,6 +41,30 @@ const RETRYABLE_REASON = new Map([
   [433, 'Tavily pay-as-you-go limit exceeded'],
 ])
 
+/**
+ * Research is asynchronous: `POST /research` queues a task and returns a
+ * `request_id`; `GET /research/{request_id}` reports progress, then the report.
+ * We poll that task in-process so one tool call can return the finished report,
+ * and fall back to the bare id when the caller's budget runs out.
+ * https://docs.tavily.com/documentation/api-reference/endpoint/research
+ */
+const RESEARCH_POLL_INTERVAL_MS = 5000
+/**
+ * How long a single call waits before handing the id back. `mini` finishes
+ * narrow questions in seconds (observed live: ~13s); `pro` and `auto` run for
+ * minutes, so they get the longer default. The official MCP tool blocks up to
+ * 5 min for mini and 15 for pro/auto; `RESEARCH_MAX_WAIT_SECONDS` matches that
+ * upper bound, and the default stays short enough that an agent is not stuck.
+ */
+const RESEARCH_DEFAULT_WAIT_SECONDS = 300
+const RESEARCH_MINI_WAIT_SECONDS = 120
+const RESEARCH_MAX_WAIT_SECONDS = 900
+/** Per-HTTP-request ceiling; the caller's overall wait is bounded separately. */
+const RESEARCH_REQUEST_TIMEOUT_MS = 30000
+
+/** Task statuses after which polling stops. */
+const RESEARCH_TERMINAL_STATUS = new Set(['completed', 'failed'])
+
 const MANAGER_STATE = 'tavily-manager.json'
 
 /**
@@ -192,6 +217,26 @@ function combineSignals(signal, ms) {
   }
 }
 
+/** Sleep, rejecting as soon as the caller's signal aborts. */
+function sleepWithAbort(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal !== undefined && signal !== null && signal.aborted === true) {
+      reject(new Error('tavily_research: aborted while waiting for the research task'))
+      return
+    }
+    const onAbort = () => {
+      clearTimeout(timer)
+      if (signal !== undefined && signal !== null) signal.removeEventListener('abort', onAbort)
+      reject(new Error('tavily_research: aborted while waiting for the research task'))
+    }
+    const timer = setTimeout(() => {
+      if (signal !== undefined && signal !== null) signal.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    if (signal !== undefined && signal !== null) signal.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
 function buildBody(input) {
   const body = {
     query: input.query,
@@ -209,38 +254,58 @@ function buildBody(input) {
   return body
 }
 
-/** POST to `https://api.tavily.com/<operation>`; returns a normalized outcome. */
-async function callOperation(operation, body, key, exec, timeoutMs) {
+/**
+ * Call one Tavily endpoint; returns a normalized outcome.
+ *
+ * `request` selects the transport: `method`/`path` default to a POST to
+ * `/<operation>` (search, extract, map, crawl, research-create), and
+ * `notFound: 'outcome'` turns a 404 into `{ kind: 'not-found' }` instead of an
+ * error — `GET /research/{id}` answers 404 for a valid task id when the key
+ * asking is not the one that owns it, which the retrieve path must be able to
+ * step past.
+ */
+async function callOperation(operation, body, key, exec, timeoutMs, request = {}) {
+  const method = request.method ?? 'POST'
+  const path = request.path ?? operation
   const combined = combineSignals(exec.signal, timeoutMs)
   try {
-    const response = await fetch(`${TAVILY_BASE_URL}/${operation}`, {
-      method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        accept: 'application/json',
-        authorization: 'Bearer ' + key,
-        'user-agent': 'dsh-tool-tavily-search/0.2.0',
-      },
-      body: JSON.stringify(body),
-      signal: combined.signal,
-    })
+    const headers = {
+      accept: 'application/json',
+      authorization: 'Bearer ' + key,
+      'user-agent': 'dsh-tool-tavily-search/0.2.0',
+    }
+    const init = { method, headers, signal: combined.signal }
+    if (method !== 'GET') {
+      headers['content-type'] = 'application/json'
+      init.body = JSON.stringify(body ?? {})
+    }
+    const response = await fetch(`${TAVILY_BASE_URL}/${path}`, init)
     if (RETRYABLE_STATUS.has(response.status)) {
       return { kind: 'retryable', statusCode: response.status }
     }
+    if (request.notFound === 'outcome' && response.status === 404) {
+      return { kind: 'not-found', statusCode: 404 }
+    }
     if (!response.ok) {
       let message = 'HTTP ' + response.status
+      let errorCode
       try {
         const parsed = await response.json()
         if (parsed !== null && typeof parsed === 'object') {
           if (typeof parsed.error === 'string') message = parsed.error
+          else if (typeof parsed.detail === 'string') message = parsed.detail
           else if (parsed.error !== null && typeof parsed.error === 'object' && typeof parsed.error.message === 'string') message = parsed.error.message
           // 432/433 and other API failures arrive as {"detail":{"error":…}}.
           else if (parsed.detail !== undefined && parsed.detail !== null && typeof parsed.detail === 'object' && typeof parsed.detail.error === 'string') message = parsed.detail.error
+          const detail = parsed.detail !== null && typeof parsed.detail === 'object' ? parsed.detail : parsed
+          if (typeof detail.error_code === 'string') errorCode = detail.error_code
         }
       } catch {
         /* keep the status message */
       }
-      throw new Error(`tavily_${operation}: ${message}`)
+      const error = new Error(`tavily_${operation}: ${message}`)
+      if (errorCode !== undefined) error.errorCode = errorCode
+      throw error
     }
     return { kind: 'ok', statusCode: response.status, json: await response.json() }
   } catch (error) {
@@ -487,6 +552,134 @@ function renderJson(_args, value) {
   return [{ type: 'text', text: JSON.stringify(value, null, 2) }]
 }
 
+/* ---------------------------------------------------------------------------
+ * tavily_research / tavily_get_research. Research is the one Tavily capability
+ * the four direct tools cannot reach: `POST /research` queues an asynchronous
+ * task and `GET /research/{request_id}` returns a synthesized, cited report.
+ * It is deliberately NOT a search replacement either — it costs far more
+ * credits (mini 4-110, pro 15-250) than a `tavily_search` call.
+ * ------------------------------------------------------------------------- */
+
+function normalizeOutputSchema(value) {
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== 'object' || Array.isArray(value)) throw new Error('output_schema must be a JSON Schema object')
+  const properties = value.properties
+  if (properties === null || properties === undefined || typeof properties !== 'object' || Array.isArray(properties) || Object.keys(properties).length === 0) {
+    throw new Error('output_schema must include a non-empty properties object')
+  }
+  if (value.required !== undefined && (!Array.isArray(value.required) || value.required.some((name) => typeof name !== 'string'))) {
+    throw new Error('output_schema.required must be an array of property names')
+  }
+  return value
+}
+
+function domainList(args, name) {
+  const value = optionalStringList(args, name)
+  if (value === undefined) return []
+  if (value.length > 20) throw new Error(`${name} accepts at most 20 entries`)
+  return value
+}
+
+function clampWaitSeconds(value, model) {
+  const fallback = model === 'mini' ? RESEARCH_MINI_WAIT_SECONDS : RESEARCH_DEFAULT_WAIT_SECONDS
+  if (value === undefined) return fallback
+  const n = Number(value)
+  if (!Number.isFinite(n) || n < 0) throw new Error('timeout_seconds must be a number of seconds, 0 or more')
+  return Math.min(RESEARCH_MAX_WAIT_SECONDS, Math.round(n))
+}
+
+/**
+ * Normalize `tavily_research` arguments. The API field is `input`; `query` is
+ * accepted as an alias because every neighbouring tool spells it that way.
+ */
+export function normalizeResearchArgs(args) {
+  const raw = typeof args.input === 'string' && args.input.trim().length > 0
+    ? args.input
+    : (typeof args.query === 'string' ? args.query : '')
+  const input = raw.trim()
+  if (input.length === 0) throw new Error('tavily_research: input must be a non-empty string')
+  const model = optionalEnum(args, 'model', ['mini', 'pro', 'auto']) ?? 'auto'
+  return {
+    input,
+    model,
+    citationFormat: optionalEnum(args, 'citation_format', ['numbered', 'mla', 'apa', 'chicago']),
+    outputLength: optionalEnum(args, 'output_length', ['short', 'standard', 'long']),
+    includeDomains: domainList(args, 'include_domains'),
+    excludeDomains: domainList(args, 'exclude_domains'),
+    outputSchema: normalizeOutputSchema(args.output_schema),
+    waitSeconds: clampWaitSeconds(args.timeout_seconds, model),
+  }
+}
+
+export function buildResearchBody(input) {
+  const body = { input: input.input, model: input.model }
+  include(body, 'citation_format', input.citationFormat)
+  include(body, 'output_length', input.outputLength)
+  if (input.includeDomains.length > 0) body.include_domains = input.includeDomains
+  if (input.excludeDomains.length > 0) body.exclude_domains = input.excludeDomains
+  include(body, 'output_schema', input.outputSchema)
+  return body
+}
+
+/** Whether a research `status` ends the polling loop. */
+export function isTerminalResearchStatus(status) {
+  return RESEARCH_TERMINAL_STATUS.has(status)
+}
+
+/**
+ * Project a research task response from any of the three calls that produce
+ * one (create, poll, retrieve). `content` is a string for a prose report and a
+ * real JSON object when `output_schema` was supplied, so an object is
+ * serialized and flagged rather than dropped.
+ */
+export function projectResearch(response) {
+  const status = typeof response?.status === 'string' && response.status.length > 0 ? response.status : 'unknown'
+  const out = {
+    requestId: typeof response?.request_id === 'string' ? response.request_id : '',
+    status,
+  }
+  if (typeof response?.created_at === 'string') out.createdAt = response.created_at
+  if (typeof response?.model === 'string') out.model = response.model
+  if (typeof response?.response_time === 'number') out.responseTime = response.response_time
+  if (status === 'completed') {
+    if (typeof response.content === 'string' && response.content.length > 0) out.content = response.content
+    else if (response.content !== null && typeof response.content === 'object') {
+      out.content = JSON.stringify(response.content, null, 2)
+      out.contentType = 'json'
+    }
+    const sources = Array.isArray(response.sources) ? response.sources.flatMap((source) => {
+      if (source === null || typeof source !== 'object' || typeof source.url !== 'string' || source.url.length === 0) return []
+      return [{
+        url: source.url,
+        ...(typeof source.title === 'string' && source.title.length > 0 ? { title: source.title } : {}),
+        ...(typeof source.favicon === 'string' && source.favicon.length > 0 ? { favicon: source.favicon } : {}),
+      }]
+    }) : []
+    if (sources.length > 0) out.sources = sources
+  }
+  if (response?.usage !== null && typeof response?.usage === 'object' && typeof response.usage.credits === 'number') {
+    out.credits = response.usage.credits
+  }
+  return out
+}
+
+function renderResearch(_args, value) {
+  const heading = value.status === 'completed'
+    ? 'Tavily research report'
+    : value.status === 'failed' ? 'Tavily research failed' : 'Tavily research ' + value.status
+  const parts = [heading + ' — request ' + value.requestId]
+  if (typeof value.content === 'string' && value.content.length > 0) parts.push(value.content)
+  if (Array.isArray(value.sources) && value.sources.length > 0) {
+    parts.push('Sources:\n' + value.sources.map((source) => {
+      const label = typeof source.title === 'string' && source.title.length > 0 ? source.title : hostnameOf(source.url)
+      return '- [' + label + '](' + source.url + ')'
+    }).join('\n'))
+  }
+  if (typeof value.note === 'string' && value.note.length > 0) parts.push(value.note)
+  if (typeof value.credits === 'number') parts.push('Credits used: ' + value.credits)
+  return [{ type: 'text', text: parts.join('\n\n') }]
+}
+
 const PAGE_SCHEMA = {
   type: 'object',
   additionalProperties: false,
@@ -532,6 +725,33 @@ const CRAWL_OUTPUT_SCHEMA = {
   },
 }
 
+const RESEARCH_SOURCE_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    url: { type: 'string', required: true },
+    title: { type: 'string' },
+    favicon: { type: 'string' },
+  },
+}
+
+const RESEARCH_OUTPUT_SCHEMA = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    requestId: { type: 'string', required: true },
+    status: { type: 'string', required: true },
+    content: { type: 'string' },
+    contentType: { type: 'string' },
+    createdAt: { type: 'string' },
+    model: { type: 'string' },
+    sources: { type: 'array', items: RESEARCH_SOURCE_SCHEMA },
+    credits: { type: 'number' },
+    responseTime: { type: 'number' },
+    note: { type: 'string' },
+  },
+}
+
 const NAVIGATION_PARAMETERS = {
   url: { type: 'string', required: true, description: 'The HTTP(S) URL to map or crawl.' },
   instructions: { type: 'string', description: 'Natural-language guidance for which pages to include.' },
@@ -544,16 +764,19 @@ const NAVIGATION_PARAMETERS = {
 }
 
 /**
- * Register the `tavily_search`, `tavily_extract`, `tavily_map`, and
- * `tavily_crawl` model tools on `ctx`, and return one disposer that
- * unregisters all of them plus the two prompt sections.
+ * Register the `tavily_search`, `tavily_extract`, `tavily_map`,
+ * `tavily_crawl`, `tavily_research`, and `tavily_get_research` model tools on
+ * `ctx`, and return one disposer that unregisters all of them plus the three
+ * prompt sections.
  *
  * No web search provider is registered here: `web_search` keeps its native
  * provider and `ctx.web` is never touched.
  */
-export function installTavilyTool(ctx) {
+export function installTavilyTool(ctx, options = {}) {
   let rotation = 0
   const scheduler = createAccountScheduler()
+  // Injectable so tests can drive the poll loop without waiting seconds.
+  const pollIntervalMs = options.pollIntervalMs ?? RESEARCH_POLL_INTERVAL_MS
 
   // 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
@@ -579,8 +802,31 @@ export function installTavilyTool(ctx) {
     return { keys: [], source: 'unconfigured' }
   }
 
+  /** Resolve the key pool and the concurrency policy for one call. */
+  async function resolvePool(operation, exec) {
+    const { keys, source } = await resolveKeys()
+    if (keys.length === 0) {
+      throw new Error(`tavily_${operation}: TAVILY_API_KEYS is not configured — add it via the Tavily Search settings card or ~/.dsh/.credentials.yaml (comma-separated)`)
+    }
+    const policy = readConcurrencyPolicy()
+    const groups = policy.balanced ? keys.map((key) => accountOfKey(key, policy.accounts)) : null
+    const signal = exec !== null && exec !== undefined ? exec.signal : undefined
+    return { keys, source, policy, groups, signal }
+  }
+
+  /** Run one request on `pool.keys[index]`, honouring the account cap. */
+  async function runOnPoolKey(pool, index, operation, body, timeoutMs, exec, request) {
+    const group = pool.groups === null ? null : pool.groups[index]
+    if (group !== null) await scheduler.acquire(group, pool.policy.cap, pool.signal)
+    try {
+      return await callOperation(operation, body, pool.keys[index], exec, timeoutMs, request)
+    } finally {
+      if (group !== null) scheduler.release(group)
+    }
+  }
+
   /**
-   * Run `body` through the rotation/failover loop; returns the response JSON.
+   * Run `body` through the rotation/failover loop.
    *
    * The first key is picked from the shared round-robin cursor, and each
    * attempt advances by exactly one slot, so one call tries every configured
@@ -593,17 +839,15 @@ export function installTavilyTool(ctx) {
    * 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.
+   *
+   * Returns the response JSON plus the pool slot that served it, because
+   * research must keep asking with the key that owns the task.
    */
-  async function requestWithRotation(operation, body, timeoutMs, exec, detail) {
-    const { keys, source } = await resolveKeys()
-    if (keys.length === 0) {
-      throw new Error(`tavily_${operation}: TAVILY_API_KEYS is not configured — add it via the Tavily Search settings card or ~/.dsh/.credentials.yaml (comma-separated)`)
-    }
+  async function requestWithRotationResult(operation, body, timeoutMs, exec, detail, request) {
+    const pool = await resolvePool(operation, exec)
+    const { keys, source, policy, groups, signal } = pool
     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
@@ -635,7 +879,7 @@ export function installTavilyTool(ctx) {
       const started = Date.now()
       let outcome
       try {
-        outcome = await callOperation(operation, body, key, exec, timeoutMs)
+        outcome = await callOperation(operation, body, key, exec, timeoutMs, request)
       } finally {
         if (group !== null) scheduler.release(group)
       }
@@ -643,7 +887,7 @@ export function installTavilyTool(ctx) {
         rotation = (index + 1) % keys.length
         const extra = typeof detail === 'function' ? detail(outcome.json) : {}
         ctx.logger.info(`tavily_${operation}: ok %j`, { ...extra, status: outcome.statusCode, ms: Date.now() - started, keys: keys.length, source })
-        return outcome.json
+        return { json: outcome.json, index, keys, pool }
       }
       lastRetryable = outcome.statusCode
       rotation = (index + 1) % keys.length
@@ -653,6 +897,11 @@ export function installTavilyTool(ctx) {
     throw new Error(`tavily_${operation}: all ${attempts} configured key(s) failed with HTTP ${lastRetryable} (${reason})`)
   }
 
+  /** The rotation loop's JSON, for callers that do not need the owning key. */
+  async function requestWithRotation(operation, body, timeoutMs, exec, detail) {
+    return (await requestWithRotationResult(operation, body, timeoutMs, exec, detail)).json
+  }
+
   tools.register(defineTool({
     name: 'tavily_search',
     description: 'Search the web through the Tavily API. Returns ranked results with titles, URLs, snippets, relevance scores, and an optional generated answer. Supports basic/advanced depth, news topic with a freshness window, and domain allow/deny filters.',
@@ -757,6 +1006,117 @@ export function installTavilyTool(ctx) {
     },
   }))
 
+  /** `GET /research/{id}` — the task is owned by one key, so reuse that slot. */
+  const researchPath = (requestId) => 'research/' + encodeURIComponent(requestId) + '?include_usage=true'
+
+  tools.register(defineTool({
+    name: 'tavily_research',
+    description: 'Run multi-source research through the Tavily Research API and return a synthesized, cited report. It starts an asynchronous research task and waits for it, so one call can return the finished report; if the wait runs out it returns the request id for tavily_get_research. Costs far more credits than tavily_search (mini 4-110, pro 15-250): use it when a written report is wanted, not for an ordinary lookup.',
+    parameters: {
+      input: { type: 'string', required: true, description: 'The research task or question to investigate, in full. `query` is accepted as an alias.' },
+      model: { type: 'string', enum: ['mini', 'pro', 'auto'], description: 'mini for narrow, well-scoped questions; pro for broad multi-angle research; auto (default) lets Tavily choose.' },
+      citation_format: { type: 'string', enum: ['numbered', 'mla', 'apa', 'chicago'], description: 'Citation style inside the report (default numbered).' },
+      output_length: { type: 'string', enum: ['short', 'standard', 'long'], description: 'Typed control over report size; a target, not a hard cap (default standard).' },
+      include_domains: { type: 'array', items: { type: 'string' }, description: 'Soft preference for sources, host-based; at most 20 domains.' },
+      exclude_domains: { type: 'array', items: { type: 'string' }, description: 'Hard blocklist, subdomains included; at most 20 domains.' },
+      output_schema: { type: 'object', additionalProperties: true, description: 'Optional JSON Schema object describing a structured report; must include a non-empty properties object.' },
+      timeout_seconds: { type: 'number', description: 'How long to wait for completion before returning the still-running task id: 0 returns immediately after queueing; defaults to 120s for mini and 300s otherwise; maximum 900.' },
+    },
+    output: { schema: RESEARCH_OUTPUT_SCHEMA, render: renderResearch },
+    timeoutMs: (RESEARCH_MAX_WAIT_SECONDS + 60) * 1000,
+    isConcurrencySafe: () => true,
+    async execute(args, exec) {
+      const input = normalizeResearchArgs(args)
+      let started
+      try {
+        started = await requestWithRotationResult('research', buildResearchBody(input), RESEARCH_REQUEST_TIMEOUT_MS, exec, (json) => ({
+          model: json.model,
+          status: json.status,
+        }))
+      } catch (error) {
+        if (error instanceof Error && error.errorCode === 'research_stream_required') {
+          throw new Error('tavily_research: this Tavily key requires streamed research, which this plugin does not support — use the Tavily MCP row (tavily_research) for this account')
+        }
+        throw error
+      }
+      const requestId = typeof started.json?.request_id === 'string' ? started.json.request_id : ''
+      if (requestId.length === 0) throw new Error('tavily_research: the API returned no request_id')
+
+      let current = started.json
+      let stopped = ''
+      const deadline = Date.now() + input.waitSeconds * 1000
+      const signal = exec !== null && exec !== undefined ? exec.signal : undefined
+      while (!isTerminalResearchStatus(typeof current?.status === 'string' ? current.status : '') && Date.now() < deadline) {
+        await sleepWithAbort(Math.min(pollIntervalMs, deadline - Date.now()), signal)
+        const outcome = await runOnPoolKey(started.pool, started.index, 'research', undefined, RESEARCH_REQUEST_TIMEOUT_MS, exec, {
+          method: 'GET',
+          path: researchPath(requestId),
+          notFound: 'outcome',
+        })
+        if (outcome.kind === 'ok') {
+          current = outcome.json
+          continue
+        }
+        if (outcome.kind === 'not-found') {
+          stopped = 'Tavily no longer knows this request id (HTTP 404).'
+          break
+        }
+        stopped = `Polling stopped after HTTP ${outcome.statusCode}.`
+        break
+      }
+
+      const value = projectResearch(current)
+      if (value.requestId.length === 0) value.requestId = requestId
+      if (!isTerminalResearchStatus(value.status)) {
+        const reason = stopped.length > 0
+          ? stopped
+          : input.waitSeconds === 0
+            ? 'Queued without waiting.'
+            : `Still running after ${input.waitSeconds}s.`
+        value.note = reason + ' Call tavily_get_research with requestId ' + requestId + ' to collect the report when it finishes.'
+      }
+      return value
+    },
+  }))
+
+  tools.register(defineTool({
+    name: 'tavily_get_research',
+    description: 'Retrieve a Tavily research task by request id: its status while it runs, and the full cited report once it has completed. Use it after tavily_research returns a task that is still running.',
+    parameters: {
+      request_id: { type: 'string', required: true, description: 'The requestId returned by tavily_research.' },
+    },
+    output: { schema: RESEARCH_OUTPUT_SCHEMA, render: renderResearch },
+    timeoutMs: 60000,
+    isConcurrencySafe: () => true,
+    async execute(args, exec) {
+      const requestId = optionalString(args, 'request_id')
+      if (requestId === undefined) throw new Error('tavily_get_research: request_id must be a non-empty string')
+      const pool = await resolvePool('research', exec)
+      const first = rotation
+      let lastRetryable = 0
+      // A task is owned by the key that created it, and a pool may span
+      // accounts, so a 404 means "not this key" until every key has answered.
+      for (let attempt = 0; attempt < pool.keys.length; attempt++) {
+        const index = (first + attempt) % pool.keys.length
+        const outcome = await runOnPoolKey(pool, index, 'research', undefined, RESEARCH_REQUEST_TIMEOUT_MS, exec, {
+          method: 'GET',
+          path: researchPath(requestId),
+          notFound: 'outcome',
+        })
+        if (outcome.kind === 'ok') {
+          rotation = (index + 1) % pool.keys.length
+          return projectResearch(outcome.json)
+        }
+        if (outcome.kind === 'retryable') lastRetryable = outcome.statusCode
+      }
+      if (lastRetryable !== 0) {
+        const reason = RETRYABLE_REASON.get(lastRetryable) ?? 'invalid key or rate limit'
+        throw new Error(`tavily_research: all ${pool.keys.length} configured key(s) failed with HTTP ${lastRetryable} (${reason})`)
+      }
+      throw new Error(`tavily_research: no configured key knows request ${requestId} (HTTP 404) — check the id, or the key that started the task may have been removed`)
+    },
+  }))
+
   const systemPrompt = ctx.get('systemPrompt')
   const section = (value) => {
     if (systemPrompt !== undefined) disposers.push(systemPrompt.section(value))
@@ -772,6 +1132,11 @@ export function installTavilyTool(ctx) {
       order: 112,
       text: 'For pages already known by URL, use tavily_extract to pull their full content, tavily_map to discover a site\'s links without fetching content, and tavily_crawl to capture the extracted content of an entire site. These are optional extras on top of the built-in web_search tool, which is never replaced.',
     })
+    section({
+      name: 'tool:tavily_research',
+      order: 113,
+      text: 'For a question that wants a synthesized, multi-source written report rather than a list of links, use tavily_research. It queues a Tavily research task and waits for the finished report. It costs far more credits than tavily_search (mini 4-110, pro 15-250), so prefer tavily_search for ordinary lookups and reserve research for broad or multi-angle questions. If it returns status pending or in_progress the task is still running: call tavily_get_research with the returned requestId to collect the report later.',
+    })
   }
 
   const credentials = ctx.get('credentials')

package/src/invariant.js

@@ -1,18 +0,0 @@
-/**
- * Package-owned invariant companion for `@moguiyu/dsh-tavily`.
- */
-const PACKAGE_NAME = '@moguiyu/dsh-tavily'
-
-/** Cordis companion plugin name. */
-const name = 'dsh-tavily-invariant'
-
-/** Service required before the companion can reserve package ownership. */
-const inject = ['invariants']
-
-/** No runtime invariant: this tool has no independent lifecycle stream. */
-const install = () => {}
-
-/** Register this package's invariant companion. */
-const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
-
-export { apply, inject, name }