dsh-search-enhance 0.2.0 → 0.2.2

package/lib/diagnostics/types.d.ts

@@ -1,5 +1,5 @@
 import type { CredentialProvider } from '@deepseek-ai/dsh-credentials';
-import type { Config, FallbackMode, MinimumCapabilityProfile, SearchApiProtocol, SearchDepth, SearchProfile, ThinkingLevel } from '../config.js';
+import type { Config, FallbackMode, MinimumCapabilityProfile, SearchApiProtocol, ThinkingLevel } from '../config.js';
 import type { ProviderErrorKind } from '../provider-runtime/index.js';
 export declare const DIAGNOSTIC_ACTIONS: readonly ["show", "test"];
 export type DiagnosticAction = (typeof DIAGNOSTIC_ACTIONS)[number];
@@ -38,8 +38,6 @@ export interface DiagnosticMinimumProfile {
 }
 /** Safe deployment facts. Values, refs, endpoints, proxies, and paths do not fit this type. */
 export interface DiagnosticConfigurationStatus {
-    readonly defaultProfile: SearchProfile;
-    readonly defaultDepth: SearchDepth;
     readonly searchApiProtocol: SearchApiProtocol;
     readonly searchModelConfigured: boolean;
     readonly thinkingLevel: ThinkingLevel;

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,9 @@ 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,
-            depth: 'compact',
-            profile: 'coding_docs',
+            collectionTruncated: exaOutcome.truncated,
             query: validated.query,
-            sources,
+            sources: Object.freeze(qualitySources),
         });
         return Object.freeze({
             attempts,
@@ -712,6 +719,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/index.js

@@ -1,116 +1,30 @@
 import { Config as SearchEnhanceConfig } from './config.js';
-import { Context7CachedOperations, DocumentationSearchService, PersistentContext7Cache, } from './documentation/index.js';
-import { SearchOrchestrator } from './orchestration/index.js';
+import { ResearchExecutor } from './research/executor.js';
 import { registerToolDiscoveryGuidance } from './prompt/tool-discovery.js';
-import { Context7RemoteClient } from './providers/context7.js';
-import { ExaProvider } from './providers/exa.js';
-import { FirecrawlSearchProvider } from './providers/firecrawl.js';
-import { FirecrawlScrapeProvider } from './providers/firecrawl-scrape.js';
-import { DirectFetchProvider } from './providers/direct-fetch.js';
-import { ParallelSearchProvider } from './providers/parallel.js';
-import { ParallelExtractProvider } from './providers/parallel-extract.js';
-import { SearchApiProvider } from './providers/search-api.js';
-import { SmartDirectProvider } from './providers/smart-direct.js';
-import { TavilySearchProvider } from './providers/tavily.js';
-import { TavilyExtractProvider } from './providers/tavily-extract.js';
-import { TavilyMapProvider } from './providers/tavily-map.js';
-import { SOURCE_RECORD_DOMAIN_SPEC, SOURCE_RECORD_TABLE_NAME, SearchEnhanceSourceService, SourceRecordStore, } from './source-storage/index.js';
 import { installAgentToolDisclosure } from './tool-discovery/index.js';
-import { ForegroundOperationScope, createDocsSearchTool, createSearchSourcesTool, createSearchToolsTool, createWebExtractTool, createWebMapTool, createWebSearchTool, } from './tools/index.js';
-import { WebExtractOrchestrator } from './web-extract/orchestrator.js';
+import { createWebResearchTool } from './tools/index.js';
+import { createSearchServices } from './tools/services.js';
 import { installWebConfigBridge } from './web-config/host.js';
 export const name = 'search-enhance';
-export const inject = ['agents', 'configEditor', 'credentials', 'storageDomain', 'systemPrompt', 'tools'];
+// Display services are discovered per call through reflect.get, never required here.
+export const inject = ['agents', 'configEditor', 'credentials', 'llm', 'storageDomain', 'subagents', 'systemPrompt', 'tools'];
 export const Config = SearchEnhanceConfig;
 export async function apply(ctx, config) {
-    const effective = config;
-    const domain = await ctx.storageDomain.open(SOURCE_RECORD_DOMAIN_SPEC);
-    const store = new SourceRecordStore(domain.table(SOURCE_RECORD_TABLE_NAME), {
-        maxBytes: effective.retention.sourceEventMaxBytes,
-        maxRecords: effective.retention.sourceStoreMaxRecords,
-        maxSources: effective.retention.sourceEventMaxSources,
-        maxPageSize: effective.retention.searchSourcesMaxPageSize,
-        maxPageBytes: effective.retention.searchSourcesPageMaxBytes,
-        maxSnippetCharacters: effective.retention.searchSourcesSnippetMaxCharacters,
-    });
-    const operations = new ForegroundOperationScope();
-    // ConfigEditor reconciles edits by rebuilding this plugin in-process; a saved
-    // configuration is active as soon as the edit request completes.
-    const getConfig = () => effective;
-    const providerDependencies = { credentials: ctx.credentials };
-    const context7Cache = new PersistentContext7Cache(ctx.storageDomain, {
-        maxEntries: effective.cache.maxEntries,
-        maxEntryBytes: effective.cache.context7EntryMaxBytes,
-    });
-    const cachedContext7 = new Context7CachedOperations(context7Cache);
-    const context7Remote = new Context7RemoteClient(providerDependencies);
-    const exa = new ExaProvider(providerDependencies);
-    let documentation;
-    // Keep dependent shutdown in one ordered disposer: stop both public-tool and
-    // service calls, close the lazy docs cache, then drain source writes/domain.
-    ctx.effect(() => async () => {
-        await Promise.all([
-            operations.stop(),
-            documentation?.stop() ?? Promise.resolve(),
-        ]);
-        await context7Cache.close();
-        store.stop();
-        await store.drain();
-        await domain.close();
-    });
-    new SearchEnhanceSourceService(ctx, store);
-    documentation = new DocumentationSearchService(ctx, {
-        context7: context7Remote,
-        context7Cache: cachedContext7,
-        exa,
-        getConfig,
-    });
-    const searchApi = new SearchApiProvider({
-        credentials: ctx.credentials,
-        getConfig,
-    });
-    const firecrawl = new FirecrawlSearchProvider(providerDependencies);
-    const tavily = new TavilySearchProvider(providerDependencies);
-    const parallel = new ParallelSearchProvider(providerDependencies);
-    const orchestrator = new SearchOrchestrator({
-        exa,
-        firecrawl,
-        getConfig,
-        mainSearch: searchApi,
-        parallel,
-        tavily,
-    });
-    const webExtract = new WebExtractOrchestrator({
-        tavilyExtract: new TavilyExtractProvider(providerDependencies),
-        firecrawlScrape: new FirecrawlScrapeProvider(providerDependencies),
-        parallelExtract: new ParallelExtractProvider(providerDependencies),
-        smartDirect: new SmartDirectProvider(),
-        direct: new DirectFetchProvider(),
-        getConfig,
-    });
-    const disclosure = installAgentToolDisclosure(ctx, {
-        mode: effective.toolDiscovery.mode,
-        webSearchDefinition: createWebSearchTool({
-            getConfig, operations, orchestrator, sources: ctx.searchEnhanceSources,
-        }),
-        deferredTools: {
-            sources: createSearchSourcesTool({
-                getConfig, operations, sources: ctx.searchEnhanceSources,
-            }),
-            site_map: createWebMapTool({
-                getConfig, operations, provider: new TavilyMapProvider(providerDependencies),
-            }),
+    const { tools, operations } = await createSearchServices(ctx, config);
+    const research = new ResearchExecutor(ctx, () => config);
+    ctx.effect(() => async () => { await operations.stop(); research.dispose(); });
+    installAgentToolDisclosure(ctx, {
+        mode: config.toolDiscovery.mode,
+        residentTools: {
+            docs_search: tools.docs_search,
+            web_extract: tools.web_extract,
+            web_research: createWebResearchTool({ research, operations }),
         },
+        canReadSourceRef: (agent, ref) => ctx.searchEnhanceSources.lookup(agent.session, ref).state === 'found',
+        sourceRefForCall: (agent, call) => ctx.searchEnhanceSources.sourceRefForCall(agent.session, call),
+        webSearchDefinition: tools.web_search,
+        deferredTools: { sources: tools.search_sources, site_map: tools.web_map },
     });
-    const residentToolDefinitions = [
-        createDocsSearchTool({
-            documentation, getConfig, operations, sources: ctx.searchEnhanceSources,
-        }),
-        createWebExtractTool({ getConfig, operations, orchestrator: webExtract }),
-        createSearchToolsTool(disclosure),
-    ];
-    for (const definition of residentToolDefinitions)
-        ctx.tools.register(definition);
     registerToolDiscoveryGuidance(ctx);
     installWebConfigBridge(ctx);
 }

package/lib/orchestration/orchestrator.js

@@ -320,10 +320,7 @@ export class SearchOrchestrator {
         }
         let strategy;
         try {
-            strategy = resolveSearchStrategy(config, {
-                ...(input.depth === undefined ? {} : { depth: input.depth }),
-                ...(input.profile === undefined ? {} : { profile: input.profile }),
-            });
+            strategy = resolveSearchStrategy(config);
         }
         catch (error) {
             throw new ProviderError({
@@ -562,8 +559,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'));
             }
@@ -583,10 +582,8 @@ export class SearchOrchestrator {
                 ...slots.map(slot => sourceAttempt(slot)),
             ]);
             const routing = Object.freeze({
-                depth: strategy.depth,
                 supplementalProviders: slots.filter(slot => config.supplementalSearch[slot.key]).map(slot => slot.key),
                 sourcesPerProvider: config.supplementalSearch.maxSourcesPerProvider,
-                profile: strategy.profile,
             });
             const answer = limitedAnswer.text.length === 0 ? undefined : limitedAnswer.text;
             const candidate = {
@@ -607,8 +604,6 @@ export class SearchOrchestrator {
                 diagnostics: { attempts, routing },
                 persistence: {
                     collectionTruncated,
-                    depth: strategy.depth,
-                    profile: strategy.profile,
                     query,
                     sources: prioritizedSources,
                 },

package/lib/orchestration/types.d.ts

@@ -1,9 +1,9 @@
-import type { Config, SearchDepth, SearchProfile, SupplementalSearchProvider } from '../config.js';
+import type { Config, SupplementalSearchProvider } from '../config.js';
 import type { CanonicalSource, SourceRecordCandidate } from '../contracts/index.js';
 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 {
@@ -14,8 +14,6 @@ export interface SearchWarning {
 }
 /** One operation's fixed policy decision, excluding credentials and endpoints. */
 export interface SearchRoutingDecision {
-    readonly profile: SearchProfile;
-    readonly depth: SearchDepth;
     readonly supplementalProviders: readonly SupplementalSearchProvider[];
     readonly sourcesPerProvider: number;
 }
@@ -47,8 +45,6 @@ export interface SearchOrchestrationResult {
 }
 export interface SearchOrchestrationInput {
     readonly query: string;
-    readonly profile?: unknown;
-    readonly depth?: unknown;
     /** Optional caller-owned operation snapshot; otherwise `getConfig()` is read once. */
     readonly config?: Config;
     readonly signal: AbortSignal;

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,19 +9,24 @@ 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)
         return undefined;
-    return `Source reference: ${sourceRef}\n\nFor more sources, call search_tools({ capabilities: ["sources"] }), then call search_sources directly on the next step.`;
+    return `Source reference: ${sourceRef}\n\nFor more sources, call search_sources directly on the next step; it becomes available automatically.`;
 }
 function warningText(warning) {
     const subject = [warning.provider, warning.capability].filter(Boolean).join('/');
@@ -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.d.ts

@@ -1,6 +1,6 @@
 import type { Context } from '@deepseek-ai/cordis';
 export declare const TOOL_DISCOVERY_GUIDANCE: string;
 export declare const EVIDENCE_DISCIPLINE_GUIDANCE: string;
-/** Register deterministic guidance that never reads Agent state or tool visibility. */
+/** Register main/ordinary-agent guidance; the dedicated research persona owns its own routing. */
 export declare function registerToolDiscoveryGuidance(ctx: Context): void;
 //# sourceMappingURL=tool-discovery.d.ts.map

package/lib/prompt/tool-discovery.js

@@ -1,19 +1,17 @@
 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.',
+    'For multi-step investigations, comparisons or corroboration across sources, delegate to web_research with a self-contained question and all constraints; wait for its URL-and-excerpt report. Use web_search/docs_search/web_extract directly for quick lookups, documentation or a known URL.',
+    'web_research accepts optional timeout_ms for this call\'s total budget, including creation, reasoning, retrieval and reporting: default 600000 ms; integer range 60000–3600000 ms. Choose by task complexity, for example 120000 for a focused comparison or 1200000 for broad corroboration; omission uses the default, and more time does not guarantee better evidence.',
+    'After a successful search returns a readable source_ref, search_sources becomes available automatically on the next step. Call it directly to paginate retained sources; no loader is needed.',
 ].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, use web_research for multi-step investigations; otherwise 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. */
+/** Register main/ordinary-agent guidance; the dedicated research persona owns its own routing. */
 export function registerToolDiscoveryGuidance(ctx) {
     ctx.systemPrompt.section({
         name: 'search-enhance:tool-discovery',