dsh-search-enhance 0.1.3 → 0.1.5

package/README.md

@@ -14,11 +14,11 @@ DSH Agent
   │
   └─ 固定模型工具 surface（schema 与顺序不随披露状态变化）
       ├─ web_search ──────> Grok 主搜索
-      │                      ├─ 按需要补充 Context7 / Exa
+      │                      ├─ 按需要补充 Exa 文档来源
       │                      ├─ 按需要补充 Tavily / Firecrawl
       │                      └─ 返回回答、来源；有 source_ref 时追加 search_sources manifest
       │
-      ├─ docs_search ─────> Context7 / Exa 文档检索
+      ├─ docs_search ─────> 显式 Context7 库身份 / Exa 文档发现
       │                      └─ 返回文档片段、来源；有 source_ref 时追加 search_sources manifest
       │
       ├─ web_extract ─────> Tavily → Firecrawl → smart_direct → direct
@@ -45,7 +45,7 @@ DSH Agent
 | 工具 | 调用方式与用途 |
 | --- | --- |
 | `web_search` | 直接调用。使用 Grok 生成通用搜索的主要回答，并按搜索类型补充其他来源 |
-| `docs_search` | 直接调用。检索库、框架、SDK、API 和源码仓库文档 |
+| `docs_search` | 直接调用。已知精确 `/org/project` 时传 `library_id`；已知包或产品名时传 `library_name`；不知道库身份时用 `provider: auto` 进行 Exa 发现 |
 | `web_extract` | 直接调用。读取指定网页正文，用于核对搜索摘要中的重要内容 |
 | `search_tools` | 直接调用。按需返回延迟能力的 operation manifest，不注册新的模型工具 |
 | `search_call` | 固定网关。通过 `search_call({ operation, arguments })` 调用已经激活的延迟 operation |
@@ -78,11 +78,13 @@ DSH Agent
 ### 一次完整搜索如何进行
 
 1. 通用问题直接调用 `web_search`，文档问题直接调用 `docs_search`。
-2. 当搜索产生来源时，结果会包含可见来源、`source_ref` 和追加的 `search_sources` manifest，同时自动激活 `sources`。
-3. 在下一 step 需要更多来源时，调用 `search_call({ operation: 'search_sources', arguments: { source_ref, offset: 0, limit: 20, format: 'compact' } })` 分页读取，而不是直接调用 `search_sources`。
-4. 对重要结论，选择权威链接并直接调用 `web_extract` 获取网页正文。
-5. 如果任务需要站点内发现、研究计划、精细 Context7 查询或连接检查，先调用例如 `search_tools({ capabilities: ['site_map'] })` 取得 manifest；`progressive` 模式从下一 step、`all` 模式立即通过 `search_call({ operation: 'web_map', arguments: { url: 'https://example.com' } })` 调用相应 operation。
-6. 最终回答综合主搜索、补充来源和已经读取的网页正文，并保留来源链接。
+2. 调用 `docs_search` 时保持任务问题与库身份分离。例如 `{"query":"JWT authentication middleware API","library_name":"FastAPI"}`。同时提供 `library_id` 和 `library_name` 时，合法 `library_id` 优先并跳过 resolve。
+3. `provider: auto` 没有 `library_id`/`library_name` 时只使用 Exa；`provider: context7` 或 `all` 缺少库身份会在凭据、缓存和网络前失败。普通 `web_search` 的文档增强也只使用 Exa，不猜测 Context7 库。
+4. 当搜索产生来源时，结果会包含可见来源、`source_ref` 和追加的 `search_sources` manifest，同时自动激活 `sources`。
+5. 在下一 step 需要更多来源时，调用 `search_call({ operation: 'search_sources', arguments: { source_ref, offset: 0, limit: 20, format: 'compact' } })` 分页读取，而不是直接调用 `search_sources`。
+6. 对重要结论，选择权威链接并直接调用 `web_extract` 获取网页正文。
+7. 如果任务需要站点内发现、研究计划、精细 Context7 查询或连接检查，先调用例如 `search_tools({ capabilities: ['site_map'] })` 取得 manifest；`progressive` 模式从下一 step、`all` 模式立即通过 `search_call({ operation: 'web_map', arguments: { url: 'https://example.com' } })` 调用相应 operation。
+8. 最终回答综合主搜索、补充来源和已经读取的网页正文，并保留来源链接。
 
 `source_ref` 只是完整来源列表的引用，不等同于网页正文；重要事实仍应通过 `web_extract` 读取原页面后再下结论。
 
@@ -135,7 +137,7 @@ dsh web
 
 | 服务 | 用途 | 默认密钥名称 |
 | --- | --- | --- |
-| Context7 | 查找库和框架文档 | `CONTEXT7_API_KEY` |
+| Context7 | 使用显式 `library_name` 或 `library_id` 查找库和框架文档 | `CONTEXT7_API_KEY` |
 | Exa | 补充文档和网页结果 | `EXA_API_KEY` |
 | Tavily | 补充搜索、读取网页和发现站点页面 | `TAVILY_API_KEY` |
 | Firecrawl | 补充搜索和读取网页 | `FIRECRAWL_API_KEY` |

package/lib/diagnostics/probes.d.ts

@@ -4,7 +4,8 @@ import type { BoundedSourceProvider } from '../providers/types.js';
 import type { DiagnosticCapability, DiagnosticProbe, DiagnosticProbeInput, DiagnosticProbeResult, DiagnosticProviderName } from './types.js';
 /** Fixed, non-user-controlled diagnostic targets. */
 export declare const DIAGNOSTIC_SEARCH_QUERY = "search-enhance fixed connectivity diagnostic";
-export declare const DIAGNOSTIC_CONTEXT7_QUERY = "react documentation";
+export declare const DIAGNOSTIC_CONTEXT7_LIBRARY_NAME = "React";
+export declare const DIAGNOSTIC_CONTEXT7_QUERY = "documentation connectivity diagnostic";
 export declare const DIAGNOSTIC_RESULT_LIMIT = 1;
 /** Uses the public bounded model-list GET; it never calls Search API main search. */
 export declare class SearchApiModelListDiagnosticProbe implements DiagnosticProbe {

package/lib/diagnostics/probes.js

@@ -1,7 +1,8 @@
 import { throwIfAborted } from '../provider-runtime/index.js';
 /** Fixed, non-user-controlled diagnostic targets. */
 export const DIAGNOSTIC_SEARCH_QUERY = 'search-enhance fixed connectivity diagnostic';
-export const DIAGNOSTIC_CONTEXT7_QUERY = 'react documentation';
+export const DIAGNOSTIC_CONTEXT7_LIBRARY_NAME = 'React';
+export const DIAGNOSTIC_CONTEXT7_QUERY = 'documentation connectivity diagnostic';
 export const DIAGNOSTIC_RESULT_LIMIT = 1;
 const COMPLETE = Object.freeze({ state: 'complete' });
 const NOT_CONFIGURED = Object.freeze({ state: 'not_configured' });
@@ -38,6 +39,7 @@ export class Context7ResolveDiagnosticProbe {
         await this.context7.resolve({
             config: input.config,
             limit: DIAGNOSTIC_RESULT_LIMIT,
+            libraryName: DIAGNOSTIC_CONTEXT7_LIBRARY_NAME,
             onDispatch: input.onDispatch,
             query: DIAGNOSTIC_CONTEXT7_QUERY,
             signal: input.signal,

package/lib/documentation/cache.d.ts

@@ -49,6 +49,7 @@ export interface Context7CacheRepository {
 /** Cache identity includes every bounded input that can change a successful resolve value. */
 export declare function context7ResolveCacheKey(input: {
     readonly baseUrl: string;
+    readonly libraryName: string;
     readonly query: string;
     readonly maxResults: number;
     readonly maxLibraryTextCharacters: number;

package/lib/documentation/cache.js

@@ -40,11 +40,15 @@ export function context7ResolveCacheKey(input) {
     positiveSafeInteger(input.maxResults, 'maxResults');
     positiveSafeInteger(input.maxLibraryTextCharacters, 'maxLibraryTextCharacters');
     positiveSafeInteger(input.maxEntryBytes, 'maxEntryBytes');
+    const libraryName = input.libraryName.trim();
     const query = input.query.trim();
+    if (libraryName.length === 0)
+        throw new RangeError('Context7 library name must not be empty');
     if (query.length === 0)
         throw new RangeError('Context7 resolve query must not be empty');
     return `ctx7r_${digestIdentity('resolve', {
         baseUrl: normalizedBaseUrl(input.baseUrl),
+        libraryName,
         maxEntryBytes: input.maxEntryBytes,
         maxLibraryTextCharacters: input.maxLibraryTextCharacters,
         maxResults: input.maxResults,

package/lib/documentation/context7-cache.d.ts

@@ -39,6 +39,7 @@ export interface Context7CacheClock {
     now(): number;
 }
 export interface Context7ResolveCachedInput {
+    readonly libraryName: string;
     readonly query: string;
     readonly maxResults: number;
     readonly forceRefresh: boolean;

package/lib/documentation/context7-cache.js

@@ -174,6 +174,7 @@ export class Context7CachedOperations {
         throwIfAborted(input.signal);
         const cacheKey = context7ResolveCacheKey({
             baseUrl: input.config.providers.context7.baseUrl,
+            libraryName: input.libraryName,
             maxEntryBytes: input.config.cache.context7EntryMaxBytes,
             maxLibraryTextCharacters: input.config.cache.context7LibraryTextMaxCharacters,
             maxResults: input.maxResults,

package/lib/documentation/index.d.ts

@@ -1,5 +1,5 @@
 export { CONTEXT7_CACHE_DOMAIN_NAME, CONTEXT7_CACHE_DOMAIN_SPEC, CONTEXT7_CACHE_FORMAT_VERSION, CONTEXT7_CACHE_KEY_PATTERN, CONTEXT7_CACHE_TABLE_NAME, CONTEXT7_DOC_REF_PATTERN, CachedContext7LibrarySchema, CachedDocumentationSnippetSchema, Context7CacheEntrySchema, Context7CacheKeySchema, Context7DocsCacheEntrySchema, Context7DocRefSchema, Context7ResolveCacheEntrySchema, type CachedContext7Library, type CachedDocumentationSnippet, type Context7CacheDomain, type Context7CacheEntry, type Context7CacheKey, type Context7DocsCacheEntry, type Context7DocRef, type Context7ResolveCacheEntry, } from './cache-domain.js';
 export { CONTEXT7_CACHE_QUERY_MAX_SCAN_RECORDS, CONTEXT7_CACHE_QUERY_MAX_TERMS, CONTEXT7_CACHE_QUERY_MAX_TEXT_CHARACTERS, Context7CacheError, Context7CacheStore, PersistentContext7Cache, context7DocsCacheKey, context7ResolveCacheKey, isContext7DocRef, type Context7CacheErrorCode, type Context7CacheLimits, type Context7CacheRepository, type Context7CacheWriteResult, type Context7CachedDocFound, type Context7CachedDocLookup, type Context7CachedDocMatch, type Context7CachedDocMatchFound, type Context7CachedDocMatchNotFound, type Context7CachedDocNotFound, type Context7CachedDocQuery, } from './cache.js';
 export { CONTEXT7_CACHE_STATES, Context7CachedOperations, Context7OperationFailure, context7CacheEntryIsFresh, isContext7LibraryId, normalizeContext7LibraryId, permitsContext7StaleFallback, type CachedContext7Operation, type Context7CacheClock, type Context7CacheState, type Context7DocsCachedInput, type Context7DocsRemoteResult, type Context7OperationPath, type Context7RemoteDiagnostics, type Context7ResolveCachedInput, type Context7ResolveRemoteResult, } from './context7-cache.js';
-export { DOCUMENTATION_CACHE_PATH_STATES, DOCUMENTATION_CACHE_SKIP_REASONS, DOCUMENTATION_PROVIDER_STATES, DOCUMENTATION_RESULT_PROVIDERS, DOCUMENTATION_SEARCH_PROVIDERS, DOCUMENTATION_SEARCH_SERVICE_KEY, DOCUMENTATION_WARNING_CODES, DocumentationContext7Provider, DocumentationSearchInfrastructureError, DocumentationSearchService, type Context7CachedDocSearchInput, type Context7DocsInput, type Context7DocsResult, type Context7ResolveInput, type Context7ResolveResult, type DocumentationCachePath, type DocumentationCachePathState, type DocumentationCacheReport, type DocumentationCacheSkipReason, type DocumentationProviderState, type DocumentationProviderStatus, type DocumentationResultProvider, type DocumentationSearchDependencies, type DocumentationSearchInput, type DocumentationSearchProvider, type DocumentationSearchResult, type DocumentationWarning, type DocumentationWarningCode, } from './service.js';
+export { DOCUMENTATION_CACHE_PATH_STATES, DOCUMENTATION_CACHE_SKIP_REASONS, DOCUMENTATION_PROVIDER_STATES, DOCUMENTATION_RESULT_PROVIDERS, DOCUMENTATION_SEARCH_PROVIDERS, DOCUMENTATION_SEARCH_SERVICE_KEY, DOCUMENTATION_WARNING_CODES, DocumentationSearchInfrastructureError, DocumentationSearchService, type Context7CachedDocSearchInput, type Context7DocsInput, type Context7DocsResult, type Context7ResolveInput, type Context7ResolveResult, type DocumentationCachePath, type DocumentationCachePathState, type DocumentationCacheReport, type DocumentationCacheSkipReason, type DocumentationProviderState, type DocumentationProviderStatus, type DocumentationResultProvider, type DocumentationSearchDependencies, type DocumentationSearchInput, type DocumentationSearchProvider, type DocumentationSearchResult, type DocumentationWarning, type DocumentationWarningCode, } from './service.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/documentation/index.js

@@ -1,5 +1,5 @@
 export { CONTEXT7_CACHE_DOMAIN_NAME, CONTEXT7_CACHE_DOMAIN_SPEC, CONTEXT7_CACHE_FORMAT_VERSION, CONTEXT7_CACHE_KEY_PATTERN, CONTEXT7_CACHE_TABLE_NAME, CONTEXT7_DOC_REF_PATTERN, CachedContext7LibrarySchema, CachedDocumentationSnippetSchema, Context7CacheEntrySchema, Context7CacheKeySchema, Context7DocsCacheEntrySchema, Context7DocRefSchema, Context7ResolveCacheEntrySchema, } from './cache-domain.js';
 export { CONTEXT7_CACHE_QUERY_MAX_SCAN_RECORDS, CONTEXT7_CACHE_QUERY_MAX_TERMS, CONTEXT7_CACHE_QUERY_MAX_TEXT_CHARACTERS, Context7CacheError, Context7CacheStore, PersistentContext7Cache, context7DocsCacheKey, context7ResolveCacheKey, isContext7DocRef, } from './cache.js';
 export { CONTEXT7_CACHE_STATES, Context7CachedOperations, Context7OperationFailure, context7CacheEntryIsFresh, isContext7LibraryId, normalizeContext7LibraryId, permitsContext7StaleFallback, } from './context7-cache.js';
-export { DOCUMENTATION_CACHE_PATH_STATES, DOCUMENTATION_CACHE_SKIP_REASONS, DOCUMENTATION_PROVIDER_STATES, DOCUMENTATION_RESULT_PROVIDERS, DOCUMENTATION_SEARCH_PROVIDERS, DOCUMENTATION_SEARCH_SERVICE_KEY, DOCUMENTATION_WARNING_CODES, DocumentationContext7Provider, DocumentationSearchInfrastructureError, DocumentationSearchService, } from './service.js';
+export { DOCUMENTATION_CACHE_PATH_STATES, DOCUMENTATION_CACHE_SKIP_REASONS, DOCUMENTATION_PROVIDER_STATES, DOCUMENTATION_RESULT_PROVIDERS, DOCUMENTATION_SEARCH_PROVIDERS, DOCUMENTATION_SEARCH_SERVICE_KEY, DOCUMENTATION_WARNING_CODES, DocumentationSearchInfrastructureError, DocumentationSearchService, } from './service.js';
 //# sourceMappingURL=index.js.map

package/lib/documentation/service.d.ts

@@ -2,8 +2,8 @@ import { Service, type Context } from '@deepseek-ai/cordis';
 import type { Config } from '../config.js';
 import type { CanonicalSource, SourceRecordCandidate } from '../contracts/index.js';
 import { type ProviderAttemptRecord, type ProviderErrorKind } from '../provider-runtime/index.js';
-import { Context7RemoteClient, type Context7Library } from '../providers/context7.js';
-import type { BoundedSourceProvider, DocumentationSnippet, SourceProviderSearchInput, SourceProviderSearchOutcome } from '../providers/types.js';
+import { type Context7RemoteClient, type Context7Library } from '../providers/context7.js';
+import type { BoundedSourceProvider, DocumentationSnippet } from '../providers/types.js';
 import type { Context7DocsCacheEntry, Context7DocRef } from './cache-domain.js';
 import { type Context7CachedDocLookup, type Context7CachedDocMatch } from './cache.js';
 import { Context7CachedOperations, type Context7OperationPath } from './context7-cache.js';
@@ -43,7 +43,10 @@ export interface DocumentationWarning {
 export interface DocumentationSearchInput {
     readonly query: string;
     readonly provider?: DocumentationSearchProvider;
+    /** Exact Context7 id; when present it takes priority and bypasses resolve. */
     readonly libraryId?: string;
+    /** Explicit Context7 package/product identity; never inferred from query. */
+    readonly libraryName?: string;
     readonly maxResults: number;
     readonly forceRefresh?: boolean;
     readonly signal: AbortSignal;
@@ -125,7 +128,7 @@ export declare class DocumentationSearchInfrastructureError extends Error {
     constructor(attempts: readonly ProviderAttemptRecord[], warnings: readonly DocumentationWarning[], cache: Readonly<DocumentationCacheReport>, cause: unknown);
 }
 export interface DocumentationSearchDependencies {
-    readonly context7: Context7RemoteClient;
+    readonly context7: Pick<Context7RemoteClient, 'resolve' | 'docs'>;
     readonly context7Cache: Context7CachedOperations;
     readonly exa: BoundedSourceProvider;
     readonly getConfig: () => Config;
@@ -138,8 +141,8 @@ declare module '@deepseek-ai/cordis' {
     }
 }
 /**
- * Lifecycle-bound documentation core shared by the high-level docs Consumer,
- * enhancement routing, and the deferred granular Context7 Consumers.
+ * Lifecycle-bound documentation core shared by the high-level docs Consumer
+ * and the deferred granular Context7 Consumers.
  */
 export declare class DocumentationSearchService extends Service {
     private readonly context7;
@@ -167,13 +170,4 @@ export declare class DocumentationSearchService extends Service {
     private runContext7;
     private runExa;
 }
-/** Context7-only adapter used by web_search while sharing the high-level service/cache. */
-export declare class DocumentationContext7Provider implements BoundedSourceProvider {
-    private readonly documentation;
-    readonly capability: "docs_search";
-    readonly provider: "context7";
-    constructor(documentation: DocumentationSearchService);
-    configured(): Promise<boolean>;
-    search(input: SourceProviderSearchInput): Promise<SourceProviderSearchOutcome>;
-}
 //# sourceMappingURL=service.d.ts.map

package/lib/documentation/service.js

@@ -1,10 +1,10 @@
 import { Service } from '@deepseek-ai/cordis';
 import { createProviderAttemptRecord, isAbortError, isProviderError, ProviderError, throwIfAborted, } from '../provider-runtime/index.js';
-import { boundSourceProviderResult } from '../providers/bounded-result.js';
-import { Context7RemoteClient, context7LibrarySource, selectContext7Library, } from '../providers/context7.js';
+import { context7LibrarySource, selectContext7Library, } from '../providers/context7.js';
 import { applySourceQuality } from '../search/index.js';
 import { CONTEXT7_CACHE_QUERY_MAX_SCAN_RECORDS, } from './cache.js';
 import { CONTEXT7_CACHE_STATES, Context7CachedOperations, Context7OperationFailure, isContext7LibraryId, normalizeContext7LibraryId, } from './context7-cache.js';
+const CONTEXT7_RESOLVE_CANDIDATE_LIMIT = 30;
 export const DOCUMENTATION_SEARCH_SERVICE_KEY = 'searchEnhanceDocumentation';
 export const DOCUMENTATION_SEARCH_PROVIDERS = ['auto', 'context7', 'exa', 'all'];
 export const DOCUMENTATION_RESULT_PROVIDERS = ['context7', 'exa'];
@@ -189,17 +189,34 @@ function validateInput(input, config) {
             provider: 'documentation-search',
         });
     }
-    if (input.libraryId !== undefined && !isContext7LibraryId(input.libraryId)) {
+    let libraryId;
+    if (provider !== 'exa' && input.libraryId !== undefined) {
+        if (!isContext7LibraryId(input.libraryId)) {
+            throw new ProviderError({
+                capability: 'docs_search',
+                kind: 'invalid_request',
+                provider: 'context7',
+            });
+        }
+        libraryId = normalizeContext7LibraryId(input.libraryId);
+    }
+    const libraryName = provider !== 'exa'
+        && libraryId === undefined
+        && input.libraryName !== undefined
+        ? context7Text(input.libraryName, config)
+        : undefined;
+    if ((provider === 'context7' || provider === 'all')
+        && libraryId === undefined
+        && libraryName === undefined) {
         throw new ProviderError({
             capability: 'docs_search',
             kind: 'invalid_request',
-            provider: 'context7',
+            provider: 'context7-library-name-or-id-required',
         });
     }
     return {
-        ...(input.libraryId === undefined
-            ? {}
-            : { libraryId: normalizeContext7LibraryId(input.libraryId) }),
+        ...(libraryId === undefined ? {} : { libraryId }),
+        ...(libraryName === undefined ? {} : { libraryName }),
         provider,
         query,
     };
@@ -238,8 +255,8 @@ function frozenPathOutcome(outcome) {
     });
 }
 /**
- * Lifecycle-bound documentation core shared by the high-level docs Consumer,
- * enhancement routing, and the deferred granular Context7 Consumers.
+ * Lifecycle-bound documentation core shared by the high-level docs Consumer
+ * and the deferred granular Context7 Consumers.
  */
 export class DocumentationSearchService extends Service {
     context7;
@@ -347,6 +364,7 @@ export class DocumentationSearchService extends Service {
         await Promise.allSettled([...this.active]);
     }
     async executeContext7Resolve(input) {
+        const candidateLimit = input.candidateLimit ?? input.maxResults;
         const startedAt = safeClockValue(this.now);
         let dispatches = 0;
         const resolved = await this.context7Cache.resolve({
@@ -354,20 +372,22 @@ export class DocumentationSearchService extends Service {
             forceRefresh: input.forceRefresh,
             load: () => this.context7.resolve({
                 config: input.config,
-                limit: input.maxResults,
+                limit: candidateLimit,
                 onDispatch: () => {
                     dispatches += 1;
                     input.onDispatch?.();
                 },
-                query: input.libraryName,
+                libraryName: input.libraryName,
+                query: input.query,
                 signal: input.signal,
             }),
-            maxResults: input.maxResults,
-            query: input.libraryName,
+            maxResults: candidateLimit,
+            libraryName: input.libraryName,
+            query: input.query,
             signal: input.signal,
         });
-        const candidates = Object.freeze([...resolved.entry.libraries]);
-        const selected = selectContext7Library(candidates, input.libraryName, input.query);
+        const candidates = Object.freeze(resolved.entry.libraries.slice(0, input.maxResults));
+        const selected = selectContext7Library(resolved.entry.libraries, input.libraryName, input.query);
         return Object.freeze({
             attempts: successfulCacheAttempts('resolve', resolved, dispatches, elapsed(startedAt, this.now)),
             cache: cachePath(resolved.cache, resolved.evictedEntries),
@@ -417,8 +437,12 @@ export class DocumentationSearchService extends Service {
         const config = input.config ?? this.getConfig();
         const validated = validateInput(input, config);
         const forceRefresh = input.forceRefresh === true;
-        const runContext7 = validated.provider !== 'exa';
-        const autoExa = validated.provider === 'auto' && config.fallbackMode === 'auto';
+        const hasContext7Identity = validated.libraryId !== undefined || validated.libraryName !== undefined;
+        const runContext7 = validated.provider === 'context7'
+            || validated.provider === 'all'
+            || (validated.provider === 'auto' && hasContext7Identity);
+        const autoExa = validated.provider === 'auto'
+            && (!hasContext7Identity || config.fallbackMode === 'auto');
         const considerExa = validated.provider === 'exa' || validated.provider === 'all' || autoExa;
         let exaConfigured = false;
         let exaProbeError;
@@ -438,6 +462,7 @@ export class DocumentationSearchService extends Service {
                 config,
                 forceRefresh,
                 ...(validated.libraryId === undefined ? {} : { libraryId: validated.libraryId }),
+                ...(validated.libraryName === undefined ? {} : { libraryName: validated.libraryName }),
                 maxResults: input.maxResults,
                 query: validated.query,
                 signal,
@@ -631,13 +656,21 @@ export class DocumentationSearchService extends Service {
             attempts.push(skippedAttempt('context7-resolve'));
         }
         else {
+            if (input.libraryName === undefined) {
+                throw new ProviderError({
+                    capability: 'docs_search',
+                    kind: 'invalid_request',
+                    provider: 'context7-library-name-or-id-required',
+                });
+            }
             const startedAt = safeClockValue(this.now);
             try {
                 const resolved = await this.executeContext7Resolve({
                     config: input.config,
                     forceRefresh: input.forceRefresh,
-                    libraryName: input.query,
+                    libraryName: input.libraryName,
                     maxResults: input.maxResults,
+                    candidateLimit: Math.min(CONTEXT7_RESOLVE_CANDIDATE_LIMIT, input.config.retention.providerMaxSources),
                     onDispatch: () => { resolveDispatches += 1; },
                     query: input.query,
                     signal: input.signal,
@@ -835,65 +868,4 @@ export class DocumentationSearchService extends Service {
         }
     }
 }
-/** Context7-only adapter used by web_search while sharing the high-level service/cache. */
-export class DocumentationContext7Provider {
-    documentation;
-    capability = 'docs_search';
-    provider = 'context7';
-    constructor(documentation) {
-        this.documentation = documentation;
-    }
-    async configured() {
-        return true;
-    }
-    async search(input) {
-        let result;
-        try {
-            result = await this.documentation.search({
-                config: input.config,
-                forceRefresh: false,
-                maxResults: input.limit,
-                provider: 'context7',
-                query: input.query,
-                signal: input.signal,
-            });
-        }
-        catch (error) {
-            if (error instanceof DocumentationSearchInfrastructureError && error.cause !== undefined) {
-                throw error.cause;
-            }
-            throw error;
-        }
-        const warnings = result.warnings.flatMap(warning => {
-            if (warning.code !== 'cache_stale'
-                && warning.code !== 'cache_evicted'
-                && warning.code !== 'provider_failed')
-                return [];
-            return [Object.freeze({
-                    code: warning.code,
-                    ...(warning.errorKind === undefined ? {} : { errorKind: warning.errorKind }),
-                    provider: warning.provider ?? 'context7',
-                })];
-        });
-        const attempts = result.attempts
-            .filter(attempt => !attempt.provider.startsWith('context7-cache-'))
-            .reduce((sum, attempt) => sum + attempt.attempts, 0);
-        return Object.freeze({
-            attempts: Math.max(1, attempts),
-            result: boundSourceProviderResult({
-                capability: 'docs_search',
-                config: input.config,
-                inputTruncated: result.truncated,
-                provider: 'context7',
-                requestedSources: input.limit,
-                responseBytes: result.providerResponseBytes,
-                snippets: result.snippets,
-                sources: result.sources,
-            }),
-            state: 'complete',
-            totalDelayMs: 0,
-            ...(warnings.length === 0 ? {} : { warnings: Object.freeze(warnings) }),
-        });
-    }
-}
 //# sourceMappingURL=service.js.map

package/lib/index.js

@@ -1,6 +1,6 @@
 import { Context7ResolveDiagnosticProbe, SearchApiModelListDiagnosticProbe, SearchDiagnostics, SourceSearchDiagnosticProbe, } from './diagnostics/index.js';
 import { Config as SearchEnhanceConfig, SEARCH_ENHANCE_SETTINGS_NAMESPACE, } from './config.js';
-import { Context7CachedOperations, DocumentationContext7Provider, DocumentationSearchService, PersistentContext7Cache, } from './documentation/index.js';
+import { Context7CachedOperations, DocumentationSearchService, PersistentContext7Cache, } from './documentation/index.js';
 import { SearchOrchestrator } from './orchestration/index.js';
 import { registerToolDiscoveryGuidance } from './prompt/tool-discovery.js';
 import { Context7RemoteClient } from './providers/context7.js';
@@ -82,7 +82,6 @@ export async function apply(ctx, config) {
         ],
     });
     const orchestrator = new SearchOrchestrator({
-        context7: new DocumentationContext7Provider(documentation),
         exa,
         firecrawl,
         getConfig,

package/lib/orchestration/orchestrator.d.ts

@@ -16,7 +16,6 @@ export declare function mergeCanonicalSources(...groups: ReadonlyArray<readonly
 export declare class SearchOrchestrator {
     private readonly getConfig;
     private readonly mainSearch;
-    private readonly context7;
     private readonly exa;
     private readonly tavily;
     private readonly firecrawl;

package/lib/orchestration/orchestrator.js

@@ -294,7 +294,6 @@ function sourceAttempt(slot, mainFailed) {
 export class SearchOrchestrator {
     getConfig;
     mainSearch;
-    context7;
     exa;
     tavily;
     firecrawl;
@@ -302,7 +301,6 @@ export class SearchOrchestrator {
     constructor(dependencies) {
         this.getConfig = dependencies.getConfig;
         this.mainSearch = dependencies.mainSearch;
-        this.context7 = dependencies.context7;
         this.exa = dependencies.exa;
         this.tavily = dependencies.tavily;
         this.firecrawl = dependencies.firecrawl;
@@ -347,17 +345,6 @@ export class SearchOrchestrator {
         const relayAbort = () => fanout.abort(signal.reason);
         signal.addEventListener('abort', relayAbort, { once: true });
         const slots = [
-            {
-                available: false,
-                capability: 'docs_search',
-                key: 'context7',
-                limit: 0,
-                planningDurationMs: 0,
-                planningError: undefined,
-                provider: this.context7,
-                skipReason: undefined,
-                track: undefined,
-            },
             {
                 available: false,
                 capability: 'docs_search',
@@ -438,8 +425,8 @@ export class SearchOrchestrator {
             }
             throwIfAborted(signal);
             throwIfAborted(fanout.signal);
-            const tavilySlot = slots[2];
-            const firecrawlSlot = slots[3];
+            const tavilySlot = slots[1];
+            const firecrawlSlot = slots[2];
             if (tavilySlot === undefined || firecrawlSlot === undefined) {
                 throw new Error('discovery slots are incomplete');
             }

package/lib/orchestration/types.d.ts

@@ -65,7 +65,6 @@ export interface MainSearchProvider {
 export interface SearchOrchestratorDependencies {
     readonly getConfig: () => Config;
     readonly mainSearch: MainSearchProvider;
-    readonly context7: BoundedSourceProvider;
     readonly exa: BoundedSourceProvider;
     readonly tavily: BoundedSourceProvider;
     readonly firecrawl: BoundedSourceProvider;

package/lib/presentation/render.d.ts

@@ -1,4 +1,8 @@
 import type { DocsSearchOutput, WebSearchOutput, SearchDiagnosticsOutput, SearchSourcesOutput, WebExtractOutput, WebMapOutput } from '../tools/schemas.js';
+export declare function sourceDisplayLabel(source: {
+    readonly title?: string;
+    readonly url: string;
+}): string;
 /**
  * Pure Native projection in the product-defined order. The operation-selected
  * limit is carried in the canonical value, so replay never consults Settings,

package/lib/presentation/render.js

@@ -3,6 +3,11 @@ const DISCOVERY_NOTICE = 'Evidence level: discovery. Snippets are discovery meta
 function inline(value) {
     return value.replace(/\s+/gu, ' ').trim();
 }
+export function sourceDisplayLabel(source) {
+    if (source.title !== undefined && source.title.trim().length > 0)
+        return source.title;
+    return new URL(source.url).hostname;
+}
 function renderWithBoundedNotice(text, notice, maximumBytes, fallbackNotice) {
     if (notice === undefined || notice.length === 0) {
         return truncateUtf8(text, maximumBytes).text;
@@ -77,7 +82,7 @@ function sourceSection(value) {
         const source = value.sources[index];
         if (source === undefined)
             continue;
-        lines.push(`${index + 1}. ${inline(source.title ?? 'Untitled source')}`);
+        lines.push(`${index + 1}. ${inline(sourceDisplayLabel(source))}`);
         lines.push(`   URL: ${source.url}`);
         if (source.publishedAt !== undefined) {
             lines.push(`   Date: ${inline(source.publishedAt)}`);
@@ -190,7 +195,7 @@ function docsSourceSection(value) {
         const source = value.sources[index];
         if (source === undefined)
             continue;
-        lines.push(`${index + 1}. ${inline(source.title ?? 'Untitled source')}`);
+        lines.push(`${index + 1}. ${inline(sourceDisplayLabel(source))}`);
         lines.push(`   URL: ${source.url}`);
         if (source.publishedAt !== undefined)
             lines.push(`   Date: ${inline(source.publishedAt)}`);
@@ -247,7 +252,7 @@ function renderPageSources(page) {
         const source = page.sources[index];
         if (source === undefined)
             continue;
-        lines.push(`${page.offset + index + 1}. ${inline(source.title ?? 'Untitled source')}`);
+        lines.push(`${page.offset + index + 1}. ${inline(sourceDisplayLabel(source))}`);
         lines.push(`   URL: ${source.url}`);
         lines.push(`   Category: ${source.category}`);
         if (source.date !== undefined)

package/lib/prompt/tool-discovery.js

@@ -1,5 +1,7 @@
 export const TOOL_DISCOVERY_GUIDANCE = [
     'Search Enhance keeps a fixed model-facing surface: web_search, docs_search, web_extract, search_tools, and search_call.',
+    'For docs_search, pass library_id when an exact /org/project id is known, or pass library_name directly when the package or product is known; for example docs_search({ query: "JWT authentication middleware API", library_name: "FastAPI" }). Do not activate granular Context7 merely to resolve first.',
+    'For broad, cross-project, or unknown-library documentation discovery, use docs_search with provider: "auto" and no library identity; this uses Exa instead of guessing a Context7 library.',
     'Use search_tools only when the resident search tools cannot complete the task. It returns append-only capability and operation manifests; do not activate every capability preemptively.',
     'Run a manifested deferred operation with search_call({ operation, arguments }). In progressive mode, a newly disclosed capability is callable on the next model step; in all mode, deferred operations are active immediately. search_call fails closed while an operation is inactive.',
     'Activate planning only for explicit deep research, multi-source verification, or complex comparison. Activate diagnostics only when the user asks about Provider configuration or connectivity.',

package/lib/providers/context7.d.ts

@@ -3,10 +3,14 @@ import type { CanonicalSource } from '../contracts/index.js';
 import type { CachedContext7Library } from '../documentation/cache-domain.js';
 import { type Context7DocsRemoteResult, type Context7ResolveRemoteResult } from '../documentation/context7-cache.js';
 import { type ProviderHttpDependencies } from './http.js';
-import type { BoundedSourceProvider, DocumentationSnippet, SourceProviderSearchInput, SourceProviderSearchOutcome } from './types.js';
+import type { DocumentationSnippet, SourceProviderSearchInput } from './types.js';
 export interface Context7ProviderDependencies extends ProviderHttpDependencies {
     readonly credentials: Pick<CredentialProvider, 'describe' | 'resolve'>;
 }
+/** Explicit Context7 library identity and independent documentation task. */
+export interface Context7ResolveRemoteInput extends SourceProviderSearchInput {
+    readonly libraryName: string;
+}
 export type Context7Library = CachedContext7Library;
 export interface ParsedContext7Libraries {
     readonly libraries: readonly Context7Library[];
@@ -22,7 +26,7 @@ export interface ParsedContext7Snippets {
 export declare function parseContext7LibraryResponse(body: string, maximumItems: number, maximumTextCharacters: number): Readonly<ParsedContext7Libraries>;
 /** Compatibility parser with fixed defensive ceilings. */
 export declare function parseContext7Libraries(body: string): readonly Context7Library[];
-/** Stable selection by exact name, description relevance, trust, benchmark, and snippet coverage. */
+/** Stable selection led by explicit library identity, then bounded secondary signals. */
 export declare function selectContext7Library(libraries: readonly Context7Library[], libraryName: string, query?: string): Context7Library | undefined;
 /** Parse JSON or plain-text Context7 v2 documentation bodies exactly once and bound every snippet. */
 export declare function parseContext7SnippetResponse(body: string, maximumItems: number, maximumCharacters: number): Readonly<ParsedContext7Snippets>;
@@ -39,18 +43,9 @@ export declare class Context7RemoteClient {
     private readonly credentials;
     private readonly http;
     constructor(dependencies: Context7ProviderDependencies);
-    resolve(input: SourceProviderSearchInput): Promise<Readonly<Context7ResolveRemoteResult>>;
+    resolve(input: Context7ResolveRemoteInput): Promise<Readonly<Context7ResolveRemoteResult>>;
     docs(input: SourceProviderSearchInput & {
         readonly libraryId: string;
     }): Promise<Readonly<Context7DocsRemoteResult>>;
 }
-/** Direct resolve-then-docs adapter retained for registration-free Provider use. */
-export declare class Context7Provider implements BoundedSourceProvider {
-    readonly capability = "docs_search";
-    readonly provider = "context7";
-    private readonly remote;
-    constructor(dependencies: Context7ProviderDependencies);
-    configured(): Promise<boolean>;
-    search(input: SourceProviderSearchInput): Promise<SourceProviderSearchOutcome>;
-}
 //# sourceMappingURL=context7.d.ts.map

package/lib/providers/context7.js

@@ -1,6 +1,5 @@
 import { isContext7LibraryId, normalizeContext7LibraryId, } from '../documentation/context7-cache.js';
 import { ProviderError, truncateCharacters } from '../provider-runtime/index.js';
-import { boundSourceProviderResult } from './bounded-result.js';
 import { canonicalHttpUrl, firstString, isRecord, nonEmptyQuery, positiveLimit, providerEndpoint, resolveOptionalCredential, } from './helpers.js';
 import { ProviderHttpClient } from './http.js';
 const PROVIDER = 'context7';
@@ -121,50 +120,55 @@ export function parseContext7Libraries(body) {
 function normalizedMatchText(value) {
     return (value ?? '').toLowerCase().replace(/^@/, '').replace(/[^a-z0-9]+/g, '');
 }
-function context7LibraryScore(item, libraryName, query) {
+function normalizedTerms(value) {
+    return value.toLowerCase()
+        .split(/[^a-z0-9@._-]+/)
+        .map(normalizedMatchText)
+        .filter(term => term.length > 0);
+}
+function context7LibraryScore(item, libraryName, queryTerms) {
     const wanted = normalizedMatchText(libraryName);
     const rawText = `${item.id ?? ''} ${item.title ?? ''} ${item.description ?? ''}`.toLowerCase();
     const title = normalizedMatchText(item.title);
     const description = normalizedMatchText(item.description);
     const idSegments = (item.id ?? '').split('/').filter(Boolean).map(normalizedMatchText);
     let score = 0;
-    if (/official.*documentation|documentation.*official|official docs|react\.dev/.test(rawText))
-        score += 260;
-    if (rawText.includes('react.dev'))
-        score += 120;
     if (wanted.length > 0) {
-        if (title === wanted)
-            score += 240;
-        if (idSegments.some(segment => segment === wanted))
-            score += 220;
-        if (idSegments.at(-1) === wanted)
-            score += 40;
-        if (title.startsWith(wanted))
-            score += 50;
-        if (title.includes(wanted))
-            score += 20;
+        const titleIdentity = title === wanted
+            ? 1000
+            : title.startsWith(wanted)
+                ? 200
+                : title.includes(wanted)
+                    ? 100
+                    : 0;
+        const idIdentity = idSegments.some(segment => segment === wanted)
+            ? 900 + (idSegments.at(-1) === wanted ? 100 : 0)
+            : 0;
+        score += Math.max(titleIdentity, idIdentity);
         if (description.includes(wanted))
-            score += 8;
+            score += 15;
     }
-    for (const term of query.toLowerCase().split(/[^a-z0-9@.\-/]+/).filter(term => term.length > 1)) {
-        const normalizedTerm = normalizedMatchText(term);
-        if (normalizedTerm.length === 0)
+    let queryRelevance = 0;
+    for (const term of queryTerms) {
+        if (term.length <= 1)
             continue;
-        if (title === normalizedTerm)
-            score += 24;
-        else if (title.includes(normalizedTerm))
-            score += 2;
-        if (idSegments.some(segment => segment === normalizedTerm))
-            score += 20;
-        if (description.includes(normalizedTerm))
-            score += 1;
+        if (title === term)
+            queryRelevance += 3;
+        else if (title.includes(term))
+            queryRelevance += 1;
+        if (idSegments.some(segment => segment === term))
+            queryRelevance += 2;
+        if (description.includes(term))
+            queryRelevance += 1;
     }
+    score += Math.min(30, queryRelevance);
     if (/official|documentation|docs/.test(rawText))
         score += 10;
     if (item.trustScore !== undefined)
-        score += item.trustScore * 2;
-    if (item.benchmarkScore !== undefined)
-        score += item.benchmarkScore / 2;
+        score += Math.min(20, Math.max(0, item.trustScore) * 2);
+    if (item.benchmarkScore !== undefined) {
+        score += Math.min(50, Math.max(0, item.benchmarkScore) / 2);
+    }
     if (item.totalSnippets !== undefined) {
         score += Math.min(30, Math.log10(Math.max(1, item.totalSnippets)) * 8);
     }
@@ -172,13 +176,14 @@ function context7LibraryScore(item, libraryName, query) {
         score += Math.min(20, Math.log10(Math.max(1, item.stars)) * 4);
     return score;
 }
-/** Stable selection by exact name, description relevance, trust, benchmark, and snippet coverage. */
+/** Stable selection led by explicit library identity, then bounded secondary signals. */
 export function selectContext7Library(libraries, libraryName, query = libraryName) {
+    const queryTerms = normalizedTerms(query);
     return libraries
         .map((library, index) => ({
         index,
         library,
-        score: context7LibraryScore(library, libraryName, query),
+        score: context7LibraryScore(library, libraryName, queryTerms),
     }))
         .filter(candidate => isContext7LibraryId(candidate.library.id))
         .sort((left, right) => right.score - left.score || left.index - right.index)[0]?.library;
@@ -288,12 +293,14 @@ export class Context7RemoteClient {
         this.http = new ProviderHttpClient(dependencies);
     }
     async resolve(input) {
+        const libraryName = nonEmptyQuery(input.libraryName, PROVIDER, CAPABILITY);
         const query = nonEmptyQuery(input.query, PROVIDER, CAPABILITY);
         const limit = positiveLimit(input.limit, PROVIDER, CAPABILITY);
         const providerConfig = input.config.providers.context7;
         const credential = await resolveOptionalCredential(this.credentials, providerConfig.credentialRef, input.signal, PROVIDER, CAPABILITY);
-        const resolveUrl = new URL(providerEndpoint(providerConfig.baseUrl, '/api/v2/search'));
+        const resolveUrl = new URL(providerEndpoint(providerConfig.baseUrl, '/api/v2/libs/search'));
         resolveUrl.searchParams.set('query', query);
+        resolveUrl.searchParams.set('libraryName', libraryName);
         const response = await this.http.requestText({
             capability: CAPABILITY,
             endpoint: resolveUrl.href,
@@ -346,60 +353,4 @@ export class Context7RemoteClient {
         });
     }
 }
-/** Direct resolve-then-docs adapter retained for registration-free Provider use. */
-export class Context7Provider {
-    capability = CAPABILITY;
-    provider = PROVIDER;
-    remote;
-    constructor(dependencies) {
-        this.remote = new Context7RemoteClient(dependencies);
-    }
-    async configured() {
-        return true;
-    }
-    async search(input) {
-        const query = nonEmptyQuery(input.query, PROVIDER, CAPABILITY);
-        const limit = positiveLimit(input.limit, PROVIDER, CAPABILITY);
-        const resolved = await this.remote.resolve({ ...input, query, limit });
-        const selected = selectContext7Library(resolved.libraries, query, query);
-        if (selected?.id === undefined || !isContext7LibraryId(selected.id)) {
-            return Object.freeze({
-                attempts: resolved.attempts,
-                result: boundSourceProviderResult({
-                    capability: CAPABILITY,
-                    config: input.config,
-                    inputTruncated: resolved.truncated,
-                    provider: PROVIDER,
-                    requestedSources: limit,
-                    responseBytes: resolved.responseBytes,
-                    sources: [],
-                }),
-                state: 'complete',
-                totalDelayMs: resolved.totalDelayMs,
-            });
-        }
-        const libraryId = normalizeContext7LibraryId(selected.id);
-        const docs = await this.remote.docs({ ...input, libraryId, query, limit });
-        const snippets = docs.snippets.map(snippet => Object.freeze({
-            ...snippet,
-            libraryId,
-        }));
-        const source = context7LibrarySource(selected, input.config.providers.context7.baseUrl, input.config.webExtract.maxUrlCharacters, snippets[0]?.content ?? selected.description);
-        return Object.freeze({
-            attempts: resolved.attempts + docs.attempts,
-            result: boundSourceProviderResult({
-                capability: CAPABILITY,
-                config: input.config,
-                inputTruncated: resolved.truncated || docs.truncated,
-                provider: PROVIDER,
-                requestedSources: limit,
-                responseBytes: resolved.responseBytes + docs.responseBytes,
-                snippets,
-                sources: source === undefined ? [] : [source],
-            }),
-            state: 'complete',
-            totalDelayMs: resolved.totalDelayMs + docs.totalDelayMs,
-        });
-    }
-}
 //# sourceMappingURL=context7.js.map

package/lib/providers/index.d.ts

@@ -1,5 +1,5 @@
 export { boundSourceProviderResult, type BoundSourceProviderResultInput, } from './bounded-result.js';
-export { Context7Provider, Context7RemoteClient, context7LibrarySource, context7LibraryUrl, parseContext7Libraries, parseContext7LibraryResponse, parseContext7Snippets, parseContext7SnippetResponse, selectContext7Library, type Context7Library, type Context7ProviderDependencies, type ParsedContext7Libraries, type ParsedContext7Snippets, } from './context7.js';
+export { Context7RemoteClient, context7LibrarySource, context7LibraryUrl, parseContext7Libraries, parseContext7LibraryResponse, parseContext7Snippets, parseContext7SnippetResponse, selectContext7Library, type Context7Library, type Context7ProviderDependencies, type Context7ResolveRemoteInput, type ParsedContext7Libraries, type ParsedContext7Snippets, } from './context7.js';
 export { SmartDirectAdapter, SmartDirectProvider, type SmartDirectProviderDependencies, } from './smart-direct.js';
 export { SMART_DIRECT_BROWSER_PROFILES, SMART_DIRECT_OPERATING_SYSTEMS, type SmartDirectBrowserProfile, type SmartDirectOperatingSystem, } from './smart-direct-profiles.js';
 export { DirectFetchAdapter, DirectFetchProvider, type DirectFetchProviderDependencies, } from './direct-fetch.js';

package/lib/providers/index.js

@@ -1,5 +1,5 @@
 export { boundSourceProviderResult, } from './bounded-result.js';
-export { Context7Provider, Context7RemoteClient, context7LibrarySource, context7LibraryUrl, parseContext7Libraries, parseContext7LibraryResponse, parseContext7Snippets, parseContext7SnippetResponse, selectContext7Library, } from './context7.js';
+export { Context7RemoteClient, context7LibrarySource, context7LibraryUrl, parseContext7Libraries, parseContext7LibraryResponse, parseContext7Snippets, parseContext7SnippetResponse, selectContext7Library, } from './context7.js';
 export { SmartDirectAdapter, SmartDirectProvider, } from './smart-direct.js';
 export { SMART_DIRECT_BROWSER_PROFILES, SMART_DIRECT_OPERATING_SYSTEMS, } from './smart-direct-profiles.js';
 export { DirectFetchAdapter, DirectFetchProvider, } from './direct-fetch.js';

package/lib/search/parse.d.ts

@@ -31,7 +31,7 @@ export interface ParsedSearchApiResponse {
 }
 /** Extract URL-validated inline Markdown citations in answer order for internal orchestration. */
 export declare function extractMarkdownCitationUrls(text: string, maximumUrlCharacters?: number): readonly string[];
-/** Convert Search API prose/source conventions immediately into provider-neutral records. */
+/** Convert Search API prose/source conventions with one bounded link scan and exact-URL enrichment. */
 export declare function parseSearchAnswerText(text: string, limitOverrides?: Partial<SearchResponseParseLimits>): ParsedSearchApiResponse;
 /**
  * Parse a complete, already-bounded Search API body (SSE or non-streaming JSON).

package/lib/search/parse.js

@@ -28,9 +28,9 @@ export const DEFAULT_SEARCH_RESPONSE_PARSE_LIMITS = Object.freeze({
     maxTitleCharacters: 1000,
     maxUrlCharacters: 8192,
 });
-const URL_PATTERN = /https?:\/\/[^\s<>"'`，。、；：！？》）】)]+/g;
-const MARKDOWN_LINK_PATTERN = /\[([^\]]+)]\((https?:\/\/[^)]+)\)/g;
-const MARKDOWN_LINK_LINE_PATTERN = /\[[^\]]+]\(https?:\/\/[^)]+\)/;
+const BARE_URL_PATTERN = /https?:\/\/[^\s<>"'`，。、；：！？》）】]+/g;
+const MARKDOWN_URL_BOUNDARIES = new Set(['<', '>', '"', "'", '`', '，', '。', '、', '；', '：', '！', '？', '》', '）', '】']);
+const URL_TRAILING_PUNCTUATION = new Set(['.', ',', ';', ':', '!', '?']);
 const SOURCES_HEADING_PATTERN = /(?:^|\n)(?:#{1,6}\s*)?(?:\*\*|__)?\s*(?:sources?|references?|citations?|信源|参考资料|参考|引用|来源列表|来源)(?:\s*[（(][^)\n]*[)）])?\s*(?:(?:\*\*|__)\s*)?[:：]?\s*(?:(?:\*\*|__)\s*)?$/gim;
 const SOURCES_FUNCTION_PATTERN = /(^|\n)\s*(sources|source|citations|citation|references|reference|citation_card|source_cards|source_card)\s*\(/gim;
 function isRecord(value) {
@@ -78,8 +78,172 @@ function firstBoundedString(record, keys, maximum) {
     }
     return undefined;
 }
+function isAsciiDigit(character) {
+    return character !== undefined && character >= '0' && character <= '9';
+}
+function isCitationOrdinalLabel(label) {
+    const trimmed = label.trim();
+    if (trimmed.length === 0)
+        return false;
+    for (let index = 0; index < trimmed.length; index += 1) {
+        if (!isAsciiDigit(trimmed[index]))
+            return false;
+    }
+    return true;
+}
+function isMarkdownUrlBoundary(character) {
+    return /\s/u.test(character) || MARKDOWN_URL_BOUNDARIES.has(character);
+}
+/** Scan the supported Markdown HTTP(S) link subset once without recursive parsing. */
+function scanMarkdownHttpLinks(text) {
+    const links = [];
+    const intervals = [];
+    const scanDestination = (urlStart) => {
+        if (!text.startsWith('http://', urlStart) && !text.startsWith('https://', urlStart)) {
+            return { resume: urlStart };
+        }
+        let depth = 0;
+        for (let index = urlStart; index < text.length; index += 1) {
+            const character = text[index];
+            if (character === undefined)
+                break;
+            if (isMarkdownUrlBoundary(character))
+                return { resume: index + 1 };
+            if (character === '(') {
+                depth += 1;
+            }
+            else if (character === ')') {
+                if (depth === 0) {
+                    return {
+                        end: index + 1,
+                        resume: index + 1,
+                        url: text.slice(urlStart, index),
+                    };
+                }
+                depth -= 1;
+            }
+        }
+        return { resume: text.length };
+    };
+    let cursor = 0;
+    while (cursor < text.length) {
+        const start = text.indexOf('[', cursor);
+        if (start === -1)
+            break;
+        if (start > 0 && text[start - 1] === '[') {
+            cursor = start + 1;
+            continue;
+        }
+        let label;
+        let citationOrdinal;
+        let destinationOpen;
+        if (text[start + 1] === '[') {
+            const digitsStart = start + 2;
+            let labelEnd = digitsStart;
+            while (isAsciiDigit(text[labelEnd]))
+                labelEnd += 1;
+            if (labelEnd === digitsStart
+                || text[labelEnd] !== ']'
+                || text[labelEnd + 1] !== ']'
+                || text[labelEnd + 2] !== '(') {
+                labelEnd = text[digitsStart] === '[' ? digitsStart + 1 : digitsStart;
+                while (labelEnd < text.length
+                    && text[labelEnd] !== ']'
+                    && text[labelEnd] !== '['
+                    && !isMarkdownUrlBoundary(text[labelEnd] ?? ''))
+                    labelEnd += 1;
+                if (text[labelEnd] === ']'
+                    && text[labelEnd + 1] === ']'
+                    && text[labelEnd + 2] === '(') {
+                    const rejected = scanDestination(labelEnd + 3);
+                    if (rejected.end !== undefined) {
+                        intervals.push(Object.freeze({ end: rejected.end, start }));
+                    }
+                    cursor = rejected.resume;
+                }
+                else {
+                    cursor = text[labelEnd] === '[' ? labelEnd : labelEnd + 1;
+                }
+                continue;
+            }
+            label = text.slice(digitsStart, labelEnd);
+            citationOrdinal = true;
+            destinationOpen = labelEnd + 2;
+        }
+        else {
+            const labelStart = start + 1;
+            let labelEnd = labelStart;
+            while (labelEnd < text.length
+                && text[labelEnd] !== ']'
+                && text[labelEnd] !== '[')
+                labelEnd += 1;
+            if (labelEnd === labelStart
+                || text[labelEnd] !== ']'
+                || text[labelEnd + 1] !== '(') {
+                cursor = text[labelEnd] === '[' ? labelEnd : labelEnd + 1;
+                continue;
+            }
+            label = text.slice(labelStart, labelEnd);
+            citationOrdinal = isCitationOrdinalLabel(label);
+            destinationOpen = labelEnd + 1;
+        }
+        const destination = scanDestination(destinationOpen + 1);
+        if (destination.end !== undefined && destination.url !== undefined) {
+            const link = Object.freeze({
+                citationOrdinal,
+                end: destination.end,
+                label,
+                start,
+                url: destination.url,
+            });
+            links.push(link);
+            intervals.push(link);
+        }
+        cursor = destination.resume;
+    }
+    return Object.freeze({
+        intervals: Object.freeze(intervals),
+        links: Object.freeze(links),
+    });
+}
+/** Remove only sentence punctuation and unmatched ASCII closing parens at the URL tail. */
+function trimUrlTail(raw) {
+    const value = raw.trim();
+    const unmatchedClosings = [];
+    let depth = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index];
+        if (character === '(')
+            depth += 1;
+        else if (character === ')') {
+            if (depth === 0)
+                unmatchedClosings.push(index);
+            else
+                depth -= 1;
+        }
+    }
+    let end = value.length;
+    let unmatchedIndex = unmatchedClosings.length - 1;
+    let changed = true;
+    while (changed) {
+        changed = false;
+        while (end > 0 && URL_TRAILING_PUNCTUATION.has(value[end - 1] ?? '')) {
+            end -= 1;
+            changed = true;
+        }
+        while (unmatchedIndex >= 0 && (unmatchedClosings[unmatchedIndex] ?? -1) >= end) {
+            unmatchedIndex -= 1;
+        }
+        if (unmatchedClosings[unmatchedIndex] === end - 1) {
+            end -= 1;
+            unmatchedIndex -= 1;
+            changed = true;
+        }
+    }
+    return value.slice(0, end);
+}
 function validatedHttpUrl(raw, limits) {
-    const url = raw.trim().replace(/[.,;:!?]+$/, '');
+    const url = trimUrlTail(raw);
     const actual = characterLength(url);
     if (actual > limits.maxUrlCharacters) {
         throw new SearchResponseParseError('limit', { actual, maximum: limits.maxUrlCharacters });
@@ -96,13 +260,31 @@ function validatedHttpUrl(raw, limits) {
 }
 function addSource(state, candidate, limits) {
     const url = validatedHttpUrl(candidate.url, limits);
-    if (url === undefined || state.seen.has(url))
+    if (url === undefined)
         return;
-    state.seen.add(url);
+    const existingIndex = state.sourceIndexByUrl.get(url);
+    if (existingIndex !== undefined) {
+        const existing = state.sources[existingIndex];
+        const title = existing.title ?? candidate.title;
+        const snippet = existing.snippet ?? candidate.snippet;
+        const publishedAt = existing.publishedAt ?? candidate.publishedAt;
+        if (title !== existing.title
+            || snippet !== existing.snippet
+            || publishedAt !== existing.publishedAt) {
+            state.sources[existingIndex] = Object.freeze({
+                ...existing,
+                ...(title === undefined ? {} : { title }),
+                ...(snippet === undefined ? {} : { snippet }),
+                ...(publishedAt === undefined ? {} : { publishedAt }),
+            });
+        }
+        return;
+    }
     if (state.sources.length >= limits.maxSources) {
         state.truncated = true;
         return;
     }
+    const index = state.sources.length;
     state.sources.push(Object.freeze({
         provider: 'search-api',
         url,
@@ -110,40 +292,50 @@ function addSource(state, candidate, limits) {
         ...(candidate.snippet === undefined ? {} : { snippet: candidate.snippet }),
         ...(candidate.publishedAt === undefined ? {} : { publishedAt: candidate.publishedAt }),
     }));
+    state.sourceIndexByUrl.set(url, index);
 }
 function extractUrls(text) {
     const urls = [];
-    const seen = new Set();
-    for (const match of text.matchAll(URL_PATTERN)) {
+    for (const match of text.matchAll(BARE_URL_PATTERN)) {
         const raw = match[0];
         if (raw === undefined)
             continue;
-        const url = raw.replace(/[.,;:!?]+$/, '');
-        if (seen.has(url))
-            continue;
-        seen.add(url);
-        urls.push(url);
+        urls.push(raw);
     }
     return urls;
 }
-function addMarkdownSources(text, state, limits) {
-    for (const match of text.matchAll(MARKDOWN_LINK_PATTERN)) {
-        const rawTitle = match[1];
-        const rawUrl = match[2];
-        if (rawTitle === undefined || rawUrl === undefined)
-            continue;
-        const title = boundedOptionalString(rawTitle, limits.maxTitleCharacters);
+function addMarkdownSources(links, state, limits) {
+    for (const link of links) {
+        const title = link.citationOrdinal
+            ? undefined
+            : boundedOptionalString(link.label, limits.maxTitleCharacters);
         addSource(state, {
-            url: rawUrl,
+            url: link.url,
             ...(title === undefined ? {} : { title }),
         }, limits);
     }
 }
+function maskMarkdownLinkIntervals(text, intervals) {
+    if (intervals.length === 0)
+        return text;
+    const parts = [];
+    let cursor = 0;
+    for (const link of intervals) {
+        parts.push(text.slice(cursor, link.start), ' ');
+        cursor = link.end;
+    }
+    parts.push(text.slice(cursor));
+    return parts.join('');
+}
 /** Extract URL-validated inline Markdown citations in answer order for internal orchestration. */
 export function extractMarkdownCitationUrls(text, maximumUrlCharacters = DEFAULT_SEARCH_RESPONSE_PARSE_LIMITS.maxUrlCharacters) {
     assertSafeInteger(maximumUrlCharacters, 'maximumUrlCharacters', false);
-    const state = { seen: new Set(), sources: [], truncated: false };
-    addMarkdownSources(text, state, {
+    const state = {
+        sourceIndexByUrl: new Map(),
+        sources: [],
+        truncated: false,
+    };
+    addMarkdownSources(scanMarkdownHttpLinks(text).links, state, {
         ...DEFAULT_SEARCH_RESPONSE_PARSE_LIMITS,
         maxSources: Number.MAX_SAFE_INTEGER,
         maxUrlCharacters: maximumUrlCharacters,
@@ -151,8 +343,9 @@ export function extractMarkdownCitationUrls(text, maximumUrlCharacters = DEFAULT
     return Object.freeze(state.sources.map(source => source.url));
 }
 function addTextSources(text, state, limits) {
-    addMarkdownSources(text, state, limits);
-    const bareText = text.replace(MARKDOWN_LINK_PATTERN, ' ');
+    const markdown = scanMarkdownHttpLinks(text);
+    addMarkdownSources(markdown.links, state, limits);
+    const bareText = maskMarkdownLinkIntervals(text, markdown.intervals);
     for (const url of extractUrls(bareText))
         addSource(state, { url }, limits);
 }
@@ -323,7 +516,11 @@ function splitDetailsBlockSources(text, state, limits) {
     const openIndex = lower.lastIndexOf('<details', closeIndex);
     if (openIndex === -1)
         return undefined;
-    const temporary = { seen: new Set(), sources: [], truncated: false };
+    const temporary = {
+        sourceIndexByUrl: new Map(),
+        sources: [],
+        truncated: false,
+    };
     addTextSources(text.slice(openIndex, closeIndex + '</details>'.length), temporary, limits);
     if (temporary.sources.length < 2 && !temporary.truncated)
         return undefined;
@@ -337,7 +534,7 @@ function isLinkOnlyLine(line) {
     const stripped = line.replace(/^\s*(?:[-*]|\d+\.)\s*/, '').trim();
     return stripped.length > 0 && (stripped.startsWith('http://')
         || stripped.startsWith('https://')
-        || MARKDOWN_LINK_LINE_PATTERN.test(stripped));
+        || scanMarkdownHttpLinks(stripped).links.length > 0);
 }
 function splitTailLinkBlock(text, state, limits) {
     const lines = text.split(/\r?\n/);
@@ -368,7 +565,7 @@ function splitTailLinkBlock(text, state, limits) {
         return undefined;
     return lines.slice(0, tailStart).join('\n').trimEnd();
 }
-/** Convert Search API prose/source conventions immediately into provider-neutral records. */
+/** Convert Search API prose/source conventions with one bounded link scan and exact-URL enrichment. */
 export function parseSearchAnswerText(text, limitOverrides = {}) {
     const limits = { ...DEFAULT_SEARCH_RESPONSE_PARSE_LIMITS, ...limitOverrides };
     validateLimits(limits);
@@ -376,14 +573,22 @@ export function parseSearchAnswerText(text, limitOverrides = {}) {
     if (trimmed.length === 0) {
         return Object.freeze({ answer: '', sources: Object.freeze([]), sourcesTruncated: false });
     }
-    const trailingState = { seen: new Set(), sources: [], truncated: false };
+    const trailingState = {
+        sourceIndexByUrl: new Map(),
+        sources: [],
+        truncated: false,
+    };
     const answer = splitFunctionCallSources(trimmed, trailingState, limits)
         ?? splitHeadingSources(trimmed, trailingState, limits)
         ?? splitDetailsBlockSources(trimmed, trailingState, limits)
         ?? splitTailLinkBlock(trimmed, trailingState, limits)
         ?? trimmed;
-    const state = { seen: new Set(), sources: [], truncated: false };
-    addMarkdownSources(answer, state, limits);
+    const state = {
+        sourceIndexByUrl: new Map(),
+        sources: [],
+        truncated: false,
+    };
+    addMarkdownSources(scanMarkdownHttpLinks(answer).links, state, limits);
     for (const source of trailingState.sources)
         addSource(state, source, limits);
     state.truncated ||= trailingState.truncated;

package/lib/tools/docs-search.js

@@ -179,6 +179,7 @@ async function executeDocsSearch(args, exec, dependencies, signal) {
     const result = await dependencies.documentation.search({
         query: args.query,
         ...(args.provider === undefined ? {} : { provider: args.provider }),
+        ...(args.library_name === undefined ? {} : { libraryName: args.library_name }),
         ...(args.library_id === undefined ? {} : { libraryId: args.library_id }),
         maxResults,
         ...(args.force_refresh === undefined ? {} : { forceRefresh: args.force_refresh }),
@@ -197,7 +198,7 @@ async function executeDocsSearch(args, exec, dependencies, signal) {
 export function createDocsSearchTool(dependencies) {
     return defineTool({
         name: 'docs_search',
-        description: 'High-level SDK/API/framework/README/release documentation search. Routes Context7 first and optionally Exa, returns discovery snippets and durable source_ref pagination; common documentation tasks do not need granular Context7 tools.',
+        description: 'High-level SDK/API/framework/README/release documentation search. Pass library_id for an exact Context7 id or library_name for a package/product; auto without either uses Exa discovery, while context7/all require one. Returns bounded discovery snippets and durable source_ref pagination.',
         parameters: DOCS_SEARCH_PARAMETERS,
         output: {
             schema: DOCS_SEARCH_OUTPUT_SCHEMA,

package/lib/tools/schemas.d.ts

@@ -153,11 +153,15 @@ export declare const DOCS_SEARCH_PARAMETERS: {
     readonly provider: {
         readonly type: "string";
         readonly enum: readonly ["auto", "context7", "exa", "all"];
-        readonly description: "auto (default), Context7, Exa, or both documentation discovery routes.";
+        readonly description: "auto (default), Context7, Exa, or both. Without a Context7 library identity, auto is Exa-only.";
+    };
+    readonly library_name: {
+        readonly type: "string";
+        readonly description: "Optional Context7 package or product name, such as React or FastAPI. Required for Context7 resolve when library_id is absent; never sent to Exa.";
     };
     readonly library_id: {
         readonly type: "string";
-        readonly description: "Optional exact Context7 /org/project or /org/project/version id; valid ids skip resolve.";
+        readonly description: "Optional exact Context7 /org/project or /org/project/version id; takes priority over library_name and strictly skips resolve.";
     };
     readonly max_results: {
         readonly type: "integer";

package/lib/tools/schemas.js

@@ -144,11 +144,15 @@ export const DOCS_SEARCH_PARAMETERS = {
     provider: {
         type: 'string',
         enum: DOCUMENTATION_SEARCH_PROVIDERS,
-        description: 'auto (default), Context7, Exa, or both documentation discovery routes.',
+        description: 'auto (default), Context7, Exa, or both. Without a Context7 library identity, auto is Exa-only.',
+    },
+    library_name: {
+        type: 'string',
+        description: 'Optional Context7 package or product name, such as React or FastAPI. Required for Context7 resolve when library_id is absent; never sent to Exa.',
     },
     library_id: {
         type: 'string',
-        description: 'Optional exact Context7 /org/project or /org/project/version id; valid ids skip resolve.',
+        description: 'Optional exact Context7 /org/project or /org/project/version id; takes priority over library_name and strictly skips resolve.',
     },
     max_results: {
         type: 'integer',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-search-enhance",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Bounded search, documentation, extraction, progressively disclosed site mapping/research planning, and read-only diagnostics for DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",