dsh-search-enhance 0.2.0 → 0.2.1

package/README.md

@@ -2,21 +2,19 @@
 
 English | [简体中文](README.zh.md)
 
-`dsh-search-enhance` is a search extension for DeepSeek Harness. It uses a Grok-compatible Search API for primary web answers and can optionally use Context7, Exa, Tavily, and Firecrawl for documentation lookup, supplementary discovery, page extraction, and site mapping.
+`dsh-search-enhance` is a search extension for DeepSeek Harness. It uses a Grok-compatible Search API for primary web answers and can optionally use Context7, Exa, Tavily, Firecrawl, and Parallel for documentation lookup, supplementary discovery, page extraction, and site mapping.
 
 The plugin presents search results, sources, and page content separately. Searches return an answer or documentation snippets with source links; you can ask for more sources when needed. To check important details, ask it to read the original page. Search snippets remain distinct from fetched page content.
 
-> Bring your own endpoints and credentials. The plugin ships no API keys. A Grok-compatible endpoint is required for `web_search`; Context7, Exa, Tavily, and Firecrawl are optional.
-
-![A DSH Web session that searches, checks documentation, extracts an official page, and returns a sourced answer](https://raw.githubusercontent.com/umineko987/dsh-search-enhance/main/assets/search-workflow.png)
+> Bring your own endpoints and credentials. The plugin ships no API keys. A Grok-compatible endpoint is required for `web_search`; Context7, Exa, Tavily, Firecrawl, and Parallel are optional.
 
 ## Key characteristics
 
-- `web_search` uses the Grok-compatible endpoint for the main answer and runs all user-selected supplemental Providers (Exa, Tavily, Firecrawl) in parallel, with an independent per-Provider source limit.
+- `web_search` uses the Grok-compatible endpoint for the main answer and runs all user-selected supplemental Providers (Exa, Tavily, Firecrawl, Parallel) in parallel, with an independent per-Provider source limit.
 - Sources are normalized, de-duplicated, and reordered using source category, requested version, and publication-time signals before they are shown.
 - `source_ref` keeps the complete source record in private durable storage, allowing the Agent to paginate beyond the links included in the initial result.
 - `docs_search` uses Context7 only with an explicit `library_name` or `library_id`; requests without a library identity use Exa discovery.
-- `web_extract` requires one explicit `provider` from the user-enabled set: `tavily_extract`, `firecrawl_scrape`, `smart_direct`, or `direct`. It reports the route, evidence level, and available page metadata; failures never switch Providers.
+- `web_extract` requires one explicit `provider` from the user-enabled set: `tavily_extract`, `firecrawl_scrape`, `parallel_extract`, `smart_direct`, or `direct`. It reports the route, evidence level, and available page metadata; failures never switch Providers.
 - Ask for more sources or related pages on a specific website when needed; no manual tool loading is required.
 - Supplemental search defaults to no Providers selected. Unselected Providers are never requested; missing credentials and failures of selected Providers remain visible as warnings.
 
@@ -86,10 +84,11 @@ Configure only the routes you need.
 | Exa | Broad documentation and supplementary discovery | `EXA_API_KEY` | No |
 | Tavily | Supplementary search, page extraction, and site mapping | `TAVILY_API_KEY` | No |
 | Firecrawl | Supplementary search and page extraction | `FIRECRAWL_API_KEY` | No |
+| Parallel | Supplementary search and Markdown page extraction | `PARALLEL_API_KEY` | No |
 
 In the plugin settings, select any combination of **supplemental search Providers**. Each selected Provider runs alongside the main search, using `supplementalSearch.maxSourcesPerProvider` (default `5`, maximum `100`). This selection applies to all search profiles.
 
-Separately, select the **extraction Providers** available to the Agent. Each `web_extract` call must choose exactly one enabled Provider, for example `{ "url": "https://example.com/", "provider": "direct", "format": "markdown" }`. Disabled, unconfigured, unsupported, or failed Providers do not trigger automatic fallback. Extraction Providers are enabled by default; disable any you do not want the Agent to use.
+Separately, select the **extraction Providers** available to the Agent. Each `web_extract` call must choose exactly one enabled Provider, for example `{ "url": "https://example.com/", "provider": "direct", "format": "markdown" }`. Disabled, unconfigured, unsupported, or failed Providers do not trigger automatic fallback. Parallel extraction supports Markdown only and is disabled by default; enable it explicitly. Other extraction Providers are enabled by default; disable any you do not want the Agent to use.
 
 For `docs_search`, Context7 requires an explicit `library_name` or `library_id`. Without one, `provider: "auto"` uses Exa instead of guessing a package name from the full question.
 

package/README.zh.md

@@ -2,21 +2,19 @@
 
 [English](README.md) | 简体中文
 
-`dsh-search-enhance` 是 DeepSeek Harness 的搜索增强插件。它使用 Grok-compatible Search API 生成普通网页搜索的主要回答，并可选用 Context7、Exa、Tavily 和 Firecrawl 完成文档检索、补充来源、网页正文提取和站点页面发现。
+`dsh-search-enhance` 是 DeepSeek Harness 的搜索增强插件。它使用 Grok-compatible Search API 生成普通网页搜索的主要回答，并可选用 Context7、Exa、Tavily、Firecrawl 和 Parallel 完成文档检索、补充来源、网页正文提取和站点页面发现。
 
 插件将搜索结果、参考来源和网页正文分开呈现。搜索时先给出回答或文档片段及来源链接，需要更多来源时可以继续追问；核对重要内容时，再要求读取原网页。搜索摘要与实际读取的正文会明确区分。
 
-> 你需要自行提供所选服务的端点和凭据，插件不内置任何 API Key。`web_search` 需要 Grok-compatible 端点；Context7、Exa、Tavily 和 Firecrawl 均为可选 Provider。
-
-![DSH Web 会话：搜索、检索文档、提取官方页面并生成带来源的回答](https://raw.githubusercontent.com/umineko987/dsh-search-enhance/main/assets/search-workflow.png)
+> 你需要自行提供所选服务的端点和凭据，插件不内置任何 API Key。`web_search` 需要 Grok-compatible 端点；Context7、Exa、Tavily、Firecrawl 和 Parallel 均为可选 Provider。
 
 ## 主要特点
 
-- `web_search` 使用 Grok-compatible 端点生成主要回答，并行调用用户勾选的全部补充搜索 Provider（Exa、Tavily、Firecrawl），每家使用独立的来源数量上限。
+- `web_search` 使用 Grok-compatible 端点生成主要回答，并行调用用户勾选的全部补充搜索 Provider（Exa、Tavily、Firecrawl、Parallel），每家使用独立的来源数量上限。
 - 来源在展示前会经过 URL 标准化、去重，并根据来源类别、目标版本和发布时间信号重新排序。
 - `source_ref` 将完整来源记录保存在插件私有持久存储中，Agent 可以继续分页读取首次结果未展示的来源。
 - `docs_search` 只在提供明确 `library_name` 或 `library_id` 时使用 Context7；没有库身份的请求使用 Exa 发现。
-- `web_extract` 每次必须通过 `provider` 指定一家用户已启用的服务：`tavily_extract`、`firecrawl_scrape`、`smart_direct` 或 `direct`。结果报告提取路径、证据等级和页面元数据，失败不自动换服务。
+- `web_extract` 每次必须通过 `provider` 指定一家用户已启用的服务：`tavily_extract`、`firecrawl_scrape`、`parallel_extract`、`smart_direct` 或 `direct`。结果报告提取路径、证据等级和页面元数据，失败不自动换服务。
 - 需要时可继续查看更多来源，或查找某个网站下的相关页面，无需手动加载工具。
 - 补充搜索默认不选择任何 Provider。未选中的服务不会被请求；选中服务缺少凭据或执行失败会在结果中显示警告。
 
@@ -86,10 +84,11 @@ dsh web
 | Exa | 广泛文档发现和补充发现 | `EXA_API_KEY` | 否 |
 | Tavily | 补充搜索、网页提取和站点映射 | `TAVILY_API_KEY` | 否 |
 | Firecrawl | 补充搜索和网页提取 | `FIRECRAWL_API_KEY` | 否 |
+| Parallel | 补充搜索和 Markdown 网页提取 | `PARALLEL_API_KEY` | 否 |
 
 在插件设置中，可以多选 **补充搜索 Provider**。选中项与主搜索并行执行，每家使用 `supplementalSearch.maxSourcesPerProvider` 限制来源数量（默认 `5`，最大 `100`）。选择对所有搜索 profile 生效。
 
-另外，多选 **网页提取 Provider** 可以限制 Agent 可用的服务范围。每次 `web_extract` 必须明确选择一家已启用服务，例如 `{ "url": "https://example.com/", "provider": "direct", "format": "markdown" }`。服务被禁用、缺少凭据、不支持格式或执行失败时，直接报告错误，不自动回退。提取服务默认全部启用，可取消勾选不希望使用的服务。
+另外，多选 **网页提取 Provider** 可以限制 Agent 可用的服务范围。每次 `web_extract` 必须明确选择一家已启用服务，例如 `{ "url": "https://example.com/", "provider": "direct", "format": "markdown" }`。服务被禁用、缺少凭据、不支持格式或执行失败时，直接报告错误，不自动回退。Parallel 提取仅支持 Markdown，默认关闭，需要手动启用；其他提取服务默认启用，可取消勾选不希望使用的服务。
 
 对于 `docs_search`，Context7 需要明确的 `library_name` 或 `library_id`。两者都未提供时，`provider: "auto"` 使用 Exa，不会根据完整问题猜测包名。
 

package/client/client.js

@@ -38,6 +38,24 @@ window.__ModuleLoader__.load({
 			["defaultProfile"],
 			["defaultDepth"],
 			["toolTimeoutMs"],
+			["retention", "docsSearchMaxResults"],
+			...[
+				"auto",
+				"coding_docs",
+				"code_examples",
+				"project_research",
+				"academic",
+				"fact_check"
+			].flatMap((profile) => [
+				"compact",
+				"normal",
+				"deep"
+			].map((depth) => [
+				"budgets",
+				profile,
+				depth,
+				"maxVisibleSources"
+			])),
 			["toolDiscovery", "mode"],
 			...WEB_SUPPLEMENTAL_SEARCH_PROVIDERS.map((provider) => ["supplementalSearch", provider]),
 			["supplementalSearch", "maxSourcesPerProvider"],
@@ -432,6 +450,8 @@ window.__ModuleLoader__.load({
 				defaultProfile: config.defaultProfile,
 				defaultDepth: config.defaultDepth,
 				toolTimeoutMs: config.toolTimeoutMs,
+				retention: { ...config.retention },
+				budgets: Object.fromEntries(Object.entries(config.budgets).map(([profile, depths]) => [profile, Object.fromEntries(Object.entries(depths).map(([depth, budget]) => [depth, { ...budget }]))])),
 				toolDiscovery: { ...config.toolDiscovery },
 				supplementalSearch: { ...config.supplementalSearch },
 				searchApi: { ...config.searchApi },
@@ -694,7 +714,7 @@ window.__ModuleLoader__.load({
 			]);
 			const mutations = (0, react.useMemo)(() => snapshot === void 0 || draft === void 0 ? [] : mutationsFor(snapshot.value, draft), [draft, snapshot]);
 			const dirty = mutations.length > 0;
-			const valid = draft !== void 0 && snapshot !== void 0 && validTimeouts(draft) && validSupplementalSearch(draft, snapshot.options.supplementalSearchMaxSources);
+			const valid = draft !== void 0 && snapshot !== void 0 && validTimeouts(draft) && validSupplementalSearch(draft, snapshot.options.supplementalSearchMaxSources) && Number.isInteger(draft.retention.docsSearchMaxResults) && draft.retention.docsSearchMaxResults >= snapshot.options.docsSearchMinResults && draft.retention.docsSearchMaxResults <= snapshot.options.docsSearchMaxResults && Object.values(draft.budgets).every((depths) => Object.values(depths).every((budget) => Number.isInteger(budget.maxVisibleSources) && budget.maxVisibleSources >= 0 && budget.maxVisibleSources <= snapshot.options.visibleSourcesMax));
 			const editable = phase === "ready" && snapshot?.writable === true && !saving;
 			const updateProvider = (provider, value) => {
 				setDraft((current) => current === void 0 ? current : provider === "searchApi" ? {
@@ -1016,6 +1036,60 @@ window.__ModuleLoader__.load({
 												}
 											})
 										}),
+										/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Field, {
+											label: t("maxVisibleSources"),
+											overridden: isOverridden(snapshot.user, [
+												"budgets",
+												draft.defaultProfile,
+												draft.defaultDepth,
+												"maxVisibleSources"
+											]),
+											t,
+											hint: t("maxVisibleSourcesHint"),
+											children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(NumberInput, {
+												label: t("maxVisibleSources"),
+												value: draft.budgets[draft.defaultProfile][draft.defaultDepth].maxVisibleSources,
+												min: 0,
+												max: snapshot.options.visibleSourcesMax,
+												disabled: !editable,
+												onChange: (maxVisibleSources) => {
+													setDraft((current) => current === void 0 ? current : {
+														...current,
+														budgets: {
+															...current.budgets,
+															[current.defaultProfile]: {
+																...current.budgets[current.defaultProfile],
+																[current.defaultDepth]: { maxVisibleSources }
+															}
+														}
+													});
+													setFeedback("idle");
+												}
+											})
+										}),
+										/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Field, {
+											label: t("docsSearchMaxResults"),
+											overridden: isOverridden(snapshot.user, ["retention", "docsSearchMaxResults"]),
+											t,
+											hint: t("docsSearchMaxResultsHint"),
+											children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(NumberInput, {
+												label: t("docsSearchMaxResults"),
+												value: draft.retention.docsSearchMaxResults,
+												min: snapshot.options.docsSearchMinResults,
+												max: snapshot.options.docsSearchMaxResults,
+												disabled: !editable,
+												onChange: (docsSearchMaxResults) => {
+													setDraft((current) => current === void 0 ? current : {
+														...current,
+														retention: {
+															...current.retention,
+															docsSearchMaxResults
+														}
+													});
+													setFeedback("idle");
+												}
+											})
+										}),
 										/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Field, {
 											label: t("toolTimeoutMs"),
 											overridden: isOverridden(snapshot.user, ["toolTimeoutMs"]),
@@ -1441,6 +1515,10 @@ window.__ModuleLoader__.load({
 			strategyIntro: "Defaults used when a tool call does not choose its own profile or depth.",
 			defaultProfile: "Default profile",
 			defaultDepth: "Default depth",
+			maxVisibleSources: "Initial web_search source limit",
+			maxVisibleSourcesHint: "Applies to the profile/depth selected above, not Provider collection or storage. Use source_ref for retained sources; model-text byte limits still apply.",
+			docsSearchMaxResults: "docs_search request ceiling",
+			docsSearchMaxResultsHint: "Allows max_results values from 1 up to this ceiling (default call: 6). Does not override an explicit smaller value. Collect more by increasing max_results and rerunning; pagination reads only retained records.",
 			toolDiscoveryMode: "Tool discovery",
 			toolTimeoutMs: "Whole tool timeout (ms)",
 			extraSourcesHeading: "Supplemental search providers",
@@ -1496,7 +1574,7 @@ window.__ModuleLoader__.load({
 			conflict: "The configuration changed elsewhere. Reload before saving again.",
 			saveFailed: "The configuration could not be saved.",
 			readOnly: "The Settings document is read-only.",
-			invalidNumber: "Timeouts must be positive whole numbers, and supplementary source counts must be whole numbers within their allowed range.",
+			invalidNumber: "Timeouts must be positive whole numbers; source and request limits must be whole numbers within their allowed range.",
 			overridden: "User override",
 			inherited: "Inherited"
 		};
@@ -1522,6 +1600,10 @@ window.__ModuleLoader__.load({
 			strategyIntro: "工具调用未显式选择 profile 或 depth 时使用这些默认值。",
 			defaultProfile: "默认 Profile",
 			defaultDepth: "默认深度",
+			maxVisibleSources: "web_search 首次展示来源上限",
+			maxVisibleSourcesHint: "只影响上方所选 Profile / 深度的首次展示，不限制服务收集或存储；已保留来源可通过 source_ref 分页，模型文本仍受字节上限约束。",
+			docsSearchMaxResults: "docs_search 请求数量最高值",
+			docsSearchMaxResultsHint: "允许 max_results 从 1 到此最高值（调用默认 6 条），不会覆盖模型明确传入的较小值。需要更多结果时提高 max_results 后重搜；分页只能读取已保留记录。",
 			toolDiscoveryMode: "工具披露模式",
 			toolTimeoutMs: "工具总超时（毫秒）",
 			extraSourcesHeading: "补充搜索服务",
@@ -1577,7 +1659,7 @@ window.__ModuleLoader__.load({
 			conflict: "配置已在其他位置发生变化。请重新读取后再保存。",
 			saveFailed: "无法保存配置。",
 			readOnly: "Settings 文档为只读。",
-			invalidNumber: "超时必须是正整数；补充来源数量必须是允许范围内的整数。",
+			invalidNumber: "超时必须是正整数；来源与请求数量上限必须是允许范围内的整数。",
 			overridden: "用户覆盖",
 			inherited: "继承值"
 		};

package/client/types/client/locales.d.ts

@@ -20,6 +20,10 @@ export declare const en: {
     readonly strategyIntro: "Defaults used when a tool call does not choose its own profile or depth.";
     readonly defaultProfile: "Default profile";
     readonly defaultDepth: "Default depth";
+    readonly maxVisibleSources: "Initial web_search source limit";
+    readonly maxVisibleSourcesHint: "Applies to the profile/depth selected above, not Provider collection or storage. Use source_ref for retained sources; model-text byte limits still apply.";
+    readonly docsSearchMaxResults: "docs_search request ceiling";
+    readonly docsSearchMaxResultsHint: "Allows max_results values from 1 up to this ceiling (default call: 6). Does not override an explicit smaller value. Collect more by increasing max_results and rerunning; pagination reads only retained records.";
     readonly toolDiscoveryMode: "Tool discovery";
     readonly toolTimeoutMs: "Whole tool timeout (ms)";
     readonly extraSourcesHeading: "Supplemental search providers";
@@ -75,7 +79,7 @@ export declare const en: {
     readonly conflict: "The configuration changed elsewhere. Reload before saving again.";
     readonly saveFailed: "The configuration could not be saved.";
     readonly readOnly: "The Settings document is read-only.";
-    readonly invalidNumber: "Timeouts must be positive whole numbers, and supplementary source counts must be whole numbers within their allowed range.";
+    readonly invalidNumber: "Timeouts must be positive whole numbers; source and request limits must be whole numbers within their allowed range.";
     readonly overridden: "User override";
     readonly inherited: "Inherited";
 };

package/client/types/web-config/contracts.d.ts

@@ -30,6 +30,12 @@ export interface WebEditableConfig {
     defaultProfile: string;
     defaultDepth: string;
     toolTimeoutMs: number;
+    retention: {
+        docsSearchMaxResults: number;
+    };
+    budgets: Record<string, Record<string, {
+        maxVisibleSources: number;
+    }>>;
     toolDiscovery: {
         mode: string;
     };
@@ -76,6 +82,9 @@ export interface WebConfigOptions {
     parallelSearchModes: readonly string[];
     proxyUrlMaxCharacters: number;
     supplementalSearchMaxSources: number;
+    docsSearchMinResults: number;
+    docsSearchMaxResults: number;
+    visibleSourcesMax: number;
 }
 export interface WebCredentialState {
     ref: string;

package/lib/documentation/service.d.ts

@@ -18,7 +18,7 @@ export interface DocumentationProviderStatus {
     readonly provider: DocumentationResultProvider;
     readonly state: DocumentationProviderState;
 }
-export declare const DOCUMENTATION_WARNING_CODES: readonly ["provider_failed", "provider_not_configured", "cache_stale", "cache_evicted", "provider_result_truncated", "no_results"];
+export declare const DOCUMENTATION_WARNING_CODES: readonly ["provider_failed", "provider_not_configured", "cache_stale", "cache_evicted", "provider_result_truncated", "library_not_found", "collection_limit_reached", "visible_sources_truncated", "no_results"];
 export type DocumentationWarningCode = (typeof DOCUMENTATION_WARNING_CODES)[number];
 export declare const DOCUMENTATION_CACHE_PATH_STATES: readonly ["hit", "miss", "refresh", "stale", "skipped", "failed"];
 export type DocumentationCachePathState = (typeof DOCUMENTATION_CACHE_PATH_STATES)[number];

package/lib/documentation/service.js

@@ -15,6 +15,9 @@ export const DOCUMENTATION_WARNING_CODES = [
     'cache_stale',
     'cache_evicted',
     'provider_result_truncated',
+    'library_not_found',
+    'collection_limit_reached',
+    'visible_sources_truncated',
     'no_results',
 ];
 export const DOCUMENTATION_CACHE_PATH_STATES = [
@@ -592,12 +595,18 @@ export class DocumentationSearchService extends Service {
         const qualitySources = applySourceQuality(validated.query, compatibleSources);
         const sources = Object.freeze(qualitySources.slice(0, input.maxResults));
         const snippets = Object.freeze(contextOutcome.snippets.slice(0, input.maxResults));
-        const truncated = contextOutcome.truncated
-            || exaOutcome.truncated
-            || sources.length < qualitySources.length
+        const providerTruncated = contextOutcome.truncated || exaOutcome.truncated;
+        const visibleSourcesTruncated = sources.length < qualitySources.length;
+        const truncated = providerTruncated
+            || visibleSourcesTruncated
             || snippets.length < contextOutcome.snippets.length;
-        if (truncated)
+        if (providerTruncated)
             warnings.push(fixedWarning('provider_result_truncated'));
+        if (visibleSourcesTruncated)
+            warnings.push(fixedWarning('visible_sources_truncated'));
+        if (exaOutcome.state === 'complete' && exaOutcome.sources.length >= input.maxResults) {
+            warnings.push(fixedWarning('collection_limit_reached', { provider: 'exa', count: input.maxResults }));
+        }
         const completedValidPath = contextOutcome.completedValidPath || exaOutcome.completedValidPath;
         if (sources.length === 0 && snippets.length === 0 && !completedValidPath) {
             const cause = contextOutcome.error ?? exaOutcome.error ?? new ProviderError({
@@ -613,11 +622,11 @@ export class DocumentationSearchService extends Service {
         }
         const cache = contextOutcome.cache ?? cacheReport(cachePath('skipped', 0, 'provider_not_selected'), cachePath('skipped', 0, 'provider_not_selected'));
         const persistence = Object.freeze({
-            collectionTruncated: truncated,
+            collectionTruncated: exaOutcome.truncated,
             depth: 'compact',
             profile: 'coding_docs',
             query: validated.query,
-            sources,
+            sources: Object.freeze(qualitySources),
         });
         return Object.freeze({
             attempts,
@@ -712,6 +721,7 @@ export class DocumentationSearchService extends Service {
         }
         if (selectedLibrary?.id === undefined || !isContext7LibraryId(selectedLibrary.id)) {
             docsReport = cachePath('skipped', 0, 'library_not_found');
+            warnings.push(fixedWarning('library_not_found', { provider: 'context7', path: 'resolve' }));
             attempts.push(skippedAttempt('context7-docs'));
             return frozenPathOutcome({
                 attempts,

package/lib/orchestration/orchestrator.js

@@ -562,8 +562,10 @@ export class SearchOrchestrator {
             const collectionTruncated = providerTruncated || mainSourcesTruncated;
             const visibleSourcesTruncated = visibleSources.length < prioritizedSources.length;
             const sourcesTruncated = collectionTruncated || visibleSourcesTruncated;
-            if (sourcesTruncated)
+            if (collectionTruncated)
                 warnings.push(warning('sources_truncated'));
+            if (visibleSourcesTruncated)
+                warnings.push(warning('visible_sources_truncated'));
             if (mainSucceeded && rawAnswer.trim().length === 0 && prioritizedSources.length === 0) {
                 warnings.push(warning('no_results'));
             }

package/lib/orchestration/types.d.ts

@@ -3,7 +3,7 @@ import type { CanonicalSource, SourceRecordCandidate } from '../contracts/index.
 import type { ProviderAttemptRecord, ProviderCapability, ProviderErrorKind } from '../provider-runtime/index.js';
 import type { SearchApiResolvedSearchInput, SearchApiSearchResult } from '../providers/search-api.js';
 import type { BoundedSourceProvider } from '../providers/types.js';
-export declare const SEARCH_WARNING_CODES: readonly ["main_search_failed", "native_search_unconfirmed", "provider_failed", "provider_not_configured", "provider_result_truncated", "cache_stale", "cache_evicted", "answer_truncated", "sources_truncated", "canonical_output_truncated", "no_results"];
+export declare const SEARCH_WARNING_CODES: readonly ["main_search_failed", "native_search_unconfirmed", "provider_failed", "provider_not_configured", "provider_result_truncated", "cache_stale", "cache_evicted", "answer_truncated", "sources_truncated", "visible_sources_truncated", "source_retention_truncated", "canonical_output_truncated", "no_results"];
 export type SearchWarningCode = (typeof SEARCH_WARNING_CODES)[number];
 /** Stable, secret-free warning; it deliberately has no arbitrary message field. */
 export interface SearchWarning {

package/lib/orchestration/types.js

@@ -8,6 +8,8 @@ export const SEARCH_WARNING_CODES = [
     'cache_evicted',
     'answer_truncated',
     'sources_truncated',
+    'visible_sources_truncated',
+    'source_retention_truncated',
     'canonical_output_truncated',
     'no_results',
 ];

package/lib/presentation/render.d.ts

@@ -11,8 +11,11 @@ export declare function renderWebSearchLimitations(value: WebSearchOutput): stri
  * Settings, caches, the clock, or network state.
  */
 export declare function renderWebSearchText(value: WebSearchOutput): string;
+export declare function isWebSearchModelTextTruncated(value: WebSearchOutput): boolean;
+export declare function renderDocsSearchLimitations(value: DocsSearchOutput): string | undefined;
 /** Pure Native projection for docs_search; it never reads Settings, cache, storage, or the network. */
 export declare function renderDocsSearchText(value: DocsSearchOutput): string;
+export declare function isDocsSearchModelTextTruncated(value: DocsSearchOutput): boolean;
 /** Pure model-text projection for one private-storage source page. */
 export declare function renderSearchSourcesText(value: SearchSourcesOutput): string;
 /**

package/lib/presentation/render.js

@@ -9,14 +9,19 @@ export function sourceDisplayLabel(source) {
     return new URL(source.url).hostname;
 }
 function renderWithBoundedNotice(text, notice, maximumBytes) {
-    if (notice === undefined)
-        return truncateUtf8(text, maximumBytes).text;
     const separator = '\n\n';
-    const prefixBudget = maximumBytes - utf8ByteLength(notice) - utf8ByteLength(separator);
+    const complete = notice === undefined ? text : `${text}${separator}${notice}`;
+    if (utf8ByteLength(complete) <= maximumBytes)
+        return complete;
+    const marker = '[Model text truncated by model_text_max_bytes.]';
+    const suffix = notice === undefined
+        ? marker
+        : `${marker}\nCounts below describe the canonical result, not fully displayed text.${separator}${notice}`;
+    const prefixBudget = maximumBytes - utf8ByteLength(suffix) - utf8ByteLength(separator);
     if (prefixBudget <= 0)
-        return truncateUtf8(notice, maximumBytes).text;
+        return truncateUtf8(suffix, maximumBytes).text;
     const prefix = truncateUtf8(text, prefixBudget).text;
-    return prefix.length === 0 ? notice : `${prefix}${separator}${notice}`;
+    return prefix.length === 0 ? suffix : `${prefix}${separator}${suffix}`;
 }
 function sourceLoadingNotice(sourceRef) {
     if (sourceRef === undefined)
@@ -45,7 +50,11 @@ function warningText(warning) {
         case 'answer_truncated':
             return 'The generated answer was truncated.';
         case 'sources_truncated':
-            return 'The source collection or retained source record was truncated.';
+            return 'Source collection reached a Provider limit; uncollected sources cannot be recovered by pagination. Rerun with a larger collection limit where supported.';
+        case 'visible_sources_truncated':
+            return 'Only an inline source prefix is shown; use source_ref to page retained sources.';
+        case 'source_retention_truncated':
+            return 'Source storage dropped some collected sources at its count/byte limit; pagination cannot recover those entries.';
         case 'canonical_output_truncated':
             return 'The canonical search value was truncated to its configured limit.';
         case 'no_results':
@@ -87,9 +96,8 @@ function sourceSummary(value) {
 /** Shared model/card notice; Provider failures precede generic truncation information. */
 export function renderWebSearchLimitations(value) {
     const lines = value.warnings.map(warningText);
-    if (value.truncated) {
-        lines.push('The answer, visible sources, Provider collection, or retained source record was bounded.');
-    }
+    if (value.truncated && lines.length === 0)
+        lines.push('The canonical search result was bounded.');
     if (lines.length === 0)
         return undefined;
     return `Limitations\n${lines.map(line => `- ${line}`).join('\n')}`;
@@ -104,15 +112,20 @@ export function renderWebSearchText(value) {
         renderWebSearchLimitations(value),
         answerSection(value),
         sourceSection(value),
-        sourceSummary(value),
-        DISCOVERY_NOTICE,
     ].filter((section) => section !== undefined);
     const complete = sections.join('\n\n');
     const maximumBytes = Number.isSafeInteger(value.model_text_max_bytes)
         && value.model_text_max_bytes > 0
         ? value.model_text_max_bytes
         : 0;
-    return renderWithBoundedNotice(complete, sourceLoadingNotice(value.source_ref), maximumBytes);
+    return renderWithBoundedNotice(complete, [sourceSummary(value), DISCOVERY_NOTICE, sourceLoadingNotice(value.source_ref)]
+        .filter((section) => section !== undefined).join('\n\n'), maximumBytes);
+}
+export function isWebSearchModelTextTruncated(value) {
+    const maximumBytes = Number.isSafeInteger(value.model_text_max_bytes) && value.model_text_max_bytes > 0
+        ? value.model_text_max_bytes : 0;
+    return utf8ByteLength(renderWebSearchText({ ...value, model_text_max_bytes: Number.MAX_SAFE_INTEGER }))
+        > maximumBytes;
 }
 function docsWarningText(warning) {
     const subject = [warning.provider, warning.path].filter(Boolean).join('/');
@@ -131,8 +144,14 @@ function docsWarningText(warning) {
             return `A documentation Provider bounded its discovery result${detail}.`;
         case 'no_results':
             return 'Documentation search completed without matching snippets or sources.';
-        case 'sources_truncated':
-            return 'The durable source record retained only a bounded source prefix.';
+        case 'library_not_found':
+            return 'No Context7 library matched library_name. No unrelated library was selected; check the name or supply an exact library_id.';
+        case 'collection_limit_reached':
+            return `The Provider returned its requested limit (${warning.count ?? 'max_results'}). Counts cover this request, not all available matches. Increase max_results and rerun to collect more; pagination only reads retained records.`;
+        case 'visible_sources_truncated':
+            return 'Only an inline source prefix is shown; use source_ref to page retained sources.';
+        case 'source_retention_truncated':
+            return 'Source storage dropped some collected sources at its count/byte limit; pagination cannot recover those entries.';
         case 'canonical_output_truncated':
             return 'The documentation result was shortened to its configured canonical JSON limit.';
     }
@@ -191,6 +210,12 @@ function docsSourceSection(value) {
     }
     return lines.join('\n');
 }
+export function renderDocsSearchLimitations(value) {
+    const lines = value.warnings.map(docsWarningText);
+    if (value.truncated && lines.length === 0)
+        lines.push('The canonical documentation result was bounded.');
+    return lines.length === 0 ? undefined : `Limitations\n${lines.map(line => `- ${line}`).join('\n')}`;
+}
 /** Pure Native projection for docs_search; it never reads Settings, cache, storage, or the network. */
 export function renderDocsSearchText(value) {
     const status = value.state === 'partial' ? 'partial' : 'complete';
@@ -201,35 +226,34 @@ export function renderDocsSearchText(value) {
             : 'Documentation discovery completed; bounded discovery results follow.';
     const sections = [
         `Documentation search (${status})\n${explanation}`,
+        renderDocsSearchLimitations(value),
         docsLibrarySection(value),
         docsSnippetSection(value),
         docsSourceSection(value),
-        [
-            `Sources shown: ${value.returned_sources}/${value.total_sources}`,
-            `Snippets shown: ${value.returned_snippets}/${value.total_snippets}`,
-        ].join('\n'),
         [
             docsCachePathText('Context7 resolve cache', value.cache.resolve),
             docsCachePathText('Context7 docs cache', value.cache.docs),
             docsProviderSection(value),
         ].join('\n'),
-        value.truncated || value.warnings.length > 0
-            ? [
-                'Limitations',
-                ...(value.truncated
-                    ? ['- Documentation snippets, visible sources, Provider collection, or retained sources were bounded.']
-                    : []),
-                ...value.warnings.map(warning => `- ${docsWarningText(warning)}`),
-            ].join('\n')
-            : undefined,
-        'Evidence level: discovery. Documentation snippets and source summaries are discovery metadata, not verified fetched page-body evidence; inspect an exact source page before relying on a claim.',
     ].filter((section) => section !== undefined);
-    const complete = sections.join('\n\n');
+    const notice = [
+        `Sources shown: ${value.returned_sources}/${value.total_sources}`,
+        `Snippets shown: ${value.returned_snippets}/${value.total_snippets}`,
+        'Counts cover collected results for this request, not all available matches.',
+        'Evidence level: discovery. Documentation snippets and source summaries are not verified fetched page-body evidence.',
+        sourceLoadingNotice(value.source_ref),
+    ].filter((section) => section !== undefined).join('\n\n');
     const maximumBytes = Number.isSafeInteger(value.model_text_max_bytes)
         && value.model_text_max_bytes > 0
         ? value.model_text_max_bytes
         : 0;
-    return renderWithBoundedNotice(complete, sourceLoadingNotice(value.source_ref), maximumBytes);
+    return renderWithBoundedNotice(sections.join('\n\n'), notice, maximumBytes);
+}
+export function isDocsSearchModelTextTruncated(value) {
+    const maximumBytes = Number.isSafeInteger(value.model_text_max_bytes) && value.model_text_max_bytes > 0
+        ? value.model_text_max_bytes : 0;
+    return utf8ByteLength(renderDocsSearchText({ ...value, model_text_max_bytes: Number.MAX_SAFE_INTEGER }))
+        > maximumBytes;
 }
 function renderPageSources(page) {
     if (page.sources.length === 0)
@@ -261,13 +285,15 @@ export function renderSearchSourcesText(value) {
     const sections = [
         renderPageSources(value),
         [
-            `Page returned: ${value.returned}; retained total: ${value.total}; original total: ${value.total_before_retention}.`,
+            `Page returned: ${value.returned}; retained total: ${value.total}; collected total before storage: ${value.total_before_retention}.`,
             value.has_more && value.next_offset !== undefined
                 ? `More sources are available at offset ${value.next_offset}.`
                 : 'No later retained source page is available.',
-            value.truncated
-                ? 'The retained source record is truncated.'
-                : undefined,
+            value.total < value.total_before_retention
+                ? 'Source storage dropped collected entries; pagination cannot recover them.'
+                : value.truncated
+                    ? 'Upstream source collection was bounded; pagination cannot recover uncollected entries.'
+                    : undefined,
             value.page_byte_limited
                 ? 'This page was shortened by its canonical JSON byte limit.'
                 : undefined,

package/lib/presentation/web-card.js

@@ -1,5 +1,5 @@
 import { DOCUMENTATION_CACHE_PATH_STATES, DOCUMENTATION_CACHE_SKIP_REASONS, } from '../documentation/index.js';
-import { isWebExtractModelTextTruncated, isWebMapModelTextTruncated, renderWebSearchLimitations, } from './render.js';
+import { isDocsSearchModelTextTruncated, isWebSearchModelTextTruncated, renderDocsSearchLimitations, isWebExtractModelTextTruncated, isWebMapModelTextTruncated, renderWebSearchLimitations, } from './render.js';
 import { WEB_EXTRACT_EVIDENCE_LEVELS, WEB_EXTRACT_ROUTES, } from '../web-extract/types.js';
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -49,7 +49,7 @@ export function webSearchPresentationMeta(_args, value) {
         source_produced: value.source_ref !== undefined,
         ...(answer === undefined ? {} : { answer }),
         sources: value.sources.map(source => ({ ...source })),
-        truncated: value.truncated,
+        truncated: value.truncated || isWebSearchModelTextTruncated(value),
     };
 }
 /** Generic pending web-search intent whose title is exactly the query. */
@@ -99,17 +99,19 @@ export function presentWebSearchResult(args, result) {
  * durable disclosure recovery; cache paths, credentials, and source_ref stay out.
  */
 export function docsSearchPresentationMeta(_args, value) {
+    const limitations = renderDocsSearchLimitations(value);
     return {
         version: 1,
         type: 'docs_search',
         source_produced: value.source_ref !== undefined,
+        ...(limitations === undefined ? {} : { limitations }),
         sources: value.sources.map(source => ({ ...source })),
         snippets: value.snippets.map(snippet => ({ ...snippet })),
         cache: {
             resolve: { ...value.cache.resolve },
             docs: { ...value.cache.docs },
         },
-        truncated: value.truncated,
+        truncated: value.truncated || isDocsSearchModelTextTruncated(value),
     };
 }
 /** Pending documentation discovery intent; snippets are not presented as fetched pages. */
@@ -155,6 +157,7 @@ function parseDocsSearchMeta(value) {
         || value.version !== 1
         || value.type !== 'docs_search'
         || typeof value.truncated !== 'boolean'
+        || !isOptionalString(value.limitations)
         || !Array.isArray(value.snippets)
         || !isRecord(value.cache))
         return undefined;
@@ -173,6 +176,7 @@ function parseDocsSearchMeta(value) {
     return {
         version: 1,
         type: 'docs_search',
+        ...(value.limitations === undefined ? {} : { limitations: value.limitations }),
         sources,
         snippets,
         cache: { resolve, docs },
@@ -193,8 +197,11 @@ function docsCacheLabel(meta) {
 }
 function docsCardAnswer(meta) {
     if (meta.snippets.length === 0)
-        return undefined;
-    const lines = ['Documentation snippets (discovery metadata; not fetched page bodies):'];
+        return meta.limitations;
+    const lines = [
+        ...(meta.limitations === undefined ? [] : [meta.limitations, '']),
+        'Documentation snippets (discovery metadata; not fetched page bodies):',
+    ];
     for (let index = 0; index < meta.snippets.length; index += 1) {
         const snippet = meta.snippets[index];
         if (snippet === undefined)
@@ -216,7 +223,10 @@ export function presentDocsSearchResult(args, result) {
     const label = docsCacheLabel(meta);
     const title = `Docs${label === undefined ? '' : ` (${label})`}: ${args.query}`;
     if (meta.sources.length === 0 && meta.snippets.length === 0) {
-        return { card: 'generic', title: `No documentation results: ${args.query}` };
+        const reason = meta.cache.docs.reason === 'library_not_found'
+            ? 'No matching Context7 library; check library_name or supply library_id'
+            : 'No documentation results';
+        return { card: 'generic', title: `${reason}: ${args.query}` };
     }
     const answer = docsCardAnswer(meta);
     return {

package/lib/prompt/tool-discovery.js

@@ -1,17 +1,13 @@
 export const TOOL_DISCOVERY_GUIDANCE = [
-    'Search Enhance keeps web_search, docs_search, web_extract, and search_tools resident. Optional real tools search_sources and web_map can be loaded per Agent.',
-    'For docs_search, pass library_id when an exact /org/project id is known, or library_name when the package/product is known; for example docs_search({ query: "JWT authentication middleware API", library_name: "FastAPI" }). Library resolution is handled internally.',
-    '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.',
-    'For webpage bodies (articles, blogs, repository READMEs, and model cards), prefer web_extract with exactly one explicitly selected enabled Provider. Use the host web_fetch, when available, for raw JSON APIs, XML/Atom feeds, or other structured responses.',
-    'Use HTTPS URLs directly when available. HTTP 200 with only a title or an app shell is not usable page-body evidence; choose a suitable enabled extraction Provider explicitly rather than repeatedly fetching the same shell. Do not bypass URL safety checks.',
-    'Use search_tools({ capabilities: ["sources"] }) only when a source_ref needs pagination, or search_tools({ capabilities: ["site_map"] }) to discover URLs under a known website. Do not load optional tools preemptively.',
-    'Newly loaded tools become available on the next model step. Call search_sources or web_map directly using the tool definitions supplied by the host; already loaded tools stay available.',
-    'Search source metadata and mapped URLs are discovery, not verified webpage-body evidence.',
+    'For docs_search, use known library identity for library-specific queries; omit it for broad/cross-project or unknown-library discovery (auto uses Exa). Never guess a Context7 library.',
+    'Read webpage bodies with web_extract, choosing exactly one enabled Provider; use host web_fetch (if available) for structured responses such as raw JSON APIs or XML/Atom.',
+    'Prefer HTTPS. A title/app shell alone is not usable page-body evidence; choose another suitable enabled extraction Provider instead of refetching the same shell. Never bypass URL safety checks.',
+    'Load sources via search_tools for source_ref pagination, or site_map for URLs under a known site. Call newly loaded search_sources/web_map directly on the next model step; reuse loaded tools and do not load preemptively.',
 ].join('\n');
 export const EVIDENCE_DISCIPLINE_GUIDANCE = [
-    'For current or external factual questions, start with one focused web_search (use docs_search for SDK/API documentation); do not inspect local files, settings, sessions, or credentials unless the user explicitly asks about local state.',
-    'Treat web_search/docs_search answers, snippets, and source metadata as discovery, not claim-level evidence.',
-    'Before asserting decisive factual or causal conclusions, inspect selected authoritative URLs with web_extract; never present an inferred mechanism as source-stated fact, and label unestablished mechanisms as inference or unconfirmed.',
+    'For current/external facts, start with one focused web_search (docs_search for SDK/API docs); do not inspect local files/settings/sessions/credentials unless the user explicitly asks about local state.',
+    'Search answers/snippets, source metadata and mapped URLs are discovery, not claim-level evidence.',
+    'Before decisive factual/causal conclusions, inspect authoritative URLs with web_extract; label unestablished mechanisms as inference or unconfirmed, never source-stated fact.',
 ].join('\n');
 /** Register deterministic guidance that never reads Agent state or tool visibility. */
 export function registerToolDiscoveryGuidance(ctx) {

package/lib/providers/context7.js

@@ -185,7 +185,17 @@ export function selectContext7Library(libraries, libraryName, query = libraryNam
         library,
         score: context7LibraryScore(library, libraryName, queryTerms),
     }))
-        .filter(candidate => isContext7LibraryId(candidate.library.id))
+        .filter(({ library }) => {
+        if (!isContext7LibraryId(library.id))
+            return false;
+        const wanted = normalizedMatchText(libraryName);
+        if (wanted.length === 0)
+            return false;
+        const segments = library.id.split('/').filter(Boolean).map(normalizedMatchText);
+        return normalizedMatchText(library.title) === wanted
+            || segments[1] === wanted
+            || segments.slice(0, 2).join('') === wanted;
+    })
         .sort((left, right) => right.score - left.score || left.index - right.index)[0]?.library;
 }
 /** Parse JSON or plain-text Context7 v2 documentation bodies exactly once and bound every snippet. */

package/lib/tools/docs-search.js

@@ -58,8 +58,9 @@ function ensureWarning(warnings, code) {
 export function projectDocsSearchOutput(result, config, commit) {
     const warnings = result.warnings.map(outputWarning);
     const storageTruncated = commit?.record.truncated === true;
-    if (storageTruncated)
-        ensureWarning(warnings, 'sources_truncated');
+    if (commit !== undefined && commit.record.sources.length < commit.record.totalBeforeRetention) {
+        ensureWarning(warnings, 'source_retention_truncated');
+    }
     const sources = result.sources.map(source => ({
         url: source.url,
         ...(source.title === undefined ? {} : { title: source.title }),

package/lib/tools/schemas.d.ts

@@ -98,6 +98,7 @@ export declare const WEB_SEARCH_OUTPUT_SCHEMA: {
         readonly truncated: {
             readonly type: "boolean";
             readonly required: true;
+            readonly description: "Canonical result/storage truncation. Native model-text byte clipping is separately marked in rendered text and presentation metadata.";
         };
         readonly evidence_level: {
             readonly type: "string";
@@ -111,7 +112,7 @@ export declare const WEB_SEARCH_OUTPUT_SCHEMA: {
                 readonly properties: {
                     readonly code: {
                         readonly type: "string";
-                        readonly enum: readonly ["main_search_failed", "native_search_unconfirmed", "provider_failed", "provider_not_configured", "provider_result_truncated", "cache_stale", "cache_evicted", "answer_truncated", "sources_truncated", "canonical_output_truncated", "no_results"];
+                        readonly enum: readonly ["main_search_failed", "native_search_unconfirmed", "provider_failed", "provider_not_configured", "provider_result_truncated", "cache_stale", "cache_evicted", "answer_truncated", "sources_truncated", "visible_sources_truncated", "source_retention_truncated", "canonical_output_truncated", "no_results"];
                         readonly required: true;
                         readonly description: "Stable warning category.";
                     };
@@ -167,14 +168,14 @@ export declare const DOCS_SEARCH_PARAMETERS: {
         readonly type: "integer";
         readonly enum: readonly [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20];
         readonly default: 6;
-        readonly description: "Maximum results (1-20); defaults to 6 and may be lowered by Settings.";
+        readonly description: "Per-Provider collection and inline limit (1-20; default 6, capped by Settings). Not an exhaustive total: pagination only reads collected/retained sources. Increase this and rerun to collect more.";
     };
     readonly force_refresh: {
         readonly type: "boolean";
         readonly description: "Bypass fresh Context7 cache entries and request current Provider data.";
     };
 };
-export declare const DOCS_SEARCH_WARNING_CODES: readonly ["provider_failed", "provider_not_configured", "cache_stale", "cache_evicted", "provider_result_truncated", "no_results", "sources_truncated", "canonical_output_truncated"];
+export declare const DOCS_SEARCH_WARNING_CODES: readonly ["provider_failed", "provider_not_configured", "cache_stale", "cache_evicted", "provider_result_truncated", "library_not_found", "collection_limit_reached", "visible_sources_truncated", "no_results", "source_retention_truncated", "canonical_output_truncated"];
 /** Canonical high-level documentation value shared exactly by Native and Code Mode. */
 export declare const DOCS_SEARCH_OUTPUT_SCHEMA: {
     readonly type: "object";
@@ -347,6 +348,7 @@ export declare const DOCS_SEARCH_OUTPUT_SCHEMA: {
         readonly truncated: {
             readonly type: "boolean";
             readonly required: true;
+            readonly description: "Canonical result/storage truncation. Native model-text byte clipping is separately marked in rendered text and presentation metadata.";
         };
         readonly evidence_level: {
             readonly type: "string";
@@ -360,7 +362,7 @@ export declare const DOCS_SEARCH_OUTPUT_SCHEMA: {
                 readonly properties: {
                     readonly code: {
                         readonly type: "string";
-                        readonly enum: readonly ["provider_failed", "provider_not_configured", "cache_stale", "cache_evicted", "provider_result_truncated", "no_results", "sources_truncated", "canonical_output_truncated"];
+                        readonly enum: readonly ["provider_failed", "provider_not_configured", "cache_stale", "cache_evicted", "provider_result_truncated", "library_not_found", "collection_limit_reached", "visible_sources_truncated", "no_results", "source_retention_truncated", "canonical_output_truncated"];
                         readonly required: true;
                     };
                     readonly provider: {

package/lib/tools/schemas.js

@@ -107,6 +107,7 @@ export const WEB_SEARCH_OUTPUT_SCHEMA = {
         truncated: {
             type: 'boolean',
             required: true,
+            description: 'Canonical result/storage truncation. Native model-text byte clipping is separately marked in rendered text and presentation metadata.',
         },
         evidence_level: {
             type: 'string',
@@ -157,7 +158,7 @@ export const DOCS_SEARCH_PARAMETERS = {
         type: 'integer',
         enum: DOCS_SEARCH_MAX_RESULTS_VALUES,
         default: DOCS_SEARCH_DEFAULT_MAX_RESULTS,
-        description: 'Maximum results (1-20); defaults to 6 and may be lowered by Settings.',
+        description: 'Per-Provider collection and inline limit (1-20; default 6, capped by Settings). Not an exhaustive total: pagination only reads collected/retained sources. Increase this and rerun to collect more.',
     },
     force_refresh: {
         type: 'boolean',
@@ -225,7 +226,7 @@ const documentationCacheSchema = {
 };
 export const DOCS_SEARCH_WARNING_CODES = [
     ...DOCUMENTATION_WARNING_CODES,
-    'sources_truncated',
+    'source_retention_truncated',
     'canonical_output_truncated',
 ];
 const docsSearchWarningSchema = {
@@ -289,7 +290,10 @@ export const DOCS_SEARCH_OUTPUT_SCHEMA = {
         returned_sources: { type: 'integer', required: true },
         total_snippets: { type: 'integer', required: true },
         returned_snippets: { type: 'integer', required: true },
-        truncated: { type: 'boolean', required: true },
+        truncated: {
+            type: 'boolean', required: true,
+            description: 'Canonical result/storage truncation. Native model-text byte clipping is separately marked in rendered text and presentation metadata.',
+        },
         evidence_level: { type: 'string', const: 'discovery', required: true },
         warnings: {
             type: 'array',

package/lib/tools/web-search.js

@@ -19,17 +19,18 @@ function outputWarning(warning) {
         ...(warning.errorKind === undefined ? {} : { error_kind: warning.errorKind }),
     };
 }
-function ensureSourcesTruncatedWarning(warnings) {
-    if (!warnings.some(warning => warning.code === 'sources_truncated')) {
-        warnings.push({ code: 'sources_truncated' });
+function ensureRetentionWarning(warnings) {
+    if (!warnings.some(warning => warning.code === 'source_retention_truncated')) {
+        warnings.push({ code: 'source_retention_truncated' });
     }
 }
 /** Project only ordinary visible fields; Provider/category routing stays internal. */
 export function projectWebSearchOutput(result, config, commit) {
     const warnings = result.canonical.warnings.map(outputWarning);
     const storageTruncated = commit?.record.truncated === true;
-    if (storageTruncated)
-        ensureSourcesTruncatedWarning(warnings);
+    if (commit !== undefined && commit.record.sources.length < commit.record.totalBeforeRetention) {
+        ensureRetentionWarning(warnings);
+    }
     const sources = result.canonical.sources.map(source => ({
         url: source.url,
         ...(source.title === undefined ? {} : { title: source.title }),

package/lib/web-config/contracts.d.ts

@@ -30,6 +30,12 @@ export interface WebEditableConfig {
     defaultProfile: string;
     defaultDepth: string;
     toolTimeoutMs: number;
+    retention: {
+        docsSearchMaxResults: number;
+    };
+    budgets: Record<string, Record<string, {
+        maxVisibleSources: number;
+    }>>;
     toolDiscovery: {
         mode: string;
     };
@@ -76,6 +82,9 @@ export interface WebConfigOptions {
     parallelSearchModes: readonly string[];
     proxyUrlMaxCharacters: number;
     supplementalSearchMaxSources: number;
+    docsSearchMinResults: number;
+    docsSearchMaxResults: number;
+    visibleSourcesMax: number;
 }
 export interface WebCredentialState {
     ref: string;

package/lib/web-config/contracts.js

@@ -18,6 +18,9 @@ export const WEB_EDITABLE_PATHS = [
     ['defaultProfile'],
     ['defaultDepth'],
     ['toolTimeoutMs'],
+    ['retention', 'docsSearchMaxResults'],
+    ...['auto', 'coding_docs', 'code_examples', 'project_research', 'academic', 'fact_check']
+        .flatMap(profile => ['compact', 'normal', 'deep'].map(depth => ['budgets', profile, depth, 'maxVisibleSources'])),
     ['toolDiscovery', 'mode'],
     ...WEB_SUPPLEMENTAL_SEARCH_PROVIDERS.map(provider => ['supplementalSearch', provider]),
     ['supplementalSearch', 'maxSourcesPerProvider'],

package/lib/web-config/host.js

@@ -1,5 +1,5 @@
 import Schema from '@deepseek-ai/schemastery';
-import { Config as SearchEnhanceConfig, PARALLEL_SEARCH_MODES, SUPPLEMENTAL_SEARCH_MAX_SOURCES, SEARCH_API_PROTOCOLS, SEARCH_DEPTHS, SEARCH_PROFILES, THINKING_LEVELS, TOOL_DISCOVERY_MODES, WEB_EXTRACT_PROXY_URL_MAX_CHARACTERS, validateWebExtractProxyUrl, } from '../config.js';
+import { Config as SearchEnhanceConfig, DOCS_SEARCH_DEFAULT_MAX_RESULTS, DOCS_SEARCH_MAX_RESULTS_LIMIT, PARALLEL_SEARCH_MODES, SUPPLEMENTAL_SEARCH_MAX_SOURCES, SEARCH_API_PROTOCOLS, SEARCH_DEPTHS, SEARCH_PROFILES, THINKING_LEVELS, TOOL_DISCOVERY_MODES, WEB_EXTRACT_PROXY_URL_MAX_CHARACTERS, validateWebExtractProxyUrl, } from '../config.js';
 import { inspectDiagnosticStatus } from '../diagnostics/status.js';
 import { WEB_BASE_URL_MAX_CHARACTERS, WEB_CONFIG_PATH, WEB_CREDENTIAL_REF_MAX_CHARACTERS, WEB_CREDENTIAL_SLOTS, WEB_CREDENTIAL_VALUE_MAX_CHARACTERS, WEB_CREDENTIALS_PATH, WEB_EDITABLE_PATHS, WEB_MODEL_MAX_CHARACTERS, } from './contracts.js';
 export const WEB_CONFIG_REQUEST_MAX_BYTES = 64 * 1024;
@@ -59,6 +59,13 @@ function projectConfig(config) {
         defaultProfile: config.defaultProfile,
         defaultDepth: config.defaultDepth,
         toolTimeoutMs: config.toolTimeoutMs,
+        retention: { docsSearchMaxResults: config.retention.docsSearchMaxResults },
+        budgets: Object.fromEntries(Object.entries(config.budgets).map(([profile, depths]) => [
+            profile,
+            Object.fromEntries(Object.entries(depths).map(([depth, budget]) => [
+                depth, { maxVisibleSources: budget.maxVisibleSources },
+            ])),
+        ])),
         toolDiscovery: { mode: config.toolDiscovery.mode },
         supplementalSearch: { ...config.supplementalSearch },
         searchApi: {
@@ -232,6 +239,9 @@ export async function readWebConfigSnapshot(ctx, signal) {
             parallelSearchModes: [...PARALLEL_SEARCH_MODES],
             proxyUrlMaxCharacters: WEB_EXTRACT_PROXY_URL_MAX_CHARACTERS,
             supplementalSearchMaxSources: SUPPLEMENTAL_SEARCH_MAX_SOURCES,
+            docsSearchMinResults: DOCS_SEARCH_DEFAULT_MAX_RESULTS,
+            docsSearchMaxResults: DOCS_SEARCH_MAX_RESULTS_LIMIT,
+            visibleSourcesMax: 1000,
         },
         credentials: Object.fromEntries(credentialEntries),
         diagnostics: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-search-enhance",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Bounded search, documentation, extraction, and on-demand source pagination and site mapping for DeepSeek Harness",
   "repository": {
     "type": "git",
@@ -76,7 +76,9 @@
     "cordis.patch.yml",
     "README.md"
   ],
-  "sideEffects": ["./client/client.js"],
+  "sideEffects": [
+    "./client/client.js"
+  ],
   "scripts": {
     "clean": "node -e \"const { rmSync } = require('node:fs'); for (const path of ['lib', 'client']) rmSync(path, { recursive: true, force: true })\"",
     "build": "npm run clean && tsc -p tsconfig.build.json && tsdown && tsc -p tsconfig.client.build.json",
@@ -122,14 +124,30 @@
     "react": "^18.2.0"
   },
   "peerDependenciesMeta": {
-    "@deepseek-ai/dsh-client-locale": { "optional": true },
-    "@deepseek-ai/dsh-client-ui-primitives": { "optional": true },
-    "@deepseek-ai/dsh-client-ui-settings": { "optional": true },
-    "@deepseek-ai/dsh-client-ui-renderer": { "optional": true },
-    "@deepseek-ai/dsh-client-ui-settings-plugins": { "optional": true },
-    "@deepseek-ai/dsh-client-ui-slots": { "optional": true },
-    "@deepseek-ai/dsh-host-webserver": { "optional": true },
-    "react": { "optional": true }
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-primitives": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-settings": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-renderer": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-settings-plugins": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-slots": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-host-webserver": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@deepseek-ai/dsh-util-values": "0.2.0-rc.2",